diff --git a/README.md b/README.md index 97d9ad0..1782064 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,10 @@ At present, only the duck-typing functions work. To play with them, use (require '[dog-and-duck.quack.quack :as q]) ``` +## Documentation + +Full documentation is [here](https://simon-brooke.github.io/dog-and-duck/). + ## Testing Prior to testing, you should clone [activitystreams-test-documents](https://github.com/w3c-social/activitystreams-test-documents) into the `resources` directory. You can then test with diff --git a/doc/Using_ActivityPub.md b/doc/Using_ActivityPub.md index b306543..821b0fc 100644 --- a/doc/Using_ActivityPub.md +++ b/doc/Using_ActivityPub.md @@ -1,112 +1,5 @@ # Using ActivityPub -```clojure -user=> (require '[clj-activitypub.core :as activitypub]) -nil -user=> (require '[clj-activitypub.webfinger :as webfinger]) -nil -user=> (require '[clojure.walk :refer [keywordize-keys]]) -nil -user=> (require '[clojure.pprint :refer [pprint]]) -nil -user=> (def base-domain "mastodon.scot") -#'user/base-domain -user=> (def account-handle "@simon_brooke@mastodon.scot") -#'user/account-handle -user=> (in-ns 'user) -#object[clojure.lang.Namespace 0x525575 "user"] -user=> (activitypub/parse-account account-handle ) -{:domain "mastodon.scot", :username "simon_brooke"} -user=> (map *1 [:domain :username]) -("mastodon.scot" "simon_brooke") -user=> (apply webfinger/fetch-user-id *1) -"https://mastodon.scot/users/simon_brooke" -user=> (activitypub/fetch-user *1) -{"followers" "https://mastodon.scot/users/simon_brooke/followers", "inbox" "https://mastodon.scot/users/simon_brooke/inbox", "url" "https://mastodon.scot/@simon_brooke", "@context" ["https://www.w3.org/ns/activitystreams" "https://w3id.org/security/v1" {"identityKey" {"@type" "@id", "@id" "toot:identityKey"}, "EncryptedMessage" "toot:EncryptedMessage", "Ed25519Key" "toot:Ed25519Key", "devices" {"@type" "@id", "@id" "toot:devices"}, "manuallyApprovesFollowers" "as:manuallyApprovesFollowers", "schema" "http://schema.org#", "PropertyValue" "schema:PropertyValue", "Curve25519Key" "toot:Curve25519Key", "claim" {"@type" "@id", "@id" "toot:claim"}, "value" "schema:value", "Hashtag" "as:Hashtag", "movedTo" {"@id" "as:movedTo", "@type" "@id"}, "discoverable" "toot:discoverable", "messageType" "toot:messageType", "messageFranking" "toot:messageFranking", "cipherText" "toot:cipherText", "toot" "http://joinmastodon.org/ns#", "alsoKnownAs" {"@id" "as:alsoKnownAs", "@type" "@id"}, "featured" {"@id" "toot:featured", "@type" "@id"}, "featuredTags" {"@id" "toot:featuredTags", "@type" "@id"}, "Ed25519Signature" "toot:Ed25519Signature", "focalPoint" {"@container" "@list", "@id" "toot:focalPoint"}, "fingerprintKey" {"@type" "@id", "@id" "toot:fingerprintKey"}, "Device" "toot:Device", "publicKeyBase64" "toot:publicKeyBase64", "deviceId" "toot:deviceId", "suspended" "toot:suspended"}], "devices" "https://mastodon.scot/users/simon_brooke/collections/devices", "manuallyApprovesFollowers" false, "image" {"type" "Image", "mediaType" "image/jpeg", "url" "https://media.mastodon.scot/mastodon-scot-public/accounts/headers/109/252/274/874/045/781/original/e1f1823c4361fa27.jpg"}, "endpoints" {"sharedInbox" "https://mastodon.scot/inbox"}, "id" "https://mastodon.scot/users/simon_brooke", "publicKey" {"id" "https://mastodon.scot/users/simon_brooke#main-key", "owner" "https://mastodon.scot/users/simon_brooke", "publicKeyPem" "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2/6GgLJgJlPhhqFm1tUQ\noSLnWxhDwq4HlZIHrBsVjkSvUAnHKqq42Q/hta+fkWB8rmTFpmjLXDj/Fi0uejvT\nBc+KrLwfX/yR8+G87afGCRS3CaumoLJ7zkBIlsFzIKMoIke1D3QuHX95yGGXs+hp\nmyxt/+CXRyZjK7u9NG7SMRUlpwvOlpD12Aei35Nb8NSr03JvY8/WVMIbWrecyI0b\nAlwj6axxHx7J15Yo+aEtKzZ2OFKXf+sh0QF9BEnYcmVKYlR6kiOglLFHKdCBUSYi\ni9Flv00TydqlGvR5fpShBqORiy0M/FVtNXlz2sNBEsGB2meipkjh+cRLzTbYo4KL\nJwIDAQAB\n-----END PUBLIC KEY-----\n"}, "summary" "
Anarcho-syndicalist, autistic, crofter, cyclist, depressive, entrepreneur, geek, Zapatista. Politics & environment, especially #LandReform. he/him.
Twitter: @simon_brooke
GitHub: simon-brooke
FetLife: Simon_Brooke
Credo: Life is harsh. What we can do - and what we should do - is strive to make it less harsh for the people around us.
", "attachment" [{"type" "PropertyValue", "name" "Home Page", "value" "https://www.journeyman.cc/~simon/"}], "name" "Simon Brooke", "tag" [{"type" "Hashtag", "href" "https://mastodon.scot/tags/landreform", "name" "#landreform"}], "published" "2022-10-29T00:00:00Z", "preferredUsername" "simon_brooke", "discoverable" true, "alsoKnownAs" ["https://mastodon.social/users/simon_brooke"], "featured" "https://mastodon.scot/users/simon_brooke/collections/featured", "featuredTags" "https://mastodon.scot/users/simon_brooke/collections/tags", "type" "Person", "outbox" "https://mastodon.scot/users/simon_brooke/outbox", "following" "https://mastodon.scot/users/simon_brooke/following", "icon" {"type" "Image", "mediaType" "image/png", "url" "https://media.mastodon.scot/mastodon-scot-public/accounts/avatars/109/252/274/874/045/781/original/172e8f7530627e87.png"}} -user=> (def sb (keywordize-keys *1)) -#'user/sb -user=> (:outbox sb) -"https://mastodon.scot/users/simon_brooke/outbox" -user=> (require '[clojure.data.json :as json]) -nil -user=> (slurp (:outbox sb)) -Execution error (IOException) at sun.net.www.protocol.http.HttpURLConnection/getInputStream0 (HttpURLConnection.java:1894). -Server returned HTTP response code: 403 for URL: https://mastodon.scot/users/simon_brooke/outbox -user=> (pprint sb) -{:inbox "https://mastodon.scot/users/simon_brooke/inbox", - :name "Simon Brooke", - :@context - ["https://www.w3.org/ns/activitystreams" - "https://w3id.org/security/v1" - {:schema "http://schema.org#", - :messageType "toot:messageType", - :messageFranking "toot:messageFranking", - :identityKey {:@type "@id", :@id "toot:identityKey"}, - :Hashtag "as:Hashtag", - :deviceId "toot:deviceId", - :publicKeyBase64 "toot:publicKeyBase64", - :value "schema:value", - :Ed25519Key "toot:Ed25519Key", - :featured {:@id "toot:featured", :@type "@id"}, - :Curve25519Key "toot:Curve25519Key", - :discoverable "toot:discoverable", - :focalPoint {:@container "@list", :@id "toot:focalPoint"}, - :suspended "toot:suspended", - :fingerprintKey {:@type "@id", :@id "toot:fingerprintKey"}, - :Ed25519Signature "toot:Ed25519Signature", - :cipherText "toot:cipherText", - :EncryptedMessage "toot:EncryptedMessage", - :alsoKnownAs {:@id "as:alsoKnownAs", :@type "@id"}, - :featuredTags {:@id "toot:featuredTags", :@type "@id"}, - :devices {:@type "@id", :@id "toot:devices"}, - :toot "http://joinmastodon.org/ns#", - :movedTo {:@id "as:movedTo", :@type "@id"}, - :Device "toot:Device", - :PropertyValue "schema:PropertyValue", - :manuallyApprovesFollowers "as:manuallyApprovesFollowers", - :claim {:@type "@id", :@id "toot:claim"}}], - :featured - "https://mastodon.scot/users/simon_brooke/collections/featured", - :type "Person", - :discoverable true, - :icon - {:type "Image", - :mediaType "image/png", - :url - "https://media.mastodon.scot/mastodon-scot-public/accounts/avatars/109/252/274/874/045/781/original/172e8f7530627e87.png"}, - :following "https://mastodon.scot/users/simon_brooke/following", - :summary - "Anarcho-syndicalist, autistic, crofter, cyclist, depressive, entrepreneur, geek, Zapatista. Politics & environment, especially #LandReform. he/him.
Twitter: @simon_brooke
GitHub: simon-brooke
FetLife: Simon_Brooke
Credo: Life is harsh. What we can do - and what we should do - is strive to make it less harsh for the people around us.
", - :publicKey - {:id "https://mastodon.scot/users/simon_brooke#main-key", - :owner "https://mastodon.scot/users/simon_brooke", - :publicKeyPem - "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2/6GgLJgJlPhhqFm1tUQ\noSLnWxhDwq4HlZIHrBsVjkSvUAnHKqq42Q/hta+fkWB8rmTFpmjLXDj/Fi0uejvT\nBc+KrLwfX/yR8+G87afGCRS3CaumoLJ7zkBIlsFzIKMoIke1D3QuHX95yGGXs+hp\nmyxt/+CXRyZjK7u9NG7SMRUlpwvOlpD12Aei35Nb8NSr03JvY8/WVMIbWrecyI0b\nAlwj6axxHx7J15Yo+aEtKzZ2OFKXf+sh0QF9BEnYcmVKYlR6kiOglLFHKdCBUSYi\ni9Flv00TydqlGvR5fpShBqORiy0M/FVtNXlz2sNBEsGB2meipkjh+cRLzTbYo4KL\nJwIDAQAB\n-----END PUBLIC KEY-----\n"}, - :endpoints {:sharedInbox "https://mastodon.scot/inbox"}, - :preferredUsername "simon_brooke", - :id "https://mastodon.scot/users/simon_brooke", - :alsoKnownAs ["https://mastodon.social/users/simon_brooke"], - :outbox "https://mastodon.scot/users/simon_brooke/outbox", - :url "https://mastodon.scot/@simon_brooke", - :featuredTags - "https://mastodon.scot/users/simon_brooke/collections/tags", - :devices - "https://mastodon.scot/users/simon_brooke/collections/devices", - :image - {:type "Image", - :mediaType "image/jpeg", - :url - "https://media.mastodon.scot/mastodon-scot-public/accounts/headers/109/252/274/874/045/781/original/e1f1823c4361fa27.jpg"}, - :tag - [{:type "Hashtag", - :href "https://mastodon.scot/tags/landreform", - :name "#landreform"}], - :followers "https://mastodon.scot/users/simon_brooke/followers", - :published "2022-10-29T00:00:00Z", - :manuallyApprovesFollowers false, - :attachment - [{:type "PropertyValue", - :name "Home Page", - :value - "https://www.journeyman.cc/~simon/"}]} -``` +## Introduction + +I do not know what I am doing; I am learning, and playing. Nothing in this document should be treated as good advice; it simply relates to the current state of my knowledge. \ No newline at end of file diff --git a/doc/Validation_Faults.md b/doc/Validation_Faults.md new file mode 100644 index 0000000..9f6a8f6 --- /dev/null +++ b/doc/Validation_Faults.md @@ -0,0 +1,61 @@ +# Validation Faults in ActivityPub documents + +## Motivation + +This document is intended to provide an extension vocabulary for [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) documents, which provides vocabulary for categorising and describing faults in [ActivityPub](https://www.w3.org/TR/activitypub/) documents. + +The motivation is to be able to serialise a validation report on an ActivityPub document as an ActivityStreams document. + +## Intepretation + +### Conformance + +As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. + +The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119]. + +### 'the spec' + +Where the phrase 'the spec' is used in this document, it refers to a concatenation of the ActivityStreams specification and the ActivityPub specification. + +## The `Fault` object type + +The `Fault` object type is a novel object type introduced by this document to describe validation faults. Objects with the `Fault` object type MUST have at least the following fields (additional fields are not required but are optional): + +1. `:@context` whose value shall be the URL of a document specifying this vocabulary; +2. `:type` whose value shall be `Fault`; +3. `:severity` whose value shall be one of `minor`, `should`, `must` or `critical`; +4. `:fault` whose value shall be a unique token representing the particular fault type; +5. `:narrative` whose value shall be a natural language description of the fault type. + +### The Fields + +#### Context + +The value of the `@context` field of a fault report object shall be the URL of this +document, currently `https://simon-brooke.github.io/dog-and-duck/codox/Validation_Faults.html`. + +#### Type + +The value of the `type` field of a fault report object MUST be `Fault`. + +#### Severity + +Each fault report object MUST have a `severity` field whose value MUST be one of + + 1. `:minor` things which I consider to be faults, but which + don't actually breach the spec; + 2. `:should` instances where the spec says something SHOULD + be done, which isn't; + 3. `:must` instances where the spec says something MUST + be done, which isn't; + 4. `:critical` instances where I believe the fault means that + the object cannot be meaningfully processed. + +#### Fault + +Unique codes shall be assigned to each fault type, and shall be documented in this section. + +It is intended that there should ultimately be a well known site at which the fault codes can be resolved to natural language explanations in as many natural languages as possible of the nature of the particular fault. + + diff --git a/docs/cloverage/clj_activitypub/core.clj.html b/docs/cloverage/clj_activitypub/core.clj.html index d0e28ea..f00e04b 100644 --- a/docs/cloverage/clj_activitypub/core.clj.html +++ b/docs/cloverage/clj_activitypub/core.clj.html @@ -8,442 +8,451 @@ 001 (ns clj-activitypub.core