amalgm 0.1.155 → 0.1.156

package/lib/shared-realtime-tunnel.js

@@ -0,0 +1,518 @@
+'use strict';
+
+/**
+ * Cloud-shared resource synchronization over the existing event tunnel.
+ *
+ * This module owns only the shared-resource lifecycle: durable local claims,
+ * cloud acknowledgements, recipient materialization, and reconnect hydration.
+ * The parent tunnel owns WebSocket transport, routing, and backpressure.
+ */
+
+const crypto = require('crypto');
+const http = require('http');
+
+const CAPABILITY = 'shared.mutation.v1';
+const CLAIM_LIMIT = 16;
+const CLAIM_LEASE_MS = 30_000;
+const RETRY_MS = 1_000;
+
+function createSharedRealtimeTunnel({
+  send,
+  sendLarge,
+  localPort,
+  localHeaders,
+  warn,
+}) {
+  const mutationInflight = new Map();
+  const promotionInflight = new Map();
+  const attachmentInflight = new Map();
+  const inboundChains = new Map();
+
+  let enabled = false;
+  let mutationDrain = null;
+  let promotionDrain = null;
+  let attachmentDrain = null;
+  let wakeRequest = null;
+  let wakeRetryTimer = null;
+  let mutationRetryTimer = null;
+  let promotionRetryTimer = null;
+  let attachmentRetryTimer = null;
+  let localFailures = 0;
+
+  function localStateJson(method, requestPath, body) {
+    const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
+    return new Promise((resolve, reject) => {
+      const headers = localHeaders({ accept: 'application/json' });
+      if (payload) {
+        headers['content-type'] = 'application/json';
+        headers['content-length'] = String(payload.length);
+      }
+      const req = http.request({
+        hostname: '127.0.0.1',
+        port: localPort(),
+        method,
+        path: requestPath,
+        headers,
+      }, (res) => {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          let parsed = null;
+          try {
+            parsed = text ? JSON.parse(text) : null;
+          } catch {
+            reject(new Error(`local state returned invalid JSON (${res.statusCode || 502})`));
+            return;
+          }
+          if ((res.statusCode || 500) >= 400) {
+            const error = new Error(parsed?.error || `local state failed with ${res.statusCode || 500}`);
+            error.statusCode = res.statusCode || 500;
+            error.details = parsed;
+            reject(error);
+            return;
+          }
+          resolve(parsed);
+        });
+      });
+      req.on('error', reject);
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+
+  function scheduleMutationDrain(delay = 0) {
+    if (!enabled || mutationRetryTimer) return;
+    mutationRetryTimer = setTimeout(() => {
+      mutationRetryTimer = null;
+      void drainMutations();
+    }, delay);
+    mutationRetryTimer.unref?.();
+  }
+
+  function schedulePromotionDrain(delay = 0) {
+    if (!enabled || promotionRetryTimer) return;
+    promotionRetryTimer = setTimeout(() => {
+      promotionRetryTimer = null;
+      void drainPromotions();
+    }, delay);
+    promotionRetryTimer.unref?.();
+  }
+
+  function scheduleAttachmentDrain(delay = 0) {
+    if (!enabled || attachmentRetryTimer) return;
+    attachmentRetryTimer = setTimeout(() => {
+      attachmentRetryTimer = null;
+      void drainAttachments();
+    }, delay);
+    attachmentRetryTimer.unref?.();
+  }
+
+  async function drainMutations() {
+    if (!enabled || mutationDrain) return;
+    mutationDrain = (async () => {
+      const result = await localStateJson('POST', '/state/mutations/claim', {
+        limit: CLAIM_LIMIT,
+        leaseMs: CLAIM_LEASE_MS,
+      });
+      for (const claim of Array.isArray(result?.mutations) ? result.mutations : []) {
+        const envelope = claim?.envelope;
+        if (!envelope?.resourceId || !envelope?.mutationId) continue;
+        const requestId = `shared_${crypto.randomBytes(12).toString('hex')}`;
+        if (!sendLarge({ type: 'shared.mutation.submit', request_id: requestId, envelope })) {
+          await failMutationClaim(claim, 'shared tunnel backpressure: mutation was not queued');
+          scheduleMutationDrain(RETRY_MS);
+          continue;
+        }
+        mutationInflight.set(requestId, {
+          resourceId: envelope.resourceId,
+          mutationId: envelope.mutationId,
+        });
+      }
+      localFailures = 0;
+    })().catch((error) => {
+      localFailures += 1;
+      if (localFailures === 1 || localFailures % 20 === 0) {
+        warn(`shared outbox unavailable (attempt ${localFailures}): ${error?.message || error}`);
+      }
+      scheduleMutationDrain(RETRY_MS);
+    }).finally(() => {
+      mutationDrain = null;
+    });
+    await mutationDrain;
+  }
+
+  async function failMutationClaim(claim, message) {
+    try {
+      await localStateJson('POST', '/state/mutations/fail', {
+        resourceId: claim.envelope.resourceId,
+        mutationId: claim.envelope.mutationId,
+        message,
+        retryable: true,
+      });
+    } catch {
+      // The durable lease makes the row claimable again after expiry.
+    }
+  }
+
+  async function drainPromotions() {
+    if (!enabled || promotionDrain) return;
+    promotionDrain = (async () => {
+      const result = await localStateJson('POST', '/state/shared/promotions/claim', {
+        limit: 2,
+        leaseMs: CLAIM_LEASE_MS,
+      });
+      for (const claim of Array.isArray(result?.promotions) ? result.promotions : []) {
+        const promotion = claim?.frame;
+        if (!promotion?.promotionId || !promotion?.resourceId) continue;
+        const requestId = `promote_${crypto.randomBytes(12).toString('hex')}`;
+        const queued = sendLarge({
+          type: 'shared.resource.promote',
+          request_id: requestId,
+          promotion_id: promotion.promotionId,
+          resource_id: promotion.resourceId,
+          contract: promotion.contract,
+          schema_version: promotion.schemaVersion,
+          snapshot_b64: promotion.snapshotBase64,
+          snapshot_checksum: promotion.snapshotChecksum,
+          snapshot_bytes: promotion.snapshotBytes,
+          content_bytes: promotion.contentBytes,
+          name: promotion.name,
+          media_type: promotion.mediaType,
+        });
+        if (!queued) {
+          await localStateJson('POST', '/state/shared/promotions/fail', {
+            promotionId: promotion.promotionId,
+            message: 'shared tunnel backpressure: promotion was not queued',
+            retryable: true,
+          }).catch(() => {});
+          schedulePromotionDrain(RETRY_MS);
+          continue;
+        }
+        promotionInflight.set(requestId, {
+          promotionId: promotion.promotionId,
+          resourceId: promotion.resourceId,
+        });
+      }
+    })().catch(() => {
+      schedulePromotionDrain(RETRY_MS);
+    }).finally(() => {
+      promotionDrain = null;
+    });
+    await promotionDrain;
+  }
+
+  async function drainAttachments() {
+    if (!enabled || attachmentDrain) return;
+    attachmentDrain = (async () => {
+      const result = await localStateJson('POST', '/state/shared/attachments/claim', {
+        limit: 2,
+        leaseMs: CLAIM_LEASE_MS,
+      });
+      for (const attachment of Array.isArray(result?.attachments) ? result.attachments : []) {
+        if (!attachment?.attachmentId || !attachment?.resourceId) continue;
+        const requestId = `attach_${crypto.randomBytes(12).toString('hex')}`;
+        if (!send({
+          type: 'shared.resource.attach',
+          request_id: requestId,
+          attachment_id: attachment.attachmentId,
+          resource_id: attachment.resourceId,
+        })) {
+          scheduleAttachmentDrain(RETRY_MS);
+          continue;
+        }
+        attachmentInflight.set(requestId, {
+          attachmentId: attachment.attachmentId,
+          resourceId: attachment.resourceId,
+        });
+      }
+    })().catch(() => {
+      scheduleAttachmentDrain(RETRY_MS);
+    }).finally(() => {
+      attachmentDrain = null;
+    });
+    await attachmentDrain;
+  }
+
+  async function joinReplicas() {
+    try {
+      const result = await localStateJson('GET', '/state/shared/replicas');
+      for (const replica of Array.isArray(result?.replicas) ? result.replicas : []) {
+        if (!replica?.resourceId) continue;
+        send({
+          type: 'shared.resource.join',
+          request_id: `join_${crypto.randomBytes(12).toString('hex')}`,
+          resource_id: replica.resourceId,
+          after_version: replica.appliedVersion || 0,
+        });
+      }
+    } catch {
+      // The local service can still be starting; wake reconnect retries.
+    }
+  }
+
+  function parseWakeChunk(state, chunk) {
+    state.buffer += chunk.toString('utf8').replace(/\r\n/g, '\n');
+    let boundary = state.buffer.indexOf('\n\n');
+    while (boundary >= 0) {
+      const block = state.buffer.slice(0, boundary);
+      state.buffer = state.buffer.slice(boundary + 2);
+      let eventType = 'message';
+      const data = [];
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) eventType = line.slice(6).trim();
+        if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+      }
+      if (eventType === 'state' && data.length > 0) {
+        try {
+          const event = JSON.parse(data.join('\n'));
+          if (event?.sharedResourceId) {
+            scheduleAttachmentDrain();
+            schedulePromotionDrain();
+            scheduleMutationDrain();
+          }
+        } catch {
+          // The stream is only a wake signal; durable queues remain truth.
+        }
+      }
+      boundary = state.buffer.indexOf('\n\n');
+    }
+  }
+
+  function startWakeStream() {
+    if (!enabled || wakeRequest) return;
+    const state = { buffer: '' };
+    const req = http.request({
+      hostname: '127.0.0.1',
+      port: localPort(),
+      method: 'GET',
+      path: '/state/stream?bootstrap=1&resources=',
+      headers: localHeaders({ accept: 'text/event-stream' }),
+    }, (res) => {
+      if ((res.statusCode || 500) >= 400) {
+        res.resume();
+        req.destroy(new Error(`shared wake stream failed with ${res.statusCode}`));
+        return;
+      }
+      res.on('data', (chunk) => parseWakeChunk(state, Buffer.from(chunk)));
+      res.on('end', finishWakeStream);
+      res.on('error', finishWakeStream);
+    });
+    wakeRequest = req;
+    req.on('error', finishWakeStream);
+    req.end();
+
+    function finishWakeStream() {
+      if (wakeRequest === req) wakeRequest = null;
+      scheduleWakeReconnect();
+    }
+  }
+
+  function scheduleWakeReconnect() {
+    if (!enabled || wakeRetryTimer) return;
+    wakeRetryTimer = setTimeout(() => {
+      wakeRetryTimer = null;
+      startPump();
+    }, RETRY_MS);
+    wakeRetryTimer.unref?.();
+  }
+
+  function startPump() {
+    if (!enabled) return;
+    startWakeStream();
+    void joinReplicas();
+    scheduleAttachmentDrain();
+    schedulePromotionDrain();
+    scheduleMutationDrain();
+  }
+
+  function handleAttached(frame) {
+    const identity = attachmentInflight.get(frame.request_id);
+    if (!identity) return;
+    void localStateJson('POST', '/state/shared/attachments/ack', {
+      attachmentId: identity.attachmentId,
+      resourceId: frame.resource_id,
+      authorityEpoch: frame.authority_epoch,
+      headVersion: frame.head_version,
+      snapshotVersion: frame.snapshot_version,
+      snapshotChecksum: frame.snapshot_checksum,
+      snapshotBase64: frame.snapshot_b64,
+      contract: frame.contract,
+      schemaVersion: frame.schema_version,
+    }).then(() => {
+      attachmentInflight.delete(frame.request_id);
+      void joinReplicas();
+    }).catch((error) => {
+      void localStateJson('POST', '/state/shared/attachments/fail', {
+        attachmentId: identity.attachmentId,
+        message: error?.message || 'local snapshot materialization failed',
+        retryable: false,
+      }).catch(() => {});
+      attachmentInflight.delete(frame.request_id);
+    });
+  }
+
+  function handlePromoted(frame) {
+    const identity = promotionInflight.get(frame.request_id);
+    if (!identity) return;
+    void localStateJson('POST', '/state/shared/promotions/ack', {
+      promotionId: identity.promotionId,
+      resourceId: frame.resource_id,
+      authorityEpoch: frame.authority_epoch,
+      headVersion: frame.head_version,
+      snapshotVersion: frame.snapshot_version,
+      snapshotKey: frame.snapshot_key,
+      snapshotChecksum: frame.snapshot_checksum,
+    }).then(() => {
+      promotionInflight.delete(frame.request_id);
+      void joinReplicas();
+      scheduleMutationDrain();
+    }).catch(() => {
+      setTimeout(() => enabled && handlePromoted(frame), RETRY_MS).unref?.();
+    });
+  }
+
+  function handleAck(frame) {
+    const identity = mutationInflight.get(frame.request_id) || {
+      resourceId: frame.resource_id,
+      mutationId: frame.mutation_id,
+    };
+    if (!identity.resourceId || !identity.mutationId) return;
+    void localStateJson('POST', '/state/mutations/ack', {
+      resourceId: identity.resourceId,
+      mutationId: identity.mutationId,
+      version: frame.version,
+      committedAt: frame.committed_at,
+    }).then(() => {
+      mutationInflight.delete(frame.request_id);
+      scheduleMutationDrain();
+    }).catch(() => {
+      // The cloud commit is official. Preserve this exact acknowledgement.
+      setTimeout(() => enabled && handleAck(frame), RETRY_MS).unref?.();
+    });
+  }
+
+  function handleError(frame) {
+    const attachment = attachmentInflight.get(frame.request_id);
+    if (attachment) {
+      void localStateJson('POST', '/state/shared/attachments/fail', {
+        attachmentId: attachment.attachmentId,
+        message: `${frame.code || 'shared_error'}: ${frame.message || 'attachment failed'}`,
+        retryable: frame.retryable !== false,
+      }).finally(() => {
+        attachmentInflight.delete(frame.request_id);
+        if (frame.retryable !== false) scheduleAttachmentDrain(RETRY_MS);
+      });
+      return;
+    }
+
+    const promotion = promotionInflight.get(frame.request_id);
+    if (promotion) {
+      void localStateJson('POST', '/state/shared/promotions/fail', {
+        promotionId: promotion.promotionId,
+        message: `${frame.code || 'shared_error'}: ${frame.message || 'promotion failed'}`,
+        retryable: frame.retryable !== false,
+      }).finally(() => {
+        promotionInflight.delete(frame.request_id);
+        if (frame.retryable !== false) schedulePromotionDrain(RETRY_MS);
+      });
+      return;
+    }
+
+    const identity = mutationInflight.get(frame.request_id) || {
+      resourceId: frame.resource_id,
+      mutationId: frame.mutation_id,
+    };
+    if (!identity.resourceId || !identity.mutationId) return;
+    void localStateJson('POST', '/state/mutations/fail', {
+      resourceId: identity.resourceId,
+      mutationId: identity.mutationId,
+      message: `${frame.code || 'shared_error'}: ${frame.message || 'shared mutation failed'}`,
+      retryable: frame.retryable !== false,
+    }).finally(() => {
+      mutationInflight.delete(frame.request_id);
+      if (frame.retryable !== false) scheduleMutationDrain(RETRY_MS);
+    });
+  }
+
+  function handleCommitted(frame) {
+    const resourceId = frame.resource_id || frame.envelope?.resourceId;
+    if (!resourceId) return;
+    const prior = inboundChains.get(resourceId) || Promise.resolve();
+    const next = prior.then(() => localStateJson('POST', '/state/mutations/ingest', {
+      envelope: frame.envelope,
+      version: frame.version,
+      committedAt: frame.committed_at,
+      actorUserId: frame.actor_user_id,
+    })).catch((error) => {
+      warn(`shared mutation ${frame.mutation_id || 'unknown'} was not materialized: ${error?.message || error}`);
+      setTimeout(() => enabled && void joinReplicas(), RETRY_MS).unref?.();
+    }).finally(() => {
+      if (inboundChains.get(resourceId) === next) inboundChains.delete(resourceId);
+    });
+    inboundChains.set(resourceId, next);
+  }
+
+  function handleFrame(frame) {
+    if (!enabled) return false;
+    switch (frame.type) {
+      case 'shared.mutation.ack':
+        handleAck(frame);
+        return true;
+      case 'shared.resource.promoted':
+        handlePromoted(frame);
+        return true;
+      case 'shared.resource.attached':
+        handleAttached(frame);
+        return true;
+      case 'shared.mutation.committed':
+        handleCommitted(frame);
+        return true;
+      case 'shared.error':
+        handleError(frame);
+        return true;
+      case 'shared.resource.joined':
+        void localStateJson('POST', '/state/shared/replicas/authority', {
+          resourceId: frame.resource_id,
+          authorityEpoch: frame.authority_epoch,
+          headVersion: frame.head_version,
+          contract: frame.contract,
+          schemaVersion: frame.schema_version,
+        }).catch(() => {});
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  function enable(capabilities) {
+    if (!Array.isArray(capabilities) || !capabilities.includes(CAPABILITY)) {
+      stop();
+      return;
+    }
+    enabled = true;
+    startPump();
+  }
+
+  function stop() {
+    enabled = false;
+    mutationInflight.clear();
+    promotionInflight.clear();
+    attachmentInflight.clear();
+    inboundChains.clear();
+    if (wakeRequest) wakeRequest.destroy();
+    wakeRequest = null;
+    clearTimeout(wakeRetryTimer);
+    clearTimeout(mutationRetryTimer);
+    clearTimeout(promotionRetryTimer);
+    clearTimeout(attachmentRetryTimer);
+    wakeRetryTimer = null;
+    mutationRetryTimer = null;
+    promotionRetryTimer = null;
+    attachmentRetryTimer = null;
+  }
+
+  return { enable, handleFrame, stop };
+}
+
+module.exports = { CAPABILITY, createSharedRealtimeTunnel };

package/lib/tunnel-events.js

@@ -14,6 +14,7 @@ const {
   RUNTIME_STATE_FILE,
 } = require('./paths');
 const { runtimePort, runtimeServiceByName } = require('./runtime-manifest');
+const { createSharedRealtimeTunnel } = require('./shared-realtime-tunnel');
 
 const DEFAULT_GATEWAY_PORT = runtimeServiceByName('local-gateway').defaultPort;
 const DEFAULT_PORT_MONITOR_PORT = runtimeServiceByName('port-monitor').defaultPort;
@@ -407,6 +408,28 @@ function createEventTunnel({ record, foreground = false }) {
     return sendPayload(JSON.stringify(frame));
   }
 
+  // Durable mutations larger than the control threshold use the same bounded
+  // bulk queue as responses. Their identities remain independent even when
+  // several frames share the queue.
+  function sendShared(frame) {
+    const payload = JSON.stringify(frame);
+    if (payload.length <= BULK_FRAME_BYTES) return sendPayload(payload);
+    if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+    if (bulkQueuedBytes + payload.length > bulkQueueMaxBytes) return false;
+    bulkQueue.push(payloadItem(payload));
+    bulkQueuedBytes += payload.length;
+    drainBulk();
+    return true;
+  }
+
+  const sharedRealtime = createSharedRealtimeTunnel({
+    send,
+    sendLarge: sendShared,
+    localPort: defaultTargetPort,
+    localHeaders,
+    warn,
+  });
+
   // A bulk queue entry: `bytes` is the exact frame size (known up front, so
   // the queue budget applies BEFORE anything is materialized) and `build`
   // produces the JSON payload only when the frame is about to hit the wire.
@@ -793,8 +816,10 @@ function createEventTunnel({ record, foreground = false }) {
     if (!frame || typeof frame.type !== 'string') return;
     if (frame.type === 'hello_ack') {
       peerProtocolVersion = Number(frame.protocol_version) || 1;
+      sharedRealtime.enable(frame.capabilities);
       return;
     }
+    if (sharedRealtime.handleFrame(frame)) return;
     if (frame.type === 'ping') {
       send({ type: 'pong' });
       return;
@@ -882,6 +907,7 @@ function createEventTunnel({ record, foreground = false }) {
       connectedAt = 0;
       lastGatewayFrameAt = 0;
       peerProtocolVersion = 1;
+      sharedRealtime.stop();
       // Streams, sockets, and queued response frames belong to THIS gateway
       // connection: their req/conn ids mean nothing to the next one, and its
       // cancel frames will never reference them. Dropping them here is the
@@ -933,6 +959,7 @@ function createEventTunnel({ record, foreground = false }) {
       stopped = true;
       if (reconnectTimer) clearTimeout(reconnectTimer);
       if (routeTimer) clearInterval(routeTimer);
+      sharedRealtime.stop();
       stopWatchdog();
       resetBulkQueue('event tunnel stopped');
       dropActiveProxies('event tunnel stopped');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.155",
+  "version": "0.1.156",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/server/routes/state.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const stateRest = require('../../state/rest');
+const sharedRest = require('../../state/shared-rest');
 
 async function handleStateRoutes(ctx) {
   if (ctx.method === 'GET') {
@@ -24,6 +25,24 @@ async function handleStateRoutes(ctx) {
       await stateRest.handleResourceList(ctx.sendJson);
       return true;
     }
+    if (ctx.pathname === '/state/shared/replicas') {
+      await sharedRest.handleReplicaList(ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname.startsWith('/state/shared/promotions/')) {
+      await sharedRest.handlePromotionGet(
+        decodeURIComponent(ctx.pathname.slice('/state/shared/promotions/'.length)),
+        ctx.sendJson,
+      );
+      return true;
+    }
+    if (ctx.pathname.startsWith('/state/shared/attachments/')) {
+      await sharedRest.handleAttachmentGet(
+        decodeURIComponent(ctx.pathname.slice('/state/shared/attachments/'.length)),
+        ctx.sendJson,
+      );
+      return true;
+    }
     return false;
   }
 
@@ -52,6 +71,62 @@ async function handleStateRoutes(ctx) {
       await stateRest.handleDocWrite(await ctx.readJsonBody(), ctx.sendJson);
       return true;
     }
+    if (ctx.pathname === '/state/mutations/claim') {
+      await sharedRest.handleMutationClaim(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/mutations/ack') {
+      await sharedRest.handleMutationAck(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/mutations/fail') {
+      await sharedRest.handleMutationFail(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/mutations/ingest') {
+      await sharedRest.handleMutationIngest(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/replicas/register') {
+      await sharedRest.handleReplicaRegister(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/replicas/authority') {
+      await sharedRest.handleReplicaAuthority(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/promote') {
+      await sharedRest.handlePromotionStart(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/promotions/claim') {
+      await sharedRest.handlePromotionClaim(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/promotions/ack') {
+      await sharedRest.handlePromotionAck(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/promotions/fail') {
+      await sharedRest.handlePromotionFail(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/attach') {
+      await sharedRest.handleAttachmentStart(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/attachments/claim') {
+      await sharedRest.handleAttachmentClaim(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/attachments/ack') {
+      await sharedRest.handleAttachmentAck(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
+    if (ctx.pathname === '/state/shared/attachments/fail') {
+      await sharedRest.handleAttachmentFail(await ctx.readJsonBody(), ctx.sendJson);
+      return true;
+    }
     return false;
   }