Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

refactor(sync-service): hexagonal layout with axum routing and scoped auth extractors (#4478)

Wolf Mermelstein17eaa788c2ac
diff --git a/Cargo.lock b/Cargo.lock
index 268d794ae7..f2af8566c9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -19588,13 +19588,13 @@ dependencies = [
name = "sync_service"
version = "0.1.0"
dependencies = [
+ "axum",
"base64 0.22.1",
"bebop",
"futures",
"getrandom 0.3.4",
"loro",
"macro_sync_service_jwt",
- "matchit 0.8.4",
"serde",
"serde_json",
"sha2 0.10.9",
@@ -19602,9 +19602,11 @@ dependencies = [
"sync_service_bebop_schema",
"thiserror 2.0.18",
"time",
+ "tower-service",
"tracing",
"tracing-subscriber",
"tracing-web",
+ "utoipa",
"uuid",
"wasm-bindgen",
"web-time",
@@ -22604,6 +22606,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4afd7ae4f7fcc11e0e5e64b964890b3dda90f1290b0612f7cd821b381cc18826"
dependencies = [
"async-trait",
+ "axum",
"bytes",
"chrono",
"futures-channel",
diff --git a/Cargo.toml b/Cargo.toml
index 8ce2b046aa..07ca31fff7 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -432,6 +432,7 @@ tokio-tungstenite-signal = { package = "tokio-tungstenite", version = "0.27", de
tungstenite-signal = { package = "tungstenite", version = "0.27", default-features = false, features = ["handshake", "deflate"] }
tokio-util = "0.7.13"
tower = { version = "0.5.1", features = ["util"] }
+tower-service = "0.3"
tower-http = { version = "0.6.1", features = [
"compression-gzip",
"cors",
diff --git a/apps/web/src/lib/service-clients/orval.config.ts b/apps/web/src/lib/service-clients/orval.config.ts
index e68400bad2..5998503194 100644
--- a/apps/web/src/lib/service-clients/orval.config.ts
+++ b/apps/web/src/lib/service-clients/orval.config.ts
@@ -200,6 +200,20 @@ export default defineConfig({
},
},
},
+ syncService: {
+ output: {
+ biome: true,
+ // Keep the existing transport for binary payloads and permission tokens.
+ // Generate shared HTTP models alongside the Bebop websocket schema.
+ schemas: './service-sync/generated/http/schemas',
+ override: {
+ useDates: false,
+ },
+ },
+ input: {
+ target: './service-sync/openapi.json',
+ },
+ },
unfurlService: {
output: {
client: 'fetch',
diff --git a/apps/web/src/lib/service-clients/service-sync/client.ts b/apps/web/src/lib/service-clients/service-sync/client.ts
index 18daa91464..8b98c51dcd 100644
--- a/apps/web/src/lib/service-clients/service-sync/client.ts
+++ b/apps/web/src/lib/service-clients/service-sync/client.ts
@@ -11,6 +11,7 @@ import type { SafeFetchInit } from '@core/util/safeFetch';
import { InitializeFromSnapshotRequest } from '@macro-inc/collaboration/sync-service/generated/schema';
import type { SerializedEditorState } from 'lexical';
import { err, ok, type Result } from 'neverthrow';
+import type { BlameRow, DocumentMetadata } from './generated/http/schemas';
const SYNC_SERVICE_WORKER_URL = `${SYNC_SERVICE_HOSTS['worker']}`;
@@ -62,13 +63,6 @@ function syncFetch<T extends ObjectLike = never>(
});
}
-type MetadataResponse = {
- peers: Array<{
- peer_id: number;
- user_id: string;
- }>;
-};
-
export type HistorySession = {
userId: string;
startMs: number;
@@ -177,7 +171,7 @@ export const syncServiceClient = {
async getDocumentMetadata(args: { documentId: string }) {
const token = await getPermissionToken('document', args.documentId);
- const response = await syncFetch<MetadataResponse>(
+ const response = await syncFetch<DocumentMetadata>(
`/document/${args.documentId}/metadata`,
{
headers: {
@@ -191,7 +185,7 @@ export const syncServiceClient = {
return err(response.error);
}
- return ok(response.value as MetadataResponse);
+ return ok(response.value);
},
/**
* Look up who last edited a given Lexical node and when. `user_id` is a
@@ -201,17 +195,16 @@ export const syncServiceClient = {
async getNodeBlame(args: { documentId: string; nodeId: string }) {
const token = await getPermissionToken('document', args.documentId);
- const response = await syncFetch<{
- peer_id: string;
- user_id: string | null;
- timestamp_ms: number;
- }>(`/document/${args.documentId}/blame/${args.nodeId}`, {
- headers: {
- 'Content-Type': 'application/json',
- Authorization: `Bearer ${token}`,
- },
- method: 'GET',
- });
+ const response = await syncFetch<BlameRow>(
+ `/document/${args.documentId}/blame/${args.nodeId}`,
+ {
+ headers: {
+ 'Content-Type': 'application/json',
+ Authorization: `Bearer ${token}`,
+ },
+ method: 'GET',
+ }
+ );
if (response.isErr()) {
return err(response.error);
@@ -219,7 +212,7 @@ export const syncServiceClient = {
const { peer_id, user_id, timestamp_ms } = response.value;
return ok({
peerId: peer_id,
- userId: user_id,
+ userId: user_id ?? null,
editedAt: new Date(timestamp_ms),
});
},
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/binaryBody.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/binaryBody.ts
new file mode 100644
index 0000000000..7f6c7b9e27
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/binaryBody.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type BinaryBody = Blob;
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRow.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRow.ts
new file mode 100644
index 0000000000..66472704ae
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRow.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { BlameRowUserId } from './blameRowUserId';
+
+export interface BlameRow {
+ peer_id: string;
+ timestamp_ms: number;
+ user_id?: BlameRowUserId;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRowUserId.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRowUserId.ts
new file mode 100644
index 0000000000..5757d08816
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/blameRowUserId.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type BlameRowUserId = string | null;
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequest.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequest.ts
new file mode 100644
index 0000000000..d4dad53549
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequest.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { CopyDocumentRequestVersionId } from './copyDocumentRequestVersionId';
+
+export interface CopyDocumentRequest {
+ target_document_id: string;
+ version_id?: CopyDocumentRequestVersionId;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequestVersionId.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequestVersionId.ts
new file mode 100644
index 0000000000..8ec9452403
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/copyDocumentRequestVersionId.ts
@@ -0,0 +1,10 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { VersionIndicator } from './versionIndicator';
+
+export type CopyDocumentRequestVersionId = null | VersionIndicator;
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentActivePeersParams.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentActivePeersParams.ts
new file mode 100644
index 0000000000..9d168d0df3
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentActivePeersParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type DocumentActivePeersParams = {
+ /**
+ * Set to `false` or `0` to filter out AI editors
+ */
+ include_ai?: string;
+};
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentMetadata.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentMetadata.ts
new file mode 100644
index 0000000000..31790264f1
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentMetadata.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { PeerWithUserId } from './peerWithUserId';
+
+export interface DocumentMetadata {
+ id: string;
+ peers: PeerWithUserId[];
+ version_id: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentStateParams.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentStateParams.ts
new file mode 100644
index 0000000000..c7ca340c7f
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/documentStateParams.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export type DocumentStateParams = {
+ /**
+ * Return current state without prior edit history
+ */
+ shallow?: boolean;
+};
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequest.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequest.ts
new file mode 100644
index 0000000000..cf968d126d
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { GetSnapshotRequestVersionId } from './getSnapshotRequestVersionId';
+
+export interface GetSnapshotRequest {
+ version_id?: GetSnapshotRequestVersionId;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequestVersionId.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequestVersionId.ts
new file mode 100644
index 0000000000..01f7e42cfc
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/getSnapshotRequestVersionId.ts
@@ -0,0 +1,10 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+import type { VersionIndicator } from './versionIndicator';
+
+export type GetSnapshotRequestVersionId = null | VersionIndicator;
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/index.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/index.ts
new file mode 100644
index 0000000000..ed87fd9d01
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/index.ts
@@ -0,0 +1,24 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export * from './binaryBody';
+export * from './blameRow';
+export * from './blameRowUserId';
+export * from './copyDocumentRequest';
+export * from './copyDocumentRequestVersionId';
+export * from './documentActivePeersParams';
+export * from './documentMetadata';
+export * from './documentStateParams';
+export * from './getSnapshotRequest';
+export * from './getSnapshotRequestVersionId';
+export * from './peerResponse';
+export * from './peerWithUserId';
+export * from './snapshotResponse';
+export * from './updateRequest';
+export * from './updateResponse';
+export * from './versionIndicator';
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerResponse.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerResponse.ts
new file mode 100644
index 0000000000..d08e565ac9
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerResponse.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface PeerResponse {
+ peer_id: string;
+ user_id: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerWithUserId.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerWithUserId.ts
new file mode 100644
index 0000000000..8b3c4b0625
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/peerWithUserId.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface PeerWithUserId {
+ peer_id: string;
+ user_id: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/snapshotResponse.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/snapshotResponse.ts
new file mode 100644
index 0000000000..f2fcba3024
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/snapshotResponse.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface SnapshotResponse {
+ revision: string;
+ snapshot: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateRequest.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateRequest.ts
new file mode 100644
index 0000000000..c631f10c0e
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateRequest.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface UpdateRequest {
+ expectedRevision: string;
+ update: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateResponse.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateResponse.ts
new file mode 100644
index 0000000000..4222d25aa0
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/updateResponse.ts
@@ -0,0 +1,12 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface UpdateResponse {
+ applied: boolean;
+ revision: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/versionIndicator.ts b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/versionIndicator.ts
new file mode 100644
index 0000000000..361d1ba36c
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/generated/http/schemas/versionIndicator.ts
@@ -0,0 +1,13 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * Sync Service
+ * Document sync service JSON control plane
+ * OpenAPI spec version: 0.1.0
+ */
+
+export interface VersionIndicator {
+ counter: number;
+ /** Json has trouble with peer id bigints, so we need to serialize from a string */
+ peer: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-sync/openapi.json b/apps/web/src/lib/service-clients/service-sync/openapi.json
new file mode 100644
index 0000000000..f7266c5393
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-sync/openapi.json
@@ -0,0 +1,725 @@
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "Sync Service",
+ "description": "Document sync service JSON control plane",
+ "contact": {
+ "name": "Macro"
+ },
+ "version": "0.1.0"
+ },
+ "paths": {
+ "/document/{document_id}/active_peers": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_active_peers",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "include_ai",
+ "in": "query",
+ "description": "Set to `false` or `0` to filter out AI editors",
+ "required": false,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Active peer ids",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "401": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/blame/{node_id}": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_blame",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "node_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/BlameRow"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/copy": {
+ "post": {
+ "tags": ["sync_service"],
+ "operationId": "copy_document",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "description": "Source document to copy from",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CopyDocumentRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Copy succeeded; the new document was initialized"
+ },
+ "404": {
+ "description": "Source snapshot not found"
+ }
+ }
+ }
+ },
+ "/document/{document_id}/delete": {
+ "delete": {
+ "tags": ["sync_service"],
+ "operationId": "document_delete",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": ""
+ },
+ "401": {
+ "description": ""
+ },
+ "403": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/exists": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_exists",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Document exists"
+ },
+ "404": {
+ "description": "Not found"
+ }
+ }
+ }
+ },
+ "/document/{document_id}/initialize": {
+ "post": {
+ "tags": ["sync_service"],
+ "operationId": "document_initialize",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "$ref": "#/components/schemas/BinaryBody"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Initialized"
+ },
+ "401": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/metadata": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_metadata",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DocumentMetadata"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/peer/{peer_id}": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_peer",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "peer_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PeerResponse"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/document/{document_id}/raw": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_raw",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Raw document JSON"
+ },
+ "401": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/snapshot": {
+ "post": {
+ "tags": ["sync_service"],
+ "operationId": "document_snapshot",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetSnapshotRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Loro snapshot bytes",
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "$ref": "#/components/schemas/BinaryBody"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": ""
+ },
+ "401": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ },
+ {
+ "internal_key": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/state": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_state",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ },
+ {
+ "name": "shallow",
+ "in": "query",
+ "description": "Return current state without prior edit history",
+ "required": false,
+ "schema": {
+ "type": "boolean"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SnapshotResponse"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": ""
+ },
+ "403": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/update": {
+ "post": {
+ "tags": ["sync_service"],
+ "operationId": "document_update",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateResponse"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": ""
+ },
+ "401": {
+ "description": ""
+ },
+ "403": {
+ "description": ""
+ },
+ "404": {
+ "description": ""
+ },
+ "409": {
+ "description": ""
+ },
+ "413": {
+ "description": ""
+ },
+ "500": {
+ "description": ""
+ },
+ "503": {
+ "description": ""
+ }
+ },
+ "security": [
+ {
+ "document_permission": []
+ }
+ ]
+ }
+ },
+ "/document/{document_id}/wakeup": {
+ "get": {
+ "tags": ["sync_service"],
+ "operationId": "document_wakeup",
+ "parameters": [
+ {
+ "name": "document_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Keepalive scheduled"
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "BinaryBody": {
+ "type": "string",
+ "format": "binary"
+ },
+ "BlameRow": {
+ "type": "object",
+ "required": ["peer_id", "timestamp_ms"],
+ "properties": {
+ "peer_id": {
+ "type": "string"
+ },
+ "timestamp_ms": {
+ "type": "integer",
+ "format": "int64"
+ },
+ "user_id": {
+ "type": ["string", "null"]
+ }
+ }
+ },
+ "CopyDocumentRequest": {
+ "type": "object",
+ "required": ["target_document_id"],
+ "properties": {
+ "target_document_id": {
+ "type": "string"
+ },
+ "version_id": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/VersionIndicator"
+ }
+ ]
+ }
+ }
+ },
+ "DocumentMetadata": {
+ "type": "object",
+ "required": ["id", "peers", "version_id"],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "peers": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/PeerWithUserId"
+ }
+ },
+ "version_id": {
+ "type": "string"
+ }
+ }
+ },
+ "GetSnapshotRequest": {
+ "type": "object",
+ "properties": {
+ "version_id": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/VersionIndicator"
+ }
+ ]
+ }
+ }
+ },
+ "PeerResponse": {
+ "type": "object",
+ "required": ["peer_id", "user_id"],
+ "properties": {
+ "peer_id": {
+ "type": "string"
+ },
+ "user_id": {
+ "type": "string"
+ }
+ }
+ },
+ "PeerWithUserId": {
+ "type": "object",
+ "required": ["peer_id", "user_id"],
+ "properties": {
+ "peer_id": {
+ "type": "string"
+ },
+ "user_id": {
+ "type": "string"
+ }
+ }
+ },
+ "SnapshotResponse": {
+ "type": "object",
+ "required": ["snapshot", "revision"],
+ "properties": {
+ "revision": {
+ "type": "string"
+ },
+ "snapshot": {
+ "type": "string"
+ }
+ }
+ },
+ "UpdateRequest": {
+ "type": "object",
+ "required": ["expectedRevision", "update"],
+ "properties": {
+ "expectedRevision": {
+ "type": "string"
+ },
+ "update": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ },
+ "UpdateResponse": {
+ "type": "object",
+ "required": ["revision", "applied"],
+ "properties": {
+ "applied": {
+ "type": "boolean"
+ },
+ "revision": {
+ "type": "string"
+ }
+ }
+ },
+ "VersionIndicator": {
+ "type": "object",
+ "required": ["peer", "counter"],
+ "properties": {
+ "counter": {
+ "type": "integer",
+ "format": "int32"
+ },
+ "peer": {
+ "type": "string",
+ "description": "Json has trouble with peer id bigints, so we need to serialize from a string"
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "document_permission": {
+ "type": "http",
+ "scheme": "bearer"
+ },
+ "internal_key": {
+ "type": "apiKey",
+ "in": "header",
+ "name": "x-internal-auth-key"
+ }
+ }
+ },
+ "tags": [
+ {
+ "name": "sync_service",
+ "description": "Sync service"
+ }
+ ]
+}
diff --git a/services/sync-service/AGENTS.md b/services/sync-service/AGENTS.md
index 4a235ff152..39b5cd4dbb 100644
--- a/services/sync-service/AGENTS.md
+++ b/services/sync-service/AGENTS.md
@@ -12,17 +12,23 @@ updates over WebSocket.
- `README.md`: project structure, Durable Object lifecycle (in-memory vs
persistent state, the keep-alive alarm), JWT auth, and Bebop codegen. Read
it before changing this service.
-- `src/durable_object.rs` + `src/durable_object/document_api.rs`: the Durable
+- `src/inbound/durable_object.rs` + `src/inbound/durable_object/document_api.rs`: the Durable
Object — WebSocket handling, loro document state, alarm-driven snapshotting.
-- `src/durable_object/surface_api.rs`, `surface_migration.rs`: non-document
+- `src/inbound/durable_object/surface_api.rs`, `surface_migration.rs`: non-document
surfaces (spreadsheets, forms, etc.) hosted the same way.
-- `src/storage/` + `src/storage/backends/`: snapshot/op-log persistence,
+- `src/outbound/storage/` + `src/outbound/storage/backends/`: snapshot/op-log persistence,
pluggable across D1/KV/R2/combined backends (see the Cargo feature flags).
-- `src/auth.rs`: JWT verification against tokens minted by
+- `src/inbound/auth.rs` + `src/inbound/credentials.rs`: route-specific access
+ extractors and JWT verification against tokens minted by
`document_storage_service`.
- `build.rs` + `bebop-schema/`, `bebop/`: Bebop wire schema and codegen for
Rust and TypeScript bindings.
+- `src/inbound/router.rs` + `src/inbound/worker.rs`: Axum document/surface
+ routing and worker proxy/copy orchestration.
+- `src/domain/permissions.rs` + `src/domain/document.rs`: session permission
+ policy and content-agnostic atomic update use cases.
+
## Scope
- Owns: real-time sync of Loro documents over WebSocket, snapshot
@@ -35,20 +41,26 @@ updates over WebSocket.
- Change the wire protocol: `bebop/schema.bop` → `cd bebop && npx bebop-tools build`
(TS bindings) → `worker-build` regenerates Rust bindings via `build.rs`.
-- Add a storage backend: `src/storage/backends/` (new file + `mod.rs`) → gate
- it behind a new feature in `Cargo.toml` → wire into `src/storage.rs`.
-- Add a non-document surface: `src/durable_object/surface_api.rs` →
+- Add a storage backend: `src/outbound/storage/backends/` (new file + `mod.rs`) → gate
+ it behind a new feature in `Cargo.toml` → wire into `src/outbound/storage.rs`.
+- Add a non-document surface: `src/inbound/durable_object/surface_api.rs` →
`src/domain/` (surface-specific logic) → migration in
- `src/durable_object/surface_migration.rs` if it changes stored shape.
+ `src/inbound/durable_object/surface_migration.rs` if it changes stored shape.
Active-peer queries with `include_ai=false` exclude signed agent actors and the
legacy reserved AI peer range; Canvas workers use random full-width peer IDs.
+Document read/write/debug handlers declare their minimum session grant through
+Axum extractors; atomic reads/updates require a signed document grant even when
+an internal key is present. Surface grants remain kind-discriminated and exact
+to the requested surface. These are scoped sync JWTs, not app-session tokens.
+
## Checks
- `just test` (runs `worker-build`, then `npx vitest run` and `cargo test`)
from this directory.
-- `just test-no-alarm` to verify core logic without `alarm-keep-alive`.
+- `just test-no-alarm` to verify the legacy feature selection; alarms now run
+ regardless of the retained `alarm-keep-alive` compatibility flag.
- Use Node.js 22.12+/24.x/26+ for Vitest 5; install JS deps with `npm ci`
(`package-lock.json` is authoritative, not `bun.lock`).
@@ -60,7 +72,7 @@ legacy reserved AI peer range; Canvas workers use random full-width peer IDs.
10s of inactivity even with open connections; the alarm-based heartbeat in
`src/keepalive.rs` is what keeps it warm, not WebSocket traffic.
- The Durable Object handles one request or WebSocket message at a time
- (`mutation_barrier` in `src/durable_object.rs`). Keep per-update work
+ (`mutation_barrier` in `src/inbound/durable_object.rs`). Keep per-update work
proportional to the update; `LoroDoc::diff`, `fork`, and checkouts cost time
that grows with document history. A backlog past `DEFAULT_TIMEOUT_MS` (4.5 s)
makes the front worker fail connects, which clients see as close 1006.
diff --git a/services/sync-service/Cargo.toml b/services/sync-service/Cargo.toml
index ba8be170fe..1ab553977f 100644
--- a/services/sync-service/Cargo.toml
+++ b/services/sync-service/Cargo.toml
@@ -18,9 +18,15 @@ search-service = []
bebop-owned-all = ["sync_service_bebop_schema/bebop-owned-all"]
create-default-state = []
alarm-keep-alive = []
+openapi = ["dep:utoipa"]
[lib]
-crate-type = ["cdylib"]
+crate-type = ["cdylib", "rlib"]
+
+[[bin]]
+name = "sync_service_openapi"
+path = "src/bins/openapi.rs"
+required-features = ["openapi"]
[package.metadata.release]
release = false
@@ -30,7 +36,7 @@ release = false
wasm-opt = true
[dependencies]
-worker = { workspace = true, features = ['d1'] }
+worker = { workspace = true, features = ['d1', 'http', 'axum'] }
tracing.workspace = true
tracing-subscriber = { workspace = true, features = [
'time',
@@ -48,9 +54,20 @@ wasm-bindgen.workspace = true
uuid = { workspace = true, features = ["js"] }
loro.workspace = true
macro_sync_service_jwt = { path = "../../crates/macro_sync_service_jwt" }
-matchit = "0.8.4"
worker-rs-otel = { path = "../../crates/worker-rs-otel" }
subtle = { workspace = true }
base64.workspace = true
futures.workspace = true
thiserror.workspace = true
+
+# Workers cannot enable the workspace's native Tokio/compression features.
+[target.'cfg(target_family = "wasm")'.dependencies]
+axum = { version = "0.8", default-features = false, features = ["json", "query"] }
+
+[target.'cfg(not(target_family = "wasm"))'.dependencies]
+axum = { workspace = true }
+# Keep native-only schema generation out of the worker build.
+utoipa = { version = "5.4.0", optional = true }
+
+[dependencies.tower-service]
+workspace = true
diff --git a/services/sync-service/README.md b/services/sync-service/README.md
index 3455f567d0..380a8b477e 100644
--- a/services/sync-service/README.md
+++ b/services/sync-service/README.md
@@ -33,8 +33,27 @@ When a client updates a document via a WebSocket message, we apply the update to
Unfortunately, query params are the best way to authenticate a websocket connection. Since we use tls, query params should be encrypted in transit.
the `sync-service` will verify the jwt and ensure that the user has the correct permissions to access the document.
-TODO: eventually we will want to validate based on the `access_level` field in the token that the user only receives updates and does not push any updates to the document.
-
+HTTP routes use Axum `FromRequestParts` extractors to authenticate before the
+handler runs. Document view/edit/admin routes declare their minimum grant;
+atomic state/update routes require an exact signed document grant, and internal
+management routes require the shared service credential. Surface reads and
+connects require an exact, kind-discriminated surface JWT. WebSocket query tokens
+are validated against the requested session before accepting the upgrade.
+
+`src/inbound/` owns routing, credential decoding and Cloudflare callbacks;
+`src/domain/` owns permission/write policy and atomic document-update logic;
+`src/outbound/` owns persistence, secrets and external clients. The Cloudflare
+callback adapter shares one isolate-local session through `Rc`, preserving the
+mutation barrier across HTTP requests, WebSocket messages, alarms and closes.
+
+Socket write policy allows viewers to read, document commenters to change only
+comment marks, and editors to write full updates. Surface commenters cannot
+write. The HTTP API schema is generated with `just openapi`; WebSocket messages
+continue to use the Bebop schema. Regenerate the HTTP types from
+`apps/web/src/lib/service-clients` with
+`bun run orval --config orval.config.ts --project syncService`. The existing web
+transport handles binary payloads and permission tokens; Orval generates shared
+models only.
## Bebop
The bebop schema is defined in `./bebop/schema.bop`.
@@ -66,9 +85,10 @@ adds `create-default-state`; `alarm-keep-alive` is opt-in.
from existing state on the client. If a client fetches a document for the first time the worker will create
some default state for it. In the future, this feature should be disabled, and we should be inheriting default state
from the client.
-- `alarm-keep-alive`: This feature is used to prevent the in-memory state from being evicted when there are still
-active connections to the document. :warning: Tests should be run with both this feature enabled and disabled, to ensure
-that in a case where eviction logic is not working as expected, the core logic is still correct even though it might be slower.
+- `alarm-keep-alive`: Retained for compatibility with existing build commands.
+ Active sessions always schedule persistence/keep-alive alarms; this flag no
+ longer changes runtime behavior. `just test-no-alarm` checks the legacy feature
+ selection.
## Development
diff --git a/services/sync-service/justfile b/services/sync-service/justfile
index a4dde9b1d0..9488bf8a0c 100644
--- a/services/sync-service/justfile
+++ b/services/sync-service/justfile
@@ -55,3 +55,7 @@ migrate-d1-prod:
# CI runs the same two steps (.github/workflows/deploy_sync_service.yml)
deploy-prod: migrate-d1-prod
npx wrangler deploy --env prod
+
+openapi:
+ cargo run --quiet --bin sync_service_openapi --features openapi > ../../apps/web/src/lib/service-clients/service-sync/openapi.json
+ \cd ../../apps/web && bunx --bun @biomejs/biome format --write src/lib/service-clients/service-sync/openapi.json
diff --git a/services/sync-service/src/auth.rs b/services/sync-service/src/auth.rs
deleted file mode 100644
index ebf651df0c..0000000000
--- a/services/sync-service/src/auth.rs
+++ /dev/null
@@ -1,228 +0,0 @@
-use macro_sync_service_jwt::session::{
- SessionIdentity, SessionKind, SurfaceAccessLevel, decode_surface,
-};
-use serde::{Deserialize, Serialize};
-use subtle::ConstantTimeEq;
-use worker::Error;
-
-use crate::{constants::header_names, error::ResultExt, secrets::Secrets};
-
-#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, PartialOrd, Ord, Default)]
-#[serde(rename_all = "lowercase")]
-pub enum AccessLevel {
- #[default]
- View = 0,
- /// Document sockets may write comment marks; surfaces may not write.
- Comment = 1,
- Edit = 2,
- Owner = 3,
- Admin = 4,
-}
-
-/// What a session may change in the document it is connected to.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum WriteAccess {
- None,
- /// Comment anchors live in the document body, so commenting writes it;
- /// every other change must be rejected.
- CommentMarks,
- Full,
-}
-
-impl AccessLevel {
- pub fn write_access_for(&self, kind: SessionKind) -> WriteAccess {
- match (self, kind) {
- (Self::View, _) | (Self::Comment, SessionKind::Surface) => WriteAccess::None,
- (Self::Comment, SessionKind::Document) => WriteAccess::CommentMarks,
- (Self::Edit | Self::Owner | Self::Admin, _) => WriteAccess::Full,
- }
- }
-}
-
-/// Verified grant normalized at the dedicated session access boundary.
-#[derive(Debug)]
-pub struct AuthToken {
- pub user_id: Option<String>,
- document_id: String,
- pub access_level: AccessLevel,
- pub actor: Option<String>,
- pub session_kind: SessionKind,
- pub expires_at: Option<usize>,
-}
-
-#[derive(Deserialize)]
-struct DocumentClaims {
- user_id: Option<String>,
- document_id: String,
- access_level: AccessLevel,
- actor: Option<String>,
- session_kind: Option<SessionKind>,
- surface_id: Option<String>,
-}
-
-impl AuthToken {
- pub fn has_permission(&self, level: &AccessLevel) -> bool {
- self.access_level >= *level
- }
-
- pub fn has_document_id_access(&self, document_id: &str) -> bool {
- self.session_kind == SessionKind::Document
- && (self.document_id == document_id || self.access_level == AccessLevel::Admin)
- }
-}
-
-#[derive(Deserialize, Debug)]
-pub struct WebsocketQueryParams {
- pub token: String,
-}
-
-pub enum TokenFrom {
- Headers,
- QueryParams,
-}
-
-pub fn is_internal(req: &worker::Request, env: &worker::Env) -> worker::Result<bool> {
- let Some(key) = req
- .headers()
- .get(header_names::MACRO_INTERNAL_AUTH_KEY_HEADER_KEY)?
- else {
- return Ok(false);
- };
- Ok(key
- .as_bytes()
- .ct_eq(Secrets::from(env).internal_api_secret.as_bytes())
- .into())
-}
-
-fn request_token(req: &worker::Request, source: TokenFrom) -> worker::Result<String> {
- match source {
- TokenFrom::Headers => req
- .headers()
- .get(header_names::AUTHORIZATION)?
- .and_then(|header| header.strip_prefix("Bearer ").map(str::to_owned))
- .ok_or_else(|| Error::from("Missing or malformed Bearer authorization")),
- TokenFrom::QueryParams => Ok(req.query::<WebsocketQueryParams>()?.token),
- }
-}
-
-fn decode_document_token(token: &str, secret: &str) -> worker::Result<AuthToken> {
- let claims = macro_sync_service_jwt::decode::<DocumentClaims>(token, secret)
- .context("failed to decode document grant")?;
- if claims
- .session_kind
- .is_some_and(|kind| kind != SessionKind::Document)
- || claims.surface_id.is_some()
- {
- return Err(Error::from("surface grant cannot authorize a document"));
- }
- Ok(AuthToken {
- user_id: claims.user_id,
- document_id: claims.document_id,
- access_level: claims.access_level,
- actor: claims.actor,
- session_kind: SessionKind::Document,
- expires_at: None,
- })
-}
-
-fn decode_surface_token(
- token: &str,
- secret: &str,
- identity: &SessionIdentity,
-) -> worker::Result<AuthToken> {
- let claims = decode_surface(token, secret).context("failed to decode surface grant")?;
- if claims.session_identity() != *identity {
- return Err(Error::from("surface grant does not match session"));
- }
- let access_level = match claims.access_level {
- SurfaceAccessLevel::View => AccessLevel::View,
- SurfaceAccessLevel::Comment => AccessLevel::Comment,
- SurfaceAccessLevel::Edit => AccessLevel::Edit,
- SurfaceAccessLevel::Owner => AccessLevel::Owner,
- };
- Ok(AuthToken {
- user_id: claims.user_id,
- document_id: identity.storage_key(),
- access_level,
- actor: claims.actor,
- session_kind: SessionKind::Surface,
- expires_at: Some(claims.exp),
- })
-}
-
-pub fn surface_access(
- req: &worker::Request,
- env: &worker::Env,
- source: TokenFrom,
- identity: &SessionIdentity,
-) -> worker::Result<AuthToken> {
- decode_surface_token(
- &request_token(req, source)?,
- &Secrets::from(env).document_permissions_secret,
- identity,
- )
-}
-
-/// Authenticate a socket against the persisted, kind-discriminated storage key.
-pub fn socket_access(
- req: &worker::Request,
- env: &worker::Env,
- session_key: &str,
-) -> worker::Result<AuthToken> {
- if let Some(id) = session_key.strip_prefix("surface:") {
- let identity = SessionIdentity::new(SessionKind::Surface, id)
- .map_err(|error| Error::from(error.to_string()))?;
- return surface_access(req, env, TokenFrom::QueryParams, &identity);
- }
- let claims = decode_jwt(req, env, TokenFrom::QueryParams)?;
- if !claims.has_document_id_access(session_key) {
- return Err(Error::from("document grant does not match session"));
- }
- Ok(claims)
-}
-
-pub fn decode_jwt(
- req: &worker::Request,
- env: &worker::Env,
- source: TokenFrom,
-) -> worker::Result<AuthToken> {
- if matches!(source, TokenFrom::Headers) && is_internal(req, env)? {
- return Ok(AuthToken {
- user_id: None,
- document_id: String::new(),
- access_level: AccessLevel::Admin,
- actor: None,
- session_kind: SessionKind::Document,
- expires_at: None,
- });
- }
- decode_document_token(
- &request_token(req, source)?,
- &Secrets::from(env).document_permissions_secret,
- )
-}
-
-/// Dedicated access boundary for document HTTP requests. Internal service
-/// credentials do not substitute for a signed, document-scoped user grant.
-pub fn document_access(
- req: &worker::Request,
- env: &worker::Env,
- document_id: &str,
-) -> Result<
- (crate::domain::document::DocumentAccess, AuthToken),
- crate::domain::document::DocumentError,
-> {
- use crate::domain::document::DocumentError;
- let token = request_token(req, TokenFrom::Headers).map_err(|_| DocumentError::Unauthorized)?;
- let claims = decode_document_token(&token, &Secrets::from(env).document_permissions_secret)
- .map_err(|_| DocumentError::Unauthorized)?;
- let access = crate::domain::document::DocumentAccess::authorize(
- document_id,
- &claims.document_id,
- claims.access_level >= AccessLevel::Edit,
- )?;
- Ok((access, claims))
-}
-
-#[cfg(test)]
-mod test;
diff --git a/services/sync-service/src/bins/openapi.rs b/services/sync-service/src/bins/openapi.rs
new file mode 100644
index 0000000000..b8dc95b259
--- /dev/null
+++ b/services/sync-service/src/bins/openapi.rs
@@ -0,0 +1,7 @@
+use sync_service::swagger::ApiDoc;
+use utoipa::OpenApi;
+
+fn main() -> Result<(), serde_json::Error> {
+ println!("{}", ApiDoc::openapi().to_pretty_json()?);
+ Ok(())
+}
diff --git a/services/sync-service/src/domain.rs b/services/sync-service/src/domain.rs
index 54f38d0b07..8e5bc5f27c 100644
--- a/services/sync-service/src/domain.rs
+++ b/services/sync-service/src/domain.rs
@@ -1,3 +1,5 @@
//! Document synchronization policy, independent of content and storage.
pub mod document;
+pub mod models;
+pub mod permissions;
diff --git a/services/sync-service/src/domain/models.rs b/services/sync-service/src/domain/models.rs
new file mode 100644
index 0000000000..c582cd4d14
--- /dev/null
+++ b/services/sync-service/src/domain/models.rs
@@ -0,0 +1,50 @@
+#[derive(serde::Serialize, serde::Deserialize, Debug)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct VersionIndicator {
+ /// Json has trouble with peer id bigints, so we need to serialize from a string
+ pub peer: String,
+ pub counter: i32,
+}
+
+#[derive(serde::Deserialize, serde::Serialize, Debug)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct CopyDocumentRequest {
+ pub target_document_id: String,
+ pub version_id: Option<VersionIndicator>,
+}
+
+#[derive(serde::Deserialize, serde::Serialize, Debug)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct GetSnapshotRequest {
+ pub version_id: Option<VersionIndicator>,
+}
+
+#[derive(serde::Deserialize, serde::Serialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct DocumentMetadata {
+ pub id: String,
+ pub peers: Vec<PeerWithUserId>,
+ pub version_id: String,
+}
+
+#[derive(serde::Serialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct PeerResponse {
+ pub peer_id: String,
+ pub user_id: String,
+}
+
+#[derive(serde::Deserialize, serde::Serialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct PeerWithUserId {
+ pub peer_id: String,
+ pub user_id: String,
+}
+
+#[derive(serde::Deserialize, serde::Serialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub struct BlameRow {
+ pub peer_id: String,
+ pub user_id: Option<String>,
+ pub timestamp_ms: i64,
+}
diff --git a/services/sync-service/src/domain/permissions.rs b/services/sync-service/src/domain/permissions.rs
new file mode 100644
index 0000000000..7e27347996
--- /dev/null
+++ b/services/sync-service/src/domain/permissions.rs
@@ -0,0 +1,84 @@
+use macro_sync_service_jwt::session::SessionKind;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone, PartialOrd, Ord, Default)]
+#[serde(rename_all = "lowercase")]
+pub enum AccessLevel {
+ #[default]
+ View = 0,
+ /// Document sockets may write comment marks; surfaces may not write.
+ Comment = 1,
+ Edit = 2,
+ Owner = 3,
+ Admin = 4,
+}
+
+/// What a session may change in the document it is connected to.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WriteAccess {
+ None,
+ /// Comment anchors live in the document body, so commenting writes it;
+ /// every other change must be rejected.
+ CommentMarks,
+ Full,
+}
+
+/// Verified grant normalized at the dedicated session access boundary.
+#[derive(Debug)]
+pub struct AuthToken {
+ pub user_id: Option<String>,
+ pub(crate) document_id: String,
+ pub access_level: AccessLevel,
+ pub actor: Option<String>,
+ pub session_kind: SessionKind,
+ pub expires_at: Option<usize>,
+}
+
+impl AccessLevel {
+ pub fn write_access_for(&self, kind: SessionKind) -> WriteAccess {
+ match (self, kind) {
+ (Self::View, _) | (Self::Comment, SessionKind::Surface) => WriteAccess::None,
+ (Self::Comment, SessionKind::Document) => WriteAccess::CommentMarks,
+ (Self::Edit | Self::Owner | Self::Admin, _) => WriteAccess::Full,
+ }
+ }
+}
+
+impl AuthToken {
+ pub fn has_document_id_access(&self, document_id: &str) -> bool {
+ self.session_kind == SessionKind::Document
+ && (self.document_id == document_id || self.access_level == AccessLevel::Admin)
+ }
+}
+
+impl AuthToken {
+ /// Validate legacy document access, including document-admin grants.
+ pub fn require_document_permission(
+ &self,
+ id: &str,
+ level: &AccessLevel,
+ ) -> Result<(), super::document::DocumentError> {
+ if !self.has_document_id_access(id) || self.access_level < *level {
+ return Err(super::document::DocumentError::Unauthorized);
+ }
+ Ok(())
+ }
+
+ /// Atomic reads/updates always require an exact document-scoped grant.
+ pub fn document_access(
+ &self,
+ id: &str,
+ ) -> Result<super::document::DocumentAccess, super::document::DocumentError> {
+ if self.session_kind != SessionKind::Document {
+ return Err(super::document::DocumentError::Unauthorized);
+ }
+ super::document::DocumentAccess::authorize(
+ id,
+ &self.document_id,
+ self.access_level >= AccessLevel::Edit,
+ )
+ }
+}
+
+#[cfg(test)]
+mod test;
diff --git a/services/sync-service/src/domain/permissions/test.rs b/services/sync-service/src/domain/permissions/test.rs
new file mode 100644
index 0000000000..254477e761
--- /dev/null
+++ b/services/sync-service/src/domain/permissions/test.rs
@@ -0,0 +1,56 @@
+use super::*;
+
+#[test]
+fn document_grants_enforce_scope_and_minimum_permission() {
+ let token = AuthToken {
+ user_id: None,
+ document_id: "document-a".into(),
+ access_level: AccessLevel::View,
+ actor: None,
+ session_kind: SessionKind::Document,
+ expires_at: None,
+ };
+ assert!(
+ token
+ .require_document_permission("document-a", &AccessLevel::View)
+ .is_ok()
+ );
+ assert!(
+ token
+ .require_document_permission("document-a", &AccessLevel::Edit)
+ .is_err()
+ );
+ assert!(
+ token
+ .require_document_permission("document-b", &AccessLevel::View)
+ .is_err()
+ );
+ let access = token.document_access("document-a").unwrap();
+ assert!(access.require_edit().is_err());
+ assert!(token.document_access("document-b").is_err());
+}
+
+#[test]
+fn admin_grants_cannot_cross_document_scope_on_atomic_operations() {
+ let token = AuthToken {
+ user_id: None,
+ document_id: "document-a".into(),
+ access_level: AccessLevel::Admin,
+ actor: None,
+ session_kind: SessionKind::Document,
+ expires_at: None,
+ };
+ assert!(
+ token
+ .require_document_permission("document-b", &AccessLevel::Admin)
+ .is_ok()
+ );
+ assert!(
+ token
+ .document_access("document-a")
+ .unwrap()
+ .require_edit()
+ .is_ok()
+ );
+ assert!(token.document_access("document-b").is_err());
+}
diff --git a/services/sync-service/src/durable_object.rs b/services/sync-service/src/durable_object.rs
deleted file mode 100644
index 192e688e91..0000000000
--- a/services/sync-service/src/durable_object.rs
+++ /dev/null
@@ -1,1408 +0,0 @@
-use std::{
- borrow::Cow,
- collections::{BTreeMap, BTreeSet, HashMap},
- rc::Rc,
- sync::{Arc, LazyLock},
-};
-
-use bebop::Record;
-use loro::{ExportMode, awareness::EphemeralStore};
-use macro_sync_service_jwt::session::SessionKind;
-use matchit::Router;
-use serde::{Deserialize, Serialize};
-use tracing::{Instrument, debug, error, info, instrument, trace, warn};
-use worker::{
- Cors, Date, DurableObject, Env, Error, Method, Request, Response, ResponseBody,
- ResponseBuilder, Result, ScheduledTime, State, WebSocket, WebSocketIncomingMessage,
- WebSocketPair, durable_object,
-};
-
-use crate::{
- auth::{AccessLevel, TokenFrom, WriteAccess, decode_jwt, socket_access},
- constants::{SYSTEM_AUTHOR_ID, USER_PEER_D1_BINDING},
- d1::{
- PeerWithUserId, get_user_id_from_peer_id, insert_missing_user_mappings, insert_user_mapping,
- },
- domain::document::{DocumentAttribution, writing_peers},
- dss_internal::InteractionReason,
- error::ResultExt,
- generated::schema::InitializeFromSnapshotRequest,
- keepalive::{DEFAULT_TIME_TO_LIVE, keepalive},
- mutex::Mutex,
- socket::{InboundBuffers, Socket, protocol},
- state::DocumentState,
- storage::{
- SessionStorage, backends::durable_kv::DurableKVStorage, get_snapshot_storage,
- snapshot::SnapshotStorage,
- },
- tags::{get_ws_id_from_tags, new_ws_id},
- timeit,
-};
-
-pub const NO_SUCH_VALUE_ERR_STR: &str = "No such value in storage.";
-
-pub mod status_codes {
- pub const OK: u16 = 200;
- pub const NOT_FOUND: u16 = 404;
- pub const UNAUTH: u16 = 401;
- pub const FORBIDDEN: u16 = 403;
-}
-
-const DOCUMENT_ID_KEY: &str = "DOCUMENT_ID";
-
-mod document_api;
-mod document_delete;
-mod document_effects;
-mod peer_ids;
-mod surface_api;
-pub(crate) mod surface_migration;
-
-use document_effects::{report_interaction, report_new_doc_state};
-use surface_api::{SurfaceLifecycle, session_kind_from_storage_key};
-
-mod path {
- pub const CONNECT: &str = "connect";
- pub const DELETE: &str = "delete";
- pub const EXISTS: &str = "exists";
- pub const INITIALIZE: &str = "initialize";
- pub const RAW: &str = "raw";
- pub const SNAPSHOT: &str = "snapshot";
- pub const STATE: &str = "state";
- pub const UPDATE: &str = "update";
- pub const ACTIVE_PEERS_MARKER: &str = "active_peers";
- pub const PEER: &str = "peer";
- pub const METADATA: &str = "metadata";
- pub const BLAME: &str = "blame";
- pub const DEBUG_DUMP_OPERATIONS: &str = "debug_dump_operations";
- pub const DEBUG_DO_KV_GET: &str = "debug_do_kv_get";
- pub const DEBUG_DO_KV_LIST: &str = "debug_do_kv_list";
- pub const WAKEUP: &str = "wakeup";
-}
-
-pub fn response(status_code: u16) -> Response {
- Response::builder().with_status(status_code).empty()
-}
-
-#[macro_export]
-macro_rules! maybe_404 {
- ($res:expr) => {
- match $res {
- Ok(x) => Ok(x),
- Err(Error::JsError(s)) => {
- if s.contains(NO_SUCH_VALUE_ERR_STR) {
- return Ok(ResponseBuilder::new()
- .with_status(status_codes::NOT_FOUND)
- .empty());
- } else {
- Err(Error::JsError(s))
- }
- }
- Err(e) => Err(e),
- }
- };
-}
-
-macro_rules! or_unauth {
- ($none_if_unauth:expr) => {{
- let out = match $none_if_unauth {
- Some(x) => x,
- None => return Ok(response(status_codes::UNAUTH)),
- };
- out
- }};
-}
-
-#[derive(Debug, Serialize, Deserialize, Clone)]
-pub struct WebSocketMetadata {
- pub user_id: Option<String>,
- pub access_level: AccessLevel,
- #[serde(default, skip_serializing_if = "Option::is_none")]
- pub actor: Option<String>,
- #[serde(with = "u64_serde_strings")]
- pub peer_ids: BTreeSet<u64>,
- #[serde(default = "surface_api::document_kind")]
- pub session_kind: SessionKind,
- #[serde(default, skip_serializing_if = "Option::is_none")]
- pub expires_at: Option<usize>,
-}
-
-pub type WsMetaMap = BTreeMap<String, WebSocketMetadata>;
-
-#[durable_object]
-pub struct DocumentSyncSession {
- state: State,
- env: Env,
- /// id of the document, comes from URL path
- document_id: Mutex<Option<Arc<String>>>,
- /// Current document state
- document_state: Mutex<Option<Arc<DocumentState>>>,
- /// Access to document related IO
- session_storage: Mutex<Option<Rc<SessionStorage>>>,
- awareness: EphemeralStore,
- /// a map from websocket's ID's to websocket metadata
- ws_meta_map: Arc<Mutex<WsMetaMap>>,
- /// Partial inbound messages, isolated by connection.
- inbound: InboundBuffers,
- /// Buffered blame events. Flushed via D1 batch on each alarm tick.
- pending_blame: Arc<Mutex<Vec<crate::d1::BlameEvent>>>,
- /// Distinct editors since the last snapshot notification.
- pending_editors: Arc<Mutex<BTreeSet<DocumentAttribution>>>,
- /// Writing peers already recorded in D1 since this object woke, so
- /// updates skip remapping them.
- mapped_writing_peers: Mutex<BTreeSet<u64>>,
- surface_lifecycle: Mutex<Option<SurfaceLifecycle>>,
- source_migration: Mutex<Option<surface_migration::SourceState>>,
- // Serialize whole callbacks, including persistence awaits. A freeze must
- // drain every in-flight mutation before it exports or closes writers.
- mutation_barrier: futures::lock::Mutex<()>,
-}
-
-mod u64_serde_strings {
- use serde::{Deserialize, Deserializer, Serialize, Serializer};
- use std::collections::BTreeSet;
-
- pub fn serialize<S: Serializer>(
- value: &BTreeSet<u64>,
- serializer: S,
- ) -> Result<S::Ok, S::Error> {
- let string_set: BTreeSet<String> = value.iter().map(|x| x.to_string()).collect();
- string_set.serialize(serializer)
- }
-
- pub fn deserialize<'de, D: Deserializer<'de>>(
- deserializer: D,
- ) -> Result<BTreeSet<u64>, D::Error> {
- let string_set: BTreeSet<String> = BTreeSet::deserialize(deserializer)?;
- string_set
- .into_iter()
- .map(|s| s.parse::<u64>().map_err(serde::de::Error::custom))
- .collect()
- }
- #[cfg(test)]
- mod test {
- use super::*;
- #[derive(Serialize, Deserialize)]
- struct Foo {
- #[serde(with = "super")]
- set: BTreeSet<u64>,
- }
- #[test]
- fn serde_u64_btree_set() -> std::result::Result<(), Box<dyn std::error::Error>> {
- let data = BTreeSet::from([1_u64, u64::MAX, u64::MIN, 0, 42]);
- let obj = Foo { set: data.clone() };
- let json = serde_json::to_string(&obj)?;
- let result: Foo = serde_json::from_str(&json)?;
- assert_eq!(result.set, data);
- Ok(())
- }
- }
-}
-
-pub struct Wsm<'a> {
- dss: &'a DocumentSyncSession,
- ws: &'a WebSocket,
- ws_id: Option<String>,
-}
-impl<'a> Wsm<'a> {
- pub fn new(dss: &'a DocumentSyncSession, ws: &'a WebSocket) -> Self {
- Self {
- dss,
- ws,
- ws_id: None,
- }
- }
- fn get_ws_id(&mut self) -> Result<&str> {
- if self.ws_id.is_none() {
- let tags = self.dss.state.get_tags(self.ws);
- let ws_id = get_ws_id_from_tags(&tags)?;
- self.ws_id = Some(ws_id);
- }
- Ok(self.ws_id.as_ref().unwrap())
- }
- async fn maybe_update_ws_meta_map(&mut self) -> Result<()> {
- let ws_id = self.get_ws_id()?.to_string();
- if !self
- .dss
- .ws_meta_map
- .lock("Wsm::maybe_update_ws_meta_map contains_key")
- .contains_key(&ws_id)
- {
- let wsm: WebSocketMetadata = self
- .dss
- .state
- .storage()
- .get(&ws_id)
- .await?
- .ok_or(Error::from("WebSocketMetadata not found in storage"))?;
- self.dss
- .ws_meta_map
- .lock("Wsm::maybe_update_ws_meta_map insert")
- .insert(ws_id, wsm);
- }
- Ok(())
- }
- pub async fn get_peer_ids(&mut self, include_ai: bool) -> Result<Vec<u64>> {
- self.maybe_update_ws_meta_map().await?;
- let ws_id = self.get_ws_id()?.to_string();
- Ok(self
- .dss
- .ws_meta_map
- .lock("Wsm::get_peer_ids get")
- .get(&ws_id)
- .ok_or(Error::from("missing ws metadata"))?
- .active_peer_ids(include_ai))
- }
-
- pub async fn edit_attribution(&mut self) -> Result<Option<DocumentAttribution>> {
- self.maybe_update_ws_meta_map().await?;
- let ws_id = self.get_ws_id()?.to_string();
- let map = self.dss.ws_meta_map.lock("Wsm::edit_attribution");
- let meta = map.get(&ws_id).context("missing ws metadata")?;
- DocumentAttribution::from_session_claims(meta.actor.clone(), meta.user_id.clone())
- .context("invalid signed websocket attribution")
- }
-
- pub async fn write_access(&mut self) -> Result<WriteAccess> {
- self.maybe_update_ws_meta_map().await?;
- let ws_id = self.get_ws_id()?.to_string();
- Ok(self
- .dss
- .ws_meta_map
- .lock("Wsm::write_access get")
- .get(&ws_id)
- .ok_or(Error::from("missing ws metadata"))?
- .write_access())
- }
-
- pub async fn add_new_peerid(&mut self, peerid: u64, document_id: &str) -> Result<()> {
- self.maybe_update_ws_meta_map().await?;
-
- let ws_id = self.get_ws_id()?.to_string();
-
- let new_peer = {
- let mut wmm = self.dss.ws_meta_map.lock("Wsm::add_new_peerid get_mut");
- let meta = wmm
- .get_mut(&ws_id)
- .ok_or(Error::from("missing ws metadata"))?;
-
- if meta.peer_ids.insert(peerid) {
- Some(meta.clone())
- } else {
- None
- }
- };
- if let Some(meta) = new_peer {
- self.dss.state.storage().put(&ws_id, &meta).await?;
- // if user is not-anon
- if let Some(user_id) = meta.user_id {
- let db = self.dss.env.d1(USER_PEER_D1_BINDING)?;
- insert_user_mapping(db, &user_id, peerid, document_id).await?;
- }
- }
- Ok(())
- }
-}
-pub fn get_ws_id(state: &State, ws: &WebSocket) -> Result<String> {
- let tags = state.get_tags(ws);
- get_ws_id_from_tags(&tags)
-}
-
-/// Schedule an alarm 5 seconds from now.
-async fn bump_alarm(state: &State) -> Result<()> {
- let current_alarm = state.storage().get_alarm().await?;
-
- if let Some(current_alarm) = current_alarm
- && current_alarm as f64 > Date::now().as_millis() as f64
- {
- return Ok(());
- }
-
- state.storage().set_alarm(ScheduledTime::from(5000)).await?;
-
- Ok(())
-}
-
-fn take_editors(editors: &Mutex<BTreeSet<DocumentAttribution>>) -> Vec<DocumentAttribution> {
- std::mem::take(&mut *editors.lock("take document editors"))
- .into_iter()
- .collect()
-}
-
-impl DocumentSyncSession {
- pub(crate) fn env(&self) -> &Env {
- &self.env
- }
-
- pub(crate) fn socket_for(&self, ws: &WebSocket) -> Socket {
- Socket::new(ws.clone(), self.inbound.clone())
- }
-
- pub(crate) fn get_sockets(&self) -> Vec<Socket> {
- self.active_websockets()
- .into_iter()
- .map(|ws| self.socket_for(&ws))
- .collect()
- }
-
- pub fn get_websockets(&self) -> Vec<WebSocket> {
- self.active_websockets()
- }
-
- pub(crate) fn record_editor(&self, attribution: Option<&DocumentAttribution>) {
- if let Some(attribution) = attribution {
- self.pending_editors
- .lock("record document editor")
- .insert(attribution.clone());
- }
- }
-
- async fn forget_websocket_metadata(&self, ws: &WebSocket) {
- let Ok(ws_id) = get_ws_id(&self.state, ws) else {
- return;
- };
- self.socket_for(ws).forget(&ws_id);
- self.ws_meta_map
- .lock("DocumentSyncSession::forget_websocket_metadata")
- .remove(&ws_id);
- if let Err(err) = self.state.storage().delete(&ws_id).await {
- warn!(error=?err, ws_id, "failed to delete websocket metadata");
- }
- }
-
- pub fn push_blame_events(&self, events: Vec<crate::d1::BlameEvent>) {
- if events.is_empty() {
- return;
- }
- self.pending_blame
- .lock("DocumentSyncSession::push_blame_events")
- .extend(events);
- }
-
- /// Drain the pending blame buffer and write all events via a single D1
- /// batch in the background. Returns immediately; the actual write runs
- /// inside `wait_until` so the alarm handler doesn't block on D1.
- fn flush_pending_blame(&self) {
- let pending: Vec<crate::d1::BlameEvent> = std::mem::take(
- &mut *self
- .pending_blame
- .lock("DocumentSyncSession::flush_pending_blame"),
- );
- if pending.is_empty() {
- return;
- }
- let env = self.env.clone();
- self.state.wait_until(async move {
- if let Err(e) = crate::d1::insert_blame_many(&env, &pending).await {
- warn!(error = ?e, "failed to flush pending blame");
- }
- });
- }
- async fn inner_fetch(&self, req: Request) -> Result<Response> {
- let url = req.url()?;
- if url.path().starts_with("/surface/") {
- return self.surface_handler(req).await;
- }
- let segments: Vec<_> = url.path().split('/').collect();
- if let ["", "document", id, "migration", operation] = segments.as_slice() {
- return self.source_migration_handler(req, id, operation).await;
- }
- if self.source_blocked().await? {
- return Ok(response(status_codes::FORBIDDEN));
- }
- let matched = ROUTER
- .at(url.path())
- .with_context(|| format!("Failed to route url: [{url}]"))?;
-
- match (
- *matched.value,
- matched.params.get("document_id").inspect(|document_id| {
- tracing::Span::current().record("document.id", *document_id);
- trace!(route =? matched.value, document_id = document_id, "matched route");
- }),
- ) {
- // connect authenticates via jwt in query
- (path::CONNECT, Some(document_id)) => {
- return self.connect_handler(req, document_id).await;
- }
- (operation @ (path::STATE | path::UPDATE), Some(document_id)) => {
- return self
- .document_handler(req, document_id, operation == path::UPDATE)
- .await;
- }
-
- // EXIST, PEER, and WAKEUP don't require auth; DELETE requires the internal key
- (path_needs_claims, Some(document_id)) => match path_needs_claims {
- path::DELETE => return self.delete_handler(&req, document_id).await,
- path::EXISTS => return self.exists_handler(document_id).await,
- path::PEER => {
- return self
- .peer_handler(document_id, matched.params.get("peer_id"))
- .await;
- }
- path::WAKEUP => return self.wakeup(document_id).await,
- // These need auth
- rest => {
- let claims = or_unauth!(decode_jwt(&req, &self.env, TokenFrom::Headers).ok());
- or_unauth!(claims.has_document_id_access(document_id).then_some(()));
- match rest {
- path::METADATA => return self.metadata_handler(document_id).await,
- path::BLAME => {
- return self.blame_handler(matched.params.get("node_id")).await;
- }
- path::RAW => return self.raw_handler(document_id).await,
- path::SNAPSHOT => return self.snapshot_handler(req, document_id).await,
- path::ACTIVE_PEERS_MARKER => {
- // `?include_ai=false` filters out AI editors; default keeps them.
- let include_ai = req
- .url()?
- .query_pairs()
- .find(|(k, _)| k == "include_ai")
- .is_none_or(|(_, v)| !matches!(v.as_ref(), "false" | "0"));
- return self.active_peer_ids_handler(include_ai).await;
- }
- path::INITIALIZE => {
- or_unauth!(claims.has_permission(&AccessLevel::Edit).then_some(()));
- return self.initialize_handler(req, document_id).await;
- }
- path::DEBUG_DUMP_OPERATIONS => {
- or_unauth!(claims.has_permission(&AccessLevel::Admin).then_some(()));
- return self.dump_operations(document_id).await;
- }
- path::DEBUG_DO_KV_GET => {
- or_unauth!(claims.has_permission(&AccessLevel::Admin).then_some(()));
- let key = matched.params.get("key").context("missing key argoument")?;
- let value = self.session_storage().await?.debug_do_kv_get(key).await?;
- Response::from_json(&value)
- }
- path::DEBUG_DO_KV_LIST => {
- or_unauth!(claims.has_permission(&AccessLevel::Admin).then_some(()));
- let prefix = matched
- .params
- .get("prefix")
- .context("missing prefix argoument")?;
- let kvs: Vec<(String, Vec<u8>)> = self
- .session_storage()
- .await?
- .debug_list_do_kv(prefix)
- .await?
- .into_iter()
- .filter_map(|kv| kv.ok())
- .collect();
- Response::from_json(&kvs)
- }
- _ => Ok(response(status_codes::NOT_FOUND)),
- }
- }
- },
- (_, None) => Ok(response(status_codes::NOT_FOUND)),
- }
- }
-
- async fn initialize_handler(&self, mut req: Request, document_id: &str) -> Result<Response> {
- // NB: we expect DocumentSyncSession to not be initialized. If it is initialized, it's an error.
- let storage = get_snapshot_storage(&self.env, &self.state, document_id.to_string())?;
-
- if storage.has_snapshot().await? {
- return Response::error("snapshot already exists", 409);
- } else {
- debug!(document_id = document_id, "Initializing snapshot");
- let body_raw = req.bytes().await?;
- let body = InitializeFromSnapshotRequest::deserialize(&body_raw).with_context(|| format!("Failed to deserialize InitializeFromSnapshotRequest with document_id: [{document_id}]"))?;
- // Services initialize documents (imports, uploads, copies), so the
- // snapshot's peers belong to the system author unless already mapped.
- // Mapped before storing: a failed store is retried, a stored one is not.
- let writers = writing_peers(&body.snapshot)
- .map_err(|error| Error::from(format!("invalid initial snapshot: {error}")))?;
- let db = self.env.d1(USER_PEER_D1_BINDING)?;
- insert_missing_user_mappings(&db, document_id, SYSTEM_AUTHOR_ID, &writers).await?;
- storage.store_snapshot(&body.snapshot).await?;
- *self
- .document_id
- .lock("DocumentSyncSession::document_id set within initialize_handler") =
- Some(Arc::new(document_id.to_string()));
- self.state
- .storage()
- .put(DOCUMENT_ID_KEY, document_id.to_string())
- .await?;
- let dkv_storage = DurableKVStorage::new(self.state.storage());
- let session_storage = Rc::new(SessionStorage::new(
- storage,
- dkv_storage,
- SessionKind::Document,
- ));
- *self
- .session_storage
- .lock("DocumentSyncSession::session_storage set within initialize_handler") =
- Some(session_storage);
- }
-
- // Broadcast initial sync to any sockets that connected before init landed.
- if let Ok(state) = self.document_state().await
- && let Ok(snapshot) = state.export_shallow_snapshot()
- {
- let awareness = self.awareness.encode_all();
- for ws in &self.state.get_websockets() {
- if let Err(e) = protocol::send_initial_sync(
- &self.socket_for(ws),
- snapshot.as_slice(),
- awareness.as_slice(),
- ) {
- warn!(
- error =? e,
- "failed to send delayed initial sync to a waiting peer"
- );
- }
- }
- let document_id_owned = document_id.to_string();
- let env = self.env.clone();
- self.state.wait_until(async move {
- report_new_doc_state(&document_id_owned, &snapshot, &env, Vec::new()).await;
- });
- }
-
- Response::empty()
- }
-
- /// Active peer ids. With `include_ai = false`, AI editors (peer ids from the
- /// reserved AI block or signed agent actors) are filtered out.
- async fn active_peer_ids_handler(&self, include_ai: bool) -> Result<Response> {
- if !self.state.get_websockets().is_empty() {
- self.validate_surface_sockets(None).await?;
- }
- let mut peer_ids: BTreeSet<u64> = BTreeSet::new();
- for ws in self.get_websockets() {
- peer_ids.extend(Wsm::new(self, &ws).get_peer_ids(include_ai).await?);
- }
- let str_ids = peer_ids
- .into_iter()
- .map(|p| p.to_string())
- .collect::<Vec<String>>();
-
- let result = serde_json::to_vec(&str_ids).context("Failed to serialize ids")?;
- Ok(ResponseBuilder::new().body(ResponseBody::Body(result)))
- }
-
- async fn exists_handler(&self, id: &str) -> Result<Response> {
- Ok(response(if self.exists(id).await? {
- status_codes::OK
- } else {
- status_codes::NOT_FOUND
- }))
- }
-
- async fn raw_handler(&self, document_id: &str) -> Result<Response> {
- if !self.exists(document_id).await? {
- return Ok(response(status_codes::NOT_FOUND));
- }
- let out = maybe_404!(self.document_state().await)?.get_json();
- Ok(ResponseBuilder::new().body(ResponseBody::Body(out.into_bytes())))
- }
-
- async fn snapshot_handler(&self, mut req: Request, document_id: &str) -> Result<Response> {
- if !self.exists(document_id).await? {
- return Ok(response(status_codes::NOT_FOUND));
- }
-
- let bytes = req.bytes().await?;
- let body: Option<GetSnapshotRequest> = if bytes.is_empty() {
- None
- } else {
- Some(serde_json::from_slice(&bytes)?)
- };
-
- let frontiers: Option<ExportMode> = body.and_then(|b| {
- if let Some(vid) = b.version_id {
- let id = loro::ID::new(vid.peer.parse::<u64>().unwrap(), vid.counter);
- Some(ExportMode::StateOnly(Some(Cow::Owned(
- loro::Frontiers::ID(id),
- ))))
- } else {
- None
- }
- });
-
- let out = maybe_404!(self.document_state().await)?
- .export_snapshot(frontiers)
- .context("Couldn't export snapshot")?;
- Ok(ResponseBuilder::new().body(ResponseBody::Body(out)))
- }
-
- async fn dump_operations(&self, document_id: &str) -> Result<Response> {
- if !self.exists(document_id).await? {
- return Ok(response(status_codes::NOT_FOUND));
- }
- let pending_ops = self
- .session_storage()
- .await?
- .get_pending_operations()
- .await?;
-
- let n_pending_ops = pending_ops.len();
- trace!(
- pending_ops_len = n_pending_ops,
- "Applying [{}] pending ops", n_pending_ops
- );
-
- let mut ers = vec![];
- let mut key_ops = vec![];
- for res_op in pending_ops {
- match res_op {
- Ok((k, o)) => key_ops.push((k, o)),
- Err(e) => ers.push(e),
- }
- }
- if !ers.is_empty() {
- error!(errors =? ers, "DO KV operations got [{}] errors", ers.len());
- }
-
- ResponseBuilder::new().from_json(&key_ops)
- }
-
- async fn peer_handler(&self, document_id: &str, peer_id: Option<&str>) -> Result<Response> {
- let (user_id, peer_id) = if let Some(p) = peer_id {
- let p64: u64 = p
- .parse()
- .with_context(|| format!("Couldn't parse peer_id: '{p}' into u64"))?;
- let db = self.env.d1(USER_PEER_D1_BINDING)?;
- let user_id = get_user_id_from_peer_id(db, document_id, &p64).await?;
- (user_id, p.to_string())
- } else {
- return Err(Error::from("missing `peer_id` in path"));
- };
- ResponseBuilder::new().from_json(&PeerResponse { peer_id, user_id })
- }
-
- async fn wakeup(&self, document_id: &str) -> Result<Response> {
- let _ = self.warmup(document_id).await.inspect_err(
- |error| warn!(document_id = document_id, error = ?error, "failed to warm up document"),
- );
-
- let out = keepalive(DEFAULT_TIME_TO_LIVE);
- ResponseBuilder::new().from_json(&out)
- }
-
- async fn warmup(&self, document_id: &str) -> Result<()> {
- if !self.exists(document_id).await? {
- return Ok(());
- }
-
- self.session_storage().await?;
- self.document_state().await?;
- Ok(())
- }
-
- async fn metadata_handler(&self, document_id: &str) -> Result<Response> {
- if !self.exists(document_id).await? {
- return Ok(response(status_codes::NOT_FOUND));
- }
- let db = self.env.d1(USER_PEER_D1_BINDING)?;
- let peers = crate::d1::get_peers_for_document_id(db, document_id).await?;
- let version_id = self.document_state().await?.version_id();
- ResponseBuilder::new().from_json(&DocumentMetadata {
- peers,
- version_id: version_id.to_string(),
- id: document_id.to_string(),
- })
- }
-
- async fn blame_handler(&self, node_id: Option<&str>) -> Result<Response> {
- let node_id = node_id.ok_or_else(|| Error::from("missing node_id"))?;
- let document_id = self.document_id().await?.to_string();
- let db = self.env.d1(USER_PEER_D1_BINDING)?;
- match crate::d1::get_blame_for_node(db, &document_id, node_id).await? {
- Some(row) => ResponseBuilder::new().from_json(&row),
- None => Ok(response(status_codes::NOT_FOUND)),
- }
- }
-
- async fn connect_handler(&self, req: Request, document_id: &str) -> Result<Response> {
- let (res, elap) = timeit!({
- let claims = or_unauth!(socket_access(&req, &self.env, document_id).ok());
- if self.maybe_set_document_id(document_id).await? {
- trace!("init document_id={document_id}");
- } else {
- trace!("document_id={document_id} already set");
- }
-
- // Below is websocket stuff only i.e connect
- let pair = WebSocketPair::new().context("failed to create websocket pair")?;
-
- // Whether this peer is the first to join the session (used to
- // decide whether to report a `FirstJoin` interaction below).
- let is_first_join = self.state.get_websockets().is_empty();
-
- // create tag for ws and store it
- let ws_id = new_ws_id();
- trace!(ws_id = ws_id, "websocket connect");
-
- self.state
- .accept_websocket_with_tags(&pair.server, &[&ws_id]);
-
- let ws_meta = WebSocketMetadata {
- user_id: claims.user_id,
- access_level: claims.access_level,
- actor: claims.actor,
- peer_ids: Default::default(),
- session_kind: claims.session_kind,
- expires_at: claims.expires_at,
- };
-
- self.state.storage().put(&ws_id, &ws_meta).await?;
- self.ws_meta_map
- .lock("DocumentSyncSession::ws_meta_map insert in connect_handler")
- .insert(ws_id, ws_meta);
-
- // A surface may have been revoked while socket metadata was being
- // persisted. Recheck before sending any initial content.
- if claims.session_kind == SessionKind::Surface
- && !self.validate_surface_sockets(Some(&pair.server)).await?
- {
- return Ok(response(status_codes::FORBIDDEN));
- }
-
- // If the snapshot is already in storage, send the initial sync now.
- // Otherwise accept the WS without sending — initialize_handler will
- // broadcast initial sync to this socket once /initialize lands.
- let snapshot = self
- .document_state()
- .await
- .and_then(|state| state.export_shallow_snapshot());
-
- if let Ok(snapshot) = snapshot {
- // Size of the initial sync this connect sent — the server end
- // of the client's `doc.sync.initial-sync` span.
- tracing::Span::current().record("snapshot.bytes", snapshot.len());
- protocol::send_initial_sync(
- &self.socket_for(&pair.server),
- snapshot.as_slice(),
- self.awareness.encode_all().as_slice(),
- )
- .context("failed to send initial sync message")?;
- } else {
- debug!(
- document_id = document_id,
- "snapshot not yet available; deferring initial sync until /initialize"
- );
- }
-
- // This is the single source of truth for `FirstJoin`: whenever
- // the peer count genuinely transitions 0 -> 1, regardless of
- // whether the document already has content.
- if is_first_join {
- let document_id_owned = document_id.to_string();
- let env = self.env.clone();
- self.state.wait_until(async move {
- report_interaction(&document_id_owned, &env, InteractionReason::FirstJoin)
- .await;
- });
- }
-
- if claims.session_kind == SessionKind::Surface {
- bump_alarm(&self.state).await?;
- }
- Response::from_websocket(pair.client).context("failed to create websocket response")?
- });
-
- trace!(
- document_id = document_id,
- duration_ms = elap.as_millis(),
- "DO::connect"
- );
- Ok(res)
- }
-
- async fn maybe_set_document_id(&self, document_id: &str) -> Result<bool> {
- if !self.document_id_is_some() {
- debug!("Setting DO::kv({DOCUMENT_ID_KEY}, {document_id})");
- self.state
- .storage()
- .put(DOCUMENT_ID_KEY, document_id)
- .await?;
- *self
- .document_id
- .lock("DocumentSyncSession::document_id set within maybe_set_document_id") =
- Some(Arc::new(document_id.to_string()));
- Ok(true)
- } else {
- Ok(false)
- }
- }
-
- /// A connected room identity does not imply initialized collaborative content.
- async fn exists(&self, document_id: &str) -> Result<bool> {
- let snapshot_storage =
- get_snapshot_storage(&self.env, &self.state, document_id.to_string())?;
-
- if snapshot_storage.has_snapshot().await? {
- self.maybe_set_document_id(document_id).await?;
- // set up session storage
- let dkv_storage = DurableKVStorage::new(self.state.storage());
- let session_storage = Rc::new(SessionStorage::new(
- snapshot_storage,
- dkv_storage,
- session_kind_from_storage_key(document_id),
- ));
- *self
- .session_storage
- .lock("DocumentSyncSession::session_storage set within exists") =
- Some(session_storage);
- return Ok(true);
- }
- Ok(false)
- }
-
- fn document_id_is_some(&self) -> bool {
- self.document_id
- .lock("DocumentSyncSession::document_id check is_some()")
- .is_some()
- }
-
- #[instrument(skip_all, err)]
- /// Get the `document_id`. First try checking self.document_id, if not there get from DOKV.
- async fn document_id(&self) -> Result<Arc<String>> {
- self.try_document_id()
- .await?
- .ok_or(Error::from("DOCUMENT_ID not found in storage"))
- }
-
- /// Like [`Self::document_id`], but `None` instead of an error when this
- /// object holds no session.
- async fn try_document_id(&self) -> Result<Option<Arc<String>>> {
- if let Some(id) = self
- .document_id
- .lock("DocumentSyncSession::document_id get within main document_id fn")
- .as_ref()
- .cloned()
- {
- return Ok(Some(id));
- }
- let Some(id) = self
- .state
- .storage()
- .get::<String>(DOCUMENT_ID_KEY)
- .await
- .with_context(|| {
- format!(
- "Could not get document_id via DOCUMENT_ID_KEY = [{}] from DO storage",
- DOCUMENT_ID_KEY
- )
- })?
- else {
- return Ok(None);
- };
- let id = Arc::new(id);
- *self
- .document_id
- .lock("DocumentSyncSession::document_id set within main document_id fn") =
- Some(id.clone());
- Ok(Some(id))
- }
-
- async fn session_storage(&self) -> Result<Rc<SessionStorage>> {
- if let Some(ss) = self
- .session_storage
- .lock("session_storage get within main session_storage fn")
- .as_ref()
- {
- Ok(ss.clone())
- } else {
- let id = self.document_id().await?.to_string();
- let snapshot_storage = get_snapshot_storage(&self.env, &self.state, id.clone())?;
- let dkv_storage = DurableKVStorage::new(self.state.storage());
- let ss = Rc::new(SessionStorage::new(
- snapshot_storage,
- dkv_storage,
- session_kind_from_storage_key(&id),
- ));
- *self
- .session_storage
- .lock("DocumentSyncSession::session_storage set within main session_storage fn") =
- Some(ss.clone());
- Ok(ss)
- }
- }
-
- /// Gets DocumentState, loading it if needed
- async fn document_state(&self) -> Result<Arc<DocumentState>> {
- let Some(x) = self
- .document_state
- .lock("DocumentSyncSession::document_state get within main document_state fn")
- .as_ref()
- .cloned()
- else {
- let ss = Arc::new(self.session_storage().await?.load_document_state().await?);
- *self
- .document_state
- .lock("DocumentSyncSession::document_state set within main document_state fn") =
- Some(ss.clone());
- return Ok(ss);
- };
- Ok(x)
- }
-}
-
-pub static ROUTER: LazyLock<Router<&str>> = LazyLock::new(|| {
- let mut router = Router::new();
- router
- .insert("/document/{document_id}/connect", path::CONNECT)
- .unwrap();
- router
- .insert("/document/{document_id}/delete", path::DELETE)
- .unwrap();
- router
- .insert("/document/{document_id}/exists", path::EXISTS)
- .unwrap();
- router
- .insert("/document/{document_id}/initialize", path::INITIALIZE)
- .unwrap();
- router
- .insert("/document/{document_id}/raw", path::RAW)
- .unwrap();
- router
- .insert(
- "/document/{document_id}/active_peers",
- path::ACTIVE_PEERS_MARKER,
- )
- .unwrap();
- router
- .insert("/document/{document_id}/snapshot", path::SNAPSHOT)
- .unwrap();
- router
- .insert("/document/{document_id}/state", path::STATE)
- .unwrap();
- router
- .insert("/document/{document_id}/update", path::UPDATE)
- .unwrap();
- router
- .insert("/document/{document_id}/peer/{peer_id}", path::PEER)
- .unwrap();
- router
- .insert("/document/{document_id}/metadata", path::METADATA)
- .unwrap();
- router
- .insert("/document/{document_id}/blame/{node_id}", path::BLAME)
- .unwrap();
- router
- .insert(
- "/document/{document_id}/debug_dump_operations",
- path::DEBUG_DUMP_OPERATIONS,
- )
- .unwrap();
- router
- .insert(
- "/document/{document_id}/debug_do_kv_get/{key}",
- path::DEBUG_DO_KV_GET,
- )
- .unwrap();
- router
- .insert(
- "/document/{document_id}/debug_do_kv_list/{prefix}",
- path::DEBUG_DO_KV_LIST,
- )
- .unwrap();
- router
- .insert("/document/{document_id}/wakeup", path::WAKEUP)
- .unwrap();
- router
-});
-
-impl DurableObject for DocumentSyncSession {
- fn new(state: State, env: Env) -> Self {
- Self {
- state,
- env,
- document_id: Mutex::new(None),
- document_state: Mutex::new(None),
- session_storage: Mutex::new(None),
- awareness: EphemeralStore::new(5_000),
- ws_meta_map: Arc::new(Mutex::new(Default::default())),
- inbound: Arc::new(Mutex::new(HashMap::new())),
- pending_blame: Arc::new(Mutex::new(Vec::new())),
- pending_editors: Arc::new(Mutex::new(Default::default())),
- mapped_writing_peers: Mutex::new(Default::default()),
- surface_lifecycle: Mutex::new(None),
- source_migration: Mutex::new(None),
- mutation_barrier: futures::lock::Mutex::new(()),
- }
- }
-
- /// Fetch the durable object
- /// Upgrades the request to a websocket request connected to the document session
- async fn fetch(&self, req: Request) -> Result<Response> {
- let _barrier = self.mutation_barrier.lock().await;
- let set_allow_origin = if let Some(origin) = req
- .headers()
- .get("Origin")
- .context("No `Origin` header found in header")?
- {
- if is_origin_allowed(&origin) {
- Some(origin)
- } else {
- return Ok(response(status_codes::FORBIDDEN));
- }
- } else {
- None
- };
-
- if req.method() == Method::Options {
- return Ok(Response::builder()
- .with_status(status_codes::OK)
- .with_cors(&cors(set_allow_origin.as_deref()))?
- .empty());
- }
- let traceparent = worker_rs_otel::traceparent_from_request(&req);
- let (remote_id, remote_parent) = worker_rs_otel::remote_fields(traceparent.as_ref());
- let path = req.path();
- let span = tracing::info_span!(
- "do.request",
- http.path = %path,
- document.id = tracing::field::Empty,
- snapshot.bytes = tracing::field::Empty,
- trace.remote_id = %remote_id,
- trace.remote_parent = %remote_parent,
- );
-
- // Log the failure inside the span and the scope: the scope flushes
- // telemetry when it ends, and a log buffered after it is only exported
- // if a later request on the same isolate happens to flush it.
- let res = worker_rs_otel::scope(
- &self.env,
- &self.state,
- async {
- self.inner_fetch(req)
- .await
- .context("DurableObject::fetch error")
- }
- .instrument(span),
- )
- .await;
- res?.with_cors(&cors(set_allow_origin.as_deref()))
- }
-
- async fn websocket_message(&self, ws: WebSocket, msg: WebSocketIncomingMessage) -> Result<()> {
- let _barrier = self.mutation_barrier.lock().await;
- if self.source_blocked().await? {
- ws.close(Some(1008), Some("session frozen or retired"))?;
- return Ok(());
- }
- if !self.validate_surface_sockets(Some(&ws)).await? {
- return Ok(());
- }
- const PONG: &str = "pong";
- const PING: &str = "ping";
- let binary_message = match msg {
- WebSocketIncomingMessage::String(message) => {
- // Heartbeat: deliberately unspanned to keep it out of traces.
- if message == PING {
- ws.send_with_str(PONG).ok();
- } else {
- return worker_rs_otel::scope(&self.env, &self.state, async {
- warn!("Received unknown 'String' message: {message:?}");
- Ok(())
- })
- .await;
- }
- return Ok(());
- }
- WebSocketIncomingMessage::Binary(bm) => bm,
- };
- let socket = self.socket_for(&ws);
- let ws_id = get_ws_id(&self.state, &ws)?;
- let Some(binary_message) = socket.receive(&ws_id, &binary_message)? else {
- return Ok(());
- };
- worker_rs_otel::scope(&self.env, &self.state, async {
- let mut telemetry = protocol::InboundMessageTelemetry::new(binary_message.len());
-
- let res: Result<()> = async {
- let document_id = self.document_id().await.inspect_err(|_| {
- telemetry.record_error_stage("document_context");
- })?;
- let ws_id = get_ws_id_from_tags(&self.state.get_tags(&ws)).ok();
- telemetry.record_context(&document_id, ws_id);
-
- let message = protocol::deserialize_message(&binary_message).inspect_err(|_| {
- telemetry.record_message_type("invalid");
- telemetry.record_error_stage("deserialize");
- })?;
- telemetry.record_message_type(protocol::message_type(&message));
-
- protocol::process_message(
- &self.socket_for(&ws),
- &document_id,
- &*self.document_state().await?,
- &*self.session_storage().await?,
- &self.awareness,
- message,
- self,
- &mut telemetry,
- )
- .await
- .inspect_err(|_| {
- telemetry.record_error_stage("process");
- })
- .context("failed to process websocket message")?;
-
- bump_alarm(&self.state)
- .await
- .inspect_err(|_| {
- telemetry.record_error_stage("alarm");
- })
- .context("failed to keep document alive")?;
-
- Ok(())
- }
- .await;
-
- if let Err(error) = &res {
- let span = telemetry.error_span();
- {
- let _entered = span.enter();
- tracing::error!(error = ?error, "failed to handle websocket message");
- }
- }
- res
- })
- .await
- }
-
- /// Save document if needed
- async fn alarm(&self) -> Result<Response> {
- let _barrier = self.mutation_barrier.lock().await;
- if self.source_blocked().await? {
- return Response::empty();
- }
- self.validate_surface_sockets(None).await?;
- let span = tracing::info_span!("do.alarm");
- worker_rs_otel::scope(&self.env, &self.state, async {
- let state = match self
- .document_state()
- .await
- .context("failed to get document_state")
- {
- Ok(x) => x,
- Err(_e) => {
- // This is likely due to a programming issue. We don't return `Err`
- // because it wuld cause this alarm to retry, then fail again.
- return Response::empty();
- }
- };
-
- if state.should_save() {
- let seshs = self
- .session_storage()
- .await
- .context("failed to get session storage")?;
-
- // Keeps the worker alive for DEFAULT_TIME_TO_LIVE
- keepalive(DEFAULT_TIME_TO_LIVE);
-
- let doc_state = self.document_state().await?;
- let (sf, of) = doc_state.frontiers();
- seshs
- .store_snapshot(&doc_state)
- .await
- .context("failed to store snapshot")?;
-
- debug!(state_frontiers =? sf, oplog_frontiers =? of, "Stored new DocumentState");
- seshs
- .clear_applied_ops()
- .await
- .context("failed deleting applied ops")?;
-
- state.mark_exported();
-
- let document_id = self.document_id().await.ok();
- let pending_editors = self.pending_editors.clone();
- let env = self.env.clone();
- self.state.wait_until(async move {
- if let Some(document_id) = document_id
- && let Ok(snapshot) = doc_state.export_shallow_snapshot()
- {
- let editors = take_editors(&pending_editors);
- report_new_doc_state(&document_id, &snapshot, &env, editors).await;
- report_interaction(&document_id, &env, InteractionReason::Edited).await;
- }
- });
- }
-
- self.flush_pending_blame();
-
- // Re-arm the alarm while clients are connected so the in-memory state
- // stays warm and pending updates keep getting persisted. Updates reach
- // peers when they happen (PeerUpdate broadcast); pushing a full
- // snapshot to every client on every alarm tick only burned bandwidth
- // and stalled clients on large documents.
- if !self.state.get_websockets().is_empty() {
- bump_alarm(&self.state)
- .await
- .context("failed to keep document alive")?;
- } else {
- info!("durable object has reached 0 connections")
- }
-
- Response::ok("ok")
- }
- .instrument(span))
- .await
- }
-
- async fn websocket_close(
- &self,
- ws: WebSocket,
- _code: usize,
- _reason: String,
- _was_clean: bool,
- ) -> Result<()> {
- let _barrier = self.mutation_barrier.lock().await;
- if self.source_blocked().await? {
- self.forget_websocket_metadata(&ws).await;
- return Ok(());
- }
- worker_rs_otel::scope(&self.env, &self.state, async {
- // Sockets closed by `delete_handler` report back after the session is gone.
- if self.try_document_id().await?.is_none() {
- self.forget_websocket_metadata(&ws).await;
- return Ok(());
- }
- self.validate_surface_sockets(None).await?;
- let peer_ids = Wsm::new(self, &ws).get_peer_ids(true).await?;
- for peer_id in peer_ids {
- self.awareness.delete(&peer_id.to_string());
- let update = self.awareness.encode(&peer_id.to_string());
-
- // Don't silently discard the error
- protocol::broadcast_awareness(self, &self.socket_for(&ws), update.as_slice())
- .context("failed to broadcast awareness")?;
- }
-
- if self.state.get_websockets().len() == 1
- && let Ok(state) = self.document_state().await
- && let Ok(document_id) = self.document_id().await
- && let Ok(snapshot) = state.export_shallow_snapshot()
- {
- let editors = take_editors(&self.pending_editors);
- let env = self.env.clone();
- self.state.wait_until(async move {
- report_new_doc_state(&document_id, &snapshot, &env, editors).await;
- report_interaction(&document_id, &env, InteractionReason::LastLeave).await;
- });
- }
- self.forget_websocket_metadata(&ws).await;
- Ok(())
- })
- .await
- }
-
- async fn websocket_error(&self, ws: WebSocket, error: Error) -> Result<()> {
- worker_rs_otel::scope(&self.env, &self.state, async {
- let ws_id = get_ws_id(&self.state, &ws)?;
- error!(ws_id = ws_id, error = ?error, "websocket error");
- // TODO update awareness stuff
- Ok(())
- })
- .await
- }
-}
-
-#[derive(serde::Serialize, serde::Deserialize, Debug)]
-pub struct VersionIndicator {
- /// Json has trouble with peer id bigints, so we need to serialize from a string
- pub peer: String,
- pub counter: i32,
-}
-
-#[derive(serde::Deserialize, serde::Serialize, Debug)]
-pub struct CopyDocumentRequest {
- pub target_document_id: String,
- pub version_id: Option<VersionIndicator>,
-}
-
-#[derive(serde::Deserialize, serde::Serialize, Debug)]
-pub struct GetSnapshotRequest {
- pub version_id: Option<VersionIndicator>,
-}
-
-#[derive(serde::Deserialize, serde::Serialize)]
-pub struct DocumentMetadata {
- pub id: String,
- pub peers: Vec<PeerWithUserId>,
- pub version_id: String,
-}
-
-#[derive(serde::Serialize)]
-pub struct PeerResponse {
- pub peer_id: String,
- pub user_id: String,
-}
-
-pub static ALLOWED_ORIGINS: &[&str] = &[
- "http://localhost:5173",
- "http://localhost:3000",
- "http://host.local:3000",
- "https://dev.macro.com",
- "https://staging.macro.com",
- "https://www.macro.com",
- "https://macro.com",
- "capacitor://localhost",
- "https://apollo-testing.macro.com",
-];
-
-pub fn is_origin_allowed(origin: &str) -> bool {
- if ALLOWED_ORIGINS.contains(&origin) {
- return true;
- }
- // `localhost` and `*.localhost` (loopback-reserved; local dev uses
- // per-persona hostnames so each seeded user gets its own cookie jar).
- if let Some(rest) = origin.strip_prefix("http://")
- && let Some((host, port)) = rest.rsplit_once(':')
- && (host == "localhost" || host.ends_with(".localhost"))
- && let Ok(port) = port.parse::<u16>()
- {
- return (3000..=3999).contains(&port) || (20000..=60000).contains(&port);
- }
- // Allow feature branch previews: https://{subdomain}.preview.macro.com
- if let Some(host) = origin.strip_prefix("https://")
- && let Some(subdomain) = host.strip_suffix(".preview.macro.com")
- {
- return !subdomain.is_empty() && !subdomain.contains('/');
- }
- false
-}
-
-/// Workaround for this bug: <https://github.com/cloudflare/workers-rs/issues/554>
-pub fn cors(request_origin: Option<&str>) -> Cors {
- use worker::Method;
- let cors_origins = request_origin
- .map(|o| {
- if is_origin_allowed(o) {
- vec![o.to_string()]
- } else {
- vec![]
- }
- })
- .unwrap_or_default();
-
- Cors::new()
- .with_credentials(true)
- // `traceparent`/`tracestate` are injected by the web client's traced
- // fetch wrapper (see `safeFetch`), so they must be preflight-allowed or
- // the browser blocks every instrumented call. Kept in sync with
- // `macro_cors::EXTRA_HEADERS`, which the axum services use; this worker
- // can't share that list because it's built on tower-http.
- .with_allowed_headers(vec![
- "authorization",
- "content-type",
- "traceparent",
- "tracestate",
- ])
- .with_methods(vec![
- Method::Get,
- Method::Post,
- Method::Put,
- Method::Patch,
- Method::Delete,
- Method::Options,
- ])
- .with_origins(cors_origins)
-}
diff --git a/services/sync-service/src/inbound.rs b/services/sync-service/src/inbound.rs
new file mode 100644
index 0000000000..6a9fc6e1f7
--- /dev/null
+++ b/services/sync-service/src/inbound.rs
@@ -0,0 +1,6 @@
+pub mod auth;
+pub mod cors;
+pub mod credentials;
+pub mod durable_object;
+pub mod router;
+pub mod worker;
diff --git a/services/sync-service/src/inbound/auth.rs b/services/sync-service/src/inbound/auth.rs
new file mode 100644
index 0000000000..d6390e0ca5
--- /dev/null
+++ b/services/sync-service/src/inbound/auth.rs
@@ -0,0 +1,226 @@
+//! Session-scoped credentials for the worker runtime. These are document grants,
+//! not the application session credentials consumed by macro_authorization.
+use std::collections::HashMap;
+
+use axum::{
+ extract::{FromRef, FromRequestParts, Path, Query},
+ http::{StatusCode, request::Parts},
+};
+use subtle::ConstantTimeEq;
+
+use crate::secrets::Secrets;
+use crate::{
+ auth::{WebsocketQueryParams, decode_document_token},
+ constants::header_names,
+ domain::{
+ document::DocumentAccess,
+ permissions::{AccessLevel, AuthToken},
+ },
+};
+
+/// Verified document grant with the minimum permission required by its route.
+/// Internal credentials are accepted only by the legacy service APIs.
+pub struct SessionAccess<L> {
+ pub document_id: String,
+ level: std::marker::PhantomData<L>,
+}
+
+pub trait RequiredAccess: Send + Sync {
+ const LEVEL: AccessLevel;
+}
+
+pub struct View;
+impl RequiredAccess for View {
+ const LEVEL: AccessLevel = AccessLevel::View;
+}
+pub struct Edit;
+impl RequiredAccess for Edit {
+ const LEVEL: AccessLevel = AccessLevel::Edit;
+}
+pub struct Admin;
+impl RequiredAccess for Admin {
+ const LEVEL: AccessLevel = AccessLevel::Admin;
+}
+
+pub type ViewAccess = SessionAccess<View>;
+pub type EditAccess = SessionAccess<Edit>;
+pub type AdminAccess = SessionAccess<Admin>;
+
+async fn document_id(parts: &mut Parts) -> Result<String, StatusCode> {
+ let Path(params) = Path::<HashMap<String, String>>::from_request_parts(parts, &())
+ .await
+ .map_err(|_| StatusCode::BAD_REQUEST)?;
+ let id = params.get("document_id").ok_or(StatusCode::BAD_REQUEST)?;
+ tracing::Span::current().record("document.id", id.as_str());
+ Ok(id.clone())
+}
+
+fn internal(parts: &Parts, state: &Secrets) -> bool {
+ parts
+ .headers
+ .get(header_names::MACRO_INTERNAL_AUTH_KEY_HEADER_KEY)
+ .is_some_and(|key| bool::from(key.as_bytes().ct_eq(state.internal_api_secret.as_bytes())))
+}
+
+fn bearer(parts: &Parts, state: &Secrets) -> Result<AuthToken, StatusCode> {
+ let token = parts
+ .headers
+ .get(header_names::AUTHORIZATION)
+ .and_then(|value| value.to_str().ok())
+ .and_then(|value| value.strip_prefix("Bearer "))
+ .ok_or(StatusCode::UNAUTHORIZED)?;
+ decode_document_token(token, &state.document_permissions_secret)
+ .map_err(|_| StatusCode::UNAUTHORIZED)
+}
+
+impl<S: Send + Sync, L: RequiredAccess> FromRequestParts<S> for SessionAccess<L>
+where
+ Secrets: FromRef<S>,
+{
+ type Rejection = StatusCode;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let secrets = Secrets::from_ref(state);
+ let state = &secrets;
+ let document_id = document_id(parts).await?;
+ if !internal(parts, state) {
+ let claims = bearer(parts, state)?;
+ claims
+ .require_document_permission(&document_id, &L::LEVEL)
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ }
+ Ok(Self {
+ document_id,
+ level: std::marker::PhantomData,
+ })
+ }
+}
+
+/// Query-token authentication scoped to the document being connected to.
+pub struct SocketAccess {
+ pub document_id: String,
+ pub claims: AuthToken,
+}
+
+impl<S: Send + Sync> FromRequestParts<S> for SocketAccess
+where
+ Secrets: FromRef<S>,
+{
+ type Rejection = StatusCode;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let secrets = Secrets::from_ref(state);
+ let state = &secrets;
+ let document_id = document_id(parts).await?;
+ let Query(params) = Query::<WebsocketQueryParams>::from_request_parts(parts, state)
+ .await
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ let claims = decode_document_token(&params.token, &state.document_permissions_secret)
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ claims
+ .require_document_permission(&document_id, &AccessLevel::View)
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ Ok(Self {
+ document_id,
+ claims,
+ })
+ }
+}
+
+/// Atomic document reads/updates require a signed user grant even when an
+/// internal key is also present. The capability is passed into the domain.
+pub struct SignedDocumentAccess {
+ pub document_id: String,
+ pub access: DocumentAccess,
+ pub claims: AuthToken,
+}
+
+impl<S: Send + Sync> FromRequestParts<S> for SignedDocumentAccess
+where
+ Secrets: FromRef<S>,
+{
+ type Rejection = StatusCode;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let secrets = Secrets::from_ref(state);
+ let state = &secrets;
+ let document_id = document_id(parts).await?;
+ let claims = bearer(parts, state)?;
+ let access = claims
+ .document_access(&document_id)
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ Ok(Self {
+ document_id,
+ access,
+ claims,
+ })
+ }
+}
+
+/// Destructive service APIs accept only the shared internal credential.
+pub struct InternalAccess;
+
+impl<S: Send + Sync> FromRequestParts<S> for InternalAccess
+where
+ Secrets: FromRef<S>,
+{
+ type Rejection = StatusCode;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ let secrets = Secrets::from_ref(state);
+ let state = &secrets;
+ if internal(parts, state) {
+ Ok(Self)
+ } else {
+ Err(StatusCode::UNAUTHORIZED)
+ }
+ }
+}
+
+#[cfg(test)]
+mod test;
+
+/// A kind-discriminated, exact surface grant. Management keys cannot be used
+/// in place of a surface grant on read or connect routes.
+pub struct SurfaceAccess<const QUERY: bool> {
+ pub claims: AuthToken,
+}
+
+impl<S: Send + Sync, const QUERY: bool> FromRequestParts<S> for SurfaceAccess<QUERY>
+where
+ Secrets: FromRef<S>,
+{
+ type Rejection = StatusCode;
+
+ async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+ use macro_sync_service_jwt::session::{SessionIdentity, SessionKind};
+ let secrets = Secrets::from_ref(state);
+ let Path(params) = Path::<HashMap<String, String>>::from_request_parts(parts, state)
+ .await
+ .map_err(|_| StatusCode::BAD_REQUEST)?;
+ let id = params.get("surface_id").ok_or(StatusCode::BAD_REQUEST)?;
+ let identity =
+ SessionIdentity::new(SessionKind::Surface, id).map_err(|_| StatusCode::BAD_REQUEST)?;
+ let token = if QUERY {
+ let Query(params) = Query::<WebsocketQueryParams>::from_request_parts(parts, state)
+ .await
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ params.token
+ } else {
+ parts
+ .headers
+ .get(header_names::AUTHORIZATION)
+ .and_then(|value| value.to_str().ok())
+ .and_then(|value| value.strip_prefix("Bearer "))
+ .ok_or(StatusCode::UNAUTHORIZED)?
+ .to_owned()
+ };
+ let claims = crate::auth::decode_surface_token(
+ &token,
+ &secrets.document_permissions_secret,
+ &identity,
+ )
+ .map_err(|_| StatusCode::UNAUTHORIZED)?;
+ Ok(Self { claims })
+ }
+}
diff --git a/services/sync-service/src/inbound/auth/test.rs b/services/sync-service/src/inbound/auth/test.rs
new file mode 100644
index 0000000000..bc6440f435
--- /dev/null
+++ b/services/sync-service/src/inbound/auth/test.rs
@@ -0,0 +1,261 @@
+use super::*;
+use axum::{Router, body::Body, http::Request, routing::get};
+use tower_service::Service;
+
+#[test]
+fn extractors_enforce_scope_permission_and_credential_source() {
+ let secrets = Secrets {
+ internal_api_secret: "internal".into(),
+ document_permissions_secret: "secret".into(),
+ };
+ let mut router = Router::new()
+ .route(
+ "/document/{document_id}/view",
+ get(|_: ViewAccess| async {}),
+ )
+ .route(
+ "/document/{document_id}/edit",
+ get(|_: EditAccess| async {}),
+ )
+ .route(
+ "/document/{document_id}/admin",
+ get(|_: AdminAccess| async {}),
+ )
+ .route(
+ "/document/{document_id}/signed",
+ get(|_: SignedDocumentAccess| async {}),
+ )
+ .route(
+ "/document/{document_id}/connect",
+ get(|_: SocketAccess| async {}),
+ )
+ .route(
+ "/document/{document_id}/internal",
+ get(|_: InternalAccess| async {}),
+ )
+ .with_state(secrets);
+ let view = macro_sync_service_jwt::encode(
+ &serde_json::json!({"document_id": "document-a", "access_level": "view", "exp": usize::MAX / 2}),
+ "secret",
+ ).unwrap();
+ let edit = macro_sync_service_jwt::encode(
+ &serde_json::json!({"document_id": "document-a", "access_level": "edit", "exp": usize::MAX / 2}),
+ "secret",
+ ).unwrap();
+ let expired = macro_sync_service_jwt::encode(
+ &serde_json::json!({"document_id": "document-a", "access_level": "edit", "exp": 1}),
+ "secret",
+ )
+ .unwrap();
+ for (path, header, value, status) in [
+ (
+ "/document/document-a/view".into(),
+ "authorization",
+ format!("Bearer {view}"),
+ StatusCode::OK,
+ ),
+ (
+ "/document/document-b/view".into(),
+ "authorization",
+ format!("Bearer {view}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/edit".into(),
+ "authorization",
+ format!("Bearer {view}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/edit".into(),
+ "authorization",
+ format!("Bearer {edit}"),
+ StatusCode::OK,
+ ),
+ (
+ "/document/document-a/admin".into(),
+ "authorization",
+ format!("Bearer {edit}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/view".into(),
+ "authorization",
+ format!("Bearer {expired}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/view".into(),
+ "authorization",
+ "Bearer invalid".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/view".into(),
+ "authorization",
+ edit.to_string(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/admin".into(),
+ "x-internal-auth-key",
+ "internal".into(),
+ StatusCode::OK,
+ ),
+ (
+ "/document/document-a/signed".into(),
+ "x-internal-auth-key",
+ "internal".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/signed".into(),
+ "authorization",
+ format!("Bearer {view}"),
+ StatusCode::OK,
+ ),
+ (
+ "/document/document-b/signed".into(),
+ "authorization",
+ format!("Bearer {edit}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/internal".into(),
+ "authorization",
+ format!("Bearer {edit}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/internal".into(),
+ "x-internal-auth-key",
+ "wrong".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/internal".into(),
+ "x-internal-auth-key",
+ "internal".into(),
+ StatusCode::OK,
+ ),
+ (
+ format!("/document/document-a/connect?token={edit}"),
+ "authorization",
+ "".into(),
+ StatusCode::OK,
+ ),
+ (
+ format!("/document/document-b/connect?token={edit}"),
+ "authorization",
+ "".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ "/document/document-a/connect".into(),
+ "x-internal-auth-key",
+ "internal".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ ] {
+ let request = Request::builder()
+ .uri(&path)
+ .header(header, value)
+ .body(Body::empty())
+ .unwrap();
+ let response = futures::executor::block_on(router.call(request)).unwrap();
+ assert_eq!(response.status(), status, "{path}");
+ }
+}
+
+#[test]
+fn surface_extractors_reject_document_and_cross_surface_grants() {
+ use macro_sync_service_jwt::session::{SurfaceAccessLevel, SurfaceClaims, SurfaceSessionKind};
+ let id = "01952cbd-76ad-7a65-9c21-020304050607";
+ let token = macro_sync_service_jwt::session::encode_surface(
+ &SurfaceClaims {
+ session_kind: SurfaceSessionKind::Surface,
+ surface_id: id.parse().unwrap(),
+ user_id: None,
+ access_level: SurfaceAccessLevel::View,
+ actor: None,
+ exp: usize::MAX / 2,
+ iss: macro_sync_service_jwt::ISSUER.into(),
+ },
+ "secret",
+ )
+ .unwrap();
+ let document = macro_sync_service_jwt::encode(
+ &serde_json::json!({"document_id": id, "access_level": "admin", "exp": usize::MAX / 2}),
+ "secret",
+ )
+ .unwrap();
+ let mut router = Router::new()
+ .route(
+ "/surface/{surface_id}/read",
+ get(|_: SurfaceAccess<false>| async {}),
+ )
+ .route(
+ "/surface/{surface_id}/connect",
+ get(|_: SurfaceAccess<true>| async {}),
+ )
+ .route(
+ "/document/{document_id}/read",
+ get(|_: ViewAccess| async {}),
+ )
+ .with_state(Secrets {
+ internal_api_secret: "internal".into(),
+ document_permissions_secret: "secret".into(),
+ });
+ for (uri, header, value, expected) in [
+ (
+ format!("/surface/{id}/read"),
+ "authorization",
+ format!("Bearer {token}"),
+ StatusCode::OK,
+ ),
+ (
+ "/surface/01952cbd-76ad-7a65-9c21-020304050608/read".into(),
+ "authorization",
+ format!("Bearer {token}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ format!("/surface/{id}/read"),
+ "authorization",
+ format!("Bearer {document}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ format!("/document/{id}/read"),
+ "authorization",
+ format!("Bearer {token}"),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ format!("/surface/{id}/read"),
+ "x-internal-auth-key",
+ "internal".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ (
+ format!("/surface/{id}/connect?token={token}"),
+ "authorization",
+ "".into(),
+ StatusCode::OK,
+ ),
+ (
+ format!("/surface/{id}/connect?token={document}"),
+ "authorization",
+ "".into(),
+ StatusCode::UNAUTHORIZED,
+ ),
+ ] {
+ let request = Request::builder()
+ .uri(&uri)
+ .header(header, value)
+ .body(Body::empty())
+ .unwrap();
+ let response = futures::executor::block_on(router.call(request)).unwrap();
+ assert_eq!(response.status(), expected, "{uri}");
+ }
+}
diff --git a/services/sync-service/src/inbound/cors.rs b/services/sync-service/src/inbound/cors.rs
new file mode 100644
index 0000000000..85d789180a
--- /dev/null
+++ b/services/sync-service/src/inbound/cors.rs
@@ -0,0 +1,72 @@
+use worker::Cors;
+
+pub static ALLOWED_ORIGINS: &[&str] = &[
+ "http://localhost:5173",
+ "http://localhost:3000",
+ "http://host.local:3000",
+ "https://dev.macro.com",
+ "https://staging.macro.com",
+ "https://www.macro.com",
+ "https://macro.com",
+ "capacitor://localhost",
+ "https://apollo-testing.macro.com",
+];
+
+pub fn is_origin_allowed(origin: &str) -> bool {
+ if ALLOWED_ORIGINS.contains(&origin) {
+ return true;
+ }
+ // `localhost` and `*.localhost` (loopback-reserved; local dev uses
+ // per-persona hostnames so each seeded user gets its own cookie jar).
+ if let Some(rest) = origin.strip_prefix("http://")
+ && let Some((host, port)) = rest.rsplit_once(':')
+ && (host == "localhost" || host.ends_with(".localhost"))
+ && let Ok(port) = port.parse::<u16>()
+ {
+ return (3000..=3999).contains(&port) || (20000..=60000).contains(&port);
+ }
+ // Allow feature branch previews: https://{subdomain}.preview.macro.com
+ if let Some(host) = origin.strip_prefix("https://")
+ && let Some(subdomain) = host.strip_suffix(".preview.macro.com")
+ {
+ return !subdomain.is_empty() && !subdomain.contains('/');
+ }
+ false
+}
+
+/// Workaround for this bug: <https://github.com/cloudflare/workers-rs/issues/554>
+pub fn cors(request_origin: Option<&str>) -> Cors {
+ use worker::Method;
+ let cors_origins = request_origin
+ .map(|o| {
+ if is_origin_allowed(o) {
+ vec![o.to_string()]
+ } else {
+ vec![]
+ }
+ })
+ .unwrap_or_default();
+
+ Cors::new()
+ .with_credentials(true)
+ // `traceparent`/`tracestate` are injected by the web client's traced
+ // fetch wrapper (see `safeFetch`), so they must be preflight-allowed or
+ // the browser blocks every instrumented call. Kept in sync with
+ // `macro_cors::EXTRA_HEADERS`, which the axum services use; this worker
+ // can't share that list because it's built on tower-http.
+ .with_allowed_headers(vec![
+ "authorization",
+ "content-type",
+ "traceparent",
+ "tracestate",
+ ])
+ .with_methods(vec![
+ Method::Get,
+ Method::Post,
+ Method::Put,
+ Method::Patch,
+ Method::Delete,
+ Method::Options,
+ ])
+ .with_origins(cors_origins)
+}
diff --git a/services/sync-service/src/inbound/credentials.rs b/services/sync-service/src/inbound/credentials.rs
new file mode 100644
index 0000000000..df32326ccb
--- /dev/null
+++ b/services/sync-service/src/inbound/credentials.rs
@@ -0,0 +1,71 @@
+pub use crate::domain::permissions::{AccessLevel, AuthToken, WriteAccess};
+use macro_sync_service_jwt::session::{
+ SessionIdentity, SessionKind, SurfaceAccessLevel, decode_surface,
+};
+use serde::Deserialize;
+use worker::Error;
+
+use crate::error::ResultExt;
+
+#[derive(Deserialize)]
+struct DocumentClaims {
+ user_id: Option<String>,
+ document_id: String,
+ access_level: AccessLevel,
+ actor: Option<String>,
+ session_kind: Option<SessionKind>,
+ surface_id: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct WebsocketQueryParams {
+ pub token: String,
+}
+
+pub(crate) fn decode_document_token(token: &str, secret: &str) -> worker::Result<AuthToken> {
+ let claims = macro_sync_service_jwt::decode::<DocumentClaims>(token, secret)
+ .context("failed to decode document grant")?;
+ if claims
+ .session_kind
+ .is_some_and(|kind| kind != SessionKind::Document)
+ || claims.surface_id.is_some()
+ {
+ return Err(Error::from("surface grant cannot authorize a document"));
+ }
+ Ok(AuthToken {
+ user_id: claims.user_id,
+ document_id: claims.document_id,
+ access_level: claims.access_level,
+ actor: claims.actor,
+ session_kind: SessionKind::Document,
+ expires_at: None,
+ })
+}
+
+pub(crate) fn decode_surface_token(
+ token: &str,
+ secret: &str,
+ identity: &SessionIdentity,
+) -> worker::Result<AuthToken> {
+ let claims = decode_surface(token, secret).context("failed to decode surface grant")?;
+ if claims.session_identity() != *identity {
+ return Err(Error::from("surface grant does not match session"));
+ }
+ let access_level = match claims.access_level {
+ SurfaceAccessLevel::View => AccessLevel::View,
+ SurfaceAccessLevel::Comment => AccessLevel::Comment,
+ SurfaceAccessLevel::Edit => AccessLevel::Edit,
+ SurfaceAccessLevel::Owner => AccessLevel::Owner,
+ };
+ Ok(AuthToken {
+ user_id: claims.user_id,
+ document_id: identity.storage_key(),
+ access_level,
+ actor: claims.actor,
+ session_kind: SessionKind::Surface,
+ expires_at: Some(claims.exp),
+ })
+}
+
+#[cfg(test)]
+mod test;
diff --git a/services/sync-service/src/auth/test.rs b/services/sync-service/src/inbound/credentials/test.rs
similarity index 100%
rename from services/sync-service/src/auth/test.rs
rename to services/sync-service/src/inbound/credentials/test.rs
diff --git a/services/sync-service/src/inbound/durable_object.rs b/services/sync-service/src/inbound/durable_object.rs
new file mode 100644
index 0000000000..18d3e25129
--- /dev/null
+++ b/services/sync-service/src/inbound/durable_object.rs
@@ -0,0 +1,874 @@
+use super::cors::{cors, is_origin_allowed};
+use std::{
+ borrow::Cow,
+ collections::{BTreeMap, BTreeSet, HashMap},
+ rc::Rc,
+ sync::Arc,
+};
+
+use bebop::Record;
+use loro::{ExportMode, awareness::EphemeralStore};
+use macro_sync_service_jwt::session::SessionKind;
+use serde::{Deserialize, Serialize};
+use tracing::{Instrument, debug, error, info, instrument, trace, warn};
+use worker::{
+ Date, DurableObject, Env, Error, Method, Request, Response, ResponseBody, ResponseBuilder,
+ Result, ScheduledTime, State, WebSocket, WebSocketIncomingMessage, WebSocketPair,
+ durable_object,
+};
+
+use crate::{
+ auth::{AccessLevel, AuthToken, WriteAccess},
+ constants::{SYSTEM_AUTHOR_ID, USER_PEER_D1_BINDING},
+ d1::{get_user_id_from_peer_id, insert_missing_user_mappings, insert_user_mapping},
+ domain::document::{DocumentAttribution, writing_peers},
+ dss_internal::InteractionReason,
+ error::ResultExt,
+ generated::schema::InitializeFromSnapshotRequest,
+ keepalive::{DEFAULT_TIME_TO_LIVE, keepalive},
+ mutex::Mutex,
+ socket::{InboundBuffers, Socket, protocol},
+ state::DocumentState,
+ storage::{
+ SessionStorage, backends::durable_kv::DurableKVStorage, get_snapshot_storage,
+ snapshot::SnapshotStorage,
+ },
+ tags::{get_ws_id_from_tags, new_ws_id},
+ timeit,
+};
+
+pub const NO_SUCH_VALUE_ERR_STR: &str = "No such value in storage.";
+
+pub mod status_codes {
+ pub const OK: u16 = 200;
+ pub const NOT_FOUND: u16 = 404;
+ pub const UNAUTH: u16 = 401;
+ pub const FORBIDDEN: u16 = 403;
+}
+
+const DOCUMENT_ID_KEY: &str = "DOCUMENT_ID";
+
+mod callbacks;
+pub(crate) mod document_api;
+mod document_delete;
+mod document_effects;
+mod peer_ids;
+mod surface_api;
+pub(crate) mod surface_migration;
+
+use document_effects::{report_interaction, report_new_doc_state};
+use surface_api::{SurfaceLifecycle, session_kind_from_storage_key};
+
+pub fn response(status_code: u16) -> Response {
+ Response::builder().with_status(status_code).empty()
+}
+
+#[macro_export]
+macro_rules! maybe_404 {
+ ($res:expr) => {
+ match $res {
+ Ok(x) => Ok(x),
+ Err(Error::JsError(s)) => {
+ if s.contains(NO_SUCH_VALUE_ERR_STR) {
+ return Ok(ResponseBuilder::new()
+ .with_status(status_codes::NOT_FOUND)
+ .empty());
+ } else {
+ Err(Error::JsError(s))
+ }
+ }
+ Err(e) => Err(e),
+ }
+ };
+}
+
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct WebSocketMetadata {
+ pub user_id: Option<String>,
+ pub access_level: AccessLevel,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub actor: Option<String>,
+ #[serde(with = "u64_serde_strings")]
+ pub peer_ids: BTreeSet<u64>,
+ #[serde(default = "surface_api::document_kind")]
+ pub session_kind: SessionKind,
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub expires_at: Option<usize>,
+}
+
+pub type WsMetaMap = BTreeMap<String, WebSocketMetadata>;
+
+pub struct SyncSession {
+ state: State,
+ env: Env,
+ /// id of the document, comes from URL path
+ document_id: Mutex<Option<Arc<String>>>,
+ /// Current document state
+ document_state: Mutex<Option<Arc<DocumentState>>>,
+ /// Access to document related IO
+ session_storage: Mutex<Option<Rc<SessionStorage>>>,
+ awareness: EphemeralStore,
+ /// a map from websocket's ID's to websocket metadata
+ ws_meta_map: Arc<Mutex<WsMetaMap>>,
+ /// Partial inbound messages, isolated by connection.
+ inbound: InboundBuffers,
+ /// Buffered blame events. Flushed via D1 batch on each alarm tick.
+ pending_blame: Arc<Mutex<Vec<crate::d1::BlameEvent>>>,
+ /// Distinct editors since the last snapshot notification.
+ pending_editors: Arc<Mutex<BTreeSet<DocumentAttribution>>>,
+ /// Writing peers already recorded in D1 since this object woke, so
+ /// updates skip remapping them.
+ mapped_writing_peers: Mutex<BTreeSet<u64>>,
+ surface_lifecycle: Mutex<Option<SurfaceLifecycle>>,
+ source_migration: Mutex<Option<surface_migration::SourceState>>,
+ // Serialize whole callbacks, including persistence awaits. A freeze must
+ // drain every in-flight mutation before it exports or closes writers.
+ mutation_barrier: futures::lock::Mutex<()>,
+}
+
+mod u64_serde_strings;
+
+pub struct Wsm<'a> {
+ dss: &'a SyncSession,
+ ws: &'a WebSocket,
+ ws_id: Option<String>,
+}
+impl<'a> Wsm<'a> {
+ pub fn new(dss: &'a SyncSession, ws: &'a WebSocket) -> Self {
+ Self {
+ dss,
+ ws,
+ ws_id: None,
+ }
+ }
+ fn get_ws_id(&mut self) -> Result<&str> {
+ if self.ws_id.is_none() {
+ let tags = self.dss.state.get_tags(self.ws);
+ let ws_id = get_ws_id_from_tags(&tags)?;
+ self.ws_id = Some(ws_id);
+ }
+ Ok(self.ws_id.as_ref().unwrap())
+ }
+ async fn maybe_update_ws_meta_map(&mut self) -> Result<()> {
+ let ws_id = self.get_ws_id()?.to_string();
+ if !self
+ .dss
+ .ws_meta_map
+ .lock("Wsm::maybe_update_ws_meta_map contains_key")
+ .contains_key(&ws_id)
+ {
+ let wsm: WebSocketMetadata = self
+ .dss
+ .state
+ .storage()
+ .get(&ws_id)
+ .await?
+ .ok_or(Error::from("WebSocketMetadata not found in storage"))?;
+ self.dss
+ .ws_meta_map
+ .lock("Wsm::maybe_update_ws_meta_map insert")
+ .insert(ws_id, wsm);
+ }
+ Ok(())
+ }
+ pub async fn get_peer_ids(&mut self, include_ai: bool) -> Result<Vec<u64>> {
+ self.maybe_update_ws_meta_map().await?;
+ let ws_id = self.get_ws_id()?.to_string();
+ Ok(self
+ .dss
+ .ws_meta_map
+ .lock("Wsm::get_peer_ids get")
+ .get(&ws_id)
+ .ok_or(Error::from("missing ws metadata"))?
+ .active_peer_ids(include_ai))
+ }
+
+ pub async fn edit_attribution(&mut self) -> Result<Option<DocumentAttribution>> {
+ self.maybe_update_ws_meta_map().await?;
+ let ws_id = self.get_ws_id()?.to_string();
+ let map = self.dss.ws_meta_map.lock("Wsm::edit_attribution");
+ let meta = map.get(&ws_id).context("missing ws metadata")?;
+ DocumentAttribution::from_session_claims(meta.actor.clone(), meta.user_id.clone())
+ .context("invalid signed websocket attribution")
+ }
+
+ pub async fn write_access(&mut self) -> Result<WriteAccess> {
+ self.maybe_update_ws_meta_map().await?;
+ let ws_id = self.get_ws_id()?.to_string();
+ Ok(self
+ .dss
+ .ws_meta_map
+ .lock("Wsm::write_access get")
+ .get(&ws_id)
+ .ok_or(Error::from("missing ws metadata"))?
+ .write_access())
+ }
+
+ pub async fn add_new_peerid(&mut self, peerid: u64, document_id: &str) -> Result<()> {
+ self.maybe_update_ws_meta_map().await?;
+
+ let ws_id = self.get_ws_id()?.to_string();
+
+ let new_peer = {
+ let mut wmm = self.dss.ws_meta_map.lock("Wsm::add_new_peerid get_mut");
+ let meta = wmm
+ .get_mut(&ws_id)
+ .ok_or(Error::from("missing ws metadata"))?;
+
+ if meta.peer_ids.insert(peerid) {
+ Some(meta.clone())
+ } else {
+ None
+ }
+ };
+ if let Some(meta) = new_peer {
+ self.dss.state.storage().put(&ws_id, &meta).await?;
+ // if user is not-anon
+ if let Some(user_id) = meta.user_id {
+ let db = self.dss.env.d1(USER_PEER_D1_BINDING)?;
+ insert_user_mapping(db, &user_id, peerid, document_id).await?;
+ }
+ }
+ Ok(())
+ }
+}
+pub fn get_ws_id(state: &State, ws: &WebSocket) -> Result<String> {
+ let tags = state.get_tags(ws);
+ get_ws_id_from_tags(&tags)
+}
+
+/// Schedule an alarm 5 seconds from now.
+async fn bump_alarm(state: &State) -> Result<()> {
+ let current_alarm = state.storage().get_alarm().await?;
+
+ if let Some(current_alarm) = current_alarm
+ && current_alarm as f64 > Date::now().as_millis() as f64
+ {
+ return Ok(());
+ }
+
+ state.storage().set_alarm(ScheduledTime::from(5000)).await?;
+
+ Ok(())
+}
+
+fn take_editors(editors: &Mutex<BTreeSet<DocumentAttribution>>) -> Vec<DocumentAttribution> {
+ std::mem::take(&mut *editors.lock("take document editors"))
+ .into_iter()
+ .collect()
+}
+
+impl SyncSession {
+ pub(crate) fn env(&self) -> &Env {
+ &self.env
+ }
+
+ pub(crate) fn socket_for(&self, ws: &WebSocket) -> Socket {
+ Socket::new(ws.clone(), self.inbound.clone())
+ }
+
+ pub(crate) fn get_sockets(&self) -> Vec<Socket> {
+ self.active_websockets()
+ .into_iter()
+ .map(|ws| self.socket_for(&ws))
+ .collect()
+ }
+
+ pub fn get_websockets(&self) -> Vec<WebSocket> {
+ self.active_websockets()
+ }
+
+ pub(crate) fn record_editor(&self, attribution: Option<&DocumentAttribution>) {
+ if let Some(attribution) = attribution {
+ self.pending_editors
+ .lock("record document editor")
+ .insert(attribution.clone());
+ }
+ }
+
+ async fn forget_websocket_metadata(&self, ws: &WebSocket) {
+ let Ok(ws_id) = get_ws_id(&self.state, ws) else {
+ return;
+ };
+ self.socket_for(ws).forget(&ws_id);
+ self.ws_meta_map
+ .lock("SyncSession::forget_websocket_metadata")
+ .remove(&ws_id);
+ if let Err(err) = self.state.storage().delete(&ws_id).await {
+ warn!(error=?err, ws_id, "failed to delete websocket metadata");
+ }
+ }
+
+ pub fn push_blame_events(&self, events: Vec<crate::d1::BlameEvent>) {
+ if events.is_empty() {
+ return;
+ }
+ self.pending_blame
+ .lock("SyncSession::push_blame_events")
+ .extend(events);
+ }
+
+ /// Drain the pending blame buffer and write all events via a single D1
+ /// batch in the background. Returns immediately; the actual write runs
+ /// inside `wait_until` so the alarm handler doesn't block on D1.
+ fn flush_pending_blame(&self) {
+ let pending: Vec<crate::d1::BlameEvent> =
+ std::mem::take(&mut *self.pending_blame.lock("SyncSession::flush_pending_blame"));
+ if pending.is_empty() {
+ return;
+ }
+ let env = self.env.clone();
+ self.state.wait_until(async move {
+ if let Err(e) = crate::d1::insert_blame_many(&env, &pending).await {
+ warn!(error = ?e, "failed to flush pending blame");
+ }
+ });
+ }
+ pub(super) fn secrets(&self) -> crate::secrets::Secrets {
+ crate::secrets::Secrets::from(&self.env)
+ }
+
+ pub(super) async fn debug_get(&self, key: &str) -> Result<Response> {
+ Response::from_json(&self.session_storage().await?.debug_do_kv_get(key).await?)
+ }
+
+ pub(super) async fn debug_list(&self, prefix: &str) -> Result<Response> {
+ let values: Vec<(String, Vec<u8>)> = self
+ .session_storage()
+ .await?
+ .debug_list_do_kv(prefix)
+ .await?
+ .into_iter()
+ .filter_map(Result::ok)
+ .collect();
+ Response::from_json(&values)
+ }
+
+ async fn inner_fetch(self: &Rc<Self>, req: Request) -> Result<Response> {
+ let url = req.url()?;
+ let segments: Vec<_> = url.path().split('/').collect();
+ if let ["", "document", id, ..] = segments.as_slice() {
+ tracing::Span::current().record("document.id", *id);
+ }
+ let migration = matches!(segments.as_slice(), ["", "document", _, "migration", _]);
+ if !url.path().starts_with("/surface/") && !migration && self.source_blocked().await? {
+ return Ok(response(status_codes::FORBIDDEN));
+ }
+ use tower_service::Service;
+ let mut router = super::router::document_router(self.clone());
+ let response = router.call(worker::HttpRequest::try_from(req)?).await;
+ let response = response.unwrap_or_else(|error: std::convert::Infallible| match error {});
+ Response::try_from(response)
+ }
+
+ pub(in crate::inbound) async fn initialize_handler(
+ &self,
+ mut req: Request,
+ document_id: &str,
+ ) -> Result<Response> {
+ // NB: we expect SyncSession to not be initialized. If it is initialized, it's an error.
+ let storage = get_snapshot_storage(&self.env, &self.state, document_id.to_string())?;
+
+ if storage.has_snapshot().await? {
+ return Response::error("snapshot already exists", 409);
+ } else {
+ debug!(document_id = document_id, "Initializing snapshot");
+ let body_raw = req.bytes().await?;
+ let body = InitializeFromSnapshotRequest::deserialize(&body_raw).with_context(|| format!("Failed to deserialize InitializeFromSnapshotRequest with document_id: [{document_id}]"))?;
+ // Services initialize documents (imports, uploads, copies), so the
+ // snapshot's peers belong to the system author unless already mapped.
+ // Mapped before storing: a failed store is retried, a stored one is not.
+ let writers = writing_peers(&body.snapshot)
+ .map_err(|error| Error::from(format!("invalid initial snapshot: {error}")))?;
+ let db = self.env.d1(USER_PEER_D1_BINDING)?;
+ insert_missing_user_mappings(&db, document_id, SYSTEM_AUTHOR_ID, &writers).await?;
+ storage.store_snapshot(&body.snapshot).await?;
+ *self
+ .document_id
+ .lock("SyncSession::document_id set within initialize_handler") =
+ Some(Arc::new(document_id.to_string()));
+ self.state
+ .storage()
+ .put(DOCUMENT_ID_KEY, document_id.to_string())
+ .await?;
+ let dkv_storage = DurableKVStorage::new(self.state.storage());
+ let session_storage = Rc::new(SessionStorage::new(
+ storage,
+ dkv_storage,
+ SessionKind::Document,
+ ));
+ *self
+ .session_storage
+ .lock("SyncSession::session_storage set within initialize_handler") =
+ Some(session_storage);
+ }
+
+ // Broadcast initial sync to any sockets that connected before init landed.
+ if let Ok(state) = self.document_state().await
+ && let Ok(snapshot) = state.export_shallow_snapshot()
+ {
+ let awareness = self.awareness.encode_all();
+ for ws in &self.state.get_websockets() {
+ if let Err(e) = protocol::send_initial_sync(
+ &self.socket_for(ws),
+ snapshot.as_slice(),
+ awareness.as_slice(),
+ ) {
+ warn!(
+ error =? e,
+ "failed to send delayed initial sync to a waiting peer"
+ );
+ }
+ }
+ let document_id_owned = document_id.to_string();
+ let env = self.env.clone();
+ self.state.wait_until(async move {
+ report_new_doc_state(&document_id_owned, &snapshot, &env, Vec::new()).await;
+ });
+ }
+
+ Response::empty()
+ }
+
+ /// Active peer ids. With `include_ai = false`, AI editors (peer ids from the
+ /// reserved AI block or signed agent actors) are filtered out.
+ pub(in crate::inbound) async fn active_peer_ids_handler(
+ &self,
+ include_ai: bool,
+ ) -> Result<Response> {
+ if !self.state.get_websockets().is_empty() {
+ self.validate_surface_sockets(None).await?;
+ }
+ let mut peer_ids: BTreeSet<u64> = BTreeSet::new();
+ for ws in self.get_websockets() {
+ peer_ids.extend(Wsm::new(self, &ws).get_peer_ids(include_ai).await?);
+ }
+ let str_ids = peer_ids
+ .into_iter()
+ .map(|p| p.to_string())
+ .collect::<Vec<String>>();
+
+ let result = serde_json::to_vec(&str_ids).context("Failed to serialize ids")?;
+ Ok(ResponseBuilder::new().body(ResponseBody::Body(result)))
+ }
+
+ pub(in crate::inbound) async fn exists_handler(&self, id: &str) -> Result<Response> {
+ Ok(response(if self.exists(id).await? {
+ status_codes::OK
+ } else {
+ status_codes::NOT_FOUND
+ }))
+ }
+
+ pub(in crate::inbound) async fn raw_handler(&self, document_id: &str) -> Result<Response> {
+ if !self.exists(document_id).await? {
+ return Ok(response(status_codes::NOT_FOUND));
+ }
+ let out = maybe_404!(self.document_state().await)?.get_json();
+ Ok(ResponseBuilder::new().body(ResponseBody::Body(out.into_bytes())))
+ }
+
+ pub(in crate::inbound) async fn snapshot_handler(
+ &self,
+ mut req: Request,
+ document_id: &str,
+ ) -> Result<Response> {
+ if !self.exists(document_id).await? {
+ return Ok(response(status_codes::NOT_FOUND));
+ }
+
+ let bytes = req.bytes().await?;
+ let body: Option<GetSnapshotRequest> = if bytes.is_empty() {
+ None
+ } else {
+ Some(serde_json::from_slice(&bytes)?)
+ };
+
+ let frontiers = match body.and_then(|request| request.version_id) {
+ Some(version) => {
+ let Ok(peer) = version.peer.parse::<u64>() else {
+ return Ok(response(400));
+ };
+ if version.counter < 0 {
+ return Ok(response(400));
+ }
+ Some(ExportMode::StateOnly(Some(Cow::Owned(
+ loro::Frontiers::ID(loro::ID::new(peer, version.counter)),
+ ))))
+ }
+ None => None,
+ };
+
+ let out = maybe_404!(self.document_state().await)?
+ .export_snapshot(frontiers)
+ .context("Couldn't export snapshot")?;
+ Ok(ResponseBuilder::new().body(ResponseBody::Body(out)))
+ }
+
+ pub(in crate::inbound) async fn dump_operations(&self, document_id: &str) -> Result<Response> {
+ if !self.exists(document_id).await? {
+ return Ok(response(status_codes::NOT_FOUND));
+ }
+ let pending_ops = self
+ .session_storage()
+ .await?
+ .get_pending_operations()
+ .await?;
+
+ let n_pending_ops = pending_ops.len();
+ trace!(
+ pending_ops_len = n_pending_ops,
+ "Applying [{}] pending ops", n_pending_ops
+ );
+
+ let mut ers = vec![];
+ let mut key_ops = vec![];
+ for res_op in pending_ops {
+ match res_op {
+ Ok((k, o)) => key_ops.push((k, o)),
+ Err(e) => ers.push(e),
+ }
+ }
+ if !ers.is_empty() {
+ error!(errors =? ers, "DO KV operations got [{}] errors", ers.len());
+ }
+
+ ResponseBuilder::new().from_json(&key_ops)
+ }
+
+ pub(in crate::inbound) async fn peer_handler(
+ &self,
+ document_id: &str,
+ peer_id: Option<&str>,
+ ) -> Result<Response> {
+ let (user_id, peer_id) = if let Some(p) = peer_id {
+ let p64: u64 = p
+ .parse()
+ .with_context(|| format!("Couldn't parse peer_id: '{p}' into u64"))?;
+ let db = self.env.d1(USER_PEER_D1_BINDING)?;
+ let user_id = get_user_id_from_peer_id(db, document_id, &p64).await?;
+ (user_id, p.to_string())
+ } else {
+ return Err(Error::from("missing `peer_id` in path"));
+ };
+ ResponseBuilder::new().from_json(&PeerResponse { peer_id, user_id })
+ }
+
+ pub(in crate::inbound) async fn wakeup(&self, document_id: &str) -> Result<Response> {
+ let _ = self.warmup(document_id).await.inspect_err(
+ |error| warn!(document_id = document_id, error = ?error, "failed to warm up document"),
+ );
+
+ let out = keepalive(DEFAULT_TIME_TO_LIVE);
+ ResponseBuilder::new().from_json(&out)
+ }
+
+ async fn warmup(&self, document_id: &str) -> Result<()> {
+ if !self.exists(document_id).await? {
+ return Ok(());
+ }
+
+ self.session_storage().await?;
+ self.document_state().await?;
+ Ok(())
+ }
+
+ pub(in crate::inbound) async fn metadata_handler(&self, document_id: &str) -> Result<Response> {
+ if !self.exists(document_id).await? {
+ return Ok(response(status_codes::NOT_FOUND));
+ }
+ let db = self.env.d1(USER_PEER_D1_BINDING)?;
+ let peers = crate::d1::get_peers_for_document_id(db, document_id).await?;
+ let version_id = self.document_state().await?.version_id();
+ ResponseBuilder::new().from_json(&DocumentMetadata {
+ peers,
+ version_id: version_id.to_string(),
+ id: document_id.to_string(),
+ })
+ }
+
+ pub(in crate::inbound) async fn blame_handler(
+ &self,
+ node_id: Option<&str>,
+ ) -> Result<Response> {
+ let node_id = node_id.ok_or_else(|| Error::from("missing node_id"))?;
+ let document_id = self.document_id().await?.to_string();
+ let db = self.env.d1(USER_PEER_D1_BINDING)?;
+ match crate::d1::get_blame_for_node(db, &document_id, node_id).await? {
+ Some(row) => ResponseBuilder::new().from_json(&row),
+ None => Ok(response(status_codes::NOT_FOUND)),
+ }
+ }
+
+ pub(in crate::inbound) async fn connect(
+ &self,
+ claims: AuthToken,
+ document_id: &str,
+ ) -> Result<Response> {
+ let (res, elap) = timeit!({
+ if self.maybe_set_document_id(document_id).await? {
+ trace!("init document_id={document_id}");
+ } else {
+ trace!("document_id={document_id} already set");
+ }
+
+ // Below is websocket stuff only i.e connect
+ let pair = WebSocketPair::new().context("failed to create websocket pair")?;
+
+ // Whether this peer is the first to join the session (used to
+ // decide whether to report a `FirstJoin` interaction below).
+ let is_first_join = self.state.get_websockets().is_empty();
+
+ // create tag for ws and store it
+ let ws_id = new_ws_id();
+ trace!(ws_id = ws_id, "websocket connect");
+
+ self.state
+ .accept_websocket_with_tags(&pair.server, &[&ws_id]);
+
+ let ws_meta = WebSocketMetadata {
+ user_id: claims.user_id,
+ access_level: claims.access_level,
+ actor: claims.actor,
+ peer_ids: Default::default(),
+ session_kind: claims.session_kind,
+ expires_at: claims.expires_at,
+ };
+
+ self.state.storage().put(&ws_id, &ws_meta).await?;
+ self.ws_meta_map
+ .lock("SyncSession::ws_meta_map insert in connect_handler")
+ .insert(ws_id, ws_meta);
+
+ // A surface may have been revoked while socket metadata was being
+ // persisted. Recheck before sending any initial content.
+ if claims.session_kind == SessionKind::Surface
+ && !self.validate_surface_sockets(Some(&pair.server)).await?
+ {
+ return Ok(response(status_codes::FORBIDDEN));
+ }
+
+ // If the snapshot is already in storage, send the initial sync now.
+ // Otherwise accept the WS without sending — initialize_handler will
+ // broadcast initial sync to this socket once /initialize lands.
+ let snapshot = self
+ .document_state()
+ .await
+ .and_then(|state| state.export_shallow_snapshot());
+
+ if let Ok(snapshot) = snapshot {
+ // Size of the initial sync this connect sent — the server end
+ // of the client's `doc.sync.initial-sync` span.
+ tracing::Span::current().record("snapshot.bytes", snapshot.len());
+ protocol::send_initial_sync(
+ &self.socket_for(&pair.server),
+ snapshot.as_slice(),
+ self.awareness.encode_all().as_slice(),
+ )
+ .context("failed to send initial sync message")?;
+ } else {
+ debug!(
+ document_id = document_id,
+ "snapshot not yet available; deferring initial sync until /initialize"
+ );
+ }
+
+ // This is the single source of truth for `FirstJoin`: whenever
+ // the peer count genuinely transitions 0 -> 1, regardless of
+ // whether the document already has content.
+ if is_first_join {
+ let document_id_owned = document_id.to_string();
+ let env = self.env.clone();
+ self.state.wait_until(async move {
+ report_interaction(&document_id_owned, &env, InteractionReason::FirstJoin)
+ .await;
+ });
+ }
+
+ if claims.session_kind == SessionKind::Surface {
+ bump_alarm(&self.state).await?;
+ }
+ Response::from_websocket(pair.client).context("failed to create websocket response")?
+ });
+
+ trace!(
+ document_id = document_id,
+ duration_ms = elap.as_millis(),
+ "DO::connect"
+ );
+ Ok(res)
+ }
+
+ async fn maybe_set_document_id(&self, document_id: &str) -> Result<bool> {
+ if !self.document_id_is_some() {
+ debug!("Setting DO::kv({DOCUMENT_ID_KEY}, {document_id})");
+ self.state
+ .storage()
+ .put(DOCUMENT_ID_KEY, document_id)
+ .await?;
+ *self
+ .document_id
+ .lock("SyncSession::document_id set within maybe_set_document_id") =
+ Some(Arc::new(document_id.to_string()));
+ Ok(true)
+ } else {
+ Ok(false)
+ }
+ }
+
+ /// A connected room identity does not imply initialized collaborative content.
+ async fn exists(&self, document_id: &str) -> Result<bool> {
+ let snapshot_storage =
+ get_snapshot_storage(&self.env, &self.state, document_id.to_string())?;
+
+ if snapshot_storage.has_snapshot().await? {
+ self.maybe_set_document_id(document_id).await?;
+ // set up session storage
+ let dkv_storage = DurableKVStorage::new(self.state.storage());
+ let session_storage = Rc::new(SessionStorage::new(
+ snapshot_storage,
+ dkv_storage,
+ session_kind_from_storage_key(document_id),
+ ));
+ *self
+ .session_storage
+ .lock("SyncSession::session_storage set within exists") = Some(session_storage);
+ return Ok(true);
+ }
+ Ok(false)
+ }
+
+ fn document_id_is_some(&self) -> bool {
+ self.document_id
+ .lock("SyncSession::document_id check is_some()")
+ .is_some()
+ }
+
+ #[instrument(skip_all, err)]
+ /// Get the `document_id`. First try checking self.document_id, if not there get from DOKV.
+ async fn document_id(&self) -> Result<Arc<String>> {
+ self.try_document_id()
+ .await?
+ .ok_or(Error::from("DOCUMENT_ID not found in storage"))
+ }
+
+ /// Like [`Self::document_id`], but `None` instead of an error when this
+ /// object holds no session.
+ async fn try_document_id(&self) -> Result<Option<Arc<String>>> {
+ if let Some(id) = self
+ .document_id
+ .lock("SyncSession::document_id get within main document_id fn")
+ .as_ref()
+ .cloned()
+ {
+ return Ok(Some(id));
+ }
+ let Some(id) = self
+ .state
+ .storage()
+ .get::<String>(DOCUMENT_ID_KEY)
+ .await
+ .with_context(|| {
+ format!(
+ "Could not get document_id via DOCUMENT_ID_KEY = [{}] from DO storage",
+ DOCUMENT_ID_KEY
+ )
+ })?
+ else {
+ return Ok(None);
+ };
+ let id = Arc::new(id);
+ *self
+ .document_id
+ .lock("SyncSession::document_id set within main document_id fn") = Some(id.clone());
+ Ok(Some(id))
+ }
+
+ async fn session_storage(&self) -> Result<Rc<SessionStorage>> {
+ if let Some(ss) = self
+ .session_storage
+ .lock("session_storage get within main session_storage fn")
+ .as_ref()
+ {
+ Ok(ss.clone())
+ } else {
+ let id = self.document_id().await?.to_string();
+ let snapshot_storage = get_snapshot_storage(&self.env, &self.state, id.clone())?;
+ let dkv_storage = DurableKVStorage::new(self.state.storage());
+ let ss = Rc::new(SessionStorage::new(
+ snapshot_storage,
+ dkv_storage,
+ session_kind_from_storage_key(&id),
+ ));
+ *self
+ .session_storage
+ .lock("SyncSession::session_storage set within main session_storage fn") =
+ Some(ss.clone());
+ Ok(ss)
+ }
+ }
+
+ /// Gets DocumentState, loading it if needed
+ async fn document_state(&self) -> Result<Arc<DocumentState>> {
+ let Some(x) = self
+ .document_state
+ .lock("SyncSession::document_state get within main document_state fn")
+ .as_ref()
+ .cloned()
+ else {
+ let ss = Arc::new(self.session_storage().await?.load_document_state().await?);
+ *self
+ .document_state
+ .lock("SyncSession::document_state set within main document_state fn") =
+ Some(ss.clone());
+ return Ok(ss);
+ };
+ Ok(x)
+ }
+}
+
+pub use crate::domain::models::{
+ CopyDocumentRequest, DocumentMetadata, GetSnapshotRequest, PeerResponse,
+};
+
+/// Cloudflare callback adapter. The shared session is confined to one isolate.
+#[durable_object]
+pub struct DocumentSyncSession {
+ session: Rc<SyncSession>,
+}
+
+impl DurableObject for DocumentSyncSession {
+ fn new(state: State, env: Env) -> Self {
+ Self {
+ session: Rc::new(SyncSession::new(state, env)),
+ }
+ }
+
+ async fn fetch(&self, req: Request) -> Result<Response> {
+ self.session.fetch(req).await
+ }
+
+ async fn websocket_message(&self, ws: WebSocket, msg: WebSocketIncomingMessage) -> Result<()> {
+ self.session.websocket_message(ws, msg).await
+ }
+
+ async fn alarm(&self) -> Result<Response> {
+ self.session.alarm().await
+ }
+
+ async fn websocket_close(
+ &self,
+ ws: WebSocket,
+ code: usize,
+ reason: String,
+ was_clean: bool,
+ ) -> Result<()> {
+ self.session
+ .websocket_close(ws, code, reason, was_clean)
+ .await
+ }
+
+ async fn websocket_error(&self, ws: WebSocket, error: Error) -> Result<()> {
+ self.session.websocket_error(ws, error).await
+ }
+}
diff --git a/services/sync-service/src/inbound/durable_object/callbacks.rs b/services/sync-service/src/inbound/durable_object/callbacks.rs
new file mode 100644
index 0000000000..cafe842c9a
--- /dev/null
+++ b/services/sync-service/src/inbound/durable_object/callbacks.rs
@@ -0,0 +1,304 @@
+use super::*;
+
+impl SyncSession {
+ pub(super) fn new(state: State, env: Env) -> Self {
+ Self {
+ state,
+ env,
+ document_id: Mutex::new(None),
+ document_state: Mutex::new(None),
+ session_storage: Mutex::new(None),
+ awareness: EphemeralStore::new(5_000),
+ ws_meta_map: Arc::new(Mutex::new(Default::default())),
+ inbound: Arc::new(Mutex::new(HashMap::new())),
+ pending_blame: Arc::new(Mutex::new(Vec::new())),
+ pending_editors: Arc::new(Mutex::new(Default::default())),
+ mapped_writing_peers: Mutex::new(Default::default()),
+ surface_lifecycle: Mutex::new(None),
+ source_migration: Mutex::new(None),
+ mutation_barrier: futures::lock::Mutex::new(()),
+ }
+ }
+
+ /// Fetch the durable object
+ /// Upgrades the request to a websocket request connected to the document session
+ pub(super) async fn fetch(self: &Rc<Self>, req: Request) -> Result<Response> {
+ let _barrier = self.mutation_barrier.lock().await;
+ let set_allow_origin = if let Some(origin) = req
+ .headers()
+ .get("Origin")
+ .context("No `Origin` header found in header")?
+ {
+ if is_origin_allowed(&origin) {
+ Some(origin)
+ } else {
+ return Ok(response(status_codes::FORBIDDEN));
+ }
+ } else {
+ None
+ };
+
+ if req.method() == Method::Options {
+ return Ok(Response::builder()
+ .with_status(status_codes::OK)
+ .with_cors(&cors(set_allow_origin.as_deref()))?
+ .empty());
+ }
+ let traceparent = worker_rs_otel::traceparent_from_request(&req);
+ let (remote_id, remote_parent) = worker_rs_otel::remote_fields(traceparent.as_ref());
+ let path = req.path();
+ let span = tracing::info_span!(
+ "do.request",
+ http.path = %path,
+ document.id = tracing::field::Empty,
+ snapshot.bytes = tracing::field::Empty,
+ trace.remote_id = %remote_id,
+ trace.remote_parent = %remote_parent,
+ );
+
+ // Log the failure inside the span and the scope: the scope flushes
+ // telemetry when it ends, and a log buffered after it is only exported
+ // if a later request on the same isolate happens to flush it.
+ let res = worker_rs_otel::scope(
+ &self.env,
+ &self.state,
+ async {
+ self.inner_fetch(req)
+ .await
+ .context("DurableObject::fetch error")
+ }
+ .instrument(span),
+ )
+ .await;
+ res?.with_cors(&cors(set_allow_origin.as_deref()))
+ }
+
+ pub(super) async fn websocket_message(
+ &self,
+ ws: WebSocket,
+ msg: WebSocketIncomingMessage,
+ ) -> Result<()> {
+ let _barrier = self.mutation_barrier.lock().await;
+ if self.source_blocked().await? {
+ ws.close(Some(1008), Some("session frozen or retired"))?;
+ return Ok(());
+ }
+ if !self.validate_surface_sockets(Some(&ws)).await? {
+ return Ok(());
+ }
+ const PONG: &str = "pong";
+ const PING: &str = "ping";
+ let binary_message = match msg {
+ WebSocketIncomingMessage::String(message) => {
+ // Heartbeat: deliberately unspanned to keep it out of traces.
+ if message == PING {
+ ws.send_with_str(PONG).ok();
+ } else {
+ return worker_rs_otel::scope(&self.env, &self.state, async {
+ warn!("Received unknown 'String' message: {message:?}");
+ Ok(())
+ })
+ .await;
+ }
+ return Ok(());
+ }
+ WebSocketIncomingMessage::Binary(bm) => bm,
+ };
+ let socket = self.socket_for(&ws);
+ let ws_id = get_ws_id(&self.state, &ws)?;
+ let Some(binary_message) = socket.receive(&ws_id, &binary_message)? else {
+ return Ok(());
+ };
+ worker_rs_otel::scope(&self.env, &self.state, async {
+ let mut telemetry = protocol::InboundMessageTelemetry::new(binary_message.len());
+
+ let res: Result<()> = async {
+ let document_id = self.document_id().await.inspect_err(|_| {
+ telemetry.record_error_stage("document_context");
+ })?;
+ let ws_id = get_ws_id_from_tags(&self.state.get_tags(&ws)).ok();
+ telemetry.record_context(&document_id, ws_id);
+
+ let message = protocol::deserialize_message(&binary_message).inspect_err(|_| {
+ telemetry.record_message_type("invalid");
+ telemetry.record_error_stage("deserialize");
+ })?;
+ telemetry.record_message_type(protocol::message_type(&message));
+
+ protocol::process_message(
+ &self.socket_for(&ws),
+ &document_id,
+ &*self.document_state().await?,
+ &*self.session_storage().await?,
+ &self.awareness,
+ message,
+ self,
+ &mut telemetry,
+ )
+ .await
+ .inspect_err(|_| {
+ telemetry.record_error_stage("process");
+ })
+ .context("failed to process websocket message")?;
+
+ bump_alarm(&self.state)
+ .await
+ .inspect_err(|_| {
+ telemetry.record_error_stage("alarm");
+ })
+ .context("failed to keep document alive")?;
+
+ Ok(())
+ }
+ .await;
+
+ if let Err(error) = &res {
+ let span = telemetry.error_span();
+ {
+ let _entered = span.enter();
+ tracing::error!(error = ?error, "failed to handle websocket message");
+ }
+ }
+ res
+ })
+ .await
+ }
+
+ /// Save document if needed
+ pub(super) async fn alarm(&self) -> Result<Response> {
+ let _barrier = self.mutation_barrier.lock().await;
+ if self.source_blocked().await? {
+ return Response::empty();
+ }
+ self.validate_surface_sockets(None).await?;
+ let span = tracing::info_span!("do.alarm");
+ worker_rs_otel::scope(&self.env, &self.state, async {
+ let state = match self
+ .document_state()
+ .await
+ .context("failed to get document_state")
+ {
+ Ok(x) => x,
+ Err(_e) => {
+ // This is likely due to a programming issue. We don't return `Err`
+ // because it wuld cause this alarm to retry, then fail again.
+ return Response::empty();
+ }
+ };
+
+ if state.should_save() {
+ let seshs = self
+ .session_storage()
+ .await
+ .context("failed to get session storage")?;
+
+ // Keeps the worker alive for DEFAULT_TIME_TO_LIVE
+ keepalive(DEFAULT_TIME_TO_LIVE);
+
+ let doc_state = self.document_state().await?;
+ let (sf, of) = doc_state.frontiers();
+ seshs
+ .store_snapshot(&doc_state)
+ .await
+ .context("failed to store snapshot")?;
+
+ debug!(state_frontiers =? sf, oplog_frontiers =? of, "Stored new DocumentState");
+ seshs
+ .clear_applied_ops()
+ .await
+ .context("failed deleting applied ops")?;
+
+ state.mark_exported();
+
+ let document_id = self.document_id().await.ok();
+ let pending_editors = self.pending_editors.clone();
+ let env = self.env.clone();
+ self.state.wait_until(async move {
+ if let Some(document_id) = document_id
+ && let Ok(snapshot) = doc_state.export_shallow_snapshot()
+ {
+ let editors = take_editors(&pending_editors);
+ report_new_doc_state(&document_id, &snapshot, &env, editors).await;
+ report_interaction(&document_id, &env, InteractionReason::Edited).await;
+ }
+ });
+ }
+
+ self.flush_pending_blame();
+
+ // Re-arm the alarm while clients are connected so the in-memory state
+ // stays warm and pending updates keep getting persisted. Updates reach
+ // peers when they happen (PeerUpdate broadcast); pushing a full
+ // snapshot to every client on every alarm tick only burned bandwidth
+ // and stalled clients on large documents.
+ if !self.state.get_websockets().is_empty() {
+ bump_alarm(&self.state)
+ .await
+ .context("failed to keep document alive")?;
+ } else {
+ info!("durable object has reached 0 connections")
+ }
+
+ Response::ok("ok")
+ }
+ .instrument(span))
+ .await
+ }
+
+ pub(super) async fn websocket_close(
+ &self,
+ ws: WebSocket,
+ _code: usize,
+ _reason: String,
+ _was_clean: bool,
+ ) -> Result<()> {
+ let _barrier = self.mutation_barrier.lock().await;
+ if self.source_blocked().await? {
+ self.forget_websocket_metadata(&ws).await;
+ return Ok(());
+ }
+ worker_rs_otel::scope(&self.env, &self.state, async {
+ // Sockets closed by `delete_handler` report back after the session is gone.
+ if self.try_document_id().await?.is_none() {
+ self.forget_websocket_metadata(&ws).await;
+ return Ok(());
+ }
+ self.validate_surface_sockets(None).await?;
+ let peer_ids = Wsm::new(self, &ws).get_peer_ids(true).await?;
+ for peer_id in peer_ids {
+ self.awareness.delete(&peer_id.to_string());
+ let update = self.awareness.encode(&peer_id.to_string());
+
+ // Don't silently discard the error
+ protocol::broadcast_awareness(self, &self.socket_for(&ws), update.as_slice())
+ .context("failed to broadcast awareness")?;
+ }
+
+ if self.state.get_websockets().len() == 1
+ && let Ok(state) = self.document_state().await
+ && let Ok(document_id) = self.document_id().await
+ && let Ok(snapshot) = state.export_shallow_snapshot()
+ {
+ let editors = take_editors(&self.pending_editors);
+ let env = self.env.clone();
+ self.state.wait_until(async move {
+ report_new_doc_state(&document_id, &snapshot, &env, editors).await;
+ report_interaction(&document_id, &env, InteractionReason::LastLeave).await;
+ });
+ }
+ self.forget_websocket_metadata(&ws).await;
+ Ok(())
+ })
+ .await
+ }
+
+ pub(super) async fn websocket_error(&self, ws: WebSocket, error: Error) -> Result<()> {
+ worker_rs_otel::scope(&self.env, &self.state, async {
+ let ws_id = get_ws_id(&self.state, &ws)?;
+ error!(ws_id = ws_id, error = ?error, "websocket error");
+ // TODO update awareness stuff
+ Ok(())
+ })
+ .await
+ }
+}
diff --git a/services/sync-service/src/durable_object/document_api.rs b/services/sync-service/src/inbound/durable_object/document_api.rs
similarity index 92%
rename from services/sync-service/src/durable_object/document_api.rs
rename to services/sync-service/src/inbound/durable_object/document_api.rs
index 28a6dc1d42..5d2716658f 100644
--- a/services/sync-service/src/durable_object/document_api.rs
+++ b/services/sync-service/src/inbound/durable_object/document_api.rs
@@ -16,19 +16,22 @@ const MAX_BODY_BYTES: usize = (MAX_BINARY_BYTES + MAX_REVISION_BYTES).div_ceil(3
#[derive(Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
-struct UpdateRequest {
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub(crate) struct UpdateRequest {
expected_revision: String,
update: String,
}
#[derive(Serialize)]
-struct SnapshotResponse {
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub(crate) struct SnapshotResponse {
snapshot: String,
revision: String,
}
#[derive(Serialize)]
-struct UpdateResponse {
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+pub(crate) struct UpdateResponse {
revision: String,
applied: bool,
}
@@ -49,18 +52,15 @@ fn error_response(error: DocumentError) -> Result<Response> {
)
}
-impl DocumentSyncSession {
- pub(super) async fn document_handler(
+impl SyncSession {
+ pub(in crate::inbound) async fn document_handler(
&self,
mut req: Request,
document_id: &str,
is_update: bool,
+ access: crate::domain::document::DocumentAccess,
+ claims: crate::auth::AuthToken,
) -> Result<Response> {
- // A shared internal key never bypasses the user/document permission JWT.
- let (access, claims) = match crate::auth::document_access(&req, &self.env, document_id) {
- Ok(access) => access,
- Err(error) => return error_response(error),
- };
if req.method() != if is_update { Method::Post } else { Method::Get } {
return Ok(response(405));
}
diff --git a/services/sync-service/src/durable_object/document_delete.rs b/services/sync-service/src/inbound/durable_object/document_delete.rs
similarity index 81%
rename from services/sync-service/src/durable_object/document_delete.rs
rename to services/sync-service/src/inbound/durable_object/document_delete.rs
index e905d7f24f..c38cf4173c 100644
--- a/services/sync-service/src/durable_object/document_delete.rs
+++ b/services/sync-service/src/inbound/durable_object/document_delete.rs
@@ -2,31 +2,20 @@
//! service calls this after it has deleted the document and its files.
use tracing::warn;
-use worker::{Method, Request, Response, Result};
+use worker::{Response, Result};
-use super::{DocumentSyncSession, response, status_codes};
+use super::{SyncSession, response, status_codes};
use crate::{
- auth::is_internal,
constants::USER_PEER_D1_BINDING,
d1::delete_document_rows,
storage::{get_snapshot_storage, snapshot::SnapshotStorage},
};
-impl DocumentSyncSession {
+impl SyncSession {
/// Erase the snapshot, operation log, socket metadata, peer mappings, and
/// blame for `document_id`. Idempotent: a document that never had a
/// session is already deleted.
- pub(super) async fn delete_handler(
- &self,
- req: &Request,
- document_id: &str,
- ) -> Result<Response> {
- if !is_internal(req, &self.env)? {
- return Ok(response(status_codes::UNAUTH));
- }
- if req.method() != Method::Delete {
- return Ok(response(405));
- }
+ pub(in crate::inbound) async fn delete_handler(&self, document_id: &str) -> Result<Response> {
for socket in self.state.get_websockets() {
if let Err(error) = socket.close(Some(1008), Some("document deleted")) {
warn!(error = ?error, "failed to close socket of deleted document");
diff --git a/services/sync-service/src/durable_object/document_effects.rs b/services/sync-service/src/inbound/durable_object/document_effects.rs
similarity index 95%
rename from services/sync-service/src/durable_object/document_effects.rs
rename to services/sync-service/src/inbound/durable_object/document_effects.rs
index 45e0e2782f..7eaf01c8c3 100644
--- a/services/sync-service/src/durable_object/document_effects.rs
+++ b/services/sync-service/src/inbound/durable_object/document_effects.rs
@@ -4,9 +4,7 @@ use macro_sync_service_jwt::session::SessionKind;
use tracing::{error, warn};
use worker::Env;
-use super::{
- DocumentSyncSession, bump_alarm, surface_api::session_kind_from_storage_key, take_editors,
-};
+use super::{SyncSession, bump_alarm, surface_api::session_kind_from_storage_key, take_editors};
use crate::{
domain::document::{DocumentAttribution, DocumentError, DocumentUpdateEffects},
dss_internal::{DssInternal, DssInternalClient, InteractionReason},
@@ -53,7 +51,7 @@ pub(super) async fn report_interaction(session_key: &str, env: &Env, reason: Int
}
pub(super) struct WorkerDocumentEffects<'a> {
- pub session: &'a DocumentSyncSession,
+ pub session: &'a SyncSession,
pub document_state: &'a DocumentState,
pub document_id: &'a str,
pub attribution: Option<&'a DocumentAttribution>,
diff --git a/services/sync-service/src/durable_object/peer_ids.rs b/services/sync-service/src/inbound/durable_object/peer_ids.rs
similarity index 100%
rename from services/sync-service/src/durable_object/peer_ids.rs
rename to services/sync-service/src/inbound/durable_object/peer_ids.rs
diff --git a/services/sync-service/src/durable_object/peer_ids/test.rs b/services/sync-service/src/inbound/durable_object/peer_ids/test.rs
similarity index 100%
rename from services/sync-service/src/durable_object/peer_ids/test.rs
rename to services/sync-service/src/inbound/durable_object/peer_ids/test.rs
diff --git a/services/sync-service/src/durable_object/surface_api.rs b/services/sync-service/src/inbound/durable_object/surface_api.rs
similarity index 92%
rename from services/sync-service/src/durable_object/surface_api.rs
rename to services/sync-service/src/inbound/durable_object/surface_api.rs
index c1e08cfaba..f9224fb3ba 100644
--- a/services/sync-service/src/durable_object/surface_api.rs
+++ b/services/sync-service/src/inbound/durable_object/surface_api.rs
@@ -5,9 +5,9 @@ use macro_sync_service_jwt::session::{SessionIdentity, SessionKind};
use serde::{Deserialize, Serialize};
use worker::{Date, Method, Request, Response, Result, WebSocket};
-use super::{DocumentSyncSession, WebSocketMetadata, Wsm, response, status_codes};
+use super::{SyncSession, WebSocketMetadata, Wsm, response, status_codes};
use crate::{
- auth::{TokenFrom, WriteAccess, is_internal, surface_access},
+ auth::WriteAccess,
error::ResultExt,
generated::schema::InitializeFromSnapshotRequest,
state::DocumentState,
@@ -80,7 +80,7 @@ fn now_seconds() -> usize {
(Date::now().as_millis() / 1000) as usize
}
-impl DocumentSyncSession {
+impl SyncSession {
pub(super) async fn surface_lifecycle(&self) -> Result<SurfaceLifecycle> {
if let Some(value) = *self.surface_lifecycle.lock("surface lifecycle cached") {
return Ok(value);
@@ -96,7 +96,11 @@ impl DocumentSyncSession {
Ok(*cached.get_or_insert(value))
}
- pub(super) async fn surface_handler(&self, req: Request) -> Result<Response> {
+ pub(in crate::inbound) async fn surface_handler(
+ &self,
+ req: Request,
+ claims: Option<crate::auth::AuthToken>,
+ ) -> Result<Response> {
let url = req.url()?;
let segments: Vec<_> = url.path().split('/').collect();
let ["", "surface", id, operation, rest @ ..] = segments.as_slice() else {
@@ -123,23 +127,6 @@ impl DocumentSyncSession {
if req.method() != allowed_method {
return Ok(response(405));
}
- if matches!(
- *operation,
- "initialize" | "revoke" | "initialize_verified" | "import" | "verify" | "activate"
- ) {
- if !is_internal(&req, &self.env)? {
- return Ok(response(status_codes::UNAUTH));
- }
- } else {
- let source = if *operation == "connect" {
- TokenFrom::QueryParams
- } else {
- TokenFrom::Headers
- };
- if surface_access(&req, &self.env, source, &identity).is_err() {
- return Ok(response(status_codes::UNAUTH));
- }
- }
let key = identity.storage_key();
let persisted: Option<String> = self.state.storage().get(super::DOCUMENT_ID_KEY).await?;
if persisted.is_some_and(|persisted| persisted != key) {
@@ -175,7 +162,12 @@ impl DocumentSyncSession {
return Ok(response(status_codes::FORBIDDEN));
}
match *operation {
- "connect" => self.connect_handler(req, &key).await,
+ "connect" => {
+ let Some(claims) = claims else {
+ return Ok(response(status_codes::UNAUTH));
+ };
+ self.connect(claims, &key).await
+ }
"snapshot" => {
let snapshot = self.document_state().await?.export_snapshot(None)?;
Ok(Response::builder().body(worker::ResponseBody::Body(snapshot)))
diff --git a/services/sync-service/src/durable_object/surface_api/test.rs b/services/sync-service/src/inbound/durable_object/surface_api/test.rs
similarity index 100%
rename from services/sync-service/src/durable_object/surface_api/test.rs
rename to services/sync-service/src/inbound/durable_object/surface_api/test.rs
diff --git a/services/sync-service/src/durable_object/surface_migration.rs b/services/sync-service/src/inbound/durable_object/surface_migration.rs
similarity index 97%
rename from services/sync-service/src/durable_object/surface_migration.rs
rename to services/sync-service/src/inbound/durable_object/surface_migration.rs
index 9d5878f742..796c8a230c 100644
--- a/services/sync-service/src/durable_object/surface_migration.rs
+++ b/services/sync-service/src/inbound/durable_object/surface_migration.rs
@@ -10,14 +10,13 @@ use loro::{Frontiers, VersionVector};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use uuid::Uuid;
-use worker::{Method, Request, Response, Result};
+use worker::{Request, Response, Result};
use super::{
- DocumentSyncSession, response,
+ SyncSession, response,
surface_api::{LIFECYCLE_KEY, SurfaceLifecycle},
};
use crate::{
- auth::is_internal,
error::ResultExt,
state::DocumentState,
storage::{
@@ -127,7 +126,7 @@ fn persistence_boundary(req: &Request, boundary: &str) -> Result<()> {
Ok(())
}
-impl DocumentSyncSession {
+impl SyncSession {
async fn source_state(&self) -> Result<SourceState> {
if let Some(value) = self.source_migration.lock("source state").clone() {
return Ok(value);
@@ -211,18 +210,12 @@ impl DocumentSyncSession {
state.export_snapshot(None)
}
- pub(super) async fn source_migration_handler(
+ pub(in crate::inbound) async fn source_migration_handler(
&self,
mut req: Request,
id: &str,
operation: &str,
) -> Result<Response> {
- if !is_internal(&req, &self.env)? {
- return Ok(response(401));
- }
- if req.method() != Method::Post {
- return Ok(response(405));
- }
let Ok(source_id) = Uuid::parse_str(id) else {
return Ok(response(400));
};
diff --git a/services/sync-service/src/inbound/durable_object/u64_serde_strings.rs b/services/sync-service/src/inbound/durable_object/u64_serde_strings.rs
new file mode 100644
index 0000000000..827ccd97b7
--- /dev/null
+++ b/services/sync-service/src/inbound/durable_object/u64_serde_strings.rs
@@ -0,0 +1,18 @@
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+use std::collections::BTreeSet;
+
+pub fn serialize<S: Serializer>(value: &BTreeSet<u64>, serializer: S) -> Result<S::Ok, S::Error> {
+ let string_set: BTreeSet<String> = value.iter().map(|x| x.to_string()).collect();
+ string_set.serialize(serializer)
+}
+
+pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<BTreeSet<u64>, D::Error> {
+ let string_set: BTreeSet<String> = BTreeSet::deserialize(deserializer)?;
+ string_set
+ .into_iter()
+ .map(|s| s.parse::<u64>().map_err(serde::de::Error::custom))
+ .collect()
+}
+
+#[cfg(test)]
+mod test;
diff --git a/services/sync-service/src/inbound/durable_object/u64_serde_strings/test.rs b/services/sync-service/src/inbound/durable_object/u64_serde_strings/test.rs
new file mode 100644
index 0000000000..f3acfdc3c8
--- /dev/null
+++ b/services/sync-service/src/inbound/durable_object/u64_serde_strings/test.rs
@@ -0,0 +1,15 @@
+use super::*;
+#[derive(Serialize, Deserialize)]
+struct Foo {
+ #[serde(with = "super")]
+ set: BTreeSet<u64>,
+}
+#[test]
+fn serde_u64_btree_set() -> std::result::Result<(), Box<dyn std::error::Error>> {
+ let data = BTreeSet::from([1_u64, u64::MAX, u64::MIN, 0, 42]);
+ let obj = Foo { set: data.clone() };
+ let json = serde_json::to_string(&obj)?;
+ let result: Foo = serde_json::from_str(&json)?;
+ assert_eq!(result.set, data);
+ Ok(())
+}
diff --git a/services/sync-service/src/inbound/router.rs b/services/sync-service/src/inbound/router.rs
new file mode 100644
index 0000000000..c3efcd3ee0
--- /dev/null
+++ b/services/sync-service/src/inbound/router.rs
@@ -0,0 +1,420 @@
+//! HTTP routing and route-specific access requirements for sessions.
+#[cfg(feature = "openapi")]
+use super::durable_object::document_api::{SnapshotResponse, UpdateRequest, UpdateResponse};
+#[cfg(feature = "openapi")]
+use crate::domain::models::{BlameRow, DocumentMetadata, GetSnapshotRequest, PeerResponse};
+#[cfg(feature = "openapi")]
+use crate::swagger::BinaryBody;
+
+use std::{collections::HashMap, rc::Rc};
+
+use axum::{
+ Router,
+ extract::{Path, Query, Request, State},
+ http::StatusCode,
+ response::{IntoResponse, Response},
+ routing::{delete, get, post},
+};
+use worker::send::SendWrapper;
+
+use super::{
+ auth::{
+ AdminAccess, EditAccess, InternalAccess, SignedDocumentAccess, SocketAccess, SurfaceAccess,
+ ViewAccess,
+ },
+ durable_object::SyncSession,
+};
+use crate::secrets::Secrets;
+
+/// The runtime session is confined to one worker isolate; only Axum's type
+/// bounds require Send/Sync. Secrets are extracted once per request.
+#[derive(Clone)]
+pub struct RouterState {
+ pub session: SendWrapper<Rc<SyncSession>>,
+ pub secrets: Secrets,
+}
+
+pub struct AppError(worker::Error);
+
+impl From<worker::Error> for AppError {
+ fn from(error: worker::Error) -> Self {
+ Self(error)
+ }
+}
+
+impl IntoResponse for AppError {
+ fn into_response(self) -> Response {
+ tracing::error!(error = ?self.0, "sync request failed");
+ StatusCode::INTERNAL_SERVER_ERROR.into_response()
+ }
+}
+
+pub type HandlerResult = Result<Response, AppError>;
+
+pub fn document_router(session: Rc<SyncSession>) -> Router {
+ let secrets = session.secrets();
+ Router::new()
+ .route("/document/{document_id}/connect", get(connect))
+ .route("/document/{document_id}/exists", get(exists))
+ .route("/document/{document_id}/peer/{peer_id}", get(peer))
+ .route("/document/{document_id}/wakeup", get(wakeup).post(wakeup))
+ .route("/document/{document_id}/metadata", get(metadata))
+ .route("/document/{document_id}/blame/{node_id}", get(blame))
+ .route("/document/{document_id}/raw", get(raw))
+ .route(
+ "/document/{document_id}/snapshot",
+ get(snapshot).post(snapshot),
+ )
+ .route("/document/{document_id}/active_peers", get(active_peers))
+ .route("/document/{document_id}/initialize", post(initialize))
+ .route("/document/{document_id}/state", get(document_state))
+ .route("/document/{document_id}/update", post(document_update))
+ .route("/document/{document_id}/delete", delete(delete_document))
+ .route(
+ "/document/{document_id}/debug_dump_operations",
+ get(dump_operations),
+ )
+ .route(
+ "/document/{document_id}/debug_do_kv_get/{key}",
+ get(debug_get),
+ )
+ .route(
+ "/document/{document_id}/debug_do_kv_list/{prefix}",
+ get(debug_list),
+ )
+ .route(
+ "/document/{document_id}/migration/{operation}",
+ post(source_migration),
+ )
+ .route("/surface/{surface_id}/connect", get(surface_connect))
+ .route("/surface/{surface_id}/exists", get(surface_read))
+ .route("/surface/{surface_id}/active_peers", get(surface_read))
+ .route("/surface/{surface_id}/peer/{peer_id}", get(surface_read))
+ .route("/surface/{surface_id}/snapshot", post(surface_read))
+ .route("/surface/{surface_id}/initialize", post(surface_manage))
+ .route("/surface/{surface_id}/revoke", post(surface_manage))
+ .route(
+ "/surface/{surface_id}/initialize_verified",
+ post(surface_manage),
+ )
+ .route("/surface/{surface_id}/import", post(surface_manage))
+ .route("/surface/{surface_id}/verify", post(surface_manage))
+ .route("/surface/{surface_id}/activate", post(surface_manage))
+ .with_state(RouterState {
+ session: SendWrapper::new(session),
+ secrets,
+ })
+}
+
+#[worker::send]
+async fn connect(State(state): State<RouterState>, access: SocketAccess) -> HandlerResult {
+ Ok(state
+ .session
+ .connect(access.claims, &access.document_id)
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/exists", operation_id = "document_exists",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ responses((status = 200, description = "Document exists"), (status = 404, description = "Not found")),
+))]
+#[worker::send]
+pub(crate) async fn exists(
+ State(state): State<RouterState>,
+ Path(id): Path<String>,
+) -> HandlerResult {
+ Ok(state.session.exists_handler(&id).await?.into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/peer/{peer_id}", operation_id = "document_peer",
+ tag = "sync_service",
+ params(("document_id" = String, Path), ("peer_id" = String, Path)),
+ responses((status = 200, body = PeerResponse)),
+))]
+#[worker::send]
+pub(crate) async fn peer(
+ State(state): State<RouterState>,
+ Path((id, peer)): Path<(String, String)>,
+) -> HandlerResult {
+ Ok(state.session.peer_handler(&id, Some(&peer)).await?.into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/wakeup", operation_id = "document_wakeup",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ responses((status = 200, description = "Keepalive scheduled")),
+))]
+#[worker::send]
+pub(crate) async fn wakeup(
+ State(state): State<RouterState>,
+ Path(id): Path<String>,
+) -> HandlerResult {
+ Ok(state.session.wakeup(&id).await?.into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/metadata", operation_id = "document_metadata",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, body = DocumentMetadata), (status = 401), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn metadata(
+ State(state): State<RouterState>,
+ access: ViewAccess,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .metadata_handler(&access.document_id)
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/blame/{node_id}", operation_id = "document_blame",
+ tag = "sync_service",
+ params(("document_id" = String, Path), ("node_id" = String, Path)),
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, body = BlameRow), (status = 401), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn blame(
+ State(state): State<RouterState>,
+ _: ViewAccess,
+ Path((_, node)): Path<(String, String)>,
+) -> HandlerResult {
+ Ok(state.session.blame_handler(Some(&node)).await?.into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/raw", operation_id = "document_raw",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, description = "Raw document JSON"), (status = 401), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn raw(State(state): State<RouterState>, access: ViewAccess) -> HandlerResult {
+ Ok(state.session.raw_handler(&access.document_id).await?.into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ post, path = "/document/{document_id}/snapshot", operation_id = "document_snapshot",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ request_body = GetSnapshotRequest,
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, body = BinaryBody, content_type = "application/octet-stream", description = "Loro snapshot bytes"), (status = 400), (status = 401), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn snapshot(
+ State(state): State<RouterState>,
+ access: ViewAccess,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .snapshot_handler(worker::Request::try_from(req)?, &access.document_id)
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/active_peers", operation_id = "document_active_peers",
+ tag = "sync_service",
+ params(
+ ("document_id" = String, Path),
+ ("include_ai" = Option<String>, Query, description = "Set to `false` or `0` to filter out AI editors"),
+ ),
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, body = Vec<String>, description = "Active peer ids"), (status = 401)),
+))]
+#[worker::send]
+pub(crate) async fn active_peers(
+ State(state): State<RouterState>,
+ _: ViewAccess,
+ Query(params): Query<HashMap<String, String>>,
+) -> HandlerResult {
+ let include_ai = !matches!(
+ params.get("include_ai").map(String::as_str),
+ Some("false" | "0")
+ );
+ Ok(state
+ .session
+ .active_peer_ids_handler(include_ai)
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ post, path = "/document/{document_id}/initialize", operation_id = "document_initialize",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ request_body(content = BinaryBody, content_type = "application/octet-stream"),
+ security(("document_permission" = []), ("internal_key" = [])),
+ responses((status = 200, description = "Initialized"), (status = 401)),
+))]
+#[worker::send]
+pub(crate) async fn initialize(
+ State(state): State<RouterState>,
+ access: EditAccess,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .initialize_handler(worker::Request::try_from(req)?, &access.document_id)
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ get, path = "/document/{document_id}/state", operation_id = "document_state",
+ tag = "sync_service", params(("document_id" = String, Path), ("shallow" = Option<bool>, Query, description = "Return current state without prior edit history")),
+ security(("document_permission" = [])),
+ responses((status = 200, body = SnapshotResponse), (status = 401), (status = 403), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn document_state(
+ State(state): State<RouterState>,
+ access: SignedDocumentAccess,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .document_handler(
+ worker::Request::try_from(req)?,
+ &access.document_id,
+ false,
+ access.access,
+ access.claims,
+ )
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ post, path = "/document/{document_id}/update", operation_id = "document_update",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ request_body = UpdateRequest,
+ security(("document_permission" = [])),
+ responses((status = 200, body = UpdateResponse), (status = 401), (status = 403), (status = 404), (status = 400), (status = 409), (status = 413), (status = 503), (status = 500)),
+))]
+#[worker::send]
+pub(crate) async fn document_update(
+ State(state): State<RouterState>,
+ access: SignedDocumentAccess,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .document_handler(
+ worker::Request::try_from(req)?,
+ &access.document_id,
+ true,
+ access.access,
+ access.claims,
+ )
+ .await?
+ .into())
+}
+
+#[cfg_attr(feature = "openapi", utoipa::path(
+ delete, path = "/document/{document_id}/delete", operation_id = "document_delete",
+ tag = "sync_service", params(("document_id" = String, Path)),
+ security(("internal_key" = [])),
+ responses((status = 200), (status = 401), (status = 403), (status = 404)),
+))]
+#[worker::send]
+pub(crate) async fn delete_document(
+ State(state): State<RouterState>,
+ _: InternalAccess,
+ Path(id): Path<String>,
+) -> HandlerResult {
+ Ok(state.session.delete_handler(&id).await?.into())
+}
+
+#[worker::send]
+async fn dump_operations(State(state): State<RouterState>, access: AdminAccess) -> HandlerResult {
+ Ok(state
+ .session
+ .dump_operations(&access.document_id)
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn debug_get(
+ State(state): State<RouterState>,
+ _: AdminAccess,
+ Path((_, key)): Path<(String, String)>,
+) -> HandlerResult {
+ Ok(state.session.debug_get(&key).await?.into())
+}
+
+#[worker::send]
+async fn debug_list(
+ State(state): State<RouterState>,
+ _: AdminAccess,
+ Path((_, prefix)): Path<(String, String)>,
+) -> HandlerResult {
+ Ok(state.session.debug_list(&prefix).await?.into())
+}
+
+impl axum::extract::FromRef<RouterState> for Secrets {
+ fn from_ref(state: &RouterState) -> Self {
+ state.secrets.clone()
+ }
+}
+
+#[worker::send]
+async fn surface_connect(
+ State(state): State<RouterState>,
+ access: SurfaceAccess<true>,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .surface_handler(worker::Request::try_from(req)?, Some(access.claims))
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn surface_read(
+ State(state): State<RouterState>,
+ access: SurfaceAccess<false>,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .surface_handler(worker::Request::try_from(req)?, Some(access.claims))
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn surface_manage(
+ State(state): State<RouterState>,
+ _: InternalAccess,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .surface_handler(worker::Request::try_from(req)?, None)
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn source_migration(
+ State(state): State<RouterState>,
+ _: InternalAccess,
+ Path((id, operation)): Path<(String, String)>,
+ req: Request,
+) -> HandlerResult {
+ Ok(state
+ .session
+ .source_migration_handler(worker::Request::try_from(req)?, &id, &operation)
+ .await?
+ .into())
+}
diff --git a/services/sync-service/src/cf_worker.rs b/services/sync-service/src/inbound/worker.rs
similarity index 65%
rename from services/sync-service/src/cf_worker.rs
rename to services/sync-service/src/inbound/worker.rs
index d906ca9462..46c5dae77e 100644
--- a/services/sync-service/src/cf_worker.rs
+++ b/services/sync-service/src/inbound/worker.rs
@@ -2,10 +2,9 @@ use bebop::{Record, SubRecord};
use macro_sync_service_jwt::session::{SessionIdentity, SessionKind};
use tracing::{Instrument, error};
use wasm_bindgen::JsValue;
-use worker::{Env, Error, Headers, Method, Request, RequestInit, Response, Result, Stub};
+use worker::{Env, Headers, Method, Request, RequestInit, Response, Result, Stub};
use crate::{
- auth::is_internal,
constants::{
USER_PEER_D1_BINDING,
header_names::{AUTHORIZATION, MACRO_INTERNAL_AUTH_KEY_HEADER_KEY},
@@ -17,53 +16,79 @@ use crate::{
timeit_log,
timeout::{DEFAULT_TIMEOUT_MS, timeout},
};
-use std::sync::LazyLock;
+use axum::response::IntoResponse;
const DURABLE_OBJECT_NAMESPACE: &str = "DOCUMENT_SYNC_SESSION";
-mod markers {
- pub const ROOT: &str = "root";
- pub const HEALTH: &str = "health";
- pub const SCHEMA: &str = "schema";
- pub const COPY: &str = "copy";
- pub const REST: &str = "rest";
- pub const SURFACE: &str = "surface";
+/// Dispatch public endpoints and proxy session requests through Axum.
+pub async fn router(env: Env, req: Request) -> Result<Response> {
+ use axum::{
+ Router,
+ routing::{any, get, post},
+ };
+ use tower_service::Service;
+ let mut router = Router::new()
+ .route("/", get(|| async { "Hello Sync Service!" }))
+ .route("/health", get(|| async { "healthy" }))
+ .route(
+ "/schema",
+ get(|| async { include_str!("../../bebop/schema.bop") }),
+ )
+ .route("/surface/{surface_id}/activate", post(activate_route))
+ .route("/document/{document_id}/copy", any(copy_route))
+ .route("/document/{document_id}/{*rest}", any(document_route))
+ .route("/surface/{surface_id}/{*rest}", any(surface_route))
+ .with_state(env);
+ let response = router.call(worker::HttpRequest::try_from(req)?).await;
+ let response = response.unwrap_or_else(|error: std::convert::Infallible| match error {});
+ Response::try_from(response)
}
-pub async fn router(env: Env, req: Request) -> Result<Response> {
- let url = req.url()?;
- let matched = ROUTER
- .at(url.path())
- .with_context(|| format!("MatchError on url [{url}]"))?;
- match *matched.value {
- markers::ROOT => Response::builder().ok("Hello Sync Service!"),
- markers::HEALTH => Response::builder().ok("healthy"),
- markers::SCHEMA => Response::builder().ok(include_str!("../bebop/schema.bop")),
- markers::SURFACE => {
- let Some(id) = matched.params.get("surface_id") else {
- return Ok(response(status_codes::NOT_FOUND));
- };
- let Ok(identity) = SessionIdentity::new(SessionKind::Surface, id) else {
- return Ok(response(400));
- };
- if matched.params.get("rest") == Some("activate") {
- return activate_surface(&env, req, &identity).await;
- }
- pass_to_session(&env, req, &identity.storage_key()).await
- }
- needs_document_id => {
- let document_id = matched.params.get("document_id").with_context(|| {
- Error::from(format!(
- "Failed to get path parameter [doocument_id] from url: [{}]",
- url.as_ref()
- ))
- })?;
- match needs_document_id {
- markers::COPY => copy_handler(env, req, document_id).await,
- markers::REST => pass_to_durable_object(&env, req, document_id).await,
- _ => Ok(response(status_codes::NOT_FOUND)),
- }
- }
- }
+#[cfg_attr(feature = "openapi", utoipa::path(
+ post,
+ path = "/document/{document_id}/copy",
+ operation_id = "copy_document",
+ tag = "sync_service",
+ params(("document_id" = String, Path, description = "Source document to copy from")),
+ request_body = CopyDocumentRequest,
+ responses(
+ (status = 200, description = "Copy succeeded; the new document was initialized"),
+ (status = 404, description = "Source snapshot not found"),
+ ),
+))]
+#[worker::send]
+pub(crate) async fn copy_route(
+ axum::extract::State(env): axum::extract::State<Env>,
+ axum::extract::Path(id): axum::extract::Path<String>,
+ req: axum::extract::Request,
+) -> super::router::HandlerResult {
+ Ok(copy_handler(env, Request::try_from(req)?, &id)
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn document_route(
+ axum::extract::State(env): axum::extract::State<Env>,
+ axum::extract::Path((id, _)): axum::extract::Path<(String, String)>,
+ req: axum::extract::Request,
+) -> super::router::HandlerResult {
+ Ok(pass_to_durable_object(&env, Request::try_from(req)?, &id)
+ .await?
+ .into())
+}
+
+#[worker::send]
+async fn surface_route(
+ axum::extract::State(env): axum::extract::State<Env>,
+ axum::extract::Path((id, _rest)): axum::extract::Path<(String, String)>,
+ req: axum::extract::Request,
+) -> super::router::HandlerResult {
+ let Ok(identity) = SessionIdentity::new(SessionKind::Surface, &id) else {
+ return Ok(axum::http::StatusCode::BAD_REQUEST.into_response());
+ };
+ let req = Request::try_from(req)?;
+ let response = pass_to_session(&env, req, &identity.storage_key()).await?;
+ Ok(response.into())
}
/// Seal the verified original before enabling the imported target. A failed or
@@ -73,12 +98,6 @@ async fn activate_surface(
mut req: Request,
identity: &SessionIdentity,
) -> Result<Response> {
- if !is_internal(&req, env)? {
- return Ok(response(401));
- }
- if req.method() != Method::Post {
- return Ok(response(405));
- }
let bytes = req.bytes().await?;
let Ok(proof) =
serde_json::from_slice::<crate::durable_object::surface_migration::SnapshotProof>(&bytes)
@@ -193,29 +212,6 @@ pub async fn copy_handler(env: Env, mut req: Request, document_id: &str) -> Resu
Ok(ss_res)
}
-pub static ROUTER: LazyLock<matchit::Router<&str>> = LazyLock::new(|| {
- let mut router = matchit::Router::new();
- router
- .insert("/", markers::ROOT)
- .unwrap_context("Router.insert failed");
- router
- .insert("/health", markers::HEALTH)
- .unwrap_context("Router.insert failed");
- router
- .insert("/schema", markers::SCHEMA)
- .unwrap_context("Router.insert failed");
- router
- .insert("/document/{document_id}/copy", markers::COPY)
- .unwrap_context("Router.insert failed");
- router
- .insert("/document/{document_id}/{*rest}", markers::REST)
- .unwrap_context("Router.insert failed");
- router
- .insert("/surface/{surface_id}/{*rest}", markers::SURFACE)
- .unwrap_context("Router.insert failed");
- router
-});
-
pub async fn pass_to_durable_object(
env: &Env,
req: Request,
@@ -258,3 +254,24 @@ fn get_durable_object(env: &Env, document_id: &str) -> Result<Stub> {
.id_from_name(document_id)?
.get_stub()
}
+
+impl axum::extract::FromRef<Env> for crate::secrets::Secrets {
+ fn from_ref(env: &Env) -> Self {
+ Self::from(env)
+ }
+}
+
+#[worker::send]
+async fn activate_route(
+ axum::extract::State(env): axum::extract::State<Env>,
+ _: super::auth::InternalAccess,
+ axum::extract::Path(id): axum::extract::Path<String>,
+ req: axum::extract::Request,
+) -> super::router::HandlerResult {
+ let Ok(identity) = SessionIdentity::new(SessionKind::Surface, &id) else {
+ return Ok(axum::http::StatusCode::BAD_REQUEST.into_response());
+ };
+ Ok(activate_surface(&env, Request::try_from(req)?, &identity)
+ .await?
+ .into())
+}
diff --git a/services/sync-service/src/lib.rs b/services/sync-service/src/lib.rs
index bd088d98d4..7bd464f830 100644
--- a/services/sync-service/src/lib.rs
+++ b/services/sync-service/src/lib.rs
@@ -1,21 +1,18 @@
mod ai_peer;
-mod auth;
-mod cf_worker;
+use inbound::credentials as auth;
+mod inbound;
+mod outbound;
+use outbound::{d1, dss_internal, lexical_service, secrets, storage};
mod constants;
-mod d1;
mod domain;
-mod dss_internal;
-mod durable_object;
+use inbound::durable_object;
mod error;
mod generated;
pub mod keepalive;
-mod lexical_service;
mod metrics;
mod mutex;
-mod secrets;
mod socket;
mod state;
-mod storage;
mod tags;
mod timeout;
@@ -66,7 +63,7 @@ fn start() {
#[event(fetch)]
async fn fetch(req: worker::Request, env: Env, ctx: Context) -> Result<worker::Response> {
- use crate::cf_worker::router;
+ use crate::inbound::worker::router;
use tracing::Instrument;
let traceparent = worker_rs_otel::traceparent_from_request(&req);
@@ -83,3 +80,6 @@ async fn fetch(req: worker::Request, env: Env, ctx: Context) -> Result<worker::R
worker_rs_otel::scope(&env, &ctx, router(env.clone(), req).instrument(span)).await
}
+
+#[cfg(feature = "openapi")]
+pub mod swagger;
diff --git a/services/sync-service/src/outbound.rs b/services/sync-service/src/outbound.rs
new file mode 100644
index 0000000000..514e77cc7e
--- /dev/null
+++ b/services/sync-service/src/outbound.rs
@@ -0,0 +1,5 @@
+pub mod d1;
+pub mod dss_internal;
+pub mod lexical_service;
+pub mod secrets;
+pub mod storage;
diff --git a/services/sync-service/src/d1.rs b/services/sync-service/src/outbound/d1.rs
similarity index 95%
rename from services/sync-service/src/d1.rs
rename to services/sync-service/src/outbound/d1.rs
index c52cf0ce2a..aeba5fe453 100644
--- a/services/sync-service/src/d1.rs
+++ b/services/sync-service/src/outbound/d1.rs
@@ -104,11 +104,7 @@ pub async fn get_user_id_from_peer_id(
Ok(user_id)
}
-#[derive(serde::Deserialize, serde::Serialize)]
-pub struct PeerWithUserId {
- pub peer_id: String,
- pub user_id: String,
-}
+pub use crate::domain::models::PeerWithUserId;
pub async fn get_peers_for_document_id(
db: D1Database,
@@ -190,12 +186,7 @@ pub async fn delete_document_rows(db: D1Database, document_id: &str) -> worker::
Ok(())
}
-#[derive(serde::Deserialize, serde::Serialize)]
-pub struct BlameRow {
- pub peer_id: String,
- pub user_id: Option<String>,
- pub timestamp_ms: i64,
-}
+pub use crate::domain::models::BlameRow;
/// JOIN blame with peer_user_map to get last-edit info plus resolved user_id.
pub async fn get_blame_for_node(
diff --git a/services/sync-service/src/dss_internal.rs b/services/sync-service/src/outbound/dss_internal.rs
similarity index 100%
rename from services/sync-service/src/dss_internal.rs
rename to services/sync-service/src/outbound/dss_internal.rs
diff --git a/services/sync-service/src/lexical_service.rs b/services/sync-service/src/outbound/lexical_service.rs
similarity index 100%
rename from services/sync-service/src/lexical_service.rs
rename to services/sync-service/src/outbound/lexical_service.rs
diff --git a/services/sync-service/src/secrets.rs b/services/sync-service/src/outbound/secrets.rs
similarity index 100%
rename from services/sync-service/src/secrets.rs
rename to services/sync-service/src/outbound/secrets.rs
diff --git a/services/sync-service/src/storage.rs b/services/sync-service/src/outbound/storage.rs
similarity index 100%
rename from services/sync-service/src/storage.rs
rename to services/sync-service/src/outbound/storage.rs
diff --git a/services/sync-service/src/storage/backends/combined_sql_kv.rs b/services/sync-service/src/outbound/storage/backends/combined_sql_kv.rs
similarity index 100%
rename from services/sync-service/src/storage/backends/combined_sql_kv.rs
rename to services/sync-service/src/outbound/storage/backends/combined_sql_kv.rs
diff --git a/services/sync-service/src/storage/backends/durable_kv.rs b/services/sync-service/src/outbound/storage/backends/durable_kv.rs
similarity index 98%
rename from services/sync-service/src/storage/backends/durable_kv.rs
rename to services/sync-service/src/outbound/storage/backends/durable_kv.rs
index 469244fbe3..c87c18e954 100644
--- a/services/sync-service/src/storage/backends/durable_kv.rs
+++ b/services/sync-service/src/outbound/storage/backends/durable_kv.rs
@@ -57,11 +57,11 @@ impl DurableKVStorage {
}
}
- pub(in crate::storage) async fn get_key(&self, key: &str) -> Result<Option<Vec<u8>>> {
+ pub(in crate::outbound::storage) async fn get_key(&self, key: &str) -> Result<Option<Vec<u8>>> {
do_kv_result_to_result_opt(self.inner.get(key).await)
}
- pub(in crate::storage) async fn list_do_kv(
+ pub(in crate::outbound::storage) async fn list_do_kv(
&self,
prefix: &str,
) -> Result<Vec<Result<(String, Vec<u8>)>>> {
diff --git a/services/sync-service/src/storage/backends/durable_sql.rs b/services/sync-service/src/outbound/storage/backends/durable_sql.rs
similarity index 100%
rename from services/sync-service/src/storage/backends/durable_sql.rs
rename to services/sync-service/src/outbound/storage/backends/durable_sql.rs
diff --git a/services/sync-service/src/storage/backends/kv.rs b/services/sync-service/src/outbound/storage/backends/kv.rs
similarity index 100%
rename from services/sync-service/src/storage/backends/kv.rs
rename to services/sync-service/src/outbound/storage/backends/kv.rs
diff --git a/services/sync-service/src/storage/backends/mod.rs b/services/sync-service/src/outbound/storage/backends/mod.rs
similarity index 100%
rename from services/sync-service/src/storage/backends/mod.rs
rename to services/sync-service/src/outbound/storage/backends/mod.rs
diff --git a/services/sync-service/src/storage/backends/r2.rs b/services/sync-service/src/outbound/storage/backends/r2.rs
similarity index 100%
rename from services/sync-service/src/storage/backends/r2.rs
rename to services/sync-service/src/outbound/storage/backends/r2.rs
diff --git a/services/sync-service/src/storage/op_log.rs b/services/sync-service/src/outbound/storage/op_log.rs
similarity index 100%
rename from services/sync-service/src/storage/op_log.rs
rename to services/sync-service/src/outbound/storage/op_log.rs
diff --git a/services/sync-service/src/storage/snapshot.rs b/services/sync-service/src/outbound/storage/snapshot.rs
similarity index 100%
rename from services/sync-service/src/storage/snapshot.rs
rename to services/sync-service/src/outbound/storage/snapshot.rs
diff --git a/services/sync-service/src/socket/protocol.rs b/services/sync-service/src/socket/protocol.rs
index b4a55fe2a4..e9509cd899 100644
--- a/services/sync-service/src/socket/protocol.rs
+++ b/services/sync-service/src/socket/protocol.rs
@@ -6,7 +6,7 @@ use worker::Result;
use crate::{
auth::WriteAccess,
domain::document::writing_peers,
- durable_object::{DocumentSyncSession, Wsm},
+ durable_object::{SyncSession, Wsm},
error::ResultExt,
generated::schema::{FromPeer, FromRemote},
lexical_service::LexicalServiceClient,
@@ -137,11 +137,7 @@ pub fn send_initial_sync(socket: &Socket, snapshot: &[u8], awareness: &[u8]) ->
}
/// Broadcasts an awareness update to every connected peer except `from`.
-pub fn broadcast_awareness(
- dss: &DocumentSyncSession,
- from: &Socket,
- awareness: &[u8],
-) -> Result<()> {
+pub fn broadcast_awareness(dss: &SyncSession, from: &Socket, awareness: &[u8]) -> Result<()> {
for socket in dss.get_sockets() {
if socket == *from {
continue;
@@ -170,7 +166,7 @@ pub async fn process_message(
session_storage: &SessionStorage,
awareness: &EphemeralStore,
message: FromPeer<'_>,
- dss: &DocumentSyncSession,
+ dss: &SyncSession,
telemetry: &mut InboundMessageTelemetry,
) -> Result<()> {
// Loading the document after hibernation can yield to a revocation. Check
@@ -352,7 +348,7 @@ pub async fn process_message(
/// A commenter's updates are accepted only when they change nothing but
/// comment marks. Anything that cannot be checked is refused.
async fn changes_only_comment_marks(
- dss: &DocumentSyncSession,
+ dss: &SyncSession,
document_state: &DocumentState,
updates: &[SliceWrapper<'_, u8>],
) -> bool {
diff --git a/services/sync-service/src/swagger.rs b/services/sync-service/src/swagger.rs
new file mode 100644
index 0000000000..ccd4829bc4
--- /dev/null
+++ b/services/sync-service/src/swagger.rs
@@ -0,0 +1,84 @@
+use utoipa::OpenApi;
+
+use crate::domain::models::{
+ BlameRow, CopyDocumentRequest, DocumentMetadata, GetSnapshotRequest, PeerResponse,
+ PeerWithUserId, VersionIndicator,
+};
+
+/// OpenAPI spec for the sync service's JSON HTTP endpoints.
+///
+/// The WebSocket sync protocol is bebop-encoded and lives in the bebop schema
+/// (`/schema`); only the JSON control-plane endpoints are described here.
+#[derive(OpenApi)]
+#[openapi(
+ info(
+ title = "Sync Service",
+ description = "Document sync service JSON control plane",
+ contact(name = "Macro"),
+ ),
+ modifiers(&Security),
+ paths(
+ crate::inbound::worker::copy_route,
+ crate::inbound::router::exists,
+ crate::inbound::router::metadata,
+ crate::inbound::router::blame,
+ crate::inbound::router::raw,
+ crate::inbound::router::active_peers,
+ crate::inbound::router::peer,
+ crate::inbound::router::wakeup,
+ crate::inbound::router::snapshot,
+ crate::inbound::router::initialize,
+ crate::inbound::router::document_state,
+ crate::inbound::router::document_update,
+ crate::inbound::router::delete_document,
+ ),
+ components(schemas(
+ CopyDocumentRequest,
+ GetSnapshotRequest,
+ VersionIndicator,
+ DocumentMetadata,
+ PeerResponse,
+ PeerWithUserId,
+ BlameRow,
+ )),
+ tags((name = "sync_service", description = "Sync service"))
+)]
+pub struct ApiDoc;
+
+struct Security;
+
+impl utoipa::Modify for Security {
+ fn modify(&self, api: &mut utoipa::openapi::OpenApi) {
+ use utoipa::openapi::security::{
+ ApiKey, ApiKeyValue, Http, HttpAuthScheme, SecurityScheme,
+ };
+ // An unspecified Cargo license is not a valid OpenAPI 3.1 license.
+ api.info.license = None;
+ let components = api.components.get_or_insert_with(Default::default);
+ components.add_security_scheme(
+ "document_permission",
+ SecurityScheme::Http(Http::new(HttpAuthScheme::Bearer)),
+ );
+ components.add_security_scheme(
+ "internal_key",
+ SecurityScheme::ApiKey(ApiKey::Header(ApiKeyValue::new(
+ crate::constants::header_names::MACRO_INTERNAL_AUTH_KEY_HEADER_KEY,
+ ))),
+ );
+ }
+}
+
+/// Raw octet-stream payload used by the binary HTTP endpoints.
+pub(crate) struct BinaryBody;
+
+impl utoipa::PartialSchema for BinaryBody {
+ fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
+ use utoipa::openapi::schema::{KnownFormat, ObjectBuilder, SchemaFormat, Type};
+ ObjectBuilder::new()
+ .schema_type(Type::String)
+ .format(Some(SchemaFormat::KnownFormat(KnownFormat::Binary)))
+ .into()
+ }
+}
+
+impl utoipa::ToSchema for BinaryBody {}
diff --git a/services/sync-service/src/timeout.rs b/services/sync-service/src/timeout.rs
index ac53ec5834..6dcd4c52ad 100644
--- a/services/sync-service/src/timeout.rs
+++ b/services/sync-service/src/timeout.rs
@@ -130,18 +130,8 @@ impl<T> TimeoutResult<T> {
/// # Returns
/// A `TimeoutResult` indicating whether the operation completed or timed out
///
-/// # Examples
-/// ```rust
-/// use crate::timeout::{timeout, TimeoutResult};
-///
-/// async fn example() {
-/// let result = timeout(some_async_operation(), 5000).await;
-/// match result {
-/// TimeoutResult::Ok(value) => println!("Got result: {:?}", value),
-/// TimeoutResult::Timeout(err) => println!("Operation timed out: {}", err),
-/// }
-/// }
-/// ```
+/// Await the returned future and handle `TimeoutResult::Ok` or
+/// `TimeoutResult::Timeout`.
pub fn timeout<F>(future: F, duration_ms: u32) -> Timeout<F>
where
F: Future,
diff --git a/services/sync-service/tests/snapshot_endpoint.test.ts b/services/sync-service/tests/snapshot_endpoint.test.ts
index 41b1b855e0..032a0ce124 100644
--- a/services/sync-service/tests/snapshot_endpoint.test.ts
+++ b/services/sync-service/tests/snapshot_endpoint.test.ts
@@ -123,4 +123,33 @@ describe("snapshot endpoint tests", async () => {
expect(response.status).toBe(404);
});
+ test("rejects malformed snapshot versions without aborting the session", async () => {
+ const user = await createTestUser(mf, "test-doc");
+ const token = getTokenForDocument("test-doc", "test-user", "owner");
+ try {
+ for (const version of [
+ { peer: "invalid", counter: 0 },
+ { peer: "18446744073709551616", counter: 0 },
+ { peer: "1", counter: -1 },
+ ]) {
+ const response = await mf.dispatchFetch(
+ "http://localhost/document/test-doc/snapshot",
+ {
+ method: "POST",
+ headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+ body: JSON.stringify({ version_id: version }),
+ }
+ );
+ expect(response.status).toBe(400);
+ }
+ const healthy = await mf.dispatchFetch("http://localhost/document/test-doc/snapshot", {
+ headers: { Authorization: `Bearer ${token}` },
+ });
+ expect(healthy.status).toBe(200);
+ expect((await healthy.arrayBuffer()).byteLength).toBeGreaterThan(0);
+ } finally {
+ user.connection.getWebSocket().close();
+ }
+ });
+
});