18 Matching Annotations
  1. Last 7 days
    1. However, we found a few trade-offs when using clojure.spec: clojure.spec requires registering a spec for each key in every path that you care about in a data structure, which can be verbose, especially for deeply-nested data structures. We felt this pain the most when specifying the incoming webhook payloads from the providers. We didn't specify the full payloads, we only specified the values that we actually needed, some of which were nested 7-8 levels deep. To work around this, we used data-spec (part of the spec-tools project) to define the payload specs as a mirror of the shape of the actual data. clojure.spec's error output is concise, and it's not always immediately apparent where the validation failure is within the data, especially when validating a large data structure. To help with this, we used expound to generate friendlier error messages at the REPL and in tests.

      spec gotchas

    2. This system is the first significant project on which we have used clojure.spec, and it proved useful in a few ways: Specifying the inputs to each layer in one place made it easier to visualize the shape of the data as it flowed through the subsystem, and proved valuable when describing the behavior to other engineers.Instrumenting the inputs and outputs of our layer boundary functions (via Orchestra), during testing, enabled us to quickly catch cases where we deviated from the spec, allowing us to see the issue at that boundary instead of as a random error within the implementation. Validating the layer inputs against our specs in production allows us to quickly diagnose and isolate faults to the layer where it was triggered, and helps us catch when our assumptions about the shape of the webhook event are incorrect. Having specs allowed for more straightforward tests, since we didn't need to assert on the shape of the data.

      benefits of spec

    1. (s/def :ring.http/field-name (-> (s/and string? not-empty field-name-chars?) (s/with-gen #(gen/not-empty (gen-string field-name-chars)))))

      clean way of using with gen!

    2. (defn- gen-string [chars] (gen/fmap str/join (gen/vector (gen/elements chars)))) (defn- gen-query-string [] (->> (gen/tuple (gen/not-empty (gen/string-alphanumeric)) (gen-string uri-chars)) (gen/fmap (fn [[k v]] (str k "=" v))) (gen/vector) (gen/fmap #(str/join "&" %)))) (defn- gen-method [] (gen/fmap keyword (gen/not-empty (gen-string lower-case-chars)))) (defn- gen-input-stream [] (gen/fmap #(java.io.ByteArrayInputStream. %) (gen/bytes))) (defn- gen-exception [] (gen/fmap (fn [s] (Exception. s)) (gen/string-alphanumeric)))

      nice lesson on generators

    3. (defn- char-range [a b] (map char (range (int a) (inc (int b))))) (def ^:private lower-case-chars (set (char-range \a \z)))

      nice way of defining character range

  2. Oct 2018
    1. function coll-of allows a :count key to specify the required number of elements:

      good to know that there is the keyword directive :count

    2. On the flip side, it can go further than mere types, including emulating dependent types and programming-by-contract.

      spec though it's used at runtime (not compile time)

      • hence: not a replacement for types as such BUT
      • enables dependent types
      • programming by contract
    1. Relevant vocabularies A combination of some W3C and third-party vocabularies can be used to formally capture the Technical Reports metadata in RDF. The following list summarizes these vocabularies: Event-based model of the W3C process Online documentation: http://www.w3.org/2001/02pd/rec54 Namespace: http://www.w3.org/2001/02pd/rec54# Ontology of the W3C organizational structure Namespace: http://www.w3.org/2001/04/roadmap/org# Vocabulary to annotate W3C TR with regard to Quality Assurance Online documentation: http://www.w3.org/2002/05/matrix/vocab Namespace: http://www.w3.org/2002/05/matrix/vocab# Vocabulary to describe document relationships and licenses Namespace: http://www.w3.org/2000/10/swap/pim/doc# Vocabulary for contact information Namespace: http://www.w3.org/2000/10/swap/pim/contact# Dublin Core Metadata Terms Online documentation: http://dublincore.org/documents/dcmi-terms/ Namespace: http://purl.org/dc/terms/ Note that some of these vocabularies are published by W3C, but they have no formal standing (they are not W3C Recommendations). In the following, it is assumed that the following namespace aliases are defined: Prefix Namespace rec: http://www.w3.org/2001/02pd/rec54# org: http://www.w3.org/2001/04/roadmap/org# mat: http://www.w3.org/2002/05/matrix/vocab# doc: http://www.w3.org/2000/10/swap/pim/doc# con: http://www.w3.org/2000/10/swap/pim/contact# dct: http://purl.org/dc/terms/
    1. The "Standard" element is used to list all the relevant standards implemented by the project. These standards include W3C or ISO standards, RFCs, various technical specifications etc.
  3. Nov 2017
  4. Aug 2017
  5. Jul 2017
  6. Jun 2016
    1. If the exclude fragment flag is unset and url’s fragment is non-null, append "#", followed by url’s fragment, to output.
    2. If the given value is the empty string, set context object’s url’s fragment to null and terminate these steps