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.

fix(sync): gate gateway transport with PostHog

Wolf Mermelsteindf698cf8405f
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index eb05f8180a..0b32b40b49 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -114,6 +114,15 @@ Then trigger the interaction and read `window.__inst.log`. `'1,2,3' → '' → '
## Canvas collaboration
+Document sync uses the `sync-via-gateway` PostHog flag in both deployed dev and
+production. Off or unknown flag values use direct sync sockets.
+Local stacks with `sync_router` can opt in with `VITE_SYNC_VIA_GATEWAY=true`;
+`false` forces direct sync. The choice is made when a sync source is created
+and stays fixed for its lifetime. PostHog can serve a cached value on reload;
+recreate document sessions after the client receives the updated flag to change
+transport. This is not an immediate kill switch for open sessions. Provision
+the hosted router before enabling.
+
Saved canvases use the shared Loro runtime; the stored JSON is only the original
migration seed. Keep whole-file simple-save out of scene editing. Canvas
initialization, WAL/snapshot recovery and teardown live in
diff --git a/apps/web/src/lib/core/constant/featureFlags.ts b/apps/web/src/lib/core/constant/featureFlags.ts
index c4e2b63384..839f5e570e 100644
--- a/apps/web/src/lib/core/constant/featureFlags.ts
+++ b/apps/web/src/lib/core/constant/featureFlags.ts
@@ -206,11 +206,12 @@ export const ENABLE_SCRIPTING = defineFlag({
default: false,
}).enabled;
-// Multiplex document sync over the connection gateway.
-export const SYNC_VIA_GATEWAY = defineFlag({
+// Deployed dev and production defer to PostHog: the router must be provisioned
+// before enabling gateway sync. Local stacks can use the env override.
+export const syncViaGateway = defineFlag({
+ key: 'sync-via-gateway',
env: 'SYNC_VIA_GATEWAY',
- default: true,
-}).enabled;
+});
export const ENABLE_PDF_MULTISPLIT = defineFlag({
env: 'ENABLE_PDF_MULTISPLIT',
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
index 31fef56618..02e78027f1 100644
--- a/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.test.ts
@@ -19,7 +19,10 @@ vi.mock('@block-md/observability', () => ({
vi.mock('@core/constant/servers', () => ({
SYNC_SERVICE_HOSTS: { ws: 'wss://sync.test' },
}));
-vi.mock('@core/constant/featureFlags', () => ({ SYNC_VIA_GATEWAY: false }));
+vi.mock('@core/constant/featureFlags', () => ({
+ syncViaGateway: { key: 'sync-via-gateway', override: undefined },
+ isFeatureEnabled: () => false,
+}));
vi.mock('@service-connection/websocket-url', () => ({
resolveWsUrl: () => 'ws://gateway.test',
}));
diff --git a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
index 52deb84635..88b4e020af 100644
--- a/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
+++ b/apps/web/src/lib/service-clients/service-sync/source/helpers.ts
@@ -1,5 +1,5 @@
import { resumeDocumentSpan } from '@block-md/observability';
-import { SYNC_VIA_GATEWAY } from '@core/constant/featureFlags';
+import { isFeatureEnabled, syncViaGateway } from '@core/constant/featureFlags';
import { SYNC_SERVICE_HOSTS } from '@core/constant/servers';
import type {
InitialSync,
@@ -130,7 +130,9 @@ export const createSyncServiceSource = (
source: LiveSyncSource;
doInitialSync: () => ResultAsync<InitialSync, SyncError>;
} => {
- const ws: SyncSocket = SYNC_VIA_GATEWAY
+ // Pick a transport for this source's lifetime. Later flag changes apply to
+ // newly created sources without interrupting an editor's active sync session.
+ const ws: SyncSocket = isFeatureEnabled(syncViaGateway)
? syncGatewayTransport().attach(
documentId,
authorization ? undefined : token,
diff --git a/docs/agent-guide/documents.md b/docs/agent-guide/documents.md
index b6d2d20dc7..6dd0d13030 100644
--- a/docs/agent-guide/documents.md
+++ b/docs/agent-guide/documents.md
@@ -1,5 +1,13 @@
# Documents
+For gateway sync rollout checks, use PostHog flag `sync-via-gateway` (dev and
+production) and recreate document sessions after the client receives the updated
+flag. A reload can initially read PostHog's cached value; open sessions do not
+change transport when the remote value changes. Off or unavailable uses a
+direct sync-service WebSocket per document; on multiplexes document frames over
+the connection gateway. Confirm the hosted `sync_router` is provisioned before
+enabling. Local stacks can override with `VITE_SYNC_VIA_GATEWAY=true` or `false`.
+
The document header has separate Share, Copy Share Link, and Side Panel buttons.
They are borderless with a soft rounded background on hover. Share opens the
sharing dialog; copying a link is a separate action.
diff --git a/services/sync-router/AGENTS.md b/services/sync-router/AGENTS.md
index 03d6bb2ce8..dbff05cd6f 100644
--- a/services/sync-router/AGENTS.md
+++ b/services/sync-router/AGENTS.md
@@ -36,7 +36,9 @@ Cloudflare Durable Object sync sockets. It owns routing, not document state.
- Every router subscribes to the same inbound channel; multiple instances do
not partition work. Add ownership coordination before horizontal scaling.
- Local Docker and service inventory wiring are not a hosted deployment.
- Provision the router before enabling `VITE_SYNC_VIA_GATEWAY` for clients.
+ Provision the router before enabling the `sync-via-gateway` PostHog flag.
+ Deployed dev and production defer to PostHog; local stacks can opt in with
+ `VITE_SYNC_VIA_GATEWAY=true`.
## Related