> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription

## Overview

Event subscription is a mechanism that allows clients to receive real-time updates from the server.
This is particularly useful for applications that require live data, such as chat applications, stock tickers,
or any other application where data changes frequently.

## Lifecycle

The following flow represents message exchanges between a client and a server during the subscription process.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Subscription Phase
    Client->>Server: "subscription/add" request
    activate Server
    Server-->>Client: "subscription/add" response
    deactivate Server

    Note over Client,Server: Operation Phase

    loop while subscribed
        Server->>Client: "subscription/event" message
    end

    Note over Client,Server: Cleanup Phase
    Client->>Server: "subscription/remove" request
    activate Server
    Server-->>Client: "subscription/remove" response
    deactivate Server
```

## Targets

The server can send events to the following targets (highlighted in bold):

```mermaid theme={null}
flowchart TB
    subgraph core[" "]
        c_scope@{ shape: notch-rect, label: "Core Primitives <br/> scope: core" }
        user[User \n target: user]
        org[Organization \n target: organization]
        blob[Blob \n target: blob]
        revision[Revision \n target: revision]
        c_scope -.-> user
        user --> org
        org --> blob
        blob --> revision
    end

    subgraph workflow[" "]
        wf_scope@{ shape: notch-rect, label: "Workflow Blob <br/> scope: revision" }
        session[**Session** \n target: session]
        execution[Execution \n target: execution]
        wf_scope -.-> session
        session --> execution
    end

    core --> workflow
```

## Reference

### Messages

#### `subscription/add` Message

Request to subscribe to a specific event type sent by a client.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscription/add",
  "params": {
    "scope": "revision",
    "scope_id": "0A06AB3A-DD72-4D42-939A-61DC4EF69418",
    "target": "session",
    "target_id": "28E70055-DBB4-4CA8-88BC-133D6CEA68E6",
    "types": [
      "execution_started",
      "execution_ended"
    ]
  }
}
```

Server is expected to respond with a confirmation message indicating success:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

Or an error message indicating failure:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 403,
    "message": "Access forbidden"
  }
}
```

#### `subscription/remove` Message

Request to unsubscribe from a specific event type sent by a client.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscription/remove",
  "params": {
    "scope": "revision",
    "scope_id": "0A06AB3A-DD72-4D42-939A-61DC4EF69418",
    "target": "session",
    "target_id": "28E70055-DBB4-4CA8-88BC-133D6CEA68E6",
    "types": [
      "execution_started",
      "execution_ended"
    ]
  }
}
```

Request processing confirmation is delivered back to the client.

#### `subscription/event` Message

Notification sent by the server to indicate that an event has occurred.

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "subscription/event",
  "params": {
    "scope": "revision",
    "scope_id": "0A06AB3A-DD72-4D42-939A-61DC4EF69418",
    "target": "session",
    "target_id": "28E70055-DBB4-4CA8-88BC-133D6CEA68E6",
    "type": "execution_started",
    "execution": {
      "id": "452CDAC7-2ED0-4D24-8436-C6D45B34B331"
    }
  }
}
```

### Events

#### Workflow Blob - `session` Target

<CodeGroup>
  ```json Event Envelope theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      "scope": "revision",
      "scope_id": string,
      "target": "session",
      "target_id": string,
      "type": string,
      ...
      }
    }
  }
  ```

  ```json execution_started theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      ...
      "type": "execution_started",
      "execution": {
        "id": string
      }
    }
  }
  ```

  ```json execution_ended theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      ...
      "type": "execution_ended",
      "execution": {
        "id": string,
        "status": "completed" | "failed"
      }
    }
  }
  ```

  ```json session_object_modified theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      ...
      "type": "session_object_modified",
      "session_object": {
        "alias": string
      }
    }
  }
  ```

  ```json session_object_deleted theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      ...
      "type": "session_object_deleted",
      "session_object": {
        "alias": string
      }
    }
  }
  ```

  ```json session_thread_item_posted theme={null}
  {
    "jsonrpc": "2.0",
    "method": "subscription/event",
    "params": {
      ...
      "type": "session_thread_item_posted",
      "session_object": {
        "alias": string,
        "item_id": string
      }
    }
  }
  ```
</CodeGroup>