# at.adsb.sync.subscribeEvents

> Published by [adsb.at](https://lexicon.garden/identity/did:plc:32thk4eifx4ou6mxevswgjhg)

✓ This is the authoritative definition for this NSID.

## Description

Unified relay output stream aggregating aircraft telemetry from multiple at-adsb receiver stations. Re-sequences all station telemetry under a single monotonic cursor with backfill support.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:32thk4eifx4ou6mxevswgjhg/at.adsb.sync.subscribeEvents)
- [Documentation](https://lexicon.garden/lexicon/did:plc:32thk4eifx4ou6mxevswgjhg/at.adsb.sync.subscribeEvents/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:32thk4eifx4ou6mxevswgjhg/at.adsb.sync.subscribeEvents/examples)

## Definitions

### `at.adsb.sync.subscribeEvents#info`

**Type**: `object`

Control frame generated by the relay (e.g., OutdatedCursor). Upstream #info frames are not relayed.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | `string` | Yes | Operational info message name. |
| `message` | `string` | No | Human-readable info message. |

### `at.adsb.sync.subscribeEvents`

**Type**: `subscription`

Subscribe to relayed events from all stations tracked by this relay.

```json
{
  "type": "subscription",
  "errors": [
    {
      "name": "FutureCursor",
      "description": "The requested cursor is in the future (beyond the relay's current head sequence)."
    },
    {
      "name": "ConsumerTooSlow",
      "description": "The consumer's read rate is too far behind the relay's write rate. The connection has been dropped."
    }
  ],
  "message": {
    "schema": {
      "refs": [
        "#event",
        "#station",
        "#info"
      ],
      "type": "union"
    }
  },
  "parameters": {
    "type": "params",
    "properties": {
      "cursor": {
        "type": "integer",
        "description": "The last sequence number previously received. If provided, the stream will backfill from that point."
      }
    }
  },
  "description": "Subscribe to relayed events from all stations tracked by this relay."
}
```

### `at.adsb.sync.subscribeEvents#event`

**Type**: `object`

A relayed batch of operations from a single station's poll cycle.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ops` | `array` | Yes | List of operations in this batch, passed through from upstream. |
| `seq` | `integer` | Yes | The relay-minted monotonic sequence number of this message. |
| `sig` | `bytes` | No | Pass-through signature from the upstream station. This signature was computed by the station over the DAG-CBOR encoding of the upstream event body {$type: 'at.adsb.broadcast.subscribeEvents#event', seq, station, time, ops} (where seq is the station's original sequence, present here as upstreamSeq). To verify, reconstruct the upstream body by mapping upstreamSeq back to seq and including $type: 'at.adsb.broadcast.subscribeEvents#event' (dropping src), then check the signature against the station's published streamSigningKey. The signature does NOT verify against this sync frame body. |
| `src` | `string` (did) | Yes | The DID of the originating station. |
| `time` | `string` (datetime) | Yes | Timestamp from the upstream station's poll cycle. |
| `station` | `ref` → `com.atproto.repo.strongRef` | Yes | Strong reference to the emitting station's at.adsb.receiver.station record. |
| `upstreamSeq` | `integer` | Yes | The station's original sequence number from the upstream broadcast stream. Note: station seq resets on process restart; consumers should detect regression. |

### `at.adsb.sync.subscribeEvents#station`

**Type**: `object`

A station registry change observed by the relay via the AT Protocol firehose.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `op` | `string` | Yes | The type of registry change. |
| `seq` | `integer` | Yes | The relay-minted monotonic sequence number of this message. |
| `src` | `string` (did) | Yes | The DID of the station whose record changed. |
| `time` | `string` (datetime) | Yes | Timestamp of when the relay observed the firehose event. |
| `record` | `unknown` | No | The full station record. Present for create and update ops; absent for delete ops. When present, shape matches at.adsb.receiver.station record definition. |

### `at.adsb.sync.subscribeEvents#broadcastOp`

**Type**: `object`

A single operation within a relayed event. This definition MUST track at.adsb.broadcast.subscribeEvents#broadcastOp — if the upstream broadcast lexicon changes this shape, update this definition to match.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `action` | `string` | Yes | The type of operation. |
| `record` | `unknown` | Yes | The record payload. Shape determined by the record's $type field. |

## Raw Schema

```json
{
  "id": "at.adsb.sync.subscribeEvents",
  "defs": {
    "info": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64,
          "description": "Operational info message name.",
          "knownValues": [
            "OutdatedCursor"
          ]
        },
        "message": {
          "type": "string",
          "maxLength": 1024,
          "description": "Human-readable info message."
        }
      },
      "description": "Control frame generated by the relay (e.g., OutdatedCursor). Upstream #info frames are not relayed."
    },
    "main": {
      "type": "subscription",
      "errors": [
        {
          "name": "FutureCursor",
          "description": "The requested cursor is in the future (beyond the relay's current head sequence)."
        },
        {
          "name": "ConsumerTooSlow",
          "description": "The consumer's read rate is too far behind the relay's write rate. The connection has been dropped."
        }
      ],
      "message": {
        "schema": {
          "refs": [
            "#event",
            "#station",
            "#info"
          ],
          "type": "union"
        }
      },
      "parameters": {
        "type": "params",
        "properties": {
          "cursor": {
            "type": "integer",
            "description": "The last sequence number previously received. If provided, the stream will backfill from that point."
          }
        }
      },
      "description": "Subscribe to relayed events from all stations tracked by this relay."
    },
    "event": {
      "type": "object",
      "required": [
        "seq",
        "src",
        "upstreamSeq",
        "station",
        "time",
        "ops"
      ],
      "properties": {
        "ops": {
          "type": "array",
          "items": {
            "ref": "#broadcastOp",
            "type": "ref"
          },
          "description": "List of operations in this batch, passed through from upstream."
        },
        "seq": {
          "type": "integer",
          "description": "The relay-minted monotonic sequence number of this message."
        },
        "sig": {
          "type": "bytes",
          "description": "Pass-through signature from the upstream station. This signature was computed by the station over the DAG-CBOR encoding of the upstream event body {$type: 'at.adsb.broadcast.subscribeEvents#event', seq, station, time, ops} (where seq is the station's original sequence, present here as upstreamSeq). To verify, reconstruct the upstream body by mapping upstreamSeq back to seq and including $type: 'at.adsb.broadcast.subscribeEvents#event' (dropping src), then check the signature against the station's published streamSigningKey. The signature does NOT verify against this sync frame body."
        },
        "src": {
          "type": "string",
          "format": "did",
          "description": "The DID of the originating station."
        },
        "time": {
          "type": "string",
          "format": "datetime",
          "description": "Timestamp from the upstream station's poll cycle."
        },
        "station": {
          "ref": "com.atproto.repo.strongRef",
          "type": "ref",
          "description": "Strong reference to the emitting station's at.adsb.receiver.station record."
        },
        "upstreamSeq": {
          "type": "integer",
          "description": "The station's original sequence number from the upstream broadcast stream. Note: station seq resets on process restart; consumers should detect regression."
        }
      },
      "description": "A relayed batch of operations from a single station's poll cycle."
    },
    "station": {
      "type": "object",
      "required": [
        "seq",
        "src",
        "op",
        "time"
      ],
      "properties": {
        "op": {
          "type": "string",
          "maxLength": 16,
          "description": "The type of registry change.",
          "knownValues": [
            "create",
            "update",
            "delete"
          ]
        },
        "seq": {
          "type": "integer",
          "description": "The relay-minted monotonic sequence number of this message."
        },
        "src": {
          "type": "string",
          "format": "did",
          "description": "The DID of the station whose record changed."
        },
        "time": {
          "type": "string",
          "format": "datetime",
          "description": "Timestamp of when the relay observed the firehose event."
        },
        "record": {
          "type": "unknown",
          "description": "The full station record. Present for create and update ops; absent for delete ops. When present, shape matches at.adsb.receiver.station record definition."
        }
      },
      "description": "A station registry change observed by the relay via the AT Protocol firehose."
    },
    "broadcastOp": {
      "type": "object",
      "required": [
        "action",
        "record"
      ],
      "properties": {
        "action": {
          "type": "string",
          "maxLength": 16,
          "description": "The type of operation.",
          "knownValues": [
            "create",
            "update",
            "delete"
          ]
        },
        "record": {
          "type": "unknown",
          "description": "The record payload. Shape determined by the record's $type field."
        }
      },
      "description": "A single operation within a relayed event. This definition MUST track at.adsb.broadcast.subscribeEvents#broadcastOp — if the upstream broadcast lexicon changes this shape, update this definition to match."
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "Unified relay output stream aggregating aircraft telemetry from multiple at-adsb receiver stations. Re-sequences all station telemetry under a single monotonic cursor with backfill support."
}
```