## Generated by Codox

# Dog-and-duck 0.1.0-SNAPSHOT

# Using ActivityPub

## 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.

## What happens when you post a new item to an ActivityPub server

Your client issues a POST request to your outbox URI, with the object you’re posting as payload. It should be wrapped in a `Create` activity, but the spec makes clear that:

> The server MUST accept a valid [ActivityStreams] object that isn’t a subtype of Activity in the POST request to the outbox

If no `Create` wrapper is present, the server creates one before further processing the request.

The `Create` wrapper, or, if that is missing, the object itself, may have properties `to`, `bto`, `cc`, `bcc`, and `audience`.

The `to`, `bto`, `cc`, and `bcc` properties are all expected to be either URIs of actors, or URIs of collections of actors. The behaviour of your local ActivityPub server in response to these properties is similar: it sends a POST request to the `inbox` URI associated with each actor URI.

There’s one ‘magic’ URI, "https://www.w3.org/ns/activitystreams#Public". If this is specified in any of the above fields (including `audience`), then the wrapped object is sent to the outboxes of each actor on your `followers` list; but also, it is recognised by other ActivityPub servers as a public post, and will thus appear in their ‘Federated’ feed as well as in the individual feeds your followers and of people directly addressed.

### Things I don’t yet understand about Create

1. Is the entire new object transmitted in the Create transmission to each addressee, or only its (URI) `id` value?
2. What happens if an addressee’s home server is down at the time the object is posted? Is it queued for them and subsequently retried until it is delivered, or is it dropped?
3. When multiple actors on one host server are addressed in a Create request, is the `inbox` URI for each actor individually posted to, or is there one ‘postmaster’ endpoint on the server which can be addressed, from which the post can then be distributed to the particular actors’ inboxes?
4. What is the response your local server makes to your client? Does it contain the `id` of the object created, or is that `id` generated by the client in the first place?
5. If an item doesn’t have the magic public URL among its addressees, is an attempt to GET that item checked for whether the originator of the request is one of the explicit addressees? Or is such a request simply refused 401 `not authorised`?

Obviously if the outbox being posted to is not the outbox of the duly authenticated and authorised logged in user, the attempt to post to an outbox must fail with a 401 `not authorised` response.

## What happens when you post an Update activity regarding an existing item

Your client issues a POST request to your outbox URI, with the `Update` activity object as payload. The Update activity will have in its `object` field a partially specified copy of the object to be updated, containing only the `id` value and the values of those fields to be changed. Your local server will update its stored representation of the object.

I am not clear whether it will retransmit the Update to users addressed in the Create object. I see messages of the form ‘[user] edited a post’ in my Notifications feed on Mastodon, so it seems so.

## What happens when you post a Delete activity regarding an existing item

Your client issues a POST request to your outbox URI, with the `Delete` activity object as payload. The Delete activity object has in its `object` value (probably?) only the `id` value of the object to be deleted, or, at most, a `Link` object having that has that `id` value as its `href` value.

The Delete object is NOT retransmitted to the addressees of the original create request. Instead, your server will either:

1. Return a 404 reponse to all subsequent requests for the object, or
2. Return a 410 ‘Gone’ response, having as payload a `Tombstone` object.

### The Tombstone object

The Tombstone object is a means of acknowledging that the requested object did once exist. It is an ActivityStreams object with the same `id` value as the original (deleted) object,the `type` value `Tombstone`, and the following fields: `published`, `deleted`, and (presumably optionally) `updated`. The values of these fields are timestamps (? or in the case of `updated`, perhaps lists of timestamps?)

## What I don’t yet understand about this whole lifecycle

If we’re pushing entire objects – which may include media attachments – to the inboxes of many recipients who may never choose to read them, that feels like a lot of wasted bandwidth. However, if we’re pushing only ids or links of posts which are not public, that feels like a major security headache in verifying that the requestors are indeed verified recipients.

Again, the fact that Mastodon is able to show me ‘[user] edited a post’ items in my notifications seems to imply that updates of the complete edited object are being pushed out to all recipients’ inboxes, and again that seems expensive.