From 5593bb22d1ca8869032500d9d5e56b18760954fb Mon Sep 17 00:00:00 2001 From: Simon Brooke Date: Mon, 19 Dec 2022 23:50:37 +0000 Subject: [PATCH] Documentation and acknowledgement --- docs/codox/clj-activitypub.core.html | 2 +- .../codox/clj-activitypub.internal.crypto.html | 2 +- .../clj-activitypub.internal.http-util.html | 2 +- .../clj-activitypub.internal.thread-cache.html | 2 +- docs/codox/clj-activitypub.webfinger.html | 2 +- docs/codox/dog-and-duck.quack.quack.html | 18 ++++++++++++------ docs/codox/index.html | 2 +- src/clj_activitypub/core.clj | 3 +++ src/clj_activitypub/webfinger.clj | 3 +++ src/dog_and_duck/quack/quack.clj | 14 +++++++++++++- src/dog_and_duck/scratch/parser.clj | 2 ++ src/dog_and_duck/scratch/scratch.clj | 3 ++- 12 files changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/codox/clj-activitypub.core.html b/docs/codox/clj-activitypub.core.html index 9e763ef..de2f1d6 100644 --- a/docs/codox/clj-activitypub.core.html +++ b/docs/codox/clj-activitypub.core.html @@ -1,3 +1,3 @@ -clj-activitypub.core documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.core

TODO: write docs

activity

multimethod

Produces a map representing an ActivityPub activity which can be serialized directly to JSON in the form expected by the ActivityStreams 2.0 spec. See https://www.w3.org/TR/activitystreams-vocabulary/ for reference.

view source

actor

(actor {:keys [user-id username public-key]})

Accepts a config, and returns a map in the form expected by the ActivityPub spec. See https://www.w3.org/TR/activitypub/#actor-objects for reference.

view source

auth-headers

(auth-headers config {:keys [body headers]})

Given a config and request map of {:body … :headers …}, returns the original set of headers with Signature and Digest attributes appended.

view source

config

(config {:keys [domain username username-route public-key private-key], :or {username-route "/users/", public-key nil, private-key nil}})

Creates hash of computed data relevant for most ActivityPub utilities.

view source

fetch-user

(fetch-user user-id)

Fetches the customer account details located at user-id from a remote server. Will return cached results if they exist in memory.

view source

gen-signature-header

(gen-signature-header config headers)

Generates a HTTP Signature string based on the provided map of headers.

view source

obj

multimethod

Produces a map representing an ActivityPub object which can be serialized directly to JSON in the form expected by the ActivityStreams 2.0 spec. See https://www.w3.org/TR/activitystreams-vocabulary/ for reference.

view source

parse-account

(parse-account handle)

Given an ActivityPub handle (e.g. @jahfer@mastodon.social), produces a map containing {:domain … :username …}.

view source

signature-headers

TODO: write docs

view source

with-config

(with-config config)

Returns curried forms of the #activity and #obj multimethods in the form {:activity … :obj …}, with the initial parameter set to config.

view source
\ No newline at end of file +clj-activitypub.core documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.core

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

activity

multimethod

Produces a map representing an ActivityPub activity which can be serialized directly to JSON in the form expected by the ActivityStreams 2.0 spec. See https://www.w3.org/TR/activitystreams-vocabulary/ for reference.

view source

actor

(actor {:keys [user-id username public-key]})

Accepts a config, and returns a map in the form expected by the ActivityPub spec. See https://www.w3.org/TR/activitypub/#actor-objects for reference.

view source

auth-headers

(auth-headers config {:keys [body headers]})

Given a config and request map of {:body … :headers …}, returns the original set of headers with Signature and Digest attributes appended.

view source

config

(config {:keys [domain username username-route public-key private-key], :or {username-route "/users/", public-key nil, private-key nil}})

Creates hash of computed data relevant for most ActivityPub utilities.

view source

fetch-user

(fetch-user user-id)

Fetches the customer account details located at user-id from a remote server. Will return cached results if they exist in memory.

view source

gen-signature-header

(gen-signature-header config headers)

Generates a HTTP Signature string based on the provided map of headers.

view source

obj

multimethod

Produces a map representing an ActivityPub object which can be serialized directly to JSON in the form expected by the ActivityStreams 2.0 spec. See https://www.w3.org/TR/activitystreams-vocabulary/ for reference.

view source

parse-account

(parse-account handle)

Given an ActivityPub handle (e.g. @jahfer@mastodon.social), produces a map containing {:domain … :username …}.

view source

signature-headers

TODO: write docs

view source

with-config

(with-config config)

Returns curried forms of the #activity and #obj multimethods in the form {:activity … :obj …}, with the initial parameter set to config.

view source
\ No newline at end of file diff --git a/docs/codox/clj-activitypub.internal.crypto.html b/docs/codox/clj-activitypub.internal.crypto.html index 89605eb..ca50280 100644 --- a/docs/codox/clj-activitypub.internal.crypto.html +++ b/docs/codox/clj-activitypub.internal.crypto.html @@ -1,3 +1,3 @@ -clj-activitypub.internal.crypto documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.crypto

TODO: write docs

base64-encode

(base64-encode bytes)

TODO: write docs

view source

private-key

(private-key private-pem-str)

TODO: write docs

view source

sha256-base64

(sha256-base64 data)

TODO: write docs

view source

sign

(sign data private-key)

TODO: write docs

view source
\ No newline at end of file +clj-activitypub.internal.crypto documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.crypto

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

base64-encode

(base64-encode bytes)

TODO: write docs

view source

private-key

(private-key private-pem-str)

TODO: write docs

view source

sha256-base64

(sha256-base64 data)

TODO: write docs

view source

sign

(sign data private-key)

TODO: write docs

view source
\ No newline at end of file diff --git a/docs/codox/clj-activitypub.internal.http-util.html b/docs/codox/clj-activitypub.internal.http-util.html index 2726e1a..b6afb96 100644 --- a/docs/codox/clj-activitypub.internal.http-util.html +++ b/docs/codox/clj-activitypub.internal.http-util.html @@ -1,3 +1,3 @@ -clj-activitypub.internal.http-util documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.http-util

TODO: write docs

date

(date)

TODO: write docs

view source

digest

(digest body)

Accepts body from HTTP request and generates string for use in HTTP Digest request header.

view source

encode-url-params

(encode-url-params params)

TODO: write docs

view source
\ No newline at end of file +clj-activitypub.internal.http-util documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.http-util

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

date

(date)

TODO: write docs

view source

digest

(digest body)

Accepts body from HTTP request and generates string for use in HTTP Digest request header.

view source

encode-url-params

(encode-url-params params)

TODO: write docs

view source
\ No newline at end of file diff --git a/docs/codox/clj-activitypub.internal.thread-cache.html b/docs/codox/clj-activitypub.internal.thread-cache.html index 627ef04..ad0a146 100644 --- a/docs/codox/clj-activitypub.internal.thread-cache.html +++ b/docs/codox/clj-activitypub.internal.thread-cache.html @@ -1,3 +1,3 @@ -clj-activitypub.internal.thread-cache documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.thread-cache

TODO: write docs

make

(make)(make cache-if-nil)

Creates a thread-local cache.

view source
\ No newline at end of file +clj-activitypub.internal.thread-cache documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.internal.thread-cache

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

make

(make)(make cache-if-nil)

Creates a thread-local cache.

view source
\ No newline at end of file diff --git a/docs/codox/clj-activitypub.webfinger.html b/docs/codox/clj-activitypub.webfinger.html index bebfcf9..68fb97c 100644 --- a/docs/codox/clj-activitypub.webfinger.html +++ b/docs/codox/clj-activitypub.webfinger.html @@ -1,3 +1,3 @@ -clj-activitypub.webfinger documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.webfinger

TODO: write docs

fetch-user-id

(fetch-user-id domain username)

Follows the webfinger request to a remote domain, retrieving the ID of the requested account. Typically returns a string in the form of a URL.

view source

remote-uri-path

TODO: write docs

view source

resource-url

(resource-url domain username & [params])

Builds a URL pointing to the user’s account on the remote server.

view source
\ No newline at end of file +clj-activitypub.webfinger documentation

Project

Topics

Namespaces

Public Vars

clj-activitypub.webfinger

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

fetch-user-id

(fetch-user-id domain username)

Follows the webfinger request to a remote domain, retrieving the ID of the requested account. Typically returns a string in the form of a URL.

view source

remote-uri-path

TODO: write docs

view source

resource-url

(resource-url domain username & [params])

Builds a URL pointing to the user’s account on the remote server.

view source
\ No newline at end of file diff --git a/docs/codox/dog-and-duck.quack.quack.html b/docs/codox/dog-and-duck.quack.quack.html index 3382dad..602dabd 100644 --- a/docs/codox/dog-and-duck.quack.quack.html +++ b/docs/codox/dog-and-duck.quack.quack.html @@ -1,14 +1,20 @@ -dog-and-duck.quack.quack documentation

Project

Topics

Namespaces

Public Vars

dog-and-duck.quack.quack

Validator for ActivityPub objects: if it walks like a duck, and it quacks like a duck…

activity?

(activity? x)

true iff x quacks like an activity, else false.

view source

activitystreams-context-uri

The URI of the context of an ActivityStreams object is expected to be this literal string.

view source

actor-type?

(actor-type? x)

TODO: write docs

view source

actor-types

The set of types we will accept as actors.

-

There’s an explicit set of allowed actor types.

view source

actor?

(actor? x)

Returns true if x quacks like an actor, else false.

view source

collection-page?

(collection-page? x)

true iff x quacks like a page in a paged collection, else false.

view source

collection?

(collection? x type)(collection? x)

true iff x quacks like a collection of type type, else false.

-

With one argument, will recognise plain collections and ordered collections, but (currently) not collection pages.

view source

context?

(context? x)

Returns true iff x quacks like an ActivityStreams context, else false.

+dog-and-duck.quack.quack documentation

Project

Topics

Namespaces

Public Vars

dog-and-duck.quack.quack

Validator for ActivityPub objects: if it walks like a duck, and it quacks like a duck…

activity?

(activity? x)

true iff x quacks like an activity, else false.

+

NOTE THAT Section 4.1 of the spec says explicitly that

+
+

Actor objects MUST have, in addition to the properties mandated by 3.1 Object Identifiers, the following properties:

+

inbox A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; see 5.2 Inbox. outbox An [ActivityStreams] OrderedCollection comprised of all the messages produced by the actor; see 5.1 Outbox.

+
+

However, none of the provided examples in the activitystreams-test-documents repository does in fact have these properties

view source

activitystreams-context-uri

The URI of the context of an ActivityStreams object is expected to be this literal string.

view source

actor-type?

(actor-type? x)

TODO: write docs

view source

actor-types

The set of types we will accept as actors.

+

There’s an explicit set of allowed actor types.

view source

actor?

(actor? x)

Returns true if x quacks like an actor, else false.

view source

collection-page?

(collection-page? x)

true iff x quacks like a page in a paged collection, else false.

view source

collection?

(collection? x type)(collection? x)

true iff x quacks like a collection of type type, else false.

+

With one argument, will recognise plain collections and ordered collections, but (currently) not collection pages.

view source

context?

(context? x)

Returns true iff x quacks like an ActivityStreams context, else false.

A context is either 1. the URI (actually an IRI) activitystreams-context-uri, or 2. a collection comprising that URI and a map.

view source

has-context?

macro

(has-context? x)

TODO: write docs

view source

link?

(link? x)

true iff x quacks like a link, else false.

view source

object?

(object? x)

Returns true iff x is recognisably an ActivityStreams object.

+

There are several points in the specification where e.g. the :image property (if present) may be either a link or a URI.

view source

link?

(link? x)

true iff x quacks like a link, else false.

view source

object?

(object? x)

Returns true iff x is recognisably an ActivityStreams object.

NOTE THAT The ActivityStreams spec says:

All properties are optional (including the id and type)

-

But we are just not having that, because otherwise we’re flying blind. We shall reject objects lacking at least :type. Missing :id keys are tolerable because they represent transient objects, which we expect to handle.

view source

ordered-collection-page?

(ordered-collection-page? x)

true iff x quacks like a page in an ordered paged collection, else false.

view source

ordered-collection?

(ordered-collection? x)

true iff x quacks like an ordered collection, else false.

view source

persistent-object?

(persistent-object? x)

true iff x is a persistent object.

-

Transient objects in ActivityPub are not required to have an id key, but persistent ones must have a key, and it must be an IRI (but normally a URI).

view source

unordered-collection?

(unordered-collection? x)

true iff x quacks like an unordered collection, else false.

view source

verb-type?

(verb-type? x)

TODO: write docs

view source

verb-types

The set of types we will accept as verbs.

+

But we are just not having that, because otherwise we’re flying blind. We shall reject objects lacking at least :type. Missing :id keys are tolerable because they represent transient objects, which we expect to handle.

view source

ordered-collection-page?

(ordered-collection-page? x)

true iff x quacks like a page in an ordered paged collection, else false.

view source

ordered-collection?

(ordered-collection? x)

true iff x quacks like an ordered collection, else false.

view source

persistent-object?

(persistent-object? x)

true iff x is a persistent object.

+

Transient objects in ActivityPub are not required to have an id key, but persistent ones must have a key, and it must be an IRI (but normally a URI).

view source

unordered-collection?

(unordered-collection? x)

true iff x quacks like an unordered collection, else false.

view source

verb-type?

(verb-type? x)

TODO: write docs

view source

verb-types

The set of types we will accept as verbs.

There’s an explicit set of allowed verb types.

view source
\ No newline at end of file diff --git a/docs/codox/index.html b/docs/codox/index.html index f194bc9..b31eb48 100644 --- a/docs/codox/index.html +++ b/docs/codox/index.html @@ -1,3 +1,3 @@ -Dog-and-duck 0.1.0-SNAPSHOT

Project

Topics

Namespaces

Dog-and-duck 0.1.0-SNAPSHOT

Released under the GPL-2.0-or-later

A Clojure library designed to implement the ActivityPub protocol.

Installation

To install, add the following dependency to your project or build file:

[dog-and-duck "0.1.0-SNAPSHOT"]

Topics

Namespaces

clj-activitypub.core

TODO: write docs

Public variables and functions:

clj-activitypub.internal.crypto

TODO: write docs

Public variables and functions:

clj-activitypub.internal.http-util

TODO: write docs

Public variables and functions:

clj-activitypub.internal.thread-cache

TODO: write docs

Public variables and functions:

clj-activitypub.webfinger

TODO: write docs

Public variables and functions:

dog-and-duck.quack.quack

Validator for ActivityPub objects: if it walks like a duck, and it quacks like a duck…

Public variables and functions:

dog-and-duck.scratch.core

TODO: write docs

Public variables and functions:

dog-and-duck.scratch.parser

TODO: write docs

Public variables and functions:

dog-and-duck.scratch.scratch

Scratchpad where I try to understand how to do this stuff.

Public variables and functions:

\ No newline at end of file +Dog-and-duck 0.1.0-SNAPSHOT

Project

Topics

Namespaces

Dog-and-duck 0.1.0-SNAPSHOT

Released under the GPL-2.0-or-later

A Clojure library designed to implement the ActivityPub protocol.

Installation

To install, add the following dependency to your project or build file:

[dog-and-duck "0.1.0-SNAPSHOT"]

Topics

Namespaces

clj-activitypub.core

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

Public variables and functions:

clj-activitypub.internal.crypto

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

Public variables and functions:

clj-activitypub.internal.http-util

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

Public variables and functions:

clj-activitypub.internal.thread-cache

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

Public variables and functions:

clj-activitypub.webfinger

copied from Jahfer’s clj-activitypub library. If and when Jahfer issues a release of that library, this directory will be deleted and a dependency on that library will be added to the project.

Public variables and functions:

dog-and-duck.quack.quack

Validator for ActivityPub objects: if it walks like a duck, and it quacks like a duck…

Public variables and functions:

dog-and-duck.scratch.core

TODO: write docs

Public variables and functions:

dog-and-duck.scratch.parser

TODO: write docs

Public variables and functions:

dog-and-duck.scratch.scratch

Scratchpad where I try to understand how to do this stuff.

Public variables and functions:

\ No newline at end of file diff --git a/src/clj_activitypub/core.clj b/src/clj_activitypub/core.clj index 9719bc0..9385002 100644 --- a/src/clj_activitypub/core.clj +++ b/src/clj_activitypub/core.clj @@ -1,4 +1,7 @@ (ns clj-activitypub.core + "copied from [Jahfer's clj-activitypub library](https://github.com/jahfer/clj-activitypub). + If and when Jahfer issues a release of that library, this directory will be deleted and a + dependency on that library will be added to the project." (:require [clj-activitypub.internal.crypto :as crypto] [clj-activitypub.internal.thread-cache :as thread-cache] [clj-activitypub.internal.http-util :as http] diff --git a/src/clj_activitypub/webfinger.clj b/src/clj_activitypub/webfinger.clj index 6173fb3..c9aa700 100644 --- a/src/clj_activitypub/webfinger.clj +++ b/src/clj_activitypub/webfinger.clj @@ -1,4 +1,7 @@ (ns clj-activitypub.webfinger + "copied from [Jahfer's clj-activitypub library](https://github.com/jahfer/clj-activitypub). + If and when Jahfer issues a release of that library, this directory will be deleted and a + dependency on that library will be added to the project." (:require [clj-http.client :as client] [clj-activitypub.internal.http-util :as http] [clj-activitypub.internal.thread-cache :as thread-cache])) diff --git a/src/dog_and_duck/quack/quack.clj b/src/dog_and_duck/quack/quack.clj index 7ba0ed6..ab3a432 100644 --- a/src/dog_and_duck/quack/quack.clj +++ b/src/dog_and_duck/quack/quack.clj @@ -112,7 +112,19 @@ true)) (defn activity? - "`true` iff `x` quacks like an activity, else false." + "`true` iff `x` quacks like an activity, else false. + + **NOTE THAT** [Section 4.1 of the spec] + (https://www.w3.org/TR/activitypub/#actor-objects) says explicitly that + + > Actor objects MUST have, in addition to the properties mandated by 3.1 Object Identifiers, the following properties: + > + > inbox + > A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; see 5.2 Inbox. + > outbox + > An [ActivityStreams] OrderedCollection comprised of all the messages produced by the actor; see 5.1 Outbox. + + However, none of the provided examples in the [activitystreams-test-documents repository]() does in fact have these properties" [x] (try (and (object? x) diff --git a/src/dog_and_duck/scratch/parser.clj b/src/dog_and_duck/scratch/parser.clj index 21cd197..81f2832 100644 --- a/src/dog_and_duck/scratch/parser.clj +++ b/src/dog_and_duck/scratch/parser.clj @@ -43,3 +43,5 @@ (count objects) (map :type objects)))) (file-seq (file "resources/activitystreams-test-documents"))) + +(-> "resources/activitystreams-test-documents/simple0020.json" slurp clean first :actor) \ No newline at end of file diff --git a/src/dog_and_duck/scratch/scratch.clj b/src/dog_and_duck/scratch/scratch.clj index f5fe9ae..f4319d1 100644 --- a/src/dog_and_duck/scratch/scratch.clj +++ b/src/dog_and_duck/scratch/scratch.clj @@ -57,4 +57,5 @@ private (-> kp .getPrivateKey .getPrivateKeyDataPacket .getEncoded)] (println (str "Public key: " public)) (println (str "Private key: " private)) - ) \ No newline at end of file + ) +