@bsv/overlay 2.3.0 → 2.6.1

package/dist/cjs/src/storage/mongo/MongoPayloadStore.d.ts

@@ -0,0 +1,134 @@
+import { type ClientSession, type Db } from 'mongodb';
+import { type MongoChainScope } from './MongoSchema.js';
+/** Content types intentionally do not encode a caller's ownership domain. */
+export type MongoPayloadKind = 'raw-transaction' | 'merkle-path' | 'beef-manifest' | 'locking-script' | 'outbox-data';
+export type MongoPayloadReferenceOwnerKind = 'transaction' | 'applied-history' | 'output' | 'gasp-graph' | 'gasp-node' | 'basm-job' | 'lookup-outbox' | 'propagation-outbox' | 'manifest' | 'pin';
+export interface MongoPayloadInput {
+    kind: MongoPayloadKind;
+    /** SHA-256 of the canonical bytes, provided before upload to obtain a fenced reservation. */
+    digest: string;
+    bytes: AsyncIterable<Uint8Array>;
+    /** Canonical decimal uint64. The stream must contain exactly this many bytes. */
+    byteLength: string;
+    /** Required when the caller has already derived the raw transaction identity. */
+    txid?: string;
+    signal?: AbortSignal;
+}
+export interface MongoPayloadRef {
+    kind: MongoPayloadKind;
+    digest: string;
+    byteLength: string;
+    /** Bitcoin display-order txid, only for raw transaction payloads. */
+    txid?: string;
+}
+export interface MongoPayloadReference {
+    scope: MongoChainScope & {
+        nodeId: string;
+    };
+    payload: Pick<MongoPayloadRef, 'kind' | 'digest'>;
+    ownerKind: MongoPayloadReferenceOwnerKind;
+    ownerId: string;
+    slot: string;
+    /** Explicit pins are the sole reference class permitted to expire. */
+    expiresAt?: Date;
+}
+/** A manifest is an ordered list of independent content-addressed components. */
+export interface MongoManifestComponent {
+    manifestId: string;
+    ordinal: string;
+    kind: MongoPayloadKind;
+    payload: Pick<MongoPayloadRef, 'kind' | 'digest'>;
+}
+export interface MongoPayloadStoreOptions {
+    /** Kept deliberately far below Mongo's document cap. */
+    inlineCeilingBytes?: number;
+    /** A GridFS chunk must remain below the BSON document cap with ample overhead. */
+    gridFsChunkBytes?: number;
+    uploadLeaseMs?: number;
+    /** Application-level byte bound; BSON/GridFS are not an admission resource limit. */
+    maxPayloadBytes?: bigint;
+    now?: () => Date;
+    /** Narrow I/O seam used only to exercise crash boundaries. */
+    hooks?: Partial<Record<'afterGridFsUploaded' | 'afterGridFsPublished' | 'beforeReadyCas' | 'afterDeleteClaim', () => Promise<void> | void>>;
+}
+/** Per-operation cancellation/deadline controls supplied by the admission body. */
+export interface MongoPayloadOperationOptions {
+    timeoutMS?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Content-addressed blob primitives for the Mongo adapter. The store deliberately
+ * has no Engine/Storage methods: S03 combines its reference operations with the
+ * owner record in an admission transaction.
+ */
+export declare class MongoPayloadStore {
+    private readonly db;
+    private readonly options;
+    private readonly inlineCeiling;
+    private readonly gridFsChunkBytes;
+    private readonly uploadLeaseMs;
+    private readonly maxPayloadBytes;
+    private readonly now;
+    private readonly bucket;
+    private readonly scope;
+    private readonly writeConcern;
+    constructor(db: Db, scope: MongoChainScope & {
+        nodeId: string;
+    }, options?: MongoPayloadStoreOptions);
+    read(payload: Pick<MongoPayloadRef, 'kind' | 'digest'>, range?: {
+        offset: string;
+        byteLength: string;
+    }): Promise<Uint8Array>;
+    publish(input: MongoPayloadInput): Promise<MongoPayloadRef>;
+    /** Must be called in the same transaction that creates the referenced owner record. */
+    addReference(session: ClientSession, reference: MongoPayloadReference, operation?: MongoPayloadOperationOptions): Promise<void>;
+    /**
+     * Refreshes an existing pin's expiry when the same slot is re-added: an
+     * expired pin is reactivated with the caller's new expiry, and a still-live
+     * pin may only be extended, never silently shortened. Called only after the
+     * caller's {_id: payloadId, state: 'ready'} CAS has already matched in this
+     * transaction, so this stays serialized against a concurrent GC claim.
+     */
+    private refreshPinExpiry;
+    /** Must be called in the transaction that releases the owner record's payload obligation. */
+    releaseReference(session: ClientSession, reference: MongoPayloadReference, operation?: MongoPayloadOperationOptions): Promise<void>;
+    /**
+     * Creates one bounded manifest component and its durable pin in one caller
+     * transaction. S03 can combine this with its manifest owner record; this
+     * method does not parse or reconstruct BEEF.
+     */
+    addManifestComponent(session: ClientSession, component: MongoManifestComponent): Promise<void>;
+    /** Claims logical deletion inside a caller transaction; physical deletion resumes outside it. */
+    claimGarbage(session: ClientSession, payload: Pick<MongoPayloadRef, 'kind' | 'digest'>, operation?: MongoPayloadOperationOptions): Promise<boolean>;
+    /** Safe to retry after process death. It only deletes the file named by the deleting record. */
+    finishGarbage(payload: Pick<MongoPayloadRef, 'kind' | 'digest'>): Promise<boolean>;
+    /** Recovery may retain content; it never guesses that a missing external owner is disposable. */
+    recoverUploads(): Promise<void>;
+    private completeUpload;
+    private assertStreamedPayload;
+    private stageGridFsUpload;
+    private abandonUpload;
+    private recoverStaleUpload;
+    private reserveUpload;
+    private tryClaimUpload;
+    private streamInput;
+    private consumePayloadChunk;
+    private spillInlineToGridFs;
+    private finishPayloadUpload;
+    private fitsInline;
+    private retireOwnedFile;
+    private readBytes;
+    private verifyGridFs;
+    private refFor;
+    private payloadId;
+    private validateInput;
+    private validateReference;
+    private assertTransaction;
+    private assertOperation;
+    private nextWithAbort;
+    private awaitAbort;
+    private raceAbort;
+    private throwIfAborted;
+    private isUint64;
+}
+//# sourceMappingURL=MongoPayloadStore.d.ts.map

package/dist/cjs/src/storage/mongo/MongoPayloadStore.d.ts.map

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