Action Delivery

How actions are distributed and received across the federated Cloudillo network.

Outbound Actions

When a user creates an action, it is delivered to the relevant recipients. The set of recipients is derived from the action’s audience and type by the action DSL (the subject-keyed outbox/relay rules), broadly:

  • Broadcast actions (e.g. POST) → the issuer’s followers
  • Replies (e.g. CMNT, REACT) → the owner of the parent action
  • Relationship actions (e.g. CONN, FLLW) → the target named in the audience
  • Conversation messages (MSG) → fanned out to subscribers (see Trust & Distribution)

Each recipient gets one ActionDeliveryTask, which POSTs the action token to that instance’s inbox as {"token": "..."}. Delivery is per-recipient and retried independently, so one unreachable instance does not block the others.

Inbound Actions

Cloudillo provides two endpoints for receiving federated actions, optimized for different use cases.

Async Inbox (POST /api/inbox)

The standard endpoint for most federated actions. The payload is self-authenticating (the action token carries its own signature), so no bearer auth is required. The handler hashes the token into an action ID, queues an ActionVerifierTask on the scheduler, and returns 201 Created immediately. Verification, permission checks, and storage happen asynchronously, which keeps the sender from timing out on slow verification (e.g. while fetching keys or attachments).

If the token is a CONN action, the handler first checks a proof-of-work challenge tied to the sender’s IP; missing or invalid PoW is rejected with 428 Precondition Required. This throttles unsolicited connection requests.

Sync Inbox (POST /api/inbox/sync)

A synchronous variant for actions that need an immediate result rather than a queued ack. It runs the same verification and processing inline and returns the hook’s result in the response body. The same PoW check applies to CONN actions.

Used mainly for identity registration (IDP:REG) and other handshakes where the sender needs the outcome before continuing.

Delivery Guarantees

Delivery is handled by the task scheduler, which persists tasks so they survive server restarts and retries failures automatically.

Retry Policy

The default policy uses true exponential backoff: the delay doubles each attempt, starting at 60 seconds and capped at 1 hour, for up to 10 attempts.

backoff(n) = min(60s × 2ⁿ, 1 hour)

Attempt 1 fails → wait 60s
Attempt 2 fails → wait 120s
Attempt 3 fails → wait 240s
...doubling each time...
→ wait capped at 1 hour for later attempts

A successful POST (2xx) completes the task; any error returns failure and lets the scheduler reschedule with the next backoff until the attempt limit is reached. Delivery tasks are keyed per (action_id, recipient), so a re-queued action is not delivered twice.

Related Actions & Fan-out

Some deliveries carry more than one token. When an action is approved or invites a user, the original/context token is bundled alongside it in a related array so the recipient gets everything in one round trip. The inbox payload becomes {"token": "...", "related": ["..."]}, and conversation messages fan out to all subscribers. This is covered in detail under Trust & Distribution.

See Also