Subscription Token

This token represents a subscription to a subscribable action, such as a conversation (CONV). Subscriptions control who receives messages and updates from group activities.

The subscription token must contain both a subject (sub) field referencing the subscribable action and an audience (aud) field specifying the owner of that action. For other constraints see the Action Tokens. Like every action token it is content-addressed — see Content Addressing.

Purpose

A SUBS token records that one profile is a participant in one subscribable action: it is the membership list, the delivery list and the role assignment all at once, and creating or deleting it is how a user joins or leaves.

Required Fields

Subtypes

Content Structure

The optional content (c) field contains subscription metadata:

{
  "role": "member",
  "invitedBy": "alice.cloudillo.net",
  "message": "Joining the team discussion"
}

Database Key

The database key for a subscription token is {type}:{sub}:{iss}

This ensures only one active subscription per user per subject — see Database Keys. Example: SUBS:a1~conv123:alice.example.com.

Auto-Accept Logic

When a SUBS token is received, on_receive (crates/cloudillo-action/src/native_hooks/subs.rs:59) walks a fixed decision tree. The first branch that matches wins.

flowchart TD
    S[SUBS received] --> O{"Target has the 'O' (open) flag?"}
    O -- yes --> A["Accept, status 'A'"]
    O -- no --> I{"Invitation on record for this issuer?"}
    I -- yes --> A
    I -- no --> C{"Issuer is the target action's creator?"}
    C -- yes --> A
    C -- no --> P{"Arrived pre-approved (bundled under an owner APRV)?"}
    P -- yes --> A
    P -- no --> R["Reject, status 'D'"]

The pre-approved branch (subs.rs:117-124) is what lets a member node accept a subscription belonging to somebody it has never met. When a container owner vouches for an accepted child, the child travels bundled under the owner’s APRV as its related token; the receiving node has no local invitation and the issuer is not the creator, but the owner’s approval already answers the question. See Related Action Bundling and the worked example in Walkthrough — A Conversation in a Community.

Accepting also retires any outstanding invitation for that subject, so a consumed invitation no longer counts as pending. If no branch matches, the subscription rests at status 'D'.

Participant Roles

Each role is a superset of the one below it. Default role is member.

Federation Flow

Subscribing to a Conversation

User creates SUBS token
         │
         ▼
┌─────────────────────────────┐
│ Local processing            │
│ - Validate subject exists   │
│ - Check for INVT or 'O'     │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ schedule_delivery()         │
│ - Send to subject owner     │
└───────────┬─────────────────┘
            │
            ▼
    Owner receives SUBS
         │
         ▼
┌─────────────────────────────┐
│ on_receive hook             │
│ - Check auto-accept logic   │
│ - Accept or reject          │
│ - Update subscription list  │
└─────────────────────────────┘

Message Fan-Out and Leaving

Once subscribed, messages are delivered via schedule_subscriber_fanout() which walks the parent chain to the CONV and delivers to all subscribers. See Subscriber Fan-Out for details.

To leave, the user creates a SUBS:DEL token. The subject owner marks the subscription as deleted and removes the user from the subscriber list.

Example

User @bob.cloudillo.net subscribes to a conversation owned by @alice.cloudillo.net:

Status Values

See Also

• Walkthrough — A Conversation in a Community - SUBS in a full federated story
• Conversation Token - Subscribable group conversations
• Invitation Token - Inviting users to subscribe
• Message Token - Messages delivered to subscribers
• Federation Architecture - How messages are distributed to subscribers