fep

FEP-ae49: Semantic Routing for ActivityPub

Summary

This proposal specifies semantic request routing for ActivityPub servers: an approach to dispatching incoming activities by following the relationships declared within ActivityStreams objects and dereferencing objects using opaque URIs rather than parsing or pattern-matching URL path segments. Semantic routing treats all ActivityPub URIs as opaque identifiers and decouples implementation behavior from any particular URI path structure.

Most existing servers implement “path-based routing,” where the handler and target actor are determined from path segments such as /users/:username/inbox. This tight coupling makes it hard to migrate between software implementations without breaking URIs and violates the URI Opacity Axiom, since semantics are inferred from paths that are implementation-dependent.

Semantic routing instead relies on dereferencing ActivityStreams objects and using relationships to identify and validate inbox and outbox endpoints. This allows URIs to remain stable across implementations, simplifying migration scenarios where the domain does not change.

Motivation

ActivityPub federation works by looking up the target actor’s inbox and POSTing activities to it. The Social API works by POSTing activities to an actor’s outbox. ActivityPub documents are dereferenced (GET) using their id (URI).

Most ActivityPub servers route these requests based on a predefined URI path structure. This path-based approach has several drawbacks.

By shifting routing decisions from URI path analysis to graph traversal over ActivityStreams objects, semantic routing eliminates these problems and allows implementations to support flexible URI layouts.

Scope

This proposal:

The proposal does not modify ActivityPub or ActivityStreams. It adds constraints on implementation strategy while leaving the wire protocol unchanged.

This specification constrains only top-level request handling:

A POST to other URIs can use similar techniques, but since ActivityPub doesn’t define these kinds of posts, it is outside the scope of this document.

Internal subhandler selection (for example, by activity type, recipient conditions, or local policy checks) is an implementation detail and is out of scope as long as it is not dependent on a specific URI structure.

Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

path-based routing
A request dispatch strategy in which an HTTP server parses the URI path of an incoming request and matches path segments against a static or parameterized route table to determine the handler responsible for the request. In the ActivityPub context, this typically means extracting an actor identifier (such as a username) from the path and using it to look up the corresponding actor record in a local database, without first dereferencing the request URURIL as an ActivityStreams object.
semantic routing
A request dispatch strategy for ActivityPub servers in which the server processes a request based on the target URI rather than pattern matching on URI path segments. The dispatch uses ActivityPub objects and their relationships to determine how to process the request.
resource
An ActivityStreams object retrieved by dereferencing a resource URI.
opaque URI
A URI whose path, query, and fragment components carry no meaning to recipients beyond what is logically needed to dereference the URI or process POST requests to it RFC3986.
top-level handler
One of the three request classes in scope for this specification: inbox POST, outbox POST, or object dereference GET.

Conformance

This specification defines requirements for one conformance class:

Semantically Routing Server
An ActivityPub server (federated server or combined server) that dispatches incoming HTTP requests exclusively through semantic routing as defined in this document.

All of Section requirements are normative. All examples, notes, and sections explicitly labelled “non-normative” are informative.

Note: Implementations that satisfy the requirements in this document remain fully conformant with ActivityPub. The requirements here constrain how routing is performed, not what is placed on the wire.

Path-Based Routing: Characteristics and Problems

How Path-Based Routing Works

In a typical fediverse server using path-based routing, a web framework (such as Rails, Django, Express, or Flask) is configured with a route table mapping URI path patterns to controller functions. When an ActivityPub activity arrives addressed to a local actor, the server:

  1. Receives an HTTP POST to a URI such as https://social.example/users/alice/inbox.
  2. Matches the path /users/alice/inbox against the route pattern /users/:username/inbox.
  3. Extracts the string alice as the username.
  4. Looks up actor alice in the local database.
  5. Passes the request body to the inbox handler with alice’s database record.

A representative path-based route table from a pseudocode web framework:

POST /users/:username/inbox          → inbox_controller(username)
GET  /users/:username/outbox         → outbox_controller(username)
GET  /users/:username                → actor_controller(username)
GET  /users/:username/followers      → followers_controller(username)
GET  /users/:username/following      → following_controller(username)

The critical characteristic is that the username portion of the path is authoritative for dispatch.

Problems Introduced by Path-Based Routing

URI Lock-In and Migration Failure

Because the routing table defines the valid URI patterns for actor endpoints, changing software means either:

Neither option is satisfactory. The ActivityPub specification provides no URI migration mechanism precisely because URIs are supposed to be stable, opaque identifiers.

Example: migration failure with path-based request routing:

A community server running SoftwareA uses actor URIs of the form https://community.example/users/alice, with inbox at /users/alice/inbox.

The community migrates to SoftwareB, which uses actor URIs of the form https://community.example/alice, with inbox at /inboxes/alice.

All existing actor URIs are now invalid. Remote servers that delivered activities to /users/alice/inbox receive HTTP 404 responses. The actor’s followers on remote servers reference the old actor id, which no longer resolves.

If both SoftwareA and SoftwareB implemented semantic request routing, the migration would be a simple transfer of content with not changes to URIs.

Requirements for Semantic Routing

URI Opacity

URI opacity is the foundation of semantic routing. Routing decisions MUST NOT depend on the syntactic structure of a URI’s path, query, or fragment components.

A Semantically Routing Server MUST NOT parse the path, query string, or fragment of an incoming request URI to determine the identity of the target actor or the type of endpoint being accessed (inbox, outbox, etc.).

HTTP Request Handling

When a Semantically Routing Server receives an HTTP request, it MUST NOT depend on the syntactic structure of a URI’s path, query, or fragment components to handle it.

Semantic Routing Algorithms

This section is non-normative.

Although it may be possible to implement semantic routing using other algorithms, this section shows pseudo-code for a possible implementation. This proposal does not include details like authorization or other security considerations that are not uniquely related to semantic request routing.

HTTP GET

HTTP POST

Example:

POST /x/9f3c1 HTTP/1.1
Host: social.example
Content-Type: application/activity+json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://remote.example/activities/abcd",
  "type": "Follow",
  "actor": "https://remote.example/users/bob",
  "object": "https://social.example/actors/alice"
}

Where https://social.example/x/9f3c1 is an opaque URI that happens to be Alice’s inbox, the server can process the request semantically as follows:

  1. Treat the request target URI as an opaque identifier and do not parse path segments.
  2. Dereference https://social.example/x/9f3c1 to obtain the local inbox resource.
  3. Identify the owning actor by reading resource relations (for example, attributedTo), or by resolving reverse links from actor resources that reference this inbox.
  4. Confirm the resolved actor document contains an inbox equal to https://social.example/x/9f3c1.
  5. Dispatch to the inbox handler for that actor and continue normal ActivityPub processing of the posted activity (type: Follow, authorization checks, policy checks, delivery side-effects, and response status).

This algorithm works regardless of whether the inbox URI looks like /users/alice/inbox, /inbox/42, or /x/9f3c1.

The same procedure is used for POST requests to outbox URIs.

Shared Inbox

For sharedInbox POST, the algorithm is similar but applied to each local inbox URI targeted for delivery.

For sharedInbox GET, the opaque URI is used to identify the request target. The dereferencing or construction of the resulting OrderedCollection is implementation-dependent.

Security Considerations

TODO

Solid

This section is non-normative.

The Solid Protocol similarly treats resource URIs as opaque and uses link relations to discover associated resources. Solid’s approach to data pods, where access control and resource discovery are driven by linked metadata rather than URI structure parallels the motivation for semantic routing in ActivityPub.

Implementations

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.