@undefineds.co/xpod 0.1.0-local.202602081751

package/dist/signaling/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * WebSocket 信令服务消息类型定义
+ *
+ * 统一处理：
+ * - 心跳/状态上报（替代 /api/signal）
+ * - WebRTC 信令转发
+ * - 其他控制消息
+ */
+/**
+ * 连接类型
+ */
+export type ConnectionType = 'local' | 'client';
+/**
+ * 基础消息结构
+ */
+export interface BaseMessage {
+    type: string;
+    /** 消息 ID，用于请求-响应匹配 */
+    id?: string;
+}
+/**
+ * 心跳消息（Local → Cloud）
+ */
+export interface HeartbeatMessage extends BaseMessage {
+    type: 'heartbeat';
+    nodeId: string;
+    baseUrl?: string;
+    publicAddress?: string;
+    hostname?: string;
+    ipv4?: string;
+    ipv6?: string;
+    version?: string;
+    status?: 'online' | 'offline' | 'maintenance';
+    capabilities?: string[];
+    pods?: string[];
+    metrics?: Record<string, unknown>;
+}
+/**
+ * 心跳响应（Cloud → Local）
+ */
+export interface HeartbeatAckMessage extends BaseMessage {
+    type: 'heartbeat-ack';
+    nodeId: string;
+    lastSeen: string;
+    /** Cloud 下发的配置 */
+    config?: {
+        iceServers?: RTCIceServer[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * RTC ICE 服务器配置
+ */
+export interface RTCIceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+/**
+ * WebRTC Offer 消息
+ */
+export interface RTCOfferMessage extends BaseMessage {
+    type: 'rtc-offer';
+    /** 发送方 ID */
+    from: string;
+    /** 目标节点 ID */
+    targetId: string;
+    /** SDP offer */
+    sdp: string;
+    /** 会话 ID */
+    sessionId: string;
+}
+/**
+ * WebRTC Answer 消息
+ */
+export interface RTCAnswerMessage extends BaseMessage {
+    type: 'rtc-answer';
+    /** 发送方 ID */
+    from: string;
+    /** 目标 ID */
+    targetId: string;
+    /** SDP answer */
+    sdp: string;
+    /** 会话 ID */
+    sessionId: string;
+}
+/**
+ * WebRTC ICE Candidate 消息
+ */
+export interface RTCIceCandidateMessage extends BaseMessage {
+    type: 'rtc-ice';
+    /** 发送方 ID */
+    from: string;
+    /** 目标 ID */
+    targetId: string;
+    /** ICE candidate */
+    candidate: string;
+    /** SDP mid */
+    sdpMid?: string;
+    /** SDP mline index */
+    sdpMLineIndex?: number;
+    /** 会话 ID */
+    sessionId: string;
+}
+/**
+ * WebRTC 连接关闭消息
+ */
+export interface RTCCloseMessage extends BaseMessage {
+    type: 'rtc-close';
+    /** 发送方 ID */
+    from: string;
+    /** 目标 ID */
+    targetId: string;
+    /** 会话 ID */
+    sessionId: string;
+    /** 关闭原因 */
+    reason?: string;
+}
+/**
+ * 认证消息（连接后首条消息）
+ */
+export interface AuthMessage extends BaseMessage {
+    type: 'auth';
+    /** 连接类型 */
+    connectionType: ConnectionType;
+    /** 节点 ID（Local）或客户端 ID，client 模式可选 */
+    id?: string;
+    /** 认证令牌，client 模式可选 */
+    token?: string;
+}
+/**
+ * 认证响应
+ */
+export interface AuthAckMessage extends BaseMessage {
+    type: 'auth-ack';
+    success: boolean;
+    error?: string;
+    /** 分配的 ID（client 模式下服务端分配） */
+    assignedId?: string;
+    /** ICE 服务器配置 */
+    iceServers?: RTCIceServer[];
+}
+/**
+ * 错误消息
+ */
+export interface ErrorMessage extends BaseMessage {
+    type: 'error';
+    code: string;
+    message: string;
+    /** 相关消息 ID */
+    relatedId?: string;
+}
+/**
+ * Ping/Pong 保活消息
+ */
+export interface PingMessage extends BaseMessage {
+    type: 'ping';
+    timestamp: number;
+}
+export interface PongMessage extends BaseMessage {
+    type: 'pong';
+    timestamp: number;
+}
+/**
+ * 节点解析请求（Client → Cloud）
+ *
+ * Client 请求连接某个 Local 节点时发送
+ * Cloud 返回连接方式（直连 or WebRTC）
+ */
+export interface ResolveNodeRequest extends BaseMessage {
+    type: 'resolve-node';
+    /** 目标节点 ID */
+    targetNodeId: string;
+    /** Client 的内网 IP 列表 */
+    clientPrivateIPs?: string[];
+    /** Client 的公网 IP（可选，Cloud 也能从连接获取） */
+    clientPublicIP?: string;
+}
+/**
+ * 节点解析响应（Cloud → Client）
+ */
+export interface ResolveNodeResponse extends BaseMessage {
+    type: 'resolve-node-ack';
+    /** 目标节点 ID */
+    targetNodeId: string;
+    /** 节点是否在线 */
+    online: boolean;
+    /** 连接方式 */
+    connectionType: 'direct' | 'webrtc' | 'unavailable';
+    /** 直连信息（仅 connectionType=direct 时有效） */
+    direct?: {
+        /** Local 节点的内网 IP 列表 */
+        localIPs: string[];
+        /** Local 节点的端口 */
+        port?: number;
+        /** 推荐使用的 IP */
+        preferredIP?: string;
+    };
+    /** WebRTC 连接信息（仅 connectionType=webrtc 时有效） */
+    webrtc?: {
+        /** ICE 服务器配置 */
+        iceServers: RTCIceServer[];
+    };
+    /** 原因说明 */
+    reason?: string;
+}
+/**
+ * 所有消息类型
+ */
+export type SignalingMessage = HeartbeatMessage | HeartbeatAckMessage | RTCOfferMessage | RTCAnswerMessage | RTCIceCandidateMessage | RTCCloseMessage | AuthMessage | AuthAckMessage | ErrorMessage | PingMessage | PongMessage | ResolveNodeRequest | ResolveNodeResponse;
+/**
+ * WebRTC 信令消息类型
+ */
+export type RTCSignalingMessage = RTCOfferMessage | RTCAnswerMessage | RTCIceCandidateMessage | RTCCloseMessage;
+/**
+ * 判断是否为 RTC 信令消息
+ */
+export declare function isRTCMessage(msg: SignalingMessage): msg is RTCSignalingMessage;
+/**
+ * 连接信息
+ */
+export interface ConnectionInfo {
+    /** 连接 ID */
+    id: string;
+    /** 连接类型 */
+    type: ConnectionType;
+    /** 认证状态 */
+    authenticated: boolean;
+    /** WebID（如果已认证） */
+    webId?: string;
+    /** 连接时间 */
+    connectedAt: Date;
+    /** 最后活动时间 */
+    lastActivityAt: Date;
+    /** 节点元数据（仅 Local） */
+    metadata?: Record<string, unknown>;
+}

package/dist/signaling/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * WebSocket 信令服务消息类型定义
+ *
+ * 统一处理：
+ * - 心跳/状态上报（替代 /api/signal）
+ * - WebRTC 信令转发
+ * - 其他控制消息
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRTCMessage = isRTCMessage;
+/**
+ * 判断是否为 RTC 信令消息
+ */
+function isRTCMessage(msg) {
+    return ['rtc-offer', 'rtc-answer', 'rtc-ice', 'rtc-close'].includes(msg.type);
+}
+//# sourceMappingURL=types.js.map

package/dist/signaling/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/signaling/types.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAgQH,oCAEC;AALD;;GAEG;AACH,SAAgB,YAAY,CAAC,GAAqB;IAChD,OAAO,CAAC,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChF,CAAC","sourcesContent":["/**\n * WebSocket 信令服务消息类型定义\n *\n * 统一处理：\n * - 心跳/状态上报（替代 /api/signal）\n * - WebRTC 信令转发\n * - 其他控制消息\n */\n\n/**\n * 连接类型\n */\nexport type ConnectionType = 'local' | 'client';\n\n/**\n * 基础消息结构\n */\nexport interface BaseMessage {\n  type: string;\n  /** 消息 ID，用于请求-响应匹配 */\n  id?: string;\n}\n\n// ============ 心跳/状态消息 ============\n\n/**\n * 心跳消息（Local → Cloud）\n */\nexport interface HeartbeatMessage extends BaseMessage {\n  type: 'heartbeat';\n  nodeId: string;\n  baseUrl?: string;\n  publicAddress?: string;\n  hostname?: string;\n  ipv4?: string;\n  ipv6?: string;\n  version?: string;\n  status?: 'online' | 'offline' | 'maintenance';\n  capabilities?: string[];\n  pods?: string[];\n  metrics?: Record<string, unknown>;\n}\n\n/**\n * 心跳响应（Cloud → Local）\n */\nexport interface HeartbeatAckMessage extends BaseMessage {\n  type: 'heartbeat-ack';\n  nodeId: string;\n  lastSeen: string;\n  /** Cloud 下发的配置 */\n  config?: {\n    iceServers?: RTCIceServer[];\n    [key: string]: unknown;\n  };\n}\n\n// ============ WebRTC 信令消息 ============\n\n/**\n * RTC ICE 服务器配置\n */\nexport interface RTCIceServer {\n  urls: string | string[];\n  username?: string;\n  credential?: string;\n}\n\n/**\n * WebRTC Offer 消息\n */\nexport interface RTCOfferMessage extends BaseMessage {\n  type: 'rtc-offer';\n  /** 发送方 ID */\n  from: string;\n  /** 目标节点 ID */\n  targetId: string;\n  /** SDP offer */\n  sdp: string;\n  /** 会话 ID */\n  sessionId: string;\n}\n\n/**\n * WebRTC Answer 消息\n */\nexport interface RTCAnswerMessage extends BaseMessage {\n  type: 'rtc-answer';\n  /** 发送方 ID */\n  from: string;\n  /** 目标 ID */\n  targetId: string;\n  /** SDP answer */\n  sdp: string;\n  /** 会话 ID */\n  sessionId: string;\n}\n\n/**\n * WebRTC ICE Candidate 消息\n */\nexport interface RTCIceCandidateMessage extends BaseMessage {\n  type: 'rtc-ice';\n  /** 发送方 ID */\n  from: string;\n  /** 目标 ID */\n  targetId: string;\n  /** ICE candidate */\n  candidate: string;\n  /** SDP mid */\n  sdpMid?: string;\n  /** SDP mline index */\n  sdpMLineIndex?: number;\n  /** 会话 ID */\n  sessionId: string;\n}\n\n/**\n * WebRTC 连接关闭消息\n */\nexport interface RTCCloseMessage extends BaseMessage {\n  type: 'rtc-close';\n  /** 发送方 ID */\n  from: string;\n  /** 目标 ID */\n  targetId: string;\n  /** 会话 ID */\n  sessionId: string;\n  /** 关闭原因 */\n  reason?: string;\n}\n\n// ============ 控制消息 ============\n\n/**\n * 认证消息（连接后首条消息）\n */\nexport interface AuthMessage extends BaseMessage {\n  type: 'auth';\n  /** 连接类型 */\n  connectionType: ConnectionType;\n  /** 节点 ID（Local）或客户端 ID，client 模式可选 */\n  id?: string;\n  /** 认证令牌，client 模式可选 */\n  token?: string;\n}\n\n/**\n * 认证响应\n */\nexport interface AuthAckMessage extends BaseMessage {\n  type: 'auth-ack';\n  success: boolean;\n  error?: string;\n  /** 分配的 ID（client 模式下服务端分配） */\n  assignedId?: string;\n  /** ICE 服务器配置 */\n  iceServers?: RTCIceServer[];\n}\n\n/**\n * 错误消息\n */\nexport interface ErrorMessage extends BaseMessage {\n  type: 'error';\n  code: string;\n  message: string;\n  /** 相关消息 ID */\n  relatedId?: string;\n}\n\n/**\n * Ping/Pong 保活消息\n */\nexport interface PingMessage extends BaseMessage {\n  type: 'ping';\n  timestamp: number;\n}\n\nexport interface PongMessage extends BaseMessage {\n  type: 'pong';\n  timestamp: number;\n}\n\n// ============ 局域网探测消息 ============\n\n/**\n * 节点解析请求（Client → Cloud）\n *\n * Client 请求连接某个 Local 节点时发送\n * Cloud 返回连接方式（直连 or WebRTC）\n */\nexport interface ResolveNodeRequest extends BaseMessage {\n  type: 'resolve-node';\n  /** 目标节点 ID */\n  targetNodeId: string;\n  /** Client 的内网 IP 列表 */\n  clientPrivateIPs?: string[];\n  /** Client 的公网 IP（可选，Cloud 也能从连接获取） */\n  clientPublicIP?: string;\n}\n\n/**\n * 节点解析响应（Cloud → Client）\n */\nexport interface ResolveNodeResponse extends BaseMessage {\n  type: 'resolve-node-ack';\n  /** 目标节点 ID */\n  targetNodeId: string;\n  /** 节点是否在线 */\n  online: boolean;\n  /** 连接方式 */\n  connectionType: 'direct' | 'webrtc' | 'unavailable';\n  /** 直连信息（仅 connectionType=direct 时有效） */\n  direct?: {\n    /** Local 节点的内网 IP 列表 */\n    localIPs: string[];\n    /** Local 节点的端口 */\n    port?: number;\n    /** 推荐使用的 IP */\n    preferredIP?: string;\n  };\n  /** WebRTC 连接信息（仅 connectionType=webrtc 时有效） */\n  webrtc?: {\n    /** ICE 服务器配置 */\n    iceServers: RTCIceServer[];\n  };\n  /** 原因说明 */\n  reason?: string;\n}\n\n// ============ 联合类型 ============\n\n/**\n * 所有消息类型\n */\nexport type SignalingMessage =\n  | HeartbeatMessage\n  | HeartbeatAckMessage\n  | RTCOfferMessage\n  | RTCAnswerMessage\n  | RTCIceCandidateMessage\n  | RTCCloseMessage\n  | AuthMessage\n  | AuthAckMessage\n  | ErrorMessage\n  | PingMessage\n  | PongMessage\n  | ResolveNodeRequest\n  | ResolveNodeResponse;\n\n/**\n * WebRTC 信令消息类型\n */\nexport type RTCSignalingMessage =\n  | RTCOfferMessage\n  | RTCAnswerMessage\n  | RTCIceCandidateMessage\n  | RTCCloseMessage;\n\n/**\n * 判断是否为 RTC 信令消息\n */\nexport function isRTCMessage(msg: SignalingMessage): msg is RTCSignalingMessage {\n  return ['rtc-offer', 'rtc-answer', 'rtc-ice', 'rtc-close'].includes(msg.type);\n}\n\n/**\n * 连接信息\n */\nexport interface ConnectionInfo {\n  /** 连接 ID */\n  id: string;\n  /** 连接类型 */\n  type: ConnectionType;\n  /** 认证状态 */\n  authenticated: boolean;\n  /** WebID（如果已认证） */\n  webId?: string;\n  /** 连接时间 */\n  connectedAt: Date;\n  /** 最后活动时间 */\n  lastActivityAt: Date;\n  /** 节点元数据（仅 Local） */\n  metadata?: Record<string, unknown>;\n}\n"]}

package/dist/storage/DrizzleCompat.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Drizzle ORM Compatibility Layer
+ *
+ * Auto-selects better-sqlite3 or bun-sqlite driver based on runtime
+ */
+export type DrizzleDb = any;
+interface DrizzleDeps {
+    drizzle: (db: any) => DrizzleDb;
+}
+export declare function getDrizzleDeps(): Promise<DrizzleDeps>;
+/**
+ * Create Drizzle database instance
+ */
+export declare function createDrizzleDb(sqliteDb: any): Promise<DrizzleDb>;
+export {};

package/dist/storage/DrizzleCompat.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Drizzle ORM Compatibility Layer
+ *
+ * Auto-selects better-sqlite3 or bun-sqlite driver based on runtime
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDrizzleDeps = getDrizzleDeps;
+exports.createDrizzleDb = createDrizzleDb;
+const isBun = typeof globalThis.Bun !== 'undefined';
+let deps;
+async function getDrizzleDeps() {
+    if (deps)
+        return deps;
+    if (isBun) {
+        const bunSqlite = await Promise.resolve().then(() => __importStar(require('drizzle-orm/bun-sqlite')));
+        deps = { drizzle: bunSqlite.drizzle };
+    }
+    else {
+        const betterSqlite = await Promise.resolve().then(() => __importStar(require('drizzle-orm/better-sqlite3')));
+        deps = { drizzle: betterSqlite.drizzle };
+    }
+    return deps;
+}
+/**
+ * Create Drizzle database instance
+ */
+async function createDrizzleDb(sqliteDb) {
+    const { drizzle } = await getDrizzleDeps();
+    const db = drizzle(sqliteDb);
+    // Mark as Bun SQLite for db.ts detection
+    if (isBun) {
+        db.$isBunSqlite = true;
+    }
+    return db;
+}
+//# sourceMappingURL=DrizzleCompat.js.map

package/dist/storage/DrizzleCompat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DrizzleCompat.js","sourceRoot":"","sources":["../../src/storage/DrizzleCompat.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;AAcH,wCAYC;AAKD,0CAQC;AAnCD,MAAM,KAAK,GAAG,OAAQ,UAAkB,CAAC,GAAG,KAAK,WAAW,CAAC;AAQ7D,IAAI,IAA6B,CAAC;AAE3B,KAAK,UAAU,cAAc;IAClC,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,SAAS,GAAG,wDAAa,wBAAwB,GAAC,CAAC;QACzD,IAAI,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,MAAM,YAAY,GAAG,wDAAa,4BAA4B,GAAC,CAAC;QAChE,IAAI,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,eAAe,CAAC,QAAa;IACjD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;IAC3C,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B,yCAAyC;IACzC,IAAI,KAAK,EAAE,CAAC;QACV,EAAE,CAAC,YAAY,GAAG,IAAI,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC","sourcesContent":["/**\n * Drizzle ORM Compatibility Layer\n *\n * Auto-selects better-sqlite3 or bun-sqlite driver based on runtime\n */\n\nimport type { SQL } from 'drizzle-orm';\n\nconst isBun = typeof (globalThis as any).Bun !== 'undefined';\n\nexport type DrizzleDb = any;\n\ninterface DrizzleDeps {\n  drizzle: (db: any) => DrizzleDb;\n}\n\nlet deps: DrizzleDeps | undefined;\n\nexport async function getDrizzleDeps(): Promise<DrizzleDeps> {\n  if (deps) return deps;\n\n  if (isBun) {\n    const bunSqlite = await import('drizzle-orm/bun-sqlite');\n    deps = { drizzle: bunSqlite.drizzle };\n  } else {\n    const betterSqlite = await import('drizzle-orm/better-sqlite3');\n    deps = { drizzle: betterSqlite.drizzle };\n  }\n\n  return deps;\n}\n\n/**\n * Create Drizzle database instance\n */\nexport async function createDrizzleDb(sqliteDb: any): Promise<DrizzleDb> {\n  const { drizzle } = await getDrizzleDeps();\n  const db = drizzle(sqliteDb);\n  // Mark as Bun SQLite for db.ts detection\n  if (isBun) {\n    db.$isBunSqlite = true;\n  }\n  return db;\n}\n"]}

package/dist/storage/LockingResourceStore.d.ts

@@ -0,0 +1,8 @@
+import { LockingResourceStore as BaseLockingResourceStore, ResourceIdentifier, Representation, Conditions, ChangeMap } from '@solid/community-server';
+export declare class LockingResourceStore extends BaseLockingResourceStore {
+    protected logger: import("global-logger-factory").Logger<unknown>;
+    getLockIdentifier(identifier: ResourceIdentifier): ResourceIdentifier;
+    addResource(identifier: ResourceIdentifier, representation: Representation, conditions?: Conditions): Promise<ChangeMap>;
+    lockedRepresentationRun(identifier: ResourceIdentifier, whileLocked: () => Promise<Representation>): Promise<Representation>;
+    setRepresentation(identifier: ResourceIdentifier, representation: Representation, conditions?: Conditions): Promise<ChangeMap>;
+}

package/dist/storage/LockingResourceStore.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockingResourceStore = void 0;
+const community_server_1 = require("@solid/community-server");
+const global_logger_factory_1 = require("global-logger-factory");
+class LockingResourceStore extends community_server_1.LockingResourceStore {
+    constructor() {
+        super(...arguments);
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+    }
+    getLockIdentifier(identifier) {
+        // Guard against missing auxiliary strategy in custom wiring
+        const hasAuxiliary = this.auxiliaryStrategy?.isAuxiliaryIdentifier;
+        const lockIdentifier = hasAuxiliary ? super.getLockIdentifier(identifier) : identifier;
+        this.logger.debug(`getLockIdentifier: ${identifier.path} -> ${lockIdentifier.path}`);
+        return lockIdentifier;
+    }
+    async addResource(identifier, representation, conditions) {
+        this.logger.debug(`trying[addResource]: ${identifier.path}`);
+        try {
+            const result = await super.addResource(identifier, representation, conditions);
+            this.logger.debug(`done[addResource]: ${identifier.path}`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`locking: ${identifier.path}, ${error}`);
+            throw error;
+        }
+        finally {
+            this.logger.debug(`unlocked: ${identifier.path}`);
+        }
+    }
+    async lockedRepresentationRun(identifier, whileLocked) {
+        this.logger.debug(`trying[lockedRepresentationRun]: ${identifier.path}`);
+        try {
+            const result = await super.lockedRepresentationRun(identifier, async () => {
+                this.logger.debug(`  locked: ${identifier.path}`);
+                return await whileLocked();
+            });
+            this.logger.debug(`done[lockedRepresentationRun]: ${identifier.path}`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`locking: ${identifier.path}, ${error}`);
+            throw error;
+        }
+        finally {
+            this.logger.debug(`unlocked: ${identifier.path}`);
+        }
+    }
+    async setRepresentation(identifier, representation, conditions) {
+        this.logger.debug(`trying[setRepresentation]: ${identifier.path}`);
+        try {
+            const result = await super.setRepresentation(identifier, representation, conditions);
+            this.logger.debug(`done[setRepresentation]: ${identifier.path}`);
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`locking: ${identifier.path}, ${error}`);
+            throw error;
+        }
+        finally {
+            this.logger.debug(`unlocked: ${identifier.path}`);
+        }
+    }
+}
+exports.LockingResourceStore = LockingResourceStore;
+//# sourceMappingURL=LockingResourceStore.js.map

package/dist/storage/LockingResourceStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LockingResourceStore.js","sourceRoot":"","sources":["../../src/storage/LockingResourceStore.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  LockingResourceStore as BaseLockingResourceStore,\n  ResourceIdentifier,\n  Representation,\n  Conditions,\n  ChangeMap,\n} from '@solid/community-server';\nimport { getLoggerFor } from 'global-logger-factory';\n\nexport class LockingResourceStore extends BaseLockingResourceStore {\n  protected override logger = getLoggerFor(this);\n\n  override getLockIdentifier(identifier: ResourceIdentifier): ResourceIdentifier {\n    // Guard against missing auxiliary strategy in custom wiring\n    const hasAuxiliary = (this as any).auxiliaryStrategy?.isAuxiliaryIdentifier;\n    const lockIdentifier = hasAuxiliary ? super.getLockIdentifier(identifier) : identifier;\n    this.logger.debug(`getLockIdentifier: ${identifier.path} -> ${lockIdentifier.path}`);\n    return lockIdentifier;\n  }\n\n  override async addResource(\n    identifier: ResourceIdentifier,\n    representation: Representation,\n    conditions?: Conditions,\n  ): Promise<ChangeMap> {\n    this.logger.debug(`trying[addResource]: ${identifier.path}`);\n    try {\n      const result = await super.addResource(identifier, representation, conditions);\n      this.logger.debug(`done[addResource]: ${identifier.path}`);\n      return result;\n    } catch (error) {\n      this.logger.error(`locking: ${identifier.path}, ${error}`);\n      throw error;\n    } finally {\n      this.logger.debug(`unlocked: ${identifier.path}`);\n    }\n  }\n\n  override async lockedRepresentationRun(identifier: ResourceIdentifier, whileLocked: () => Promise<Representation>):\n  Promise<Representation> {\n    this.logger.debug(`trying[lockedRepresentationRun]: ${identifier.path}`);\n    try {\n      const result = await super.lockedRepresentationRun(identifier, async () => {\n        this.logger.debug(`  locked: ${identifier.path}`);\n        return await whileLocked();\n      });\n      this.logger.debug(`done[lockedRepresentationRun]: ${identifier.path}`);\n      return result;\n    } catch (error) {\n      this.logger.error(`locking: ${identifier.path}, ${error}`);\n      throw error;\n    } finally {\n      this.logger.debug(`unlocked: ${identifier.path}`);\n    }\n  }\n\n  override async setRepresentation(\n    identifier: ResourceIdentifier,\n    representation: Representation,\n    conditions?: Conditions,\n  ): Promise<ChangeMap> {\n    this.logger.debug(`trying[setRepresentation]: ${identifier.path}`);\n    try {\n      const result = await super.setRepresentation(identifier, representation, conditions);\n      this.logger.debug(`done[setRepresentation]: ${identifier.path}`);\n      return result;\n    } catch (error) {\n      this.logger.error(`locking: ${identifier.path}, ${error}`);\n      throw error;\n    } finally {\n      this.logger.debug(`unlocked: ${identifier.path}`);\n    }\n  }\n}\n"]}

package/dist/storage/MigratableDataAccessor.d.ts

@@ -0,0 +1,63 @@
+import type { DataAccessor } from '@solid/community-server';
+/**
+ * Progress information for data migration.
+ */
+export interface MigrationProgress {
+    /** Number of objects copied */
+    copied: number;
+    /** Total number of objects to copy */
+    total: number;
+    /** Bytes transferred so far */
+    bytesTransferred: number;
+}
+/**
+ * Extended DataAccessor interface for storage backends that support
+ * cross-region operations.
+ *
+ * Primary use: Cross-region fallback reads for instant pod migration.
+ * - Reads check local bucket first, then fallback to other region buckets
+ * - Lazy copy: files are copied to local bucket on first access
+ *
+ * Optional: Bulk migration for cleanup/cost optimization.
+ * - Not required for migration to work (fallback handles it)
+ * - Can be used to proactively move cold data and reduce cross-region costs
+ */
+export interface MigratableDataAccessor extends DataAccessor {
+    /**
+     * Check if this accessor supports cross-region operations.
+     */
+    supportsMigration(): boolean;
+    /**
+     * Bulk migrate all resources under the given prefix to a target region.
+     *
+     * This is OPTIONAL - migration works without it via fallback reads.
+     * Use this for:
+     * - Cleaning up source region to save storage costs
+     * - Proactively copying cold data to reduce latency
+     *
+     * @param prefix - Resource path prefix (e.g., "/alice/")
+     * @param targetRegion - Target region identifier
+     * @param onProgress - Optional progress callback
+     * @throws Error if migration is not supported
+     */
+    migrateToRegion(prefix: string, targetRegion: string, onProgress?: (progress: MigrationProgress) => void): Promise<void>;
+    /**
+     * Set up real-time synchronization during active migration.
+     * New writes to the source region will be replicated to the target.
+     *
+     * @param prefix - Resource path prefix
+     * @param targetRegion - Target region identifier
+     */
+    setupRealtimeSync(prefix: string, targetRegion: string): Promise<void>;
+    /**
+     * Stop real-time synchronization after migration completes.
+     *
+     * @param prefix - Resource path prefix
+     * @param targetRegion - Target region identifier
+     */
+    stopRealtimeSync(prefix: string, targetRegion: string): Promise<void>;
+}
+/**
+ * Type guard to check if a DataAccessor supports cross-region operations.
+ */
+export declare function isMigratableAccessor(accessor: DataAccessor): accessor is MigratableDataAccessor;

package/dist/storage/MigratableDataAccessor.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMigratableAccessor = isMigratableAccessor;
+/**
+ * Type guard to check if a DataAccessor supports cross-region operations.
+ */
+function isMigratableAccessor(accessor) {
+    return (typeof accessor.supportsMigration === 'function' &&
+        accessor.supportsMigration());
+}
+//# sourceMappingURL=MigratableDataAccessor.js.map

package/dist/storage/MigratableDataAccessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MigratableDataAccessor.js","sourceRoot":"","sources":["../../src/storage/MigratableDataAccessor.ts"],"names":[],"mappings":";;AAwEA,oDAKC;AARD;;GAEG;AACH,SAAgB,oBAAoB,CAAC,QAAsB;IACzD,OAAO,CACL,OAAQ,QAAmC,CAAC,iBAAiB,KAAK,UAAU;QAC3E,QAAmC,CAAC,iBAAiB,EAAE,CACzD,CAAC;AACJ,CAAC","sourcesContent":["import type { DataAccessor } from '@solid/community-server';\n\n/**\n * Progress information for data migration.\n */\nexport interface MigrationProgress {\n  /** Number of objects copied */\n  copied: number;\n  /** Total number of objects to copy */\n  total: number;\n  /** Bytes transferred so far */\n  bytesTransferred: number;\n}\n\n/**\n * Extended DataAccessor interface for storage backends that support\n * cross-region operations.\n * \n * Primary use: Cross-region fallback reads for instant pod migration.\n * - Reads check local bucket first, then fallback to other region buckets\n * - Lazy copy: files are copied to local bucket on first access\n * \n * Optional: Bulk migration for cleanup/cost optimization.\n * - Not required for migration to work (fallback handles it)\n * - Can be used to proactively move cold data and reduce cross-region costs\n */\nexport interface MigratableDataAccessor extends DataAccessor {\n  /**\n   * Check if this accessor supports cross-region operations.\n   */\n  supportsMigration(): boolean;\n\n  /**\n   * Bulk migrate all resources under the given prefix to a target region.\n   * \n   * This is OPTIONAL - migration works without it via fallback reads.\n   * Use this for:\n   * - Cleaning up source region to save storage costs\n   * - Proactively copying cold data to reduce latency\n   * \n   * @param prefix - Resource path prefix (e.g., \"/alice/\")\n   * @param targetRegion - Target region identifier\n   * @param onProgress - Optional progress callback\n   * @throws Error if migration is not supported\n   */\n  migrateToRegion(\n    prefix: string,\n    targetRegion: string,\n    onProgress?: (progress: MigrationProgress) => void,\n  ): Promise<void>;\n\n  /**\n   * Set up real-time synchronization during active migration.\n   * New writes to the source region will be replicated to the target.\n   * \n   * @param prefix - Resource path prefix\n   * @param targetRegion - Target region identifier\n   */\n  setupRealtimeSync(prefix: string, targetRegion: string): Promise<void>;\n\n  /**\n   * Stop real-time synchronization after migration completes.\n   * \n   * @param prefix - Resource path prefix\n   * @param targetRegion - Target region identifier\n   */\n  stopRealtimeSync(prefix: string, targetRegion: string): Promise<void>;\n}\n\n/**\n * Type guard to check if a DataAccessor supports cross-region operations.\n */\nexport function isMigratableAccessor(accessor: DataAccessor): accessor is MigratableDataAccessor {\n  return (\n    typeof (accessor as MigratableDataAccessor).supportsMigration === 'function' &&\n    (accessor as MigratableDataAccessor).supportsMigration()\n  );\n}\n"]}

package/dist/storage/MigratableDataAccessor.jsonld

@@ -0,0 +1,60 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigratableDataAccessor",
+      "@type": "AbstractClass",
+      "requireElement": "MigratableDataAccessor",
+      "extends": [
+        "css:dist/storage/accessors/DataAccessor.jsonld#DataAccessor"
+      ],
+      "comment": "Extended DataAccessor interface for storage backends that support cross-region operations.  Primary use: Cross-region fallback reads for instant pod migration. - Reads check local bucket first, then fallback to other region buckets - Lazy copy: files are copied to local bucket on first access  Optional: Bulk migration for cleanup/cost optimization. - Not required for migration to work (fallback handles it) - Can be used to proactively move cold data and reduce cross-region costs",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigratableDataAccessor__member_supportsMigration",
+          "memberFieldName": "supportsMigration"
+        },
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigratableDataAccessor__member_migrateToRegion",
+          "memberFieldName": "migrateToRegion"
+        },
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigratableDataAccessor__member_setupRealtimeSync",
+          "memberFieldName": "setupRealtimeSync"
+        },
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigratableDataAccessor__member_stopRealtimeSync",
+          "memberFieldName": "stopRealtimeSync"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigrationProgress",
+      "@type": "AbstractClass",
+      "requireElement": "MigrationProgress",
+      "comment": "Progress information for data migration.",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigrationProgress__member_copied",
+          "memberFieldName": "copied"
+        },
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigrationProgress__member_total",
+          "memberFieldName": "total"
+        },
+        {
+          "@id": "undefineds:dist/storage/MigratableDataAccessor.jsonld#MigrationProgress__member_bytesTransferred",
+          "memberFieldName": "bytesTransferred"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}