@aigne/afs-did-space 1.12.0-beta.5

package/dist/remote-afs.d.cts

@@ -0,0 +1,236 @@
+import { AFSBatchDeleteEntry, AFSBatchWriteEntry, AFSDeleteOptions, AFSDeleteResult, AFSListOptions, AFSListResult, AFSReadResult, AFSWriteEntryPayload, AFSWriteResult } from "@aigne/afs";
+
+//#region src/remote-afs.d.ts
+/** Per-entry batch result restored from a wire `results[i]` (single-op iso). */
+interface RpcBatchEntryResult {
+  path: string;
+  success: boolean;
+  /** Wire `status` verbatim (200/404/409/503/…). */
+  status: number;
+  data?: Record<string, unknown>;
+  error?: string;
+  code?: string;
+  /** Soft miss for `optional: true` batchRead entries. */
+  missing?: boolean;
+  /** Conflict triple — same fields `AFSConflictError` carries. */
+  conflict?: {
+    currentCid: string | null;
+    currentMtime: number | null;
+    currentDeviceId: string | null;
+  };
+}
+interface RpcBatchResult {
+  results: RpcBatchEntryResult[];
+  succeeded: number;
+  failed: number;
+}
+/** Thrown when the server does not support the batch wire ops (old daemon). */
+declare class BatchUnsupportedError extends Error {
+  constructor();
+}
+/**
+ * Envelope-level BATCH_OVER_BUDGET / PAYLOAD_TOO_LARGE — zero entries
+ * executed; the engine halves the chunk and retries (design §7.3). MUST NOT
+ * trip the capability-fallback memory.
+ */
+declare class BatchOverBudgetError extends Error {
+  constructor(message: string);
+}
+interface RpcUserSpaceAFSOptions {
+  /** Base URL of the arc daemon / worker (e.g. "http://127.0.0.1:4900"). */
+  baseUrl: string;
+  /** Bearer token. */
+  token: string;
+  /** Envelope blocklet (the app whose /user fragment is the sync target). */
+  blocklet: string;
+  /** Optional envelope sessionId. */
+  sessionId?: string;
+  /** Extra headers (test seams, tracing). Never logged. */
+  extraHeaders?: Record<string, string>;
+}
+/**
+ * SyncCloudAFS over the afs-rpc wire (`POST /api/afs/rpc`) — the transport
+ * the production daemon/worker actually serve (the legacy `/api/space` REST
+ * server is gone; `RemoteUserSpaceAFS` above survives only for the
+ * export/import CLI against legacy hosts).
+ *
+ * Sync paths are fragment-root-relative; the wire allowlist admits only
+ * `/user/**` mutations, so every path is mapped through `/user` on the way
+ * out and stripped on the way back.
+ *
+ * Batch (P4): `batchWrite`/`batchDelete`/`batchRead` send one wire envelope
+ * each (wire-contract §9) and restore per-entry results to the single-op
+ * error types (`AFSConflictError` with the triple, `BATCH_TAIL_SKIPPED`
+ * passthrough). Capability fallback: the FIRST envelope answered with the
+ * old server's exact `Unsupported op 'batch…'` 400 marks this INSTANCE as
+ * batch-unsupported (`supportsBatch === false`) and throws
+ * {@link BatchUnsupportedError}; the engine then stays on the single-op
+ * path for the rest of the instance's life. Any other 400 (e.g.
+ * BATCH_OVER_BUDGET) does NOT trip the memory.
+ */
+declare class RpcUserSpaceAFS {
+  readonly name = "rpc-user-space";
+  private baseUrl;
+  private token;
+  private blocklet;
+  private sessionId?;
+  private extraHeaders;
+  /** null = unknown (no batch envelope sent yet); set on first evidence. */
+  private batchSupported;
+  constructor(options: RpcUserSpaceAFSOptions);
+  /** Instance-scoped capability memory (per-server, design §7.1). */
+  get supportsBatch(): boolean | null;
+  private wirePath;
+  private stripUser;
+  private rpc;
+  /** Map a non-OK single-op wire response onto the AFS error types. */
+  private throwWireError;
+  /**
+   * 409 → AFSConflictError with the triple. Keyed on `code: "AFS_CONFLICT"`
+   * OR triple-field presence — NEVER the legacy `error === "if_match_failed"`
+   * string (the T4.1 存量 bug: the wire sends the stable code, see
+   * afs-rpc-wire.ts WIRE_ERROR_CODES.conflict; Swift's throwConflict already
+   * keys on the code).
+   */
+  private throwConflict;
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string): Promise<AFSReadResult>;
+  write(path: string, payload: AFSWriteEntryPayload): Promise<AFSWriteResult>;
+  delete(path: string, opts?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  /** Detect the old server's exact "unsupported batch op" 400 (design T4.2):
+   *  ONLY this text trips the per-instance fallback memory. */
+  private checkBatchUnsupported;
+  private restoreBatchResults;
+  /**
+   * One wire envelope per call — entries in the CORE batch shape
+   * (`AFSBatchWriteEntry`: `content.content` bytes + `options.ifMatch` /
+   * `options.meta` provenance), paths fragment-relative.
+   */
+  batchWrite(entries: AFSBatchWriteEntry[]): Promise<RpcBatchResult>;
+  /** Core-shaped delete entries (`options.meta.{ifMatch,deviceId,mtime}`). */
+  batchDelete(entries: AFSBatchDeleteEntry[]): Promise<RpcBatchResult>;
+  /** Entries are absolute wire paths already (e.g. "/.objects/{cid}" reads). */
+  batchRead(entries: Array<{
+    path: string;
+    optional?: boolean;
+  }>): Promise<RpcBatchResult>;
+  /**
+   * Probe whether the server's `/user` space advertises grant capability
+   * (P2 T2.5). Reads the `.actions` catalogue and checks the prepare-upload
+   * entry's `meta.grantCapability`. `false` on Node (fallback-only) or an old
+   * server with no upload actions → the engine stays on batchWrite.
+   */
+  uploadGrantCapability(): Promise<boolean>;
+  /** Run a `/user/.actions/<name>` exec. Throws `BatchUnsupportedError` when the
+   *  server lacks the action (old server) so the engine falls back. */
+  private execAction;
+  prepareUpload(entries: PrepareUploadEntryInput[]): Promise<PrepareUploadResult>;
+  commitUpload(sessionId: string, entries: CommitUploadEntryInput[]): Promise<RpcBatchResult>;
+  /** Abort a prepared session (staged objects → GC). No TS engine call site yet
+   *  — the engine bails via BatchUnsupportedError on grant loss; exposed for
+   *  protocol parity (Swift mirror) + a future P4 abort-on-timeout path. */
+  abortUpload(sessionId: string): Promise<void>;
+  /** Out-of-band PUT of object bytes via a presigned grant. Returns the HTTP
+   *  status (commit-after-200: the engine only commits entries that got 200). */
+  uploadObject(grant: UploadGrant, bytes: Uint8Array): Promise<number>;
+  /**
+   * Probe whether the server's `/user` space advertises GET-grant capability
+   * (P2 T2.4). Reads the `.actions` catalogue and checks the prepare-download
+   * entry's INDEPENDENT `meta.downloadGrantCapability` (NOT the upload
+   * `grantCapability`). `false` on Node (fallback-only) or an old server → the
+   * engine stays on batchRead.
+   */
+  downloadGrantCapability(): Promise<boolean>;
+  /** Run `prepare-download` — mints GET grants for the referenced cids. Throws
+   *  `BatchUnsupportedError` when the server lacks the action (old server). */
+  prepareDownload(entries: PrepareDownloadEntryInput[]): Promise<PrepareDownloadResult>;
+  /**
+   * Out-of-band GET of object bytes via a presigned grant (content leaves R2
+   * directly — never through the Worker / base64). Returns the raw bytes on
+   * 200. A 401/403 means the grant was rejected (token lacks GetObject / bad
+   * signature) → throws {@link DownloadForbiddenError} so the engine flips the
+   * whole session to batchRead (runtime fallback-on-403, §7.3). Any other
+   * non-2xx (404 dangling / 5xx) throws a generic Error — the engine leaves the
+   * cid unfilled so the existing missing-object path handles it.
+   */
+  downloadObject(grant: DownloadGrant): Promise<Uint8Array>;
+}
+/** A minted presigned-PUT grant (mirrors the provider's PresignedPut). */
+interface UploadGrant {
+  kind: "presigned-put";
+  url: string;
+  method: "PUT";
+  signedHeaders: Record<string, string>;
+  expiresAt: string;
+}
+interface PrepareUploadEntryInput {
+  path: string;
+  cid: string;
+  size: number;
+  /**
+   * Path-detected mime (the changelog carries none): drives the server's
+   * `treeEntry.mimeType` AND the text-mime gate for the inline copy a matching
+   * commit entry carries (inline-content-commit §5.3). Belongs on prepare so
+   * the session persists it before commit.
+   */
+  mimeType?: string;
+  ifMatch?: string;
+  deviceId?: string;
+  mtime?: number;
+}
+/**
+ * Commit entries are prepare entries PLUS an optional cid-verified inline text
+ * copy of the bytes (inline-content-commit §5.1/§5.3). Split from
+ * `PrepareUploadEntryInput` so the 2KB×N content rides ONLY the commit leg, not
+ * prepare (the grant-signing step has no use for it). The server text-mime-gates
+ * + digest-pre-verifies the copy before storing it.
+ */
+interface CommitUploadEntryInput extends PrepareUploadEntryInput {
+  content?: string;
+  /**
+   * Application metadata (did-space-metadata G2): app fields (e.g. createdAt)
+   * the commit persists to `entries.metadata`. The server strips
+   * provider-reserved keys + caps the size; not part of the digest (it is
+   * application data, not bytes).
+   */
+  metadata?: Record<string, unknown>;
+}
+interface PreparedUploadEntry {
+  path: string;
+  cid: string;
+  status: string;
+  objectKey: string;
+  checksumSha256: string;
+  grant: UploadGrant | null;
+}
+interface PrepareUploadResult {
+  sessionId: string;
+  expiresAt: string;
+  entries: PreparedUploadEntry[];
+}
+/** A minted presigned-GET grant (mirrors the provider's PresignedGet). */
+interface DownloadGrant {
+  kind: "presigned-get";
+  url: string;
+  method: "GET";
+  signedHeaders: Record<string, string>;
+  expiresAt: string;
+}
+interface PrepareDownloadEntryInput {
+  cid: string;
+  /** Error/log context only — never participates in authorization (§7.2). */
+  path?: string;
+}
+interface PreparedDownloadEntry {
+  cid: string;
+  /** "ok" | "forbidden" | "invalid" (partial-success, §7.2). */
+  status: string;
+  objectKey?: string;
+  grant?: DownloadGrant | null;
+}
+interface PrepareDownloadResult {
+  entries: PreparedDownloadEntry[];
+}
+//#endregion
+export { BatchOverBudgetError, BatchUnsupportedError, CommitUploadEntryInput, DownloadGrant, PrepareDownloadEntryInput, PrepareDownloadResult, PrepareUploadEntryInput, PrepareUploadResult, RpcBatchEntryResult, RpcBatchResult, RpcUserSpaceAFS, RpcUserSpaceAFSOptions, UploadGrant };
+//# sourceMappingURL=remote-afs.d.cts.map

package/dist/remote-afs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-afs.d.cts","names":[],"sources":["../src/remote-afs.ts"],"mappings":"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"}

package/dist/remote-afs.d.mts

@@ -0,0 +1,236 @@
+import { AFSBatchDeleteEntry, AFSBatchWriteEntry, AFSDeleteOptions, AFSDeleteResult, AFSListOptions, AFSListResult, AFSReadResult, AFSWriteEntryPayload, AFSWriteResult } from "@aigne/afs";
+
+//#region src/remote-afs.d.ts
+/** Per-entry batch result restored from a wire `results[i]` (single-op iso). */
+interface RpcBatchEntryResult {
+  path: string;
+  success: boolean;
+  /** Wire `status` verbatim (200/404/409/503/…). */
+  status: number;
+  data?: Record<string, unknown>;
+  error?: string;
+  code?: string;
+  /** Soft miss for `optional: true` batchRead entries. */
+  missing?: boolean;
+  /** Conflict triple — same fields `AFSConflictError` carries. */
+  conflict?: {
+    currentCid: string | null;
+    currentMtime: number | null;
+    currentDeviceId: string | null;
+  };
+}
+interface RpcBatchResult {
+  results: RpcBatchEntryResult[];
+  succeeded: number;
+  failed: number;
+}
+/** Thrown when the server does not support the batch wire ops (old daemon). */
+declare class BatchUnsupportedError extends Error {
+  constructor();
+}
+/**
+ * Envelope-level BATCH_OVER_BUDGET / PAYLOAD_TOO_LARGE — zero entries
+ * executed; the engine halves the chunk and retries (design §7.3). MUST NOT
+ * trip the capability-fallback memory.
+ */
+declare class BatchOverBudgetError extends Error {
+  constructor(message: string);
+}
+interface RpcUserSpaceAFSOptions {
+  /** Base URL of the arc daemon / worker (e.g. "http://127.0.0.1:4900"). */
+  baseUrl: string;
+  /** Bearer token. */
+  token: string;
+  /** Envelope blocklet (the app whose /user fragment is the sync target). */
+  blocklet: string;
+  /** Optional envelope sessionId. */
+  sessionId?: string;
+  /** Extra headers (test seams, tracing). Never logged. */
+  extraHeaders?: Record<string, string>;
+}
+/**
+ * SyncCloudAFS over the afs-rpc wire (`POST /api/afs/rpc`) — the transport
+ * the production daemon/worker actually serve (the legacy `/api/space` REST
+ * server is gone; `RemoteUserSpaceAFS` above survives only for the
+ * export/import CLI against legacy hosts).
+ *
+ * Sync paths are fragment-root-relative; the wire allowlist admits only
+ * `/user/**` mutations, so every path is mapped through `/user` on the way
+ * out and stripped on the way back.
+ *
+ * Batch (P4): `batchWrite`/`batchDelete`/`batchRead` send one wire envelope
+ * each (wire-contract §9) and restore per-entry results to the single-op
+ * error types (`AFSConflictError` with the triple, `BATCH_TAIL_SKIPPED`
+ * passthrough). Capability fallback: the FIRST envelope answered with the
+ * old server's exact `Unsupported op 'batch…'` 400 marks this INSTANCE as
+ * batch-unsupported (`supportsBatch === false`) and throws
+ * {@link BatchUnsupportedError}; the engine then stays on the single-op
+ * path for the rest of the instance's life. Any other 400 (e.g.
+ * BATCH_OVER_BUDGET) does NOT trip the memory.
+ */
+declare class RpcUserSpaceAFS {
+  readonly name = "rpc-user-space";
+  private baseUrl;
+  private token;
+  private blocklet;
+  private sessionId?;
+  private extraHeaders;
+  /** null = unknown (no batch envelope sent yet); set on first evidence. */
+  private batchSupported;
+  constructor(options: RpcUserSpaceAFSOptions);
+  /** Instance-scoped capability memory (per-server, design §7.1). */
+  get supportsBatch(): boolean | null;
+  private wirePath;
+  private stripUser;
+  private rpc;
+  /** Map a non-OK single-op wire response onto the AFS error types. */
+  private throwWireError;
+  /**
+   * 409 → AFSConflictError with the triple. Keyed on `code: "AFS_CONFLICT"`
+   * OR triple-field presence — NEVER the legacy `error === "if_match_failed"`
+   * string (the T4.1 存量 bug: the wire sends the stable code, see
+   * afs-rpc-wire.ts WIRE_ERROR_CODES.conflict; Swift's throwConflict already
+   * keys on the code).
+   */
+  private throwConflict;
+  list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
+  read(path: string): Promise<AFSReadResult>;
+  write(path: string, payload: AFSWriteEntryPayload): Promise<AFSWriteResult>;
+  delete(path: string, opts?: AFSDeleteOptions): Promise<AFSDeleteResult>;
+  /** Detect the old server's exact "unsupported batch op" 400 (design T4.2):
+   *  ONLY this text trips the per-instance fallback memory. */
+  private checkBatchUnsupported;
+  private restoreBatchResults;
+  /**
+   * One wire envelope per call — entries in the CORE batch shape
+   * (`AFSBatchWriteEntry`: `content.content` bytes + `options.ifMatch` /
+   * `options.meta` provenance), paths fragment-relative.
+   */
+  batchWrite(entries: AFSBatchWriteEntry[]): Promise<RpcBatchResult>;
+  /** Core-shaped delete entries (`options.meta.{ifMatch,deviceId,mtime}`). */
+  batchDelete(entries: AFSBatchDeleteEntry[]): Promise<RpcBatchResult>;
+  /** Entries are absolute wire paths already (e.g. "/.objects/{cid}" reads). */
+  batchRead(entries: Array<{
+    path: string;
+    optional?: boolean;
+  }>): Promise<RpcBatchResult>;
+  /**
+   * Probe whether the server's `/user` space advertises grant capability
+   * (P2 T2.5). Reads the `.actions` catalogue and checks the prepare-upload
+   * entry's `meta.grantCapability`. `false` on Node (fallback-only) or an old
+   * server with no upload actions → the engine stays on batchWrite.
+   */
+  uploadGrantCapability(): Promise<boolean>;
+  /** Run a `/user/.actions/<name>` exec. Throws `BatchUnsupportedError` when the
+   *  server lacks the action (old server) so the engine falls back. */
+  private execAction;
+  prepareUpload(entries: PrepareUploadEntryInput[]): Promise<PrepareUploadResult>;
+  commitUpload(sessionId: string, entries: CommitUploadEntryInput[]): Promise<RpcBatchResult>;
+  /** Abort a prepared session (staged objects → GC). No TS engine call site yet
+   *  — the engine bails via BatchUnsupportedError on grant loss; exposed for
+   *  protocol parity (Swift mirror) + a future P4 abort-on-timeout path. */
+  abortUpload(sessionId: string): Promise<void>;
+  /** Out-of-band PUT of object bytes via a presigned grant. Returns the HTTP
+   *  status (commit-after-200: the engine only commits entries that got 200). */
+  uploadObject(grant: UploadGrant, bytes: Uint8Array): Promise<number>;
+  /**
+   * Probe whether the server's `/user` space advertises GET-grant capability
+   * (P2 T2.4). Reads the `.actions` catalogue and checks the prepare-download
+   * entry's INDEPENDENT `meta.downloadGrantCapability` (NOT the upload
+   * `grantCapability`). `false` on Node (fallback-only) or an old server → the
+   * engine stays on batchRead.
+   */
+  downloadGrantCapability(): Promise<boolean>;
+  /** Run `prepare-download` — mints GET grants for the referenced cids. Throws
+   *  `BatchUnsupportedError` when the server lacks the action (old server). */
+  prepareDownload(entries: PrepareDownloadEntryInput[]): Promise<PrepareDownloadResult>;
+  /**
+   * Out-of-band GET of object bytes via a presigned grant (content leaves R2
+   * directly — never through the Worker / base64). Returns the raw bytes on
+   * 200. A 401/403 means the grant was rejected (token lacks GetObject / bad
+   * signature) → throws {@link DownloadForbiddenError} so the engine flips the
+   * whole session to batchRead (runtime fallback-on-403, §7.3). Any other
+   * non-2xx (404 dangling / 5xx) throws a generic Error — the engine leaves the
+   * cid unfilled so the existing missing-object path handles it.
+   */
+  downloadObject(grant: DownloadGrant): Promise<Uint8Array>;
+}
+/** A minted presigned-PUT grant (mirrors the provider's PresignedPut). */
+interface UploadGrant {
+  kind: "presigned-put";
+  url: string;
+  method: "PUT";
+  signedHeaders: Record<string, string>;
+  expiresAt: string;
+}
+interface PrepareUploadEntryInput {
+  path: string;
+  cid: string;
+  size: number;
+  /**
+   * Path-detected mime (the changelog carries none): drives the server's
+   * `treeEntry.mimeType` AND the text-mime gate for the inline copy a matching
+   * commit entry carries (inline-content-commit §5.3). Belongs on prepare so
+   * the session persists it before commit.
+   */
+  mimeType?: string;
+  ifMatch?: string;
+  deviceId?: string;
+  mtime?: number;
+}
+/**
+ * Commit entries are prepare entries PLUS an optional cid-verified inline text
+ * copy of the bytes (inline-content-commit §5.1/§5.3). Split from
+ * `PrepareUploadEntryInput` so the 2KB×N content rides ONLY the commit leg, not
+ * prepare (the grant-signing step has no use for it). The server text-mime-gates
+ * + digest-pre-verifies the copy before storing it.
+ */
+interface CommitUploadEntryInput extends PrepareUploadEntryInput {
+  content?: string;
+  /**
+   * Application metadata (did-space-metadata G2): app fields (e.g. createdAt)
+   * the commit persists to `entries.metadata`. The server strips
+   * provider-reserved keys + caps the size; not part of the digest (it is
+   * application data, not bytes).
+   */
+  metadata?: Record<string, unknown>;
+}
+interface PreparedUploadEntry {
+  path: string;
+  cid: string;
+  status: string;
+  objectKey: string;
+  checksumSha256: string;
+  grant: UploadGrant | null;
+}
+interface PrepareUploadResult {
+  sessionId: string;
+  expiresAt: string;
+  entries: PreparedUploadEntry[];
+}
+/** A minted presigned-GET grant (mirrors the provider's PresignedGet). */
+interface DownloadGrant {
+  kind: "presigned-get";
+  url: string;
+  method: "GET";
+  signedHeaders: Record<string, string>;
+  expiresAt: string;
+}
+interface PrepareDownloadEntryInput {
+  cid: string;
+  /** Error/log context only — never participates in authorization (§7.2). */
+  path?: string;
+}
+interface PreparedDownloadEntry {
+  cid: string;
+  /** "ok" | "forbidden" | "invalid" (partial-success, §7.2). */
+  status: string;
+  objectKey?: string;
+  grant?: DownloadGrant | null;
+}
+interface PrepareDownloadResult {
+  entries: PreparedDownloadEntry[];
+}
+//#endregion
+export { BatchOverBudgetError, BatchUnsupportedError, CommitUploadEntryInput, DownloadGrant, PrepareDownloadEntryInput, PrepareDownloadResult, PrepareUploadEntryInput, PrepareUploadResult, RpcBatchEntryResult, RpcBatchResult, RpcUserSpaceAFS, RpcUserSpaceAFSOptions, UploadGrant };
+//# sourceMappingURL=remote-afs.d.mts.map

package/dist/remote-afs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-afs.d.mts","names":[],"sources":["../src/remote-afs.ts"],"mappings":"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"}