@open-pencil/cloud 0.0.0-stage → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (279) hide show
  1. package/LICENSE +202 -0
  2. package/LICENSE-MIT +21 -0
  3. package/NOTICE +7 -0
  4. package/README.md +37 -2
  5. package/dist/bin/ai-relay.d.mts +1 -0
  6. package/dist/bin/ai-relay.mjs +31 -0
  7. package/dist/bin/ai-relay.mjs.map +1 -0
  8. package/dist/bin/server.d.mts +1 -0
  9. package/dist/bin/server.mjs +29 -0
  10. package/dist/bin/server.mjs.map +1 -0
  11. package/dist/client.d.ts +1520 -0
  12. package/dist/client.d.ts.map +1 -0
  13. package/dist/client.js +1917 -0
  14. package/dist/client.js.map +1 -0
  15. package/dist/contract.d.ts +2 -0
  16. package/dist/contract.js +2 -0
  17. package/dist/contract2.js +1453 -0
  18. package/dist/contract2.js.map +1 -0
  19. package/dist/email.d.ts +169 -0
  20. package/dist/email.d.ts.map +1 -0
  21. package/dist/email.js +670 -0
  22. package/dist/email.js.map +1 -0
  23. package/dist/index.d.ts +1755 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/listen.mjs +1881 -0
  26. package/dist/listen.mjs.map +1 -0
  27. package/dist/runtime-node.d.mts +10040 -0
  28. package/dist/runtime-node.d.mts.map +1 -0
  29. package/dist/runtime-node.mjs +32 -0
  30. package/dist/runtime-node.mjs.map +1 -0
  31. package/dist/server.d.ts +12792 -0
  32. package/dist/server.d.ts.map +1 -0
  33. package/dist/server.js +8475 -0
  34. package/dist/server.js.map +1 -0
  35. package/dist/server.mjs +8324 -0
  36. package/dist/server.mjs.map +1 -0
  37. package/dist/server2.mjs +505 -0
  38. package/dist/server2.mjs.map +1 -0
  39. package/package.json +124 -4
  40. package/src/admin/api/routes.ts +223 -0
  41. package/src/admin/api/security.ts +12 -0
  42. package/src/admin/audit/service.ts +138 -0
  43. package/src/admin/email/service.ts +140 -0
  44. package/src/admin/enrollment/email.ts +77 -0
  45. package/src/admin/enrollment/service.ts +308 -0
  46. package/src/admin/errors.ts +20 -0
  47. package/src/admin/index.ts +19 -0
  48. package/src/admin/list.ts +61 -0
  49. package/src/admin/operations/service.ts +70 -0
  50. package/src/admin/schema.ts +28 -0
  51. package/src/admin/users/service.ts +369 -0
  52. package/src/ai-relay/app.ts +251 -0
  53. package/src/ai-relay/config.ts +120 -0
  54. package/src/ai-relay/db/index.ts +10 -0
  55. package/src/ai-relay/db/migrate.ts +32 -0
  56. package/src/ai-relay/db/migrations/001_usage.ts +26 -0
  57. package/src/ai-relay/db/schema.ts +20 -0
  58. package/src/ai-relay/index.ts +18 -0
  59. package/src/ai-relay/metering.ts +68 -0
  60. package/src/ai-relay/usage.ts +115 -0
  61. package/src/client/ai.ts +96 -0
  62. package/src/client/api.ts +528 -0
  63. package/src/client/auth/client.ts +188 -0
  64. package/src/client/auth/failure.ts +54 -0
  65. package/src/client/auth/navigation.ts +45 -0
  66. package/src/client/device-authorization.ts +134 -0
  67. package/src/client/discovery.ts +105 -0
  68. package/src/client/images.ts +81 -0
  69. package/src/client/index.ts +53 -0
  70. package/src/client/portal/account.ts +183 -0
  71. package/src/client/portal/administration.ts +130 -0
  72. package/src/client/portal/client.ts +18 -0
  73. package/src/client/portal/request.ts +115 -0
  74. package/src/client/response.ts +51 -0
  75. package/src/client/workspaces.ts +142 -0
  76. package/src/contract/account.ts +204 -0
  77. package/src/contract/admin/index.ts +187 -0
  78. package/src/contract/ai.ts +150 -0
  79. package/src/contract/collaboration.ts +45 -0
  80. package/src/contract/discovery.ts +81 -0
  81. package/src/contract/documents.ts +265 -0
  82. package/src/contract/entitlements.ts +28 -0
  83. package/src/contract/index.ts +204 -0
  84. package/src/contract/links.ts +87 -0
  85. package/src/contract/portal.ts +11 -0
  86. package/src/contract/relay.ts +368 -0
  87. package/src/contract/sharing.ts +191 -0
  88. package/src/contract/versions.ts +87 -0
  89. package/src/contract/workspaces.ts +100 -0
  90. package/src/email/index.ts +14 -0
  91. package/src/email/render.ts +276 -0
  92. package/src/email/schema.ts +144 -0
  93. package/src/email/templates/brand.ts +105 -0
  94. package/src/email/templates/document-invitation.ts +35 -0
  95. package/src/email/templates/enrollment.ts +27 -0
  96. package/src/email/templates/layout.ts +18 -0
  97. package/src/runtime/cloudflare/email.ts +70 -0
  98. package/src/runtime/cloudflare/environment.ts +57 -0
  99. package/src/runtime/cloudflare/index.ts +3 -0
  100. package/src/runtime/cloudflare/relay.ts +136 -0
  101. package/src/runtime/cloudflare/site.ts +13 -0
  102. package/src/runtime/cloudflare/tsconfig.json +21 -0
  103. package/src/runtime/cloudflare/worker.ts +160 -0
  104. package/src/runtime/node/admin.ts +59 -0
  105. package/src/runtime/node/ai-relay/main.ts +35 -0
  106. package/src/runtime/node/ai-relay/server.ts +63 -0
  107. package/src/runtime/node/application.ts +50 -0
  108. package/src/runtime/node/bootstrap.ts +22 -0
  109. package/src/runtime/node/cleanup.ts +24 -0
  110. package/src/runtime/node/command.ts +17 -0
  111. package/src/runtime/node/config.ts +16 -0
  112. package/src/runtime/node/email/runtime.ts +43 -0
  113. package/src/runtime/node/email/transport.ts +112 -0
  114. package/src/runtime/node/entitlements/main.ts +41 -0
  115. package/src/runtime/node/entitlements/refusal.ts +15 -0
  116. package/src/runtime/node/index.ts +25 -0
  117. package/src/runtime/node/listen.ts +35 -0
  118. package/src/runtime/node/main.ts +29 -0
  119. package/src/runtime/node/migrate.ts +13 -0
  120. package/src/runtime/node/quota-reconcile.ts +9 -0
  121. package/src/runtime/node/relay.ts +54 -0
  122. package/src/runtime/node/server.ts +121 -0
  123. package/src/runtime/node/site.ts +64 -0
  124. package/src/runtime/postgres/database.ts +19 -0
  125. package/src/runtime/s3/objects.ts +244 -0
  126. package/src/runtime/site/server.ts +82 -0
  127. package/src/server/account/actions.ts +66 -0
  128. package/src/server/account/routes.ts +300 -0
  129. package/src/server/ai/errors.ts +7 -0
  130. package/src/server/ai/index.ts +4 -0
  131. package/src/server/ai/keys.ts +43 -0
  132. package/src/server/ai/routes.ts +43 -0
  133. package/src/server/ai/service.ts +70 -0
  134. package/src/server/api/index.ts +8 -0
  135. package/src/server/api/router.ts +117 -0
  136. package/src/server/api/types.ts +7 -0
  137. package/src/server/app.ts +375 -0
  138. package/src/server/auth/account.ts +73 -0
  139. package/src/server/auth/activity.ts +213 -0
  140. package/src/server/auth/adapter.ts +79 -0
  141. package/src/server/auth/email.ts +125 -0
  142. package/src/server/auth/endpoints.ts +57 -0
  143. package/src/server/auth/factory.ts +583 -0
  144. package/src/server/auth/index.ts +17 -0
  145. package/src/server/auth/mfa-assurance.ts +55 -0
  146. package/src/server/auth/runtime.ts +26 -0
  147. package/src/server/auth/session.ts +19 -0
  148. package/src/server/auth/social-providers.ts +55 -0
  149. package/src/server/auth/user-agent.ts +16 -0
  150. package/src/server/auth/workspace-access.ts +23 -0
  151. package/src/server/cleanup/configured.ts +38 -0
  152. package/src/server/cleanup/documents.ts +231 -0
  153. package/src/server/cleanup/index.ts +29 -0
  154. package/src/server/cleanup/objects.ts +27 -0
  155. package/src/server/cleanup/revisions.ts +232 -0
  156. package/src/server/cleanup/uploads.ts +129 -0
  157. package/src/server/cleanup/worker.ts +79 -0
  158. package/src/server/collaboration/index.ts +28 -0
  159. package/src/server/collaboration/relay/authorize.ts +53 -0
  160. package/src/server/collaboration/relay/awareness.ts +104 -0
  161. package/src/server/collaboration/relay/documents.ts +39 -0
  162. package/src/server/collaboration/relay/hub.ts +524 -0
  163. package/src/server/collaboration/relay/index.ts +15 -0
  164. package/src/server/collaboration/relay/persistence.ts +48 -0
  165. package/src/server/collaboration/routes.ts +77 -0
  166. package/src/server/collaboration/service.ts +188 -0
  167. package/src/server/config/deployment.ts +178 -0
  168. package/src/server/config/index.ts +20 -0
  169. package/src/server/config/limits.ts +8 -0
  170. package/src/server/config/public.ts +66 -0
  171. package/src/server/config/schema.ts +512 -0
  172. package/src/server/db/database.ts +15 -0
  173. package/src/server/db/expressions.ts +13 -0
  174. package/src/server/db/index.ts +21 -0
  175. package/src/server/db/migrate.ts +177 -0
  176. package/src/server/db/migrations/001_foundation.ts +164 -0
  177. package/src/server/db/migrations/002_upload_cleanup_claims.ts +34 -0
  178. package/src/server/db/migrations/003_document_cleanup_claims.ts +23 -0
  179. package/src/server/db/migrations/004_document_sharing.ts +82 -0
  180. package/src/server/db/migrations/005_document_collaboration_epoch.ts +13 -0
  181. package/src/server/db/migrations/006_invitation_continuation.ts +27 -0
  182. package/src/server/db/migrations/007_collaboration_state.ts +25 -0
  183. package/src/server/db/migrations/008_storage_reservations.ts +37 -0
  184. package/src/server/db/migrations/009_workspace_entitlements.ts +22 -0
  185. package/src/server/db/migrations/010_upload_finalization.ts +22 -0
  186. package/src/server/db/migrations/011_upload_finalization_lease.ts +12 -0
  187. package/src/server/db/migrations/012_transactional_email.ts +48 -0
  188. package/src/server/db/migrations/013_admin_enrollment.ts +54 -0
  189. package/src/server/db/migrations/014_enrollment_email_kinds.ts +30 -0
  190. package/src/server/db/migrations/015_cloud_rate_limit.ts +22 -0
  191. package/src/server/db/migrations/016_auth_schema.ts +16 -0
  192. package/src/server/db/migrations/017_authentication_email_kinds.ts +32 -0
  193. package/src/server/db/migrations/018_authentication_mfa.ts +78 -0
  194. package/src/server/db/migrations/019_better_auth_account_issuer.ts +42 -0
  195. package/src/server/db/migrations/020_workspace_invitations.ts +57 -0
  196. package/src/server/db/migrations/021_document_versions.ts +66 -0
  197. package/src/server/db/migrations/022_entitlement_external_version.ts +17 -0
  198. package/src/server/db/migrations/023_document_images.ts +61 -0
  199. package/src/server/db/migrations/024_account_activity.ts +66 -0
  200. package/src/server/db/migrations/025_table_names.ts +58 -0
  201. package/src/server/db/migrations/026_user_picture.ts +30 -0
  202. package/src/server/db/migrations/027_document_kind.ts +19 -0
  203. package/src/server/db/migrations/helpers.ts +78 -0
  204. package/src/server/db/tables.ts +394 -0
  205. package/src/server/documents/access.ts +103 -0
  206. package/src/server/documents/errors.ts +16 -0
  207. package/src/server/documents/images.ts +407 -0
  208. package/src/server/documents/index.ts +14 -0
  209. package/src/server/documents/limits.ts +57 -0
  210. package/src/server/documents/repository.ts +141 -0
  211. package/src/server/documents/routes.ts +239 -0
  212. package/src/server/documents/service.ts +597 -0
  213. package/src/server/documents/summary.ts +37 -0
  214. package/src/server/documents/types.ts +14 -0
  215. package/src/server/documents/versions/checkpoint.ts +98 -0
  216. package/src/server/documents/versions/history.ts +25 -0
  217. package/src/server/documents/versions/index.ts +4 -0
  218. package/src/server/documents/versions/routes.ts +112 -0
  219. package/src/server/documents/versions/service.ts +397 -0
  220. package/src/server/email/crypto.ts +57 -0
  221. package/src/server/email/index.ts +18 -0
  222. package/src/server/email/invitations.ts +30 -0
  223. package/src/server/email/service.ts +245 -0
  224. package/src/server/email/types.ts +56 -0
  225. package/src/server/email/worker.ts +33 -0
  226. package/src/server/index.ts +279 -0
  227. package/src/server/internal/index.ts +8 -0
  228. package/src/server/internal/routes.ts +41 -0
  229. package/src/server/internal/schema.ts +10 -0
  230. package/src/server/internal/service.ts +44 -0
  231. package/src/server/invitations/index.ts +6 -0
  232. package/src/server/invitations/types.ts +30 -0
  233. package/src/server/objects/index.ts +16 -0
  234. package/src/server/objects/types.ts +81 -0
  235. package/src/server/pictures/index.ts +9 -0
  236. package/src/server/pictures/provider.ts +61 -0
  237. package/src/server/pictures/routes.ts +21 -0
  238. package/src/server/pictures/service.ts +235 -0
  239. package/src/server/policy/configured.ts +23 -0
  240. package/src/server/policy/database.ts +108 -0
  241. package/src/server/policy/entitlements.ts +29 -0
  242. package/src/server/policy/index.ts +17 -0
  243. package/src/server/policy/keys.ts +23 -0
  244. package/src/server/policy/policy.ts +117 -0
  245. package/src/server/policy/provider.ts +67 -0
  246. package/src/server/policy/schema.ts +69 -0
  247. package/src/server/policy/service.ts +85 -0
  248. package/src/server/policy/static.ts +62 -0
  249. package/src/server/quota/index.ts +7 -0
  250. package/src/server/quota/reconcile.ts +61 -0
  251. package/src/server/quota/storage.ts +165 -0
  252. package/src/server/rate-limit/cleanup.ts +16 -0
  253. package/src/server/rate-limit/index.ts +12 -0
  254. package/src/server/rate-limit/keys.ts +38 -0
  255. package/src/server/rate-limit/middleware.ts +137 -0
  256. package/src/server/rate-limit/postgres.ts +79 -0
  257. package/src/server/sharing/access.ts +29 -0
  258. package/src/server/sharing/actor.ts +12 -0
  259. package/src/server/sharing/capabilities/service.ts +262 -0
  260. package/src/server/sharing/continuation.ts +85 -0
  261. package/src/server/sharing/contracts.ts +80 -0
  262. package/src/server/sharing/crypto.ts +48 -0
  263. package/src/server/sharing/document-routes.ts +41 -0
  264. package/src/server/sharing/errors.ts +12 -0
  265. package/src/server/sharing/grants/service.ts +79 -0
  266. package/src/server/sharing/http.ts +41 -0
  267. package/src/server/sharing/index.ts +39 -0
  268. package/src/server/sharing/invitations/service.ts +315 -0
  269. package/src/server/sharing/policy.ts +44 -0
  270. package/src/server/sharing/routes.ts +251 -0
  271. package/src/server/sharing/service.ts +117 -0
  272. package/src/server/validation.ts +24 -0
  273. package/src/server/worker/interval.ts +23 -0
  274. package/src/server/worker/periodic.ts +42 -0
  275. package/src/server/workspaces/index.ts +16 -0
  276. package/src/server/workspaces/members.ts +502 -0
  277. package/src/server/workspaces/repository.ts +91 -0
  278. package/src/server/workspaces/routes.ts +198 -0
  279. package/src/server/workspaces/service.ts +84 -0
@@ -0,0 +1,524 @@
1
+ import {
2
+ COLLAB_ACTIONS,
3
+ createRelayClientAssembler,
4
+ encodeSyncReply,
5
+ decodeRelayClientFrame,
6
+ decodeRoomUpdate,
7
+ MAX_COLLAB_MESSAGE_BYTES,
8
+ RELAY_CLOSE,
9
+ RELAY_SERVER_PEER,
10
+ relayServerMessages,
11
+ type RelayServerFrame
12
+ } from '#cloud/contract'
13
+ import * as Y from 'yjs'
14
+
15
+ import { authorizeRelayTicket, principalKey, type RelayAuthorization } from './authorize'
16
+ import { stampAwareness } from './awareness'
17
+ import type { CollaborationStateStore } from './persistence'
18
+
19
+ /** One client's socket, as a runtime adapter hands it to the relay. */
20
+ export type RelaySocket = {
21
+ send(data: Uint8Array): void
22
+ close(code: number, reason: string): void
23
+ }
24
+
25
+ /** What the adapter reports back about that socket. */
26
+ export type RelayConnection = {
27
+ receive(data: Uint8Array): void
28
+ closed(): void
29
+ }
30
+
31
+ export type CollaborationRelayOptions = {
32
+ authSecret: string
33
+ store: CollaborationStateStore
34
+ /**
35
+ * The one document this relay serves, for runtimes that run a relay per document; tickets for
36
+ * any other document are refused.
37
+ */
38
+ documentId?: string
39
+ /**
40
+ * The most one socket message may carry. An editor's larger frames arrive as fragments joined
41
+ * up to `MAX_COLLAB_MESSAGE_BYTES`; anyone else's frame must fit in one message.
42
+ */
43
+ maximumMessageBytes: number
44
+ maximumConnectionsPerRoom: number
45
+ /** The participant limit policy sets for a document, or null for none. */
46
+ maximumParticipants?: (documentId: string) => Promise<number | null>
47
+ /**
48
+ * The document's current collaboration epoch, which a restore advances; a ticket for an earlier
49
+ * room is turned away so nobody rejoins the document as it was.
50
+ */
51
+ currentRoomEpoch?: (documentId: string) => Promise<number | null>
52
+ /** How long after a change the room's document is saved. */
53
+ persistDelayMs?: number
54
+ /** How long a room whose last save failed waits before saving again. */
55
+ persistRetryMs?: number
56
+ /** How long a socket may stay open without presenting a ticket. */
57
+ authTimeoutMs?: number
58
+ onError?: (message: string, error: unknown) => void
59
+ }
60
+
61
+ /** Messages a viewer may send; their document writes never leave the relay. */
62
+ const VIEWER_ACTIONS = new Set<string>([COLLAB_ACTIONS.syncStep1, COLLAB_ACTIONS.awareness])
63
+
64
+ type Peer = {
65
+ id: string
66
+ socket: RelaySocket
67
+ authorization: RelayAuthorization
68
+ presenceClients: Set<number>
69
+ expiry?: ReturnType<typeof setTimeout>
70
+ }
71
+
72
+ type Room = {
73
+ id: string
74
+ identity: { documentId: string; roomEpoch: number }
75
+ document: Y.Doc
76
+ peers: Map<string, Peer>
77
+ persistTimer: ReturnType<typeof setTimeout> | null
78
+ }
79
+
80
+ export type CollaborationRelay = ReturnType<typeof createCollaborationRelay>
81
+
82
+ /**
83
+ * A runtime-neutral relay for collaboration rooms. It forwards room messages between peers and
84
+ * joins every room as a peer itself: it holds the room's document, answers sync requests from
85
+ * it, saves it, drops document writes from viewers, and stamps presence with verified identity.
86
+ */
87
+ export function createCollaborationRelay(options: CollaborationRelayOptions) {
88
+ const rooms = new Map<string, Room>()
89
+ const opening = new Map<string, Promise<Room>>()
90
+ /** Rooms whose last peer left and whose document is still being saved. */
91
+ const closing = new Map<string, Promise<void>>()
92
+ /** Set by `close()`: a failed save then drops the room instead of retrying. */
93
+ let shuttingDown = false
94
+ const persistDelayMs = options.persistDelayMs ?? 2_000
95
+ const persistRetryMs = options.persistRetryMs ?? 30_000
96
+ const authTimeoutMs = options.authTimeoutMs ?? 10_000
97
+ const report = options.onError ?? ((message, error) => console.error(`[Cloud] ${message}`, error))
98
+
99
+ function send(socket: RelaySocket, frame: RelayServerFrame) {
100
+ for (const message of relayServerMessages(frame)) socket.send(message)
101
+ }
102
+
103
+ function sendAll(sockets: Iterable<RelaySocket>, frame: RelayServerFrame) {
104
+ const messages = relayServerMessages(frame)
105
+ for (const socket of sockets) for (const message of messages) socket.send(message)
106
+ }
107
+
108
+ async function openRoom(authorization: RelayAuthorization): Promise<Room> {
109
+ const existing = rooms.get(authorization.roomId)
110
+ if (existing) return existing
111
+ const pending = opening.get(authorization.roomId)
112
+ if (pending) return pending
113
+ const identity = { documentId: authorization.documentId, roomEpoch: authorization.roomEpoch }
114
+ const created = (async () => {
115
+ // A room reopened while its last save is in flight must load what that save writes, or,
116
+ // when the save failed, take the room it kept.
117
+ await closing.get(authorization.roomId)
118
+ const kept = rooms.get(authorization.roomId)
119
+ if (kept) return kept
120
+ const document = new Y.Doc()
121
+ const state = await options.store.load(identity)
122
+ if (state) Y.applyUpdate(document, state)
123
+ const room: Room = {
124
+ id: authorization.roomId,
125
+ identity,
126
+ document,
127
+ peers: new Map(),
128
+ persistTimer: null
129
+ }
130
+ document.on('update', () => schedulePersist(room))
131
+ rooms.set(room.id, room)
132
+ return room
133
+ })()
134
+ opening.set(authorization.roomId, created)
135
+ try {
136
+ return await created
137
+ } finally {
138
+ opening.delete(authorization.roomId)
139
+ }
140
+ }
141
+
142
+ /** Saves the room's document; false when the store refused it. */
143
+ async function persist(room: Room): Promise<boolean> {
144
+ if (room.persistTimer) clearTimeout(room.persistTimer)
145
+ room.persistTimer = null
146
+ try {
147
+ await options.store.store(room.identity, Y.encodeStateAsUpdate(room.document))
148
+ return true
149
+ } catch (error) {
150
+ report('Saving a collaboration room failed:', error)
151
+ return false
152
+ }
153
+ }
154
+
155
+ function schedulePersist(room: Room) {
156
+ room.persistTimer ??= setTimeout(() => void persist(room), persistDelayMs)
157
+ }
158
+
159
+ /**
160
+ * Applies a peer's V2 update to the room, inflated first for a sync reply. Rooms are saved as
161
+ * V1 updates; only what peers exchange is V2.
162
+ */
163
+ function applyToRoom(room: Room, peer: Peer, namespace: string, payload: Uint8Array): boolean {
164
+ try {
165
+ const update = decodeRoomUpdate(payload, {
166
+ limit: MAX_COLLAB_MESSAGE_BYTES,
167
+ compressed: namespace === COLLAB_ACTIONS.syncReply
168
+ })
169
+ if (!update) {
170
+ peer.socket.close(RELAY_CLOSE.messageTooLarge, 'Collaboration update is too large')
171
+ return false
172
+ }
173
+ Y.applyUpdateV2(room.document, update, peer.id)
174
+ return true
175
+ } catch {
176
+ peer.socket.close(RELAY_CLOSE.protocol, 'Malformed document update')
177
+ return false
178
+ }
179
+ }
180
+
181
+ function forward(
182
+ room: Room,
183
+ from: Peer,
184
+ namespace: string,
185
+ target: string | null,
186
+ payload: Uint8Array
187
+ ) {
188
+ const frame: RelayServerFrame = { type: 'message', namespace, from: from.id, payload }
189
+ const recipients = target
190
+ ? [room.peers.get(target)]
191
+ : [...room.peers.values()].filter((peer) => peer !== from)
192
+ sendAll(
193
+ recipients.flatMap((peer) => (peer ? [peer.socket] : [])),
194
+ frame
195
+ )
196
+ }
197
+
198
+ function handleServerMessage(room: Room, peer: Peer, namespace: string, payload: Uint8Array) {
199
+ if (namespace === COLLAB_ACTIONS.syncStep1) {
200
+ let reply: Uint8Array
201
+ try {
202
+ reply = encodeSyncReply(room.document, payload)
203
+ } catch {
204
+ peer.socket.close(RELAY_CLOSE.protocol, 'Malformed state vector')
205
+ return
206
+ }
207
+ send(peer.socket, {
208
+ type: 'message',
209
+ namespace: COLLAB_ACTIONS.syncReply,
210
+ from: RELAY_SERVER_PEER,
211
+ payload: reply
212
+ })
213
+ } else if (namespace === COLLAB_ACTIONS.syncReply) {
214
+ applyToRoom(room, peer, namespace, payload)
215
+ }
216
+ }
217
+
218
+ function handleMessage(
219
+ room: Room,
220
+ peer: Peer,
221
+ namespace: string,
222
+ target: string | null,
223
+ payload: Uint8Array
224
+ ) {
225
+ const readOnly = peer.authorization.permission === 'view'
226
+ if (readOnly && !VIEWER_ACTIONS.has(namespace)) return
227
+ // Only the server says the history changed.
228
+ if (namespace === COLLAB_ACTIONS.versions) return
229
+
230
+ let forwarded = payload
231
+ if (namespace === COLLAB_ACTIONS.awareness) {
232
+ const stamped = stampAwareness(payload, peer.authorization, (clientId) =>
233
+ [...room.peers.values()].some(
234
+ (other) => other !== peer && other.presenceClients.has(clientId)
235
+ )
236
+ )
237
+ for (const clientId of stamped.claimed) peer.presenceClients.add(clientId)
238
+ if (!stamped.update) return
239
+ forwarded = stamped.update
240
+ }
241
+
242
+ if (target === RELAY_SERVER_PEER) {
243
+ handleServerMessage(room, peer, namespace, payload)
244
+ return
245
+ }
246
+ if (
247
+ (namespace === COLLAB_ACTIONS.yjsUpdate || namespace === COLLAB_ACTIONS.syncReply) &&
248
+ !applyToRoom(room, peer, namespace, payload)
249
+ ) {
250
+ return
251
+ }
252
+ forward(room, peer, namespace, target, forwarded)
253
+ }
254
+
255
+ function scheduleExpiry(peer: Peer) {
256
+ clearTimeout(peer.expiry)
257
+ peer.expiry = setTimeout(
258
+ () => peer.socket.close(RELAY_CLOSE.expired, 'Collaboration ticket expired'),
259
+ Math.max(0, peer.authorization.expiresAt - Date.now())
260
+ )
261
+ }
262
+
263
+ async function admit(
264
+ socket: RelaySocket,
265
+ authorization: RelayAuthorization
266
+ ): Promise<Peer | null> {
267
+ const limit = await options.maximumParticipants?.(authorization.documentId)
268
+ let room: Room
269
+ let epoch: number | null | undefined
270
+ // The room's last peer may have left while it opened, or a restore ended it; a closed room
271
+ // takes no newcomers. The epoch is read once the room is open, so a restore cannot slip between.
272
+ do {
273
+ room = await openRoom(authorization)
274
+ epoch = await options.currentRoomEpoch?.(authorization.documentId)
275
+ } while (rooms.get(room.id) !== room)
276
+ if (epoch != null && authorization.roomEpoch < epoch) {
277
+ socket.close(RELAY_CLOSE.restored, 'The document was restored')
278
+ if (room.peers.size === 0) await leaveRoom(room)
279
+ return null
280
+ }
281
+ const capacity = Math.min(limit ?? Number.POSITIVE_INFINITY, options.maximumConnectionsPerRoom)
282
+ if (room.peers.size >= capacity) {
283
+ socket.close(RELAY_CLOSE.roomFull, 'Collaboration room is full')
284
+ if (room.peers.size === 0) await leaveRoom(room)
285
+ return null
286
+ }
287
+ const peer: Peer = {
288
+ id: crypto.randomUUID(),
289
+ socket,
290
+ authorization,
291
+ presenceClients: new Set()
292
+ }
293
+ scheduleExpiry(peer)
294
+ send(socket, {
295
+ type: 'welcome',
296
+ peerId: peer.id,
297
+ peers: [RELAY_SERVER_PEER, ...room.peers.keys()]
298
+ })
299
+ for (const other of room.peers.values()) send(other.socket, { type: 'join', peerId: peer.id })
300
+ room.peers.set(peer.id, peer)
301
+ // Ask for what the newcomer has that the room lacks, such as edits made offline.
302
+ if (authorization.permission === 'edit') {
303
+ send(socket, {
304
+ type: 'message',
305
+ namespace: COLLAB_ACTIONS.syncStep1,
306
+ from: RELAY_SERVER_PEER,
307
+ payload: Y.encodeStateVector(room.document)
308
+ })
309
+ }
310
+ return peer
311
+ }
312
+
313
+ async function saveAndClose(room: Room) {
314
+ if ((await persist(room)) || shuttingDown) {
315
+ room.document.destroy()
316
+ return
317
+ }
318
+ // The room holds edits the store doesn't have: keep it for whoever joins next, and save
319
+ // again later, closing it once a save lands while nobody is in it.
320
+ rooms.set(room.id, room)
321
+ room.persistTimer = setTimeout(() => {
322
+ void (room.peers.size > 0 ? persist(room) : leaveRoom(room))
323
+ }, persistRetryMs)
324
+ }
325
+
326
+ async function leaveRoom(room: Room) {
327
+ if (room.peers.size > 0 || rooms.get(room.id) !== room) return
328
+ rooms.delete(room.id)
329
+ const saved = saveAndClose(room)
330
+ closing.set(room.id, saved)
331
+ try {
332
+ await saved
333
+ } finally {
334
+ if (closing.get(room.id) === saved) closing.delete(room.id)
335
+ }
336
+ }
337
+
338
+ function depart(peer: Peer) {
339
+ clearTimeout(peer.expiry)
340
+ const room = rooms.get(peer.authorization.roomId)
341
+ if (!room?.peers.delete(peer.id)) return
342
+ for (const other of room.peers.values()) send(other.socket, { type: 'leave', peerId: peer.id })
343
+ void leaveRoom(room)
344
+ }
345
+
346
+ return {
347
+ connect(socket: RelaySocket): RelayConnection {
348
+ let peer: Peer | null = null
349
+ /** Read through an object, since it changes across awaits and between messages. */
350
+ const state = { closed: false, authenticating: false }
351
+ const isClosed = () => state.closed
352
+ const queued: Uint8Array[] = []
353
+ let queuedBytes = 0
354
+ // Only an editor's writes can be large: a viewer's frames, and a peer's before it is
355
+ // admitted, fit in one message, so nobody else can make the relay hold more.
356
+ const assembler = createRelayClientAssembler(() =>
357
+ peer?.authorization.permission === 'edit'
358
+ ? MAX_COLLAB_MESSAGE_BYTES
359
+ : options.maximumMessageBytes
360
+ )
361
+ const authTimer = setTimeout(
362
+ () => socket.close(RELAY_CLOSE.unauthorized, 'Expected a collaboration ticket'),
363
+ authTimeoutMs
364
+ )
365
+
366
+ async function authenticate(token: string) {
367
+ let authorization: RelayAuthorization
368
+ try {
369
+ authorization = await authorizeRelayTicket(token, options.authSecret)
370
+ } catch {
371
+ socket.close(RELAY_CLOSE.unauthorized, 'Invalid collaboration ticket')
372
+ return
373
+ }
374
+ if (options.documentId !== undefined && authorization.documentId !== options.documentId) {
375
+ socket.close(RELAY_CLOSE.unauthorized, 'Ticket is for a different document')
376
+ return
377
+ }
378
+ if (state.closed) return
379
+ if (peer) {
380
+ // A refreshed ticket keeps the peer in its room as the same person; a lowered
381
+ // permission applies from now on.
382
+ const current = peer.authorization
383
+ if (
384
+ authorization.roomId !== current.roomId ||
385
+ principalKey(authorization.principal) !== principalKey(current.principal)
386
+ ) {
387
+ socket.close(RELAY_CLOSE.unauthorized, 'Ticket is for a different room or person')
388
+ return
389
+ }
390
+ peer.authorization = authorization
391
+ scheduleExpiry(peer)
392
+ return
393
+ }
394
+ clearTimeout(authTimer)
395
+ const admitted = await admit(socket, authorization)
396
+ // The socket may have closed while the room loaded.
397
+ if (admitted && isClosed()) depart(admitted)
398
+ else peer = admitted
399
+ }
400
+
401
+ function process(data: Uint8Array) {
402
+ if (data.byteLength > options.maximumMessageBytes) {
403
+ socket.close(RELAY_CLOSE.messageTooLarge, 'Collaboration message is too large')
404
+ return
405
+ }
406
+ const assembled = assembler.push(data)
407
+ if (assembled.type === 'partial') return
408
+ if (assembled.type === 'too-large') {
409
+ socket.close(RELAY_CLOSE.messageTooLarge, 'Collaboration message is too large')
410
+ return
411
+ }
412
+ const frame = assembled.type === 'frame' ? decodeRelayClientFrame(assembled.data) : null
413
+ if (!frame) {
414
+ socket.close(RELAY_CLOSE.protocol, 'Malformed collaboration frame')
415
+ return
416
+ }
417
+ if (frame.type === 'auth') {
418
+ state.authenticating = true
419
+ void authenticate(frame.token)
420
+ .catch((error: unknown) => {
421
+ report('Admitting a collaboration peer failed:', error)
422
+ socket.close(RELAY_CLOSE.protocol, 'Could not open the collaboration room')
423
+ })
424
+ .finally(() => {
425
+ state.authenticating = false
426
+ flush()
427
+ })
428
+ return
429
+ }
430
+ const room = peer && rooms.get(peer.authorization.roomId)
431
+ if (!peer || !room) {
432
+ socket.close(RELAY_CLOSE.unauthorized, 'Expected a collaboration ticket')
433
+ return
434
+ }
435
+ handleMessage(room, peer, frame.namespace, frame.target, frame.payload)
436
+ }
437
+
438
+ function flush() {
439
+ while (!state.authenticating && !state.closed && queued.length > 0) {
440
+ const next = queued.shift()
441
+ if (!next) continue
442
+ queuedBytes -= next.byteLength
443
+ process(next)
444
+ }
445
+ }
446
+
447
+ return {
448
+ receive(data) {
449
+ if (state.closed) return
450
+ queuedBytes += data.byteLength
451
+ // Before admission a peer has sent its ticket and has nothing else to say, so what
452
+ // waits for the room to open is held to one message's worth.
453
+ if (!peer && queuedBytes > options.maximumMessageBytes) {
454
+ queued.length = 0
455
+ queuedBytes = 0
456
+ socket.close(RELAY_CLOSE.messageTooLarge, 'Too much sent before joining the room')
457
+ return
458
+ }
459
+ queued.push(data)
460
+ flush()
461
+ },
462
+ closed() {
463
+ state.closed = true
464
+ queued.length = 0
465
+ queuedBytes = 0
466
+ clearTimeout(authTimer)
467
+ if (peer) depart(peer)
468
+ }
469
+ }
470
+ },
471
+
472
+ /**
473
+ * Ends a restored document's rooms: everyone in them is told the document was restored, and
474
+ * their edits to the replaced state are dropped rather than saved.
475
+ */
476
+ startOver(documentId: string) {
477
+ // A map's iteration carries on past entries deleted during it.
478
+ for (const room of rooms.values()) {
479
+ if (room.identity.documentId !== documentId) continue
480
+ rooms.delete(room.id)
481
+ if (room.persistTimer) clearTimeout(room.persistTimer)
482
+ for (const peer of room.peers.values()) {
483
+ clearTimeout(peer.expiry)
484
+ peer.socket.close(RELAY_CLOSE.restored, 'The document was restored')
485
+ }
486
+ room.peers.clear()
487
+ room.document.destroy()
488
+ }
489
+ },
490
+
491
+ /** Tells everyone in a document's rooms that its version history changed. */
492
+ announceVersions(documentId: string) {
493
+ const frame: RelayServerFrame = {
494
+ type: 'message',
495
+ namespace: COLLAB_ACTIONS.versions,
496
+ from: RELAY_SERVER_PEER,
497
+ payload: new Uint8Array()
498
+ }
499
+ sendAll(
500
+ [...rooms.values()]
501
+ .filter((room) => room.identity.documentId === documentId)
502
+ .flatMap((room) => [...room.peers.values()].map((peer) => peer.socket)),
503
+ frame
504
+ )
505
+ },
506
+
507
+ /** Saves every open room and closes its sockets, as the runtime shuts down. */
508
+ async close() {
509
+ shuttingDown = true
510
+ await Promise.all(
511
+ [...rooms.values()].map(async (room) => {
512
+ for (const peer of room.peers.values()) {
513
+ clearTimeout(peer.expiry)
514
+ peer.socket.close(1001, 'Server shutting down')
515
+ }
516
+ room.peers.clear()
517
+ await leaveRoom(room)
518
+ })
519
+ )
520
+ // Rooms whose last peer left just before, or during, shutdown are still saving.
521
+ await Promise.all(closing.values())
522
+ }
523
+ }
524
+ }
@@ -0,0 +1,15 @@
1
+ export { authorizeRelayTicket, type RelayAuthorization } from './authorize'
2
+ export { stampAwareness, type StampedAwareness, type VerifiedPresence } from './awareness'
3
+ export { relayDocumentLookups } from './documents'
4
+ export {
5
+ createCollaborationRelay,
6
+ type CollaborationRelay,
7
+ type CollaborationRelayOptions,
8
+ type RelayConnection,
9
+ type RelaySocket
10
+ } from './hub'
11
+ export {
12
+ createCollaborationStateStore,
13
+ type CollaborationRoomIdentity,
14
+ type CollaborationStateStore
15
+ } from './persistence'
@@ -0,0 +1,48 @@
1
+ import type { CloudDatabase } from '#cloud/server/db'
2
+ import type { Kysely } from 'kysely'
3
+
4
+ export type CollaborationRoomIdentity = {
5
+ documentId: string
6
+ roomEpoch: number
7
+ }
8
+
9
+ /** The relay's saved copy of each room's document, by document and collaboration epoch. */
10
+ export type CollaborationStateStore = {
11
+ load(room: CollaborationRoomIdentity): Promise<Uint8Array | null>
12
+ store(room: CollaborationRoomIdentity, state: Uint8Array): Promise<void>
13
+ }
14
+
15
+ export function createCollaborationStateStore(
16
+ database: Kysely<CloudDatabase>
17
+ ): CollaborationStateStore {
18
+ return {
19
+ async load(room) {
20
+ const row = await database
21
+ .selectFrom('documentCollaborationState')
22
+ .select('state')
23
+ .where('documentId', '=', room.documentId)
24
+ .where('roomEpoch', '=', room.roomEpoch)
25
+ .executeTakeFirst()
26
+ return row ? new Uint8Array(row.state) : null
27
+ },
28
+
29
+ async store(room, state) {
30
+ await database
31
+ .insertInto('documentCollaborationState')
32
+ .values({
33
+ documentId: room.documentId,
34
+ roomEpoch: room.roomEpoch,
35
+ state,
36
+ updatedAt: new Date()
37
+ })
38
+ .onConflict((conflict) =>
39
+ conflict.columns(['documentId', 'roomEpoch']).doUpdateSet({
40
+ state,
41
+ version: (expression) => expression('documentCollaborationState.version', '+', 1),
42
+ updatedAt: new Date()
43
+ })
44
+ )
45
+ .execute()
46
+ }
47
+ }
48
+ }
@@ -0,0 +1,77 @@
1
+ import { parseResolveDocumentShare } from '#cloud/contract'
2
+ import type { CloudActor, CloudSessionResolver } from '#cloud/server/auth'
3
+ import type { CollaborationTicketService } from '#cloud/server/collaboration/service'
4
+ import type { CloudDatabase } from '#cloud/server/db'
5
+ import { DocumentNotFoundError } from '#cloud/server/documents'
6
+ import { CLOUD_RATE_LIMITS, createRouteRateLimiter } from '#cloud/server/rate-limit'
7
+ import { DocumentShareInvalidError, DocumentShareSignInRequiredError } from '#cloud/server/sharing'
8
+ import { validatedJSON } from '#cloud/server/validation'
9
+ import { Hono, type Context } from 'hono'
10
+ import type { Kysely } from 'kysely'
11
+
12
+ export type CollaborationRouteEnvironment = { Variables: { actor: CloudActor } }
13
+
14
+ function notFound(context: Context, error: unknown): Response | null {
15
+ if (error instanceof DocumentNotFoundError || error instanceof DocumentShareInvalidError) {
16
+ return context.json({ error: { code: 'not_found' as const } }, 404)
17
+ }
18
+ if (error instanceof DocumentShareSignInRequiredError) {
19
+ return context.json({ error: { code: 'unauthorized' as const } }, 401)
20
+ }
21
+ return null
22
+ }
23
+
24
+ export function createCollaborationRoutes(
25
+ service: CollaborationTicketService,
26
+ rateLimit?: { database: Kysely<CloudDatabase>; secret: string }
27
+ ) {
28
+ const router = new Hono<CollaborationRouteEnvironment>()
29
+ if (rateLimit) {
30
+ router.use(
31
+ '/documents/:documentId/collaboration-ticket',
32
+ createRouteRateLimiter(
33
+ rateLimit.database,
34
+ rateLimit.secret,
35
+ CLOUD_RATE_LIMITS.collaborationTicket,
36
+ undefined,
37
+ (context) => context.req.param('documentId') ?? 'unknown-document'
38
+ )
39
+ )
40
+ }
41
+ return router.post('/documents/:documentId/collaboration-ticket', async (context) => {
42
+ try {
43
+ return context.json({
44
+ ticket: await service.issueUserTicket(context.get('actor'), context.req.param('documentId'))
45
+ })
46
+ } catch (error) {
47
+ const response = notFound(context, error)
48
+ if (response) return response
49
+ throw error
50
+ }
51
+ })
52
+ }
53
+
54
+ export function createPublicCollaborationRoutes(
55
+ service: CollaborationTicketService,
56
+ resolveSession?: CloudSessionResolver
57
+ ) {
58
+ return new Hono().post(
59
+ '/shares/:shareId/collaboration-ticket',
60
+ validatedJSON(parseResolveDocumentShare),
61
+ async (context) => {
62
+ try {
63
+ return context.json({
64
+ ticket: await service.issueShareTicket(
65
+ context.req.param('shareId'),
66
+ context.req.valid('json'),
67
+ resolveSession ? ((await resolveSession(context.req.raw)) ?? undefined) : undefined
68
+ )
69
+ })
70
+ } catch (error) {
71
+ const response = notFound(context, error)
72
+ if (response) return response
73
+ throw error
74
+ }
75
+ }
76
+ )
77
+ }