@open-pencil/cloud 0.17.0-beta.1 → 0.17.0-beta.4

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 (235) hide show
  1. package/README.md +1 -1
  2. package/dist/bin/{ai-relay.mjs → services.mjs} +8 -8
  3. package/dist/bin/services.mjs.map +1 -0
  4. package/dist/client.d.ts +236 -46
  5. package/dist/client.d.ts.map +1 -1
  6. package/dist/client.js +649 -400
  7. package/dist/client.js.map +1 -1
  8. package/dist/contract.d.ts +2 -2
  9. package/dist/contract.js +2 -2
  10. package/dist/contract2.js +680 -443
  11. package/dist/contract2.js.map +1 -1
  12. package/dist/email.d.ts +9 -1
  13. package/dist/email.d.ts.map +1 -1
  14. package/dist/email.js +99 -58
  15. package/dist/email.js.map +1 -1
  16. package/dist/index.d.ts +468 -64
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/listen.mjs +575 -738
  19. package/dist/listen.mjs.map +1 -1
  20. package/dist/runtime-node.d.mts +6564 -2934
  21. package/dist/runtime-node.d.mts.map +1 -1
  22. package/dist/runtime-node.mjs +6 -5
  23. package/dist/runtime-node.mjs.map +1 -1
  24. package/dist/server.d.ts +8931 -4198
  25. package/dist/server.d.ts.map +1 -1
  26. package/dist/server.js +5260 -3859
  27. package/dist/server.js.map +1 -1
  28. package/dist/server.mjs +5686 -3736
  29. package/dist/server.mjs.map +1 -1
  30. package/dist/server2.mjs +101 -79
  31. package/dist/server2.mjs.map +1 -1
  32. package/package.json +9 -6
  33. package/src/admin/api/routes.ts +103 -33
  34. package/src/admin/audit/service.ts +25 -6
  35. package/src/admin/documents/service.ts +361 -0
  36. package/src/admin/errors.ts +9 -1
  37. package/src/admin/index.ts +6 -0
  38. package/src/admin/operations/service.ts +7 -0
  39. package/src/admin/reports/service.ts +147 -0
  40. package/src/admin/schema.ts +6 -0
  41. package/src/client/api.ts +36 -21
  42. package/src/client/auth/navigation.ts +6 -5
  43. package/src/client/index.ts +7 -7
  44. package/src/client/portal/account.ts +25 -0
  45. package/src/client/portal/administration.ts +56 -0
  46. package/src/client/{ai.ts → services.ts} +44 -27
  47. package/src/contract/account.ts +58 -2
  48. package/src/contract/admin/index.ts +67 -3
  49. package/src/contract/collaboration.ts +6 -1
  50. package/src/contract/discovery.ts +22 -4
  51. package/src/contract/documents.ts +27 -0
  52. package/src/contract/entitlements.ts +2 -2
  53. package/src/contract/index.ts +63 -37
  54. package/src/contract/relay.ts +6 -0
  55. package/src/contract/reports.ts +42 -0
  56. package/src/contract/services.ts +233 -0
  57. package/src/contract/sharing.ts +3 -9
  58. package/src/email/render.ts +26 -0
  59. package/src/email/schema.ts +11 -1
  60. package/src/email/templates/brand.ts +1 -1
  61. package/src/runtime/cloudflare/environment.ts +31 -6
  62. package/src/runtime/cloudflare/index.ts +1 -1
  63. package/src/runtime/cloudflare/logging.ts +15 -0
  64. package/src/runtime/cloudflare/maintenance.ts +31 -0
  65. package/src/runtime/cloudflare/relay/index.ts +176 -0
  66. package/src/runtime/cloudflare/relay/sockets.ts +112 -0
  67. package/src/runtime/cloudflare/worker.ts +89 -26
  68. package/src/runtime/node/application.ts +5 -3
  69. package/src/runtime/node/bootstrap.ts +20 -4
  70. package/src/runtime/node/cleanup.ts +16 -3
  71. package/src/runtime/node/entitlements/main.ts +14 -11
  72. package/src/runtime/node/index.ts +1 -1
  73. package/src/runtime/node/migrate.ts +5 -1
  74. package/src/runtime/node/relay.ts +8 -2
  75. package/src/runtime/node/request-id.ts +13 -0
  76. package/src/runtime/node/server.ts +71 -15
  77. package/src/runtime/node/{ai-relay → services}/main.ts +6 -6
  78. package/src/runtime/node/{ai-relay → services}/server.ts +18 -18
  79. package/src/runtime/postgres/database.ts +20 -1
  80. package/src/runtime/posthog/errors.ts +32 -0
  81. package/src/runtime/s3/objects.ts +50 -1
  82. package/src/runtime/site/server.ts +33 -4
  83. package/src/server/account/actions.ts +5 -0
  84. package/src/server/account/deletion.ts +302 -0
  85. package/src/server/account/routes.ts +47 -3
  86. package/src/server/account/terms.ts +42 -0
  87. package/src/server/api/router.ts +12 -7
  88. package/src/server/api/types.ts +9 -0
  89. package/src/server/app.ts +93 -15
  90. package/src/server/auth/access-control.ts +63 -0
  91. package/src/server/auth/adapter.ts +11 -0
  92. package/src/server/auth/endpoints.ts +5 -1
  93. package/src/server/auth/factory.ts +30 -3
  94. package/src/server/auth/index.ts +10 -1
  95. package/src/server/cleanup/configured.ts +12 -5
  96. package/src/server/cleanup/documents.ts +165 -71
  97. package/src/server/cleanup/objects.ts +10 -2
  98. package/src/server/cleanup/revisions.ts +24 -7
  99. package/src/server/cleanup/uploads.ts +8 -2
  100. package/src/server/cleanup/worker.ts +5 -2
  101. package/src/server/collaboration/index.ts +3 -0
  102. package/src/server/collaboration/relay/connection.ts +196 -0
  103. package/src/server/collaboration/relay/documents.ts +13 -10
  104. package/src/server/collaboration/relay/hub.ts +279 -195
  105. package/src/server/collaboration/relay/index.ts +3 -1
  106. package/src/server/collaboration/relay/log.ts +79 -0
  107. package/src/server/collaboration/relay/persistence.ts +147 -22
  108. package/src/server/collaboration/relay/resume.ts +28 -0
  109. package/src/server/collaboration/routes.ts +27 -16
  110. package/src/server/collaboration/service.ts +27 -31
  111. package/src/server/config/deployment.ts +35 -4
  112. package/src/server/config/public.ts +5 -4
  113. package/src/server/config/schema.ts +104 -16
  114. package/src/server/db/expressions.ts +15 -1
  115. package/src/server/db/migrate.ts +34 -114
  116. package/src/server/db/migrations/001_accounts.ts +79 -0
  117. package/src/server/db/migrations/002_workspaces.ts +48 -0
  118. package/src/server/db/migrations/003_storage.ts +44 -0
  119. package/src/server/db/migrations/004_documents.ts +193 -0
  120. package/src/server/db/migrations/005_sharing.ts +95 -0
  121. package/src/server/db/migrations/006_operations.ts +110 -0
  122. package/src/server/db/migrations/007_trash.ts +33 -0
  123. package/src/server/db/migrations/008_terms.ts +18 -0
  124. package/src/server/db/migrations/schema.ts +71 -0
  125. package/src/server/db/tables.ts +70 -7
  126. package/src/server/documents/access.ts +66 -55
  127. package/src/server/documents/errors.ts +7 -0
  128. package/src/server/documents/images.ts +2 -1
  129. package/src/server/documents/limits.ts +9 -9
  130. package/src/server/documents/purge.ts +75 -0
  131. package/src/server/documents/repository.ts +2 -0
  132. package/src/server/documents/routes.ts +132 -80
  133. package/src/server/documents/service.ts +18 -4
  134. package/src/server/documents/summary.ts +1 -0
  135. package/src/server/documents/trash.ts +203 -0
  136. package/src/server/documents/versions/checkpoint.ts +2 -1
  137. package/src/server/documents/versions/history.ts +11 -7
  138. package/src/server/documents/versions/routes.ts +36 -25
  139. package/src/server/documents/versions/service.ts +22 -4
  140. package/src/server/errors/index.ts +99 -0
  141. package/src/server/errors/posthog.ts +80 -0
  142. package/src/server/index.ts +56 -16
  143. package/src/server/internal/index.ts +3 -3
  144. package/src/server/internal/routes.ts +7 -15
  145. package/src/server/internal/schema.ts +1 -1
  146. package/src/server/internal/service.ts +17 -23
  147. package/src/server/invitations/budget.ts +66 -0
  148. package/src/server/invitations/index.ts +1 -0
  149. package/src/server/logging.ts +76 -0
  150. package/src/server/objects/types.ts +12 -0
  151. package/src/server/pictures/routes.ts +4 -2
  152. package/src/server/pictures/service.ts +2 -1
  153. package/src/server/policy/database.ts +39 -25
  154. package/src/server/policy/index.ts +2 -1
  155. package/src/server/policy/keys.ts +5 -2
  156. package/src/server/policy/policy.ts +1 -0
  157. package/src/server/policy/schema.ts +2 -2
  158. package/src/server/policy/service.ts +12 -9
  159. package/src/server/policy/static.ts +5 -5
  160. package/src/server/policy/workspace.ts +41 -0
  161. package/src/server/quota/reconcile.ts +2 -0
  162. package/src/server/quota/storage.ts +69 -31
  163. package/src/server/rate-limit/cleanup.ts +17 -5
  164. package/src/server/rate-limit/index.ts +4 -1
  165. package/src/server/rate-limit/middleware.ts +100 -12
  166. package/src/server/reports/index.ts +8 -0
  167. package/src/server/reports/routes.ts +37 -0
  168. package/src/server/reports/service.ts +123 -0
  169. package/src/server/services/errors.ts +7 -0
  170. package/src/server/services/index.ts +8 -0
  171. package/src/server/{ai → services}/keys.ts +11 -11
  172. package/src/server/services/routes.ts +47 -0
  173. package/src/server/{ai/service.ts → services/tokens.ts} +23 -20
  174. package/src/server/sharing/capabilities/service.ts +68 -22
  175. package/src/server/sharing/document-routes.ts +30 -22
  176. package/src/server/sharing/grants/service.ts +11 -18
  177. package/src/server/sharing/http.ts +4 -0
  178. package/src/server/sharing/invitations/service.ts +21 -11
  179. package/src/server/sharing/policy.ts +9 -14
  180. package/src/server/sharing/routes.ts +108 -85
  181. package/src/server/sharing/service.ts +1 -17
  182. package/src/server/validation.ts +59 -2
  183. package/src/server/workspaces/index.ts +1 -0
  184. package/src/server/workspaces/members.ts +89 -38
  185. package/src/server/workspaces/repository.ts +2 -1
  186. package/src/server/workspaces/routes.ts +67 -45
  187. package/src/{ai-relay → services}/app.ts +48 -44
  188. package/src/{ai-relay → services}/config.ts +25 -19
  189. package/src/services/db/index.ts +10 -0
  190. package/src/services/db/migrate.ts +37 -0
  191. package/src/{ai-relay/db/migrations/001_usage.ts → services/db/migrations/001_baseline.ts} +18 -7
  192. package/src/services/db/schema.ts +22 -0
  193. package/src/services/index.ts +18 -0
  194. package/src/{ai-relay → services}/metering.ts +2 -2
  195. package/src/{ai-relay → services}/usage.ts +43 -19
  196. package/dist/bin/ai-relay.mjs.map +0 -1
  197. package/src/ai-relay/db/index.ts +0 -10
  198. package/src/ai-relay/db/migrate.ts +0 -32
  199. package/src/ai-relay/db/schema.ts +0 -20
  200. package/src/ai-relay/index.ts +0 -18
  201. package/src/contract/ai.ts +0 -150
  202. package/src/runtime/cloudflare/relay.ts +0 -136
  203. package/src/server/ai/errors.ts +0 -7
  204. package/src/server/ai/index.ts +0 -4
  205. package/src/server/ai/routes.ts +0 -43
  206. package/src/server/auth/workspace-access.ts +0 -23
  207. package/src/server/db/migrations/001_foundation.ts +0 -164
  208. package/src/server/db/migrations/002_upload_cleanup_claims.ts +0 -34
  209. package/src/server/db/migrations/003_document_cleanup_claims.ts +0 -23
  210. package/src/server/db/migrations/004_document_sharing.ts +0 -82
  211. package/src/server/db/migrations/005_document_collaboration_epoch.ts +0 -13
  212. package/src/server/db/migrations/006_invitation_continuation.ts +0 -27
  213. package/src/server/db/migrations/007_collaboration_state.ts +0 -25
  214. package/src/server/db/migrations/008_storage_reservations.ts +0 -37
  215. package/src/server/db/migrations/009_workspace_entitlements.ts +0 -22
  216. package/src/server/db/migrations/010_upload_finalization.ts +0 -22
  217. package/src/server/db/migrations/011_upload_finalization_lease.ts +0 -12
  218. package/src/server/db/migrations/012_transactional_email.ts +0 -48
  219. package/src/server/db/migrations/013_admin_enrollment.ts +0 -54
  220. package/src/server/db/migrations/014_enrollment_email_kinds.ts +0 -30
  221. package/src/server/db/migrations/015_cloud_rate_limit.ts +0 -22
  222. package/src/server/db/migrations/016_auth_schema.ts +0 -16
  223. package/src/server/db/migrations/017_authentication_email_kinds.ts +0 -32
  224. package/src/server/db/migrations/018_authentication_mfa.ts +0 -78
  225. package/src/server/db/migrations/019_better_auth_account_issuer.ts +0 -42
  226. package/src/server/db/migrations/020_workspace_invitations.ts +0 -57
  227. package/src/server/db/migrations/021_document_versions.ts +0 -66
  228. package/src/server/db/migrations/022_entitlement_external_version.ts +0 -17
  229. package/src/server/db/migrations/023_document_images.ts +0 -61
  230. package/src/server/db/migrations/024_account_activity.ts +0 -66
  231. package/src/server/db/migrations/025_table_names.ts +0 -58
  232. package/src/server/db/migrations/026_user_picture.ts +0 -30
  233. package/src/server/db/migrations/027_document_kind.ts +0 -19
  234. package/src/server/db/migrations/helpers.ts +0 -78
  235. /package/dist/bin/{ai-relay.d.mts → services.d.mts} +0 -0
@@ -0,0 +1,31 @@
1
+ import { cloudflareRayId } from './logging'
2
+
3
+ /**
4
+ * The Worker variable that takes a deployment off the air, as the Deploy Cloud workflow's
5
+ * `maintenance` input sets it: every request answers 503 and scheduled cleanup does nothing, while
6
+ * the deploy itself restarts the rooms' objects and closes their sockets. A database restore runs
7
+ * under it (deploy/openpencil/README.md).
8
+ */
9
+ export const MAINTENANCE_VARIABLE = 'OPENPENCIL_CLOUD_MAINTENANCE'
10
+
11
+ export function inMaintenance(env: Record<string, unknown>): boolean {
12
+ return env[MAINTENANCE_VARIABLE] === 'on'
13
+ }
14
+
15
+ /** How a relay socket open when maintenance began is closed: the service restarts. */
16
+ export const MAINTENANCE_CLOSE_CODE = 1012
17
+
18
+ /**
19
+ * What every request gets meanwhile; clients retry, and nothing reaches the database. It names the
20
+ * request as other responses do, by its ray ID.
21
+ */
22
+ export function maintenanceResponse(request: Request): Response {
23
+ return new Response('OpenPencil Cloud is down for maintenance.', {
24
+ status: 503,
25
+ headers: {
26
+ 'Content-Type': 'text/plain; charset=utf-8',
27
+ 'Retry-After': '300',
28
+ 'X-Request-Id': cloudflareRayId(request.headers) ?? crypto.randomUUID()
29
+ }
30
+ })
31
+ }
@@ -0,0 +1,176 @@
1
+ import { RELAY_DOCUMENT_PARAM, RELAY_HEARTBEAT } from '#cloud/contract'
2
+ import { createPostgresCloudDatabase } from '#cloud/runtime/postgres/database'
3
+ import { createS3ObjectStore } from '#cloud/runtime/s3/objects'
4
+ import {
5
+ createCollaborationRelay,
6
+ createCollaborationStateStore,
7
+ createConfiguredCloudPolicy,
8
+ relayDocumentLookups,
9
+ reportCloudError,
10
+ type CollaborationRelay
11
+ } from '#cloud/server'
12
+ import { DurableObject } from 'cloudflare:workers'
13
+ import type { Context } from 'hono'
14
+ import * as v from 'valibot'
15
+
16
+ import type { CloudflareCloudEnvironment, PreparedCloudflareCloud } from '../environment'
17
+ import { inMaintenance, MAINTENANCE_CLOSE_CODE, maintenanceResponse } from '../maintenance'
18
+ import { createRelaySockets } from './sockets'
19
+
20
+ /** What the Worker calls on a document's relay object. */
21
+ export interface CollaborationRelayRPC extends DurableObject<CloudflareCloudEnvironment> {
22
+ /** Ends the document's live rooms after a restore, without saving them. */
23
+ startOver(documentId: string): Promise<void>
24
+ /** Ends a taken-down document's live rooms, saving them. */
25
+ closeDocument(documentId: string): Promise<void>
26
+ /** Tells the document's live rooms its version history changed. */
27
+ announceVersions(documentId: string): Promise<void>
28
+ }
29
+
30
+ const documentIdSchema = v.pipe(v.string(), v.uuid())
31
+
32
+ /**
33
+ * The most a room's document may hold on Cloudflare. A Durable Object has 128 MB of memory for
34
+ * the document, the update joining it, and the snapshot written from it, so a room past this is
35
+ * turned away and its editors save without one.
36
+ */
37
+ export const CLOUDFLARE_MAXIMUM_ROOM_BYTES = 32 * 1024 * 1024
38
+
39
+ /**
40
+ * The document's relay object. With a jurisdiction, objects are created and keep their storage
41
+ * only inside it; an object named outside one is a different object, so a deployment never
42
+ * changes its jurisdiction while rooms are live.
43
+ */
44
+ export function relayFor(
45
+ env: CloudflareCloudEnvironment,
46
+ documentId: string,
47
+ jurisdiction?: DurableObjectJurisdiction
48
+ ) {
49
+ const namespace = jurisdiction ? env.RELAY.jurisdiction(jurisdiction) : env.RELAY
50
+ return namespace.get(namespace.idFromName(documentId))
51
+ }
52
+
53
+ /**
54
+ * Sends a relay socket to its document's relay object. The ticket's URL names the document; the
55
+ * object refuses tickets for any other.
56
+ */
57
+ export function relayRoute(jurisdiction?: DurableObjectJurisdiction) {
58
+ return async (c: Context<{ Bindings: CloudflareCloudEnvironment }>): Promise<Response> => {
59
+ if (c.req.header('Upgrade')?.toLowerCase() !== 'websocket') {
60
+ return c.text('Expected a WebSocket upgrade', 426)
61
+ }
62
+ const documentId = c.req.query(RELAY_DOCUMENT_PARAM)
63
+ if (!v.is(documentIdSchema, documentId)) return c.text('Missing document', 400)
64
+ return relayFor(c.env, documentId, jurisdiction).fetch(c.req.raw)
65
+ }
66
+ }
67
+
68
+ /** The relay over the deployment's PostgreSQL and object store. */
69
+ function configuredRelay(
70
+ { config }: PreparedCloudflareCloud,
71
+ documentId: string,
72
+ onError: (message: string, error: unknown) => void
73
+ ): CollaborationRelay {
74
+ // Hyperdrive keeps no session settings and ends queries past its own limit.
75
+ const database = createPostgresCloudDatabase({
76
+ connectionString: config.databaseURL,
77
+ statementTimeoutMs: null
78
+ })
79
+ return createCollaborationRelay({
80
+ authSecret: config.authSecret,
81
+ documentId,
82
+ store: createCollaborationStateStore(database, createS3ObjectStore(config)),
83
+ maximumMessageBytes: config.technicalLimits.maximumCollaborationMessageBytes,
84
+ maximumRoomBytes: CLOUDFLARE_MAXIMUM_ROOM_BYTES,
85
+ maximumConnectionsPerRoom: config.technicalLimits.maximumConnectionsPerRoom,
86
+ onError,
87
+ ...relayDocumentLookups(
88
+ database,
89
+ createConfiguredCloudPolicy(config, database),
90
+ config.deployment
91
+ )
92
+ })
93
+ }
94
+
95
+ /**
96
+ * The Durable Object class holding one document's live rooms: every epoch of the document meets
97
+ * on one relay, so a restore or a version change reaches all of them in one call. Its sockets
98
+ * hibernate with it (see `createRelaySockets`).
99
+ */
100
+ export function createCloudflareRelayObject(
101
+ prepare: (env: CloudflareCloudEnvironment) => Promise<PreparedCloudflareCloud>
102
+ ) {
103
+ return class CollaborationRelayObject
104
+ extends DurableObject<CloudflareCloudEnvironment>
105
+ implements CollaborationRelayRPC
106
+ {
107
+ constructor(ctx: DurableObjectState, env: CloudflareCloudEnvironment) {
108
+ super(ctx, env)
109
+ // Peers check the relay still hears them; the runtime answers without waking the object.
110
+ ctx.setWebSocketAutoResponse(
111
+ new WebSocketRequestResponsePair(RELAY_HEARTBEAT.ping, RELAY_HEARTBEAT.pong)
112
+ )
113
+ }
114
+
115
+ readonly #sockets = createRelaySockets({
116
+ sockets: () => this.ctx.getWebSockets(),
117
+ createRelay: async (documentId) => {
118
+ const prepared = await prepare(this.env)
119
+ return configuredRelay(prepared, documentId, (message, error) =>
120
+ this.ctx.waitUntil(
121
+ reportCloudError(prepared.reportError, message, error, { source: 'relay' })
122
+ )
123
+ )
124
+ }
125
+ })
126
+
127
+ /** Accepts a socket that `relayRoute` sent here. */
128
+ override async fetch(request: Request): Promise<Response> {
129
+ if (inMaintenance(this.env)) return maintenanceResponse(request)
130
+ const documentId = new URL(request.url).searchParams.get(RELAY_DOCUMENT_PARAM)
131
+ if (!v.is(documentIdSchema, documentId)) return new Response(null, { status: 400 })
132
+ const relay = await this.#sockets.open(documentId)
133
+ const { 0: client, 1: server } = new WebSocketPair()
134
+ this.ctx.acceptWebSocket(server)
135
+ this.#sockets.accept(server, relay)
136
+ return new Response(null, { status: 101, webSocket: client })
137
+ }
138
+
139
+ override async webSocketMessage(socket: WebSocket, message: string | ArrayBuffer) {
140
+ // A socket from before maintenance began reaches the room no more: its editor reconnects
141
+ // once maintenance ends, and nothing it sends meanwhile is written.
142
+ if (inMaintenance(this.env)) {
143
+ socket.close(MAINTENANCE_CLOSE_CODE, 'Down for maintenance')
144
+ return
145
+ }
146
+ await this.#sockets.message(socket, message)
147
+ }
148
+
149
+ // Under maintenance a closing socket leaves its room as it is: closing the room would save
150
+ // its state into a database that may be mid-restore.
151
+ override async webSocketClose(socket: WebSocket) {
152
+ if (inMaintenance(this.env)) return
153
+ await this.#sockets.closed(socket)
154
+ }
155
+
156
+ override async webSocketError(socket: WebSocket) {
157
+ if (inMaintenance(this.env)) return
158
+ await this.#sockets.closed(socket)
159
+ }
160
+
161
+ async startOver(documentId: string) {
162
+ if (!this.#sockets.active) return
163
+ ;(await this.#sockets.open(documentId)).startOver(documentId)
164
+ }
165
+
166
+ async closeDocument(documentId: string) {
167
+ if (!this.#sockets.active) return
168
+ ;(await this.#sockets.open(documentId)).closeDocument(documentId)
169
+ }
170
+
171
+ async announceVersions(documentId: string) {
172
+ if (!this.#sockets.active) return
173
+ ;(await this.#sockets.open(documentId)).announceVersions(documentId)
174
+ }
175
+ }
176
+ }
@@ -0,0 +1,112 @@
1
+ import { RELAY_CLOSE } from '#cloud/contract'
2
+ import {
3
+ readRelayPeerState,
4
+ type CollaborationRelay,
5
+ type RelayConnection,
6
+ type RelaySocket
7
+ } from '#cloud/server'
8
+
9
+ /** What the relay's sockets need from the Durable Object that holds them. */
10
+ export type RelaySocketHost = {
11
+ /** The sockets the object still holds, as `DurableObjectState.getWebSockets` lists them. */
12
+ sockets(): WebSocket[]
13
+ /** Creates the relay for the document the object serves, once per wake. */
14
+ createRelay(documentId: string): Promise<CollaborationRelay>
15
+ }
16
+
17
+ /** A socket message's bytes; text is passed on as bytes for the relay to refuse. */
18
+ function bytes(data: unknown): Uint8Array {
19
+ if (data instanceof ArrayBuffer) return new Uint8Array(data)
20
+ return new TextEncoder().encode(typeof data === 'string' ? data : '')
21
+ }
22
+
23
+ /**
24
+ * A hibernatable socket as the relay sees it. The peer's state rides on the socket as its
25
+ * attachment, so a relay woken from hibernation can resume the peer.
26
+ */
27
+ function relaySocket(socket: WebSocket): RelaySocket {
28
+ // A closing socket throws on send and close, which would stop a broadcast to the others.
29
+ const open = () => socket.readyState === WebSocket.OPEN
30
+ return {
31
+ send(data) {
32
+ if (open()) socket.send(data)
33
+ },
34
+ close(code, reason) {
35
+ if (open()) socket.close(code, reason)
36
+ },
37
+ remember(state) {
38
+ socket.serializeAttachment(state)
39
+ }
40
+ }
41
+ }
42
+
43
+ /**
44
+ * The relay a Durable Object wakes to and its sockets' connections to it. Sockets are accepted
45
+ * for hibernation, so an idle object is evicted while they stay open, each keeping its peer; the
46
+ * relay it wakes to resumes them, loading a room's document only once a message needs it.
47
+ */
48
+ export function createRelaySockets(host: RelaySocketHost) {
49
+ let relay: Promise<CollaborationRelay> | null = null
50
+ /** Each socket's connection to the relay, since the object last woke. */
51
+ const connections = new Map<WebSocket, RelayConnection>()
52
+
53
+ /** The relay, created once per wake; it takes back every socket the object still holds. */
54
+ function open(documentId: string): Promise<CollaborationRelay> {
55
+ const opened = (relay ??= host.createRelay(documentId).then((created) => {
56
+ for (const socket of host.sockets()) {
57
+ if (connections.has(socket)) continue
58
+ const state = readRelayPeerState(socket.deserializeAttachment())
59
+ // A socket the relay never admitted has no peer to resume, and its ticket is long due.
60
+ if (state) connections.set(socket, created.resume(relaySocket(socket), state))
61
+ else socket.close(RELAY_CLOSE.unauthorized, 'Expected a collaboration ticket')
62
+ }
63
+ return created
64
+ }))
65
+ opened.catch(() => {
66
+ if (relay === opened) relay = null
67
+ })
68
+ return opened
69
+ }
70
+
71
+ /**
72
+ * The socket's connection, waking the relay for the document its peer is in, or null for a
73
+ * stray socket. A socket that closed while the object hibernated may already be missing from
74
+ * the ones the woken relay takes back, so its peer is resumed here, if only to leave.
75
+ */
76
+ async function connectionOf(socket: WebSocket): Promise<RelayConnection | null> {
77
+ const known = connections.get(socket)
78
+ if (known) return known
79
+ const state = readRelayPeerState(socket.deserializeAttachment())
80
+ if (!state) return null
81
+ const woken = await open(state.authorization.documentId)
82
+ const connection = connections.get(socket) ?? woken.resume(relaySocket(socket), state)
83
+ connections.set(socket, connection)
84
+ return connection
85
+ }
86
+
87
+ return {
88
+ open,
89
+ /** Whether a relay is awake, or anyone is still connected to wake one for. */
90
+ get active() {
91
+ return relay !== null || host.sockets().length > 0
92
+ },
93
+
94
+ /** Connects a socket the object just accepted, which presents its ticket next. */
95
+ accept(socket: WebSocket, woken: CollaborationRelay) {
96
+ connections.set(socket, woken.connect(relaySocket(socket)))
97
+ },
98
+
99
+ async message(socket: WebSocket, message: string | ArrayBuffer) {
100
+ const connection = await connectionOf(socket)
101
+ if (connection) connection.receive(bytes(message))
102
+ else socket.close(RELAY_CLOSE.unauthorized, 'Expected a collaboration ticket')
103
+ },
104
+
105
+ /** Lets the socket's peer leave its room, so the room closes once it empties. */
106
+ async closed(socket: WebSocket) {
107
+ const connection = await connectionOf(socket)
108
+ connections.delete(socket)
109
+ connection?.closed()
110
+ }
111
+ }
112
+ }
@@ -4,13 +4,18 @@ import { createS3ObjectStore } from '#cloud/runtime/s3/objects'
4
4
  import { createCloudServer } from '#cloud/runtime/site/server'
5
5
  import {
6
6
  cleanupPassOptions,
7
+ cloudErrorHandler,
8
+ cloudRequestId,
7
9
  createCleanupServices,
8
10
  createCloudApp,
9
11
  createCloudAuthenticationRuntime,
10
12
  createConfiguredCloudPolicy,
11
13
  createInvitationOutbox,
12
14
  createTransactionalEmailService,
15
+ reportCloudError,
13
16
  runCleanup,
17
+ type CloudErrorReporter,
18
+ type CloudErrorSource,
14
19
  type TransactionalEmailService
15
20
  } from '#cloud/server'
16
21
  import { Hono } from 'hono'
@@ -21,7 +26,9 @@ import {
21
26
  type CloudflareCloudEnvironment,
22
27
  type PreparedCloudflareCloud
23
28
  } from './environment'
24
- import { createCloudflareRelayObject, relayFor, routeToRelay } from './relay'
29
+ import { cloudflareRayId } from './logging'
30
+ import { inMaintenance, maintenanceResponse } from './maintenance'
31
+ import { createCloudflareRelayObject, relayFor, relayRoute } from './relay'
25
32
  import { assetSiteFiles } from './site'
26
33
 
27
34
  function emailTransport({ config }: PreparedCloudflareCloud, env: CloudflareCloudEnvironment) {
@@ -30,6 +37,19 @@ function emailTransport({ config }: PreparedCloudflareCloud, env: CloudflareClou
30
37
  return createCloudflareEmailTransport(env.EMAIL)
31
38
  }
32
39
 
40
+ /** A reporter whose reports keep the Worker running until they are sent. */
41
+ function keptAlive(
42
+ reporter: CloudErrorReporter | undefined,
43
+ context: Pick<ExecutionContext, 'waitUntil'>
44
+ ): CloudErrorReporter | undefined {
45
+ if (!reporter) return undefined
46
+ return (error, errorContext) => {
47
+ const reported = reporter(error, errorContext)
48
+ context.waitUntil(reported)
49
+ return reported
50
+ }
51
+ }
52
+
33
53
  /**
34
54
  * What one request or cron run needs. Workers can't share connections between requests, so each
35
55
  * gets its own database client, closed once its background work settles.
@@ -40,7 +60,14 @@ function cloudServices(
40
60
  context: Pick<ExecutionContext, 'waitUntil'>
41
61
  ) {
42
62
  const { config } = prepared
43
- const database = createPostgresCloudDatabase({ connectionString: config.databaseURL })
63
+ const reporter = keptAlive(prepared.reportError, context)
64
+ const reportError = (message: string, error: unknown, source: CloudErrorSource) =>
65
+ reportCloudError(reporter, message, error, { source })
66
+ // Hyperdrive keeps no session settings and ends queries past its own limit.
67
+ const database = createPostgresCloudDatabase({
68
+ connectionString: config.databaseURL,
69
+ statementTimeoutMs: null
70
+ })
44
71
  const objects = createS3ObjectStore(config)
45
72
  const transport = emailTransport(prepared, env)
46
73
  const queued = createTransactionalEmailService(database, {
@@ -61,7 +88,7 @@ function cloudServices(
61
88
  const background: Promise<unknown>[] = []
62
89
  const runInBackground = (task: Promise<unknown>) => {
63
90
  background.push(
64
- task.catch((error: unknown) => console.error('[Cloud] Background work failed:', error))
91
+ task.catch((error: unknown) => reportError('Background work failed', error, 'background'))
65
92
  )
66
93
  }
67
94
  const deliver = () =>
@@ -78,28 +105,67 @@ function cloudServices(
78
105
  transport,
79
106
  runInBackground,
80
107
  deliver,
108
+ reporter,
81
109
  /** Sends what the request queued and closes the database after everything it started. */
82
110
  finish() {
83
111
  context.waitUntil(
84
112
  Promise.allSettled(background)
85
113
  .then(() => (enqueued && transport ? deliver() : undefined))
86
- .catch((error: unknown) => console.error('[Cloud] Sending email failed:', error))
114
+ .catch((error: unknown) => reportError('Sending email failed', error, 'email'))
87
115
  .then(() => database.destroy())
88
116
  )
89
117
  }
90
118
  }
91
119
  }
92
120
 
121
+ /** Cleanup, and email that failed to send after its request or that a full batch left behind. */
122
+ async function runScheduled(
123
+ prepared: PreparedCloudflareCloud,
124
+ env: CloudflareCloudEnvironment,
125
+ context: Pick<ExecutionContext, 'waitUntil'>
126
+ ) {
127
+ const services = cloudServices(prepared, env, context)
128
+ const { config, database, objects } = services
129
+ try {
130
+ if (config.cleanupEnabled) {
131
+ const policy = createConfiguredCloudPolicy(config, database)
132
+ await runCleanup(
133
+ createCleanupServices(config, database, objects, policy, services.reporter),
134
+ cleanupPassOptions(config)
135
+ )
136
+ }
137
+ if (services.transport) await services.deliver()
138
+ } finally {
139
+ services.finish()
140
+ }
141
+ }
142
+
93
143
  /**
94
144
  * OpenPencil Cloud on Cloudflare Workers, configured by a deployment TOML. The Worker serves the
95
145
  * API, the editor, and the portal per request, a Durable Object per document runs its collaboration rooms, and a
96
146
  * Cron Trigger runs cleanup and retries email.
97
147
  */
98
- export function createCloudflareCloud(configSource: string) {
99
- const prepare = cloudflareCloudSetup(configSource)
148
+ export type CloudflareCloudOptions = {
149
+ /**
150
+ * Where collaboration rooms' Durable Objects run and keep their storage, such as `eu` for a
151
+ * deployment whose data stays in the EU; by default, near whoever opens the room first.
152
+ */
153
+ relayJurisdiction?: DurableObjectJurisdiction
154
+ }
155
+
156
+ export function createCloudflareCloud(
157
+ configSource: string,
158
+ { relayJurisdiction }: CloudflareCloudOptions = {}
159
+ ) {
160
+ const { prepare, reporter } = cloudflareCloudSetup(configSource)
161
+ const relay = (env: CloudflareCloudEnvironment, documentId: string) =>
162
+ relayFor(env, documentId, relayJurisdiction)
100
163
 
101
164
  const router = new Hono<{ Bindings: CloudflareCloudEnvironment }>()
102
- .get(RELAY_PATH, routeToRelay)
165
+ // Setup, relay routing, and the runtime around the app; the app reports its own errors.
166
+ .onError((error, c) => cloudErrorHandler(keptAlive(reporter(), c.executionCtx))(error, c))
167
+ .use('*', cloudRequestId(cloudflareRayId))
168
+ .get(RELAY_PATH, relayRoute(relayJurisdiction))
103
169
  .all('*', async (c) => {
104
170
  const prepared = await prepare(c.env)
105
171
  const services = cloudServices(prepared, c.env, c.executionCtx)
@@ -117,16 +183,21 @@ export function createCloudflareCloud(configSource: string) {
117
183
  invitationOutbox: transport ? createInvitationOutbox(email) : undefined,
118
184
  transactionalEmail: email,
119
185
  enrollment,
120
- aiSigningKey: prepared.aiSigningKey,
186
+ servicesSigningKey: prepared.servicesSigningKey,
121
187
  relayURL: config.relayURL ?? defaultRelayURL(config.publicURL),
122
188
  onDocumentRestored: (documentId) =>
123
- runInBackground(relayFor(c.env, documentId).startOver(documentId)),
189
+ runInBackground(relay(c.env, documentId).startOver(documentId)),
190
+ onDocumentTakenDown: (documentId) =>
191
+ runInBackground(relay(c.env, documentId).closeDocument(documentId)),
124
192
  onDocumentVersionsChanged: (documentId) =>
125
- runInBackground(relayFor(c.env, documentId).announceVersions(documentId))
193
+ runInBackground(relay(c.env, documentId).announceVersions(documentId)),
194
+ reportError: services.reporter,
195
+ forwardedRequestId: cloudflareRayId
126
196
  })
127
197
  return await createCloudServer(app, {
128
198
  site: assetSiteFiles(c.env.ASSETS),
129
- indexingPolicy: config.indexingPolicy
199
+ indexingPolicy: config.indexingPolicy,
200
+ reportError: services.reporter
130
201
  }).fetch(c.req.raw)
131
202
  } finally {
132
203
  services.finish()
@@ -134,24 +205,16 @@ export function createCloudflareCloud(configSource: string) {
134
205
  })
135
206
 
136
207
  const worker: ExportedHandler<CloudflareCloudEnvironment> = {
137
- fetch: (request, env, context) => router.fetch(request, env, context),
208
+ fetch: (request, env, context) =>
209
+ inMaintenance(env) ? maintenanceResponse(request) : router.fetch(request, env, context),
138
210
 
139
211
  async scheduled(_controller, env, context) {
140
- const prepared = await prepare(env)
141
- const services = cloudServices(prepared, env, context)
142
- const { config, database, objects } = services
212
+ if (inMaintenance(env)) return
143
213
  try {
144
- if (config.cleanupEnabled) {
145
- const policy = createConfiguredCloudPolicy(config, database)
146
- await runCleanup(
147
- createCleanupServices(config, database, objects, policy),
148
- cleanupPassOptions(config)
149
- )
150
- }
151
- // Retries what failed to send after its request, and what a full batch left behind.
152
- if (services.transport) await services.deliver()
153
- } finally {
154
- services.finish()
214
+ await runScheduled(await prepare(env), env, context)
215
+ } catch (error) {
216
+ await reportCloudError(reporter(), 'Scheduled run failed', error, { source: 'scheduled' })
217
+ throw error
155
218
  }
156
219
  }
157
220
  }
@@ -3,7 +3,7 @@ import { createS3ObjectStore } from '#cloud/runtime/s3/objects'
3
3
  import {
4
4
  createCloudAuthenticationRuntime,
5
5
  createCloudApp,
6
- loadAISigningKey,
6
+ loadServicesSigningKey,
7
7
  type CloudApp,
8
8
  type CloudEnvironment,
9
9
  type CloudServerConfig,
@@ -12,6 +12,7 @@ import {
12
12
 
13
13
  import { loadNodeCloudServerConfig } from './config'
14
14
  import { createNodeTransactionalEmailRuntime } from './email/runtime'
15
+ import { proxyRequestId } from './request-id'
15
16
 
16
17
  export type NodeCloudApplicationOptions = {
17
18
  environment?: CloudEnvironment
@@ -29,7 +30,7 @@ export async function createNodeCloudApplication(
29
30
  }> {
30
31
  const environment = options.environment ?? process.env
31
32
  const config = await loadNodeCloudServerConfig(environment)
32
- const aiSigningKey = await loadAISigningKey(config)
33
+ const servicesSigningKey = await loadServicesSigningKey(config)
33
34
  const database = createPostgresCloudDatabase({
34
35
  connectionString: options.databaseURL ?? config.databaseURL
35
36
  })
@@ -44,7 +45,8 @@ export async function createNodeCloudApplication(
44
45
  invitationOutbox,
45
46
  transactionalEmail: email,
46
47
  enrollment,
47
- aiSigningKey
48
+ servicesSigningKey,
49
+ forwardedRequestId: proxyRequestId
48
50
  })
49
51
  return { app, config, database, objects, email }
50
52
  }
@@ -7,6 +7,25 @@ import {
7
7
 
8
8
  import { loadNodeCloudServerConfig } from './config'
9
9
 
10
+ /**
11
+ * The deployment's database, migrated to this version before anything uses it. Migrations run
12
+ * on a connection of their own without the statement timeout, since one may rewrite a large table.
13
+ */
14
+ export async function migratedNodeCloudDatabase(config: CloudServerConfig) {
15
+ const migrating = createPostgresCloudDatabase({
16
+ connectionString: config.databaseURL,
17
+ statementTimeoutMs: null
18
+ })
19
+ try {
20
+ const auth = createBetterAuthAdapter(config, migrating)
21
+ await migrateCloudDatabase(migrating, { run: auth.migrate, schemaVersion: auth.schemaVersion })
22
+ } finally {
23
+ await migrating.destroy()
24
+ }
25
+ const database = createPostgresCloudDatabase({ connectionString: config.databaseURL })
26
+ return { database, auth: createBetterAuthAdapter(config, database) }
27
+ }
28
+
10
29
  export async function createMigratedNodeCloudDatabase(
11
30
  environment: Readonly<Record<string, string | undefined>>
12
31
  ): Promise<{
@@ -15,8 +34,5 @@ export async function createMigratedNodeCloudDatabase(
15
34
  auth: ReturnType<typeof createBetterAuthAdapter>
16
35
  }> {
17
36
  const config = await loadNodeCloudServerConfig(environment)
18
- const database = createPostgresCloudDatabase({ connectionString: config.databaseURL })
19
- const auth = createBetterAuthAdapter(config, database)
20
- await migrateCloudDatabase(database, { run: auth.migrate, schemaVersion: auth.schemaVersion })
21
- return { config, database, auth }
37
+ return { config, ...(await migratedNodeCloudDatabase(config)) }
22
38
  }
@@ -1,21 +1,34 @@
1
1
  import { createPostgresCloudDatabase } from '#cloud/runtime/postgres/database'
2
+ import { createCloudErrorReporter } from '#cloud/runtime/posthog/errors'
2
3
  import { createS3ObjectStore } from '#cloud/runtime/s3/objects'
3
4
  import {
4
5
  cleanupPassOptions,
5
6
  createCleanupServices,
6
7
  createConfiguredCloudPolicy,
7
- runCleanup
8
+ createLoggingErrorReporter,
9
+ runCleanup,
10
+ writeJSONLine
8
11
  } from '#cloud/server'
9
12
 
10
13
  import { loadNodeCloudServerConfig } from './config'
11
14
 
12
15
  const config = await loadNodeCloudServerConfig(process.env)
13
- const database = createPostgresCloudDatabase({ connectionString: config.databaseURL })
16
+ // A sweep may take longer than a request should.
17
+ const database = createPostgresCloudDatabase({
18
+ connectionString: config.databaseURL,
19
+ statementTimeoutMs: null
20
+ })
14
21
  const objects = createS3ObjectStore(config)
15
22
  try {
16
23
  const policy = createConfiguredCloudPolicy(config, database)
17
24
  const result = await runCleanup(
18
- createCleanupServices(config, database, objects, policy),
25
+ createCleanupServices(
26
+ config,
27
+ database,
28
+ objects,
29
+ policy,
30
+ createLoggingErrorReporter(writeJSONLine, createCloudErrorReporter(config, 'node'))
31
+ ),
19
32
  cleanupPassOptions(config)
20
33
  )
21
34
  console.log(JSON.stringify(result))