Presence Token

This token represents an ephemeral presence indication, such as typing status or online presence. Unlike other action types, presence tokens are NOT persisted to the database - they are only forwarded via WebSocket in real-time.

The presence token must contain a subject (sub) field referencing the context (e.g., a conversation). For other constraints see the Action Tokens.

Ephemeral Nature

IMPORTANT: PRES tokens are fundamentally different from other action types:

• NOT persisted: Not stored in the database
• NOT content-addressed: No action_id is generated
• Real-time only: Forwarded via WebSocket immediately
• Short TTL: Default time-to-live of 30 seconds
• No delivery tasks: No scheduling or retry logic

This makes PRES tokens ideal for real-time status updates that don’t need to be permanent.

Purpose

PRES tokens serve several important purposes:

1. Typing Indicators: Show when someone is typing in a conversation
2. Online Status: Indicate when users are online/active
3. Activity Updates: Real-time presence in collaborative contexts
4. Low-Overhead Updates: Frequent status changes without database writes

Fields

Subtypes

Additional subtypes can be defined for application-specific presence states.

Subject Reference

The sub (subject) field specifies the context for the presence update:

• For typing indicators: the CONV action_id
• For online status: could be a user’s profile context
• Creates a scoped presence update

Why Subject Instead of Parent:

• PRES doesn’t create hierarchy (unlike comments)
• It’s contextual - “presence in this context”
• Non-hierarchical reference semantics

Processing Flow

User starts typing
         │
         ▼
┌─────────────────────────────┐
│ Create PRES:TYPING token    │
│ - sub = CONV action_id      │
│ - aud = (optional recipient)│
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ Check: Is ephemeral?        │
│ - Yes! (PRES is ephemeral)  │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ Forward to WebSocket        │
│ - No database storage       │
│ - No action_id generated    │
│ - No delivery tasks         │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ Deliver to audience         │
│ - If aud set: single user   │
│ - If not: context subscribers│
└─────────────────────────────┘

Federation Flow

Local Presence (Same Instance)

User starts typing
         │
         ▼
┌─────────────────────────────┐
│ WebSocket message           │
│ - Signed PRES token         │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ Broadcast to CONV           │
│ subscribers on same instance│
└─────────────────────────────┘

Remote Presence (Cross-Instance)

User starts typing (instance A)
         │
         ▼
┌─────────────────────────────┐
│ Forward to CONV owner       │
│ (instance B)                │
└───────────┬─────────────────┘
            │
            ▼ (HTTP POST to /inbox)
┌─────────────────────────────┐
│ Instance B receives PRES    │
│ - Verifies signature        │
│ - Does NOT store            │
│ - Forwards to WebSocket     │
└───────────┬─────────────────┘
            │
            ▼
┌─────────────────────────────┐
│ Broadcast to other          │
│ subscribers on instance B   │
└─────────────────────────────┘

Time-To-Live (TTL)

PRES tokens have an implicit TTL:

• Default: 30 seconds
• After TTL expires, presence is considered stale
• Clients should send periodic updates to maintain presence
• No explicit expiration in the token (handled by clients)

Typing indicator flow:

1. User starts typing → PRES:TYPING sent
2. User continues typing → Periodic PRES:TYPING (e.g., every 5s)
3. User stops typing → No more updates
4. After 30s → Recipients consider typing stopped

Example

User @alice.cloudillo.net is typing in a conversation:

Properties:

• No action_id generated (ephemeral)
• Not stored in database
• Forwarded immediately via WebSocket
• Recipients see “Alice is typing…”
• After 30s without update, typing indicator disappears

Security Considerations

Since PRES tokens are ephemeral:

• Still require valid signature verification
• Rate limiting applies to prevent spam
• Context (subject) must be valid
• User must have access to the context

Comparison with Persistent Actions

See Also

• Conversation Token - Context for typing indicators
• WebSocket API - Real-time message delivery
• Federation Architecture - How ephemeral actions are forwarded