@xfxstudio/claworld 2026.4.16-testing.1 → 2026.4.16-testing.2

package/src/openclaw/plugin/relay-client-shared.js

@@ -0,0 +1,146 @@
+import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
+
+export const DUPLICATE_CONNECTION_CLOSE_CODE = 4001;
+export const STALE_CONNECTION_CLOSE_CODE = 4002;
+export const TERMINAL_CLOSE_REASONS = new Set(['duplicate_connection_replaced', 'stale_connection']);
+export const DEFAULT_REPLY_ACK_TIMEOUT_MS = 5000;
+
+export function normalizeRelayWebSocketUrl(serverUrl) {
+  const parsed = new URL(serverUrl);
+  if (parsed.protocol === 'http:') parsed.protocol = 'ws:';
+  if (parsed.protocol === 'https:') parsed.protocol = 'wss:';
+
+  const pathname = parsed.pathname || '/';
+  const normalizedPathname = pathname.replace(/\/+$/, '') || '/';
+  parsed.pathname = normalizedPathname === '/' || normalizedPathname === ''
+    ? '/ws'
+    : normalizedPathname.endsWith('/ws')
+      ? normalizedPathname
+      : normalizedPathname + '/ws';
+
+  return parsed.toString();
+}
+
+export function buildInboundEnvelope(message = {}) {
+  const data = message.data || {};
+  if (message.event !== 'delivery') return null;
+  const metadata = data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)
+    ? { ...data.metadata }
+    : {};
+  return {
+    eventType: data.eventType || 'delivery',
+    deliveryId: data.deliveryId || null,
+    sessionKey: data.sessionKey || null,
+    createdAt: data.createdAt || null,
+    updatedAt: data.updatedAt || null,
+    turnCreatedAt: data.turnCreatedAt || null,
+    payload: data.payload && typeof data.payload === 'object' && !Array.isArray(data.payload)
+      ? { ...data.payload }
+      : {},
+    metadata,
+  };
+}
+
+export function normalizeOptionalText(value) {
+  if (value == null) return null;
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+export function requireClientMessageId(value = null) {
+  const normalized = normalizeOptionalText(value);
+  if (!normalized) {
+    throw new Error('claworld relay clientMessageId is required for POST /v1/orchestration/messages');
+  }
+  return normalized;
+}
+
+export function buildReplyAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_reply_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay reply acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay reply acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
+export function buildAcceptedAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_delivery_accept_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay delivery acceptance acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay delivery acceptance acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
+export function buildReplyFallbackError({
+  deliveryId = null,
+  status = 502,
+  body = {},
+  context = {},
+} = {}) {
+  return createRuntimeBoundaryError({
+    code: normalizeOptionalText(body?.code) || normalizeOptionalText(body?.error) || 'relay_reply_fallback_failed',
+    category: status >= 500 ? 'runtime' : 'transport',
+    status: Number.isInteger(status) ? status : 502,
+    message: normalizeOptionalText(body?.message) || normalizeOptionalText(body?.reason) || 'relay reply fallback failed',
+    publicMessage: 'relay reply fallback failed',
+    recoverable: status >= 500,
+    context: {
+      deliveryId: normalizeOptionalText(deliveryId),
+      ...context,
+    },
+  });
+}
+
+export function buildKeepSilentAckTimeoutError({ deliveryId, timeoutMs, context = {} } = {}) {
+  return createRuntimeBoundaryError({
+    code: 'relay_kept_silent_ack_timeout',
+    category: 'transport',
+    status: 504,
+    message: `timed out waiting for relay kept_silent acknowledgement for ${deliveryId || 'unknown-delivery'} after ${timeoutMs}ms`,
+    publicMessage: 'relay kept_silent acknowledgement timed out',
+    recoverable: true,
+    context,
+  });
+}
+
+export function buildKeepSilentFallbackError({
+  deliveryId = null,
+  status = 502,
+  body = {},
+  context = {},
+} = {}) {
+  return createRuntimeBoundaryError({
+    code: normalizeOptionalText(body?.code) || normalizeOptionalText(body?.error) || 'relay_kept_silent_fallback_failed',
+    category: status >= 500 ? 'runtime' : 'transport',
+    status: Number.isInteger(status) ? status : 502,
+    message: normalizeOptionalText(body?.message) || normalizeOptionalText(body?.reason) || 'relay kept_silent fallback failed',
+    publicMessage: 'relay kept_silent fallback failed',
+    recoverable: status >= 500,
+    context: {
+      deliveryId: normalizeOptionalText(deliveryId),
+      ...context,
+    },
+  });
+}
+
+export function isReplyAlreadyApplied(result = null, deliveryId = null) {
+  if (!result || result.status !== 409) return false;
+  if (normalizeOptionalText(result.body?.reason) !== 'delivery_not_replyable') return false;
+  if (normalizeOptionalText(result.body?.delivery?.deliveryId) !== normalizeOptionalText(deliveryId)) return false;
+  return normalizeOptionalText(result.body?.delivery?.status) === 'replied';
+}
+
+export function isDeliveryKeptSilentAlreadyApplied(result = null, deliveryId = null) {
+  if (!result || result.status !== 409) return false;
+  if (normalizeOptionalText(result.body?.reason) !== 'delivery_not_replyable') return false;
+  if (normalizeOptionalText(result.body?.delivery?.deliveryId) !== normalizeOptionalText(deliveryId)) return false;
+  return normalizeOptionalText(result.body?.delivery?.status) === 'kept_silent';
+}