docs/reference/subscriptions.md at validation · byjp.me/quickslice

byjp.me / quickslice
Auto-indexing service and GraphQL API for AT Protocol Records
quickslice / docs / reference / subscriptions.md
at validation 181 lines 2.6 kB view raw view rendered
  1# Subscriptions
  2
  3Subscriptions deliver real-time updates when records are created, updated, or deleted. The server pushes events over WebSocket instead of requiring polling.
  4
  5Connect to `/graphql` using the [`graphql-ws`](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) protocol.
  6
  7## Basic Subscription
  8
  9```graphql
 10subscription {
 11  xyzStatusphereStatusCreated {
 12    uri
 13    status
 14    createdAt
 15  }
 16}
 17```
 18
 19## Field Selection
 20
 21Request only the fields you need:
 22
 23```graphql
 24subscription {
 25  xyzStatusphereStatusCreated {
 26    status
 27  }
 28}
 29```
 30
 31Response:
 32
 33```json
 34{
 35  "data": {
 36    "xyzStatusphereStatusCreated": {
 37      "status": "🚀"
 38    }
 39  }
 40}
 41```
 42
 43## Named Subscription
 44
 45```graphql
 46subscription OnNewStatus {
 47  xyzStatusphereStatusCreated {
 48    uri
 49    status
 50    actorHandle
 51  }
 52}
 53```
 54
 55## Subscription Types
 56
 57Each collection has three subscription fields:
 58
 59- `{collection}Created` - Fires when a new record is created
 60- `{collection}Updated` - Fires when a record is updated
 61- `{collection}Deleted` - Fires when a record is deleted
 62
 63### Examples
 64
 65```graphql
 66# New status created
 67subscription {
 68  xyzStatusphereStatusCreated {
 69    uri
 70    status
 71  }
 72}
 73
 74# Status updated
 75subscription {
 76  xyzStatusphereStatusUpdated {
 77    uri
 78    status
 79  }
 80}
 81
 82# Status deleted
 83subscription {
 84  xyzStatusphereStatusDeleted {
 85    uri
 86  }
 87}
 88```
 89
 90## With Joins
 91
 92Subscriptions support joins like queries:
 93
 94```graphql
 95subscription {
 96  xyzStatusphereStatusCreated {
 97    uri
 98    status
 99    appBskyActorProfileByDid {
100      displayName
101      avatar {
102        url
103      }
104    }
105  }
106}
107```
108
109Response:
110
111```json
112{
113  "data": {
114    "xyzStatusphereStatusCreated": {
115      "uri": "at://did:plc:abc123/xyz.statusphere.status/3m4vk4wi",
116      "status": "🎉 Just shipped!",
117      "appBskyActorProfileByDid": {
118        "displayName": "Alice",
119        "avatar": {
120          "url": "https://cdn.bsky.app/img/avatar/plain/did:plc:abc123/bafyrei..."
121        }
122      }
123    }
124  }
125}
126```
127
128## WebSocket Protocol
129
130### 1. Connect
131
132```
133ws://localhost:8080/graphql          # Local development
134wss://quickslice.example.com/graphql  # Production
135```
136
137### 2. Initialize
138
139```json
140{
141  "type": "connection_init"
142}
143```
144
145### 3. Subscribe
146
147```json
148{
149  "id": "1",
150  "type": "subscribe",
151  "payload": {
152    "query": "subscription { xyzStatusphereStatusCreated { uri status } }"
153  }
154}
155```
156
157### 4. Receive Events
158
159```json
160{
161  "id": "1",
162  "type": "next",
163  "payload": {
164    "data": {
165      "xyzStatusphereStatusCreated": {
166        "uri": "at://...",
167        "status": "Hello!"
168      }
169    }
170  }
171}
172```
173
174### 5. Unsubscribe
175
176```json
177{
178  "id": "1",
179  "type": "complete"
180}
181```