@hozon/store-blob 0.1.1 → 0.2.1

package/README.md

@@ -28,15 +28,22 @@ Entries map integer flags to booleans and expose camelCase fields.
 Encryption and key IDs are optional metadata that the store does not interpret.
 Repeated entry and manifest inserts preserve existing rows.
 
-For a known remote entry, `beginTransfer` records its manifest and sets its state to `partial`.
-Retries with the same chunk size preserve manifest digests and progress.
+For a known remote entry, `beginTransfer({ blobID, chunkSize, chunks, stagingID })` records its manifest, sets its state to `partial`, and records a transfer session for `stagingID`.
+Retries with the same chunk size preserve manifest digests. Progress is preserved only while `stagingID` matches the session; a different `stagingID` clears it.
+`getTransfer`, `getTransferByStagingID`, and `touchTransfer` read and refresh the session.
 Changing chunk size while a manifest exists rejects with `Cannot change chunk size for blob <blobID>: manifest already exists`.
 Record each verified chunk with `recordTransferChunk`, then call `finalizeTransfer` when all chunks are present.
-Finalisation preserves the manifest, clears transfer progress, and sets the entry state to `local`.
+Finalisation preserves the manifest, clears transfer progress and the session, and sets the entry state to `local`.
 `beginTransfer`, `recordTransferChunk`, and `finalizeTransfer` reject absent entries with `Blob entry <blobID> not found`.
 `recordTransferChunk` rejects unknown manifest indexes with `Blob chunk <blobID> at index <index> not found`.
 Finalisation rejects missing chunks with `Cannot finalize transfer <blobID>: <count> chunk(s) missing`.
-`deleteEntry` removes the entry, manifest, and transfer progress together.
+`deleteEntry` removes the entry, manifest, transfer progress, and session together.
+Entries carry an optional `contentType` (`string | null`).
+`listEntries({ limit, cursor })` pages entries by `(createdAt, blobID)` with an opaque cursor; `limit` is 1 to 1000.
+`promoteEntry(entry, chunks)` atomically replaces an entry's manifest and marks it `local`, keeping `pinned` and `createdAt` and clearing transfers and session.
+`fillContentType(blobID, contentType)` sets the content type only when the stored one is null.
+`resetTransfer(blobID)` atomically drops the session, progress, and manifest and sets the entry to `remote-only`.
+The `1-sessions` migration resets existing `partial` entries to `remote-only`, dropping their manifests; this is not reversible.
 Manifest chunks reference entries, and transfer rows reference manifest chunks, with cascading deletion preventing orphan progress.
 
 Tables follow the database's configured prefix, which defaults to `hozon`.

package/lib/api.js

@@ -1,4 +1,26 @@
 import { chunk, withStoreTransaction } from '@hozon/db';
+import { b64uFromUTF, b64uToUTF } from '@sozai/codec';
+import { InvalidCursorError } from './errors.js';
+function encodeCursor(createdAt, blobID) {
+    return b64uFromUTF(JSON.stringify([
+        createdAt,
+        blobID
+    ]));
+}
+function decodeCursor(cursor) {
+    try {
+        const value = JSON.parse(b64uToUTF(cursor));
+        if (Array.isArray(value) && value.length === 2 && typeof value[0] === 'number' && Number.isFinite(value[0]) && typeof value[1] === 'string') {
+            return [
+                value[0],
+                value[1]
+            ];
+        }
+    } catch  {
+    // fall through
+    }
+    throw new InvalidCursorError();
+}
 export function createBlobStoreAPI(db, adapter) {
     async function insertManifest(trx, blobID, chunks) {
         const rows = chunks.map((item)=>({
@@ -25,7 +47,8 @@ export function createBlobStoreAPI(db, adapter) {
                     chunk_size: entry.chunkSize,
                     state: entry.state,
                     pinned: entry.pinned ? 1 : 0,
-                    created_at: entry.createdAt
+                    created_at: entry.createdAt,
+                    content_type: entry.contentType ?? null
                 }).onConflict((oc)=>oc.column('blob_id').doNothing()).execute();
                 await insertManifest(trx, entry.blobID, chunks);
             });
@@ -40,7 +63,8 @@ export function createBlobStoreAPI(db, adapter) {
                 chunkSize: row.chunk_size,
                 state: row.state,
                 pinned: row.pinned === 1,
-                createdAt: row.created_at
+                createdAt: row.created_at,
+                contentType: row.content_type
             };
         },
         async getChunkDigests (blobID) {
@@ -54,12 +78,13 @@ export function createBlobStoreAPI(db, adapter) {
         },
         async deleteEntry (blobID) {
             await withStoreTransaction(db, async (trx)=>{
+                await trx.deleteFrom('blob_transfer_sessions').where('blob_id', '=', blobID).execute();
                 await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
                 await trx.deleteFrom('blob_chunks').where('blob_id', '=', blobID).execute();
                 await trx.deleteFrom('blob_entries').where('blob_id', '=', blobID).execute();
             });
         },
-        async beginTransfer (blobID, chunkSize, chunks) {
+        async beginTransfer ({ blobID, chunkSize, chunks, stagingID }) {
             await withStoreTransaction(db, async (trx)=>{
                 let query = trx.selectFrom('blob_entries').select([
                     'blob_id',
@@ -79,6 +104,20 @@ export function createBlobStoreAPI(db, adapter) {
                     state: 'partial'
                 }).where('blob_id', '=', blobID).execute();
                 await insertManifest(trx, blobID, chunks);
+                const existing = await trx.selectFrom('blob_transfer_sessions').select('staging_id').where('blob_id', '=', blobID).executeTakeFirst();
+                // A new staging area holds none of the previous session's chunks.
+                if (existing !== undefined && existing.staging_id !== stagingID) {
+                    await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
+                }
+                const updatedAt = Date.now();
+                await trx.insertInto('blob_transfer_sessions').values({
+                    blob_id: blobID,
+                    staging_id: stagingID,
+                    updated_at: updatedAt
+                }).onConflict((oc)=>oc.column('blob_id').doUpdateSet({
+                        staging_id: stagingID,
+                        updated_at: updatedAt
+                    })).execute();
             });
         },
         async recordTransferChunk (blobID, index) {
@@ -94,6 +133,9 @@ export function createBlobStoreAPI(db, adapter) {
                         'blob_id',
                         'index'
                     ]).doNothing()).execute();
+                await trx.updateTable('blob_transfer_sessions').set({
+                    updated_at: Date.now()
+                }).where('blob_id', '=', blobID).execute();
             });
         },
         async getPresentChunkIndexes (blobID) {
@@ -115,7 +157,116 @@ export function createBlobStoreAPI(db, adapter) {
                     state: 'local'
                 }).where('blob_id', '=', blobID).execute();
                 await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_transfer_sessions').where('blob_id', '=', blobID).execute();
+            });
+        },
+        async getTransfer (blobID) {
+            const session = await db.selectFrom('blob_transfer_sessions').select([
+                'staging_id',
+                'updated_at'
+            ]).where('blob_id', '=', blobID).executeTakeFirst();
+            if (session === undefined) return null;
+            const rows = await db.selectFrom('blob_transfers').select('index').where('blob_id', '=', blobID).orderBy('index', 'asc').execute();
+            return {
+                stagingID: session.staging_id,
+                updatedAt: session.updated_at,
+                presentChunks: rows.map((row)=>row.index)
+            };
+        },
+        async getTransferByStagingID (stagingID) {
+            const row = await db.selectFrom('blob_transfer_sessions').select([
+                'blob_id',
+                'updated_at'
+            ]).where('staging_id', '=', stagingID).executeTakeFirst();
+            return row === undefined ? null : {
+                blobID: row.blob_id,
+                updatedAt: row.updated_at
+            };
+        },
+        async touchTransfer (blobID) {
+            await db.updateTable('blob_transfer_sessions').set({
+                updated_at: Date.now()
+            }).where('blob_id', '=', blobID).execute();
+        },
+        async listEntries (params) {
+            const { limit, cursor } = params;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+                throw new Error('Invalid limit: must be an integer between 1 and 1000');
+            }
+            let query = db.selectFrom('blob_entries').selectAll();
+            if (cursor !== undefined) {
+                const [createdAt, blobID] = decodeCursor(cursor);
+                query = query.where((eb)=>eb.or([
+                        eb('created_at', '>', createdAt),
+                        eb.and([
+                            eb('created_at', '=', createdAt),
+                            eb('blob_id', '>', blobID)
+                        ])
+                    ]));
+            }
+            const rows = await query.orderBy('created_at', 'asc').orderBy('blob_id', 'asc').limit(limit + 1).execute();
+            const page = rows.slice(0, limit);
+            const entries = page.map((row)=>({
+                    blobID: row.blob_id,
+                    contentLength: row.content_length,
+                    encrypted: row.encrypted === 1,
+                    keyID: row.key_id,
+                    chunkSize: row.chunk_size,
+                    state: row.state,
+                    pinned: row.pinned === 1,
+                    createdAt: row.created_at,
+                    contentType: row.content_type
+                }));
+            const last = page[page.length - 1];
+            const nextCursor = rows.length > limit && last !== undefined ? encodeCursor(last.created_at, last.blob_id) : null;
+            return {
+                entries,
+                nextCursor
+            };
+        },
+        async promoteEntry (entry, chunks) {
+            await withStoreTransaction(db, async (trx)=>{
+                let lock = trx.selectFrom('blob_entries').select('blob_id').where('blob_id', '=', entry.blobID);
+                if (adapter.kind === 'postgres') lock = lock.forUpdate();
+                await lock.executeTakeFirst();
+                const values = {
+                    content_length: entry.contentLength,
+                    encrypted: entry.encrypted ? 1 : 0,
+                    key_id: entry.keyID ?? null,
+                    chunk_size: entry.chunkSize,
+                    state: 'local',
+                    content_type: entry.contentType ?? null
+                };
+                await trx.insertInto('blob_entries').values({
+                    blob_id: entry.blobID,
+                    pinned: entry.pinned ? 1 : 0,
+                    created_at: entry.createdAt,
+                    ...values
+                }).onConflict((oc)=>oc.column('blob_id').doUpdateSet(values)).execute();
+                await trx.deleteFrom('blob_transfer_sessions').where('blob_id', '=', entry.blobID).execute();
+                await trx.deleteFrom('blob_transfers').where('blob_id', '=', entry.blobID).execute();
+                await trx.deleteFrom('blob_chunks').where('blob_id', '=', entry.blobID).execute();
+                await insertManifest(trx, entry.blobID, chunks);
+            });
+        },
+        async resetTransfer (blobID) {
+            await withStoreTransaction(db, async (trx)=>{
+                let lock = trx.selectFrom('blob_entries').select('blob_id').where('blob_id', '=', blobID);
+                if (adapter.kind === 'postgres') lock = lock.forUpdate();
+                const entry = await lock.executeTakeFirst();
+                if (entry === undefined) return;
+                await trx.deleteFrom('blob_transfer_sessions').where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_chunks').where('blob_id', '=', blobID).execute();
+                await trx.updateTable('blob_entries').set({
+                    state: 'remote-only'
+                }).where('blob_id', '=', blobID).execute();
             });
+        },
+        async fillContentType (blobID, contentType) {
+            await db.updateTable('blob_entries').set({
+                content_type: contentType
+            }).where('blob_id', '=', blobID).where('content_type', 'is', null).execute();
         }
     };
 }

package/lib/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class InvalidCursorError extends Error {
+    constructor(options?: ErrorOptions);
+}

package/lib/errors.js

@@ -0,0 +1,6 @@
+export class InvalidCursorError extends Error {
+    constructor(options){
+        super('Invalid cursor', options);
+        this.name = 'InvalidCursorError';
+    }
+}

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export { BLOB_STORE, blobStoreDefinition, getBlobStore } from './definition.js';
-export type { BlobChunkTable, BlobEntryTable, BlobTables, BlobTransferTable } from './tables.js';
-export type { BlobChunkInput, BlobEntry, BlobEntryInput, BlobState, BlobStoreAPI } from './types.js';
+export { InvalidCursorError } from './errors.js';
+export type { BlobChunkTable, BlobEntryTable, BlobTables, BlobTransferSessionTable, BlobTransferTable, } from './tables.js';
+export type { BeginTransferParams, BlobChunkInput, BlobEntry, BlobEntryInput, BlobState, BlobStoreAPI, BlobTransfer, } from './types.js';

package/lib/index.js

@@ -1 +1,2 @@
 export { BLOB_STORE, blobStoreDefinition, getBlobStore } from './definition.js';
+export { InvalidCursorError } from './errors.js';

package/lib/migrations.js

@@ -28,6 +28,29 @@ export function blobStoreMigrations(ctx) {
                 await db.schema.dropTable('blob_chunks').execute();
                 await db.schema.dropTable('blob_entries').execute();
             }
+        },
+        '1-sessions': {
+            async up (db) {
+                await db.schema.alterTable('blob_entries').addColumn('content_type', ctx.types.text).execute();
+                await db.schema.createTable('blob_transfer_sessions').addColumn('blob_id', ctx.types.text, (column)=>column.notNull()).addColumn('staging_id', ctx.types.text, (column)=>column.notNull().unique()).addColumn('updated_at', ctx.types.bigint, (column)=>column.notNull()).addPrimaryKeyConstraint(`${ctx.tablePrefix}_blob_transfer_sessions_pkey`, [
+                    'blob_id'
+                ]).addForeignKeyConstraint(`${ctx.tablePrefix}_blob_transfer_sessions_entry_fkey`, [
+                    'blob_id'
+                ], 'blob_entries', [
+                    'blob_id'
+                ], (constraint)=>constraint.onDelete('cascade')).execute();
+                // Partial entries predate sessions and cannot be resumed: drop their progress.
+                await db.deleteFrom('blob_transfers').where('blob_id', 'in', db.selectFrom('blob_entries').select('blob_id').where('state', '=', 'partial')).execute();
+                await db.deleteFrom('blob_chunks').where('blob_id', 'in', db.selectFrom('blob_entries').select('blob_id').where('state', '=', 'partial')).execute();
+                await db.updateTable('blob_entries').set({
+                    state: 'remote-only'
+                }).where('state', '=', 'partial').execute();
+            },
+            // The backfill (partial entries reset to remote-only, manifests dropped) is not reversible.
+            async down (db) {
+                await db.schema.dropTable('blob_transfer_sessions').execute();
+                await db.schema.alterTable('blob_entries').dropColumn('content_type').execute();
+            }
         }
     };
 }

package/lib/tables.d.ts

@@ -8,6 +8,7 @@ export type BlobEntryTable = {
     state: BlobState;
     pinned: number;
     created_at: number;
+    content_type: string | null;
 };
 export type BlobChunkTable = {
     blob_id: string;
@@ -18,8 +19,14 @@ export type BlobTransferTable = {
     blob_id: string;
     index: number;
 };
+export type BlobTransferSessionTable = {
+    blob_id: string;
+    staging_id: string;
+    updated_at: number;
+};
 export type BlobTables = {
     blob_entries: BlobEntryTable;
     blob_chunks: BlobChunkTable;
     blob_transfers: BlobTransferTable;
+    blob_transfer_sessions: BlobTransferSessionTable;
 };

package/lib/types.d.ts

@@ -8,6 +8,7 @@ export type BlobEntryInput = {
     state: BlobState;
     pinned?: boolean;
     createdAt: number;
+    contentType?: string | null;
 };
 export type BlobChunkInput = {
     index: number;
@@ -22,6 +23,18 @@ export type BlobEntry = {
     state: BlobState;
     pinned: boolean;
     createdAt: number;
+    contentType: string | null;
+};
+export type BeginTransferParams = {
+    blobID: string;
+    chunkSize: number;
+    chunks: Array<BlobChunkInput>;
+    stagingID: string;
+};
+export type BlobTransfer = {
+    stagingID: string;
+    updatedAt: number;
+    presentChunks: Array<number>;
 };
 export type BlobStoreAPI = {
     insertEntry(entry: BlobEntryInput, chunks: Array<BlobChunkInput>): Promise<void>;
@@ -29,8 +42,24 @@ export type BlobStoreAPI = {
     getChunkDigests(blobID: string): Promise<Array<Uint8Array>>;
     setPinned(blobID: string, pinned: boolean): Promise<void>;
     deleteEntry(blobID: string): Promise<void>;
-    beginTransfer(blobID: string, chunkSize: number, chunks: Array<BlobChunkInput>): Promise<void>;
+    beginTransfer(params: BeginTransferParams): Promise<void>;
     recordTransferChunk(blobID: string, index: number): Promise<void>;
     getPresentChunkIndexes(blobID: string): Promise<Array<number>>;
     finalizeTransfer(blobID: string): Promise<void>;
+    getTransfer(blobID: string): Promise<BlobTransfer | null>;
+    getTransferByStagingID(stagingID: string): Promise<{
+        blobID: string;
+        updatedAt: number;
+    } | null>;
+    touchTransfer(blobID: string): Promise<void>;
+    listEntries(params: {
+        limit: number;
+        cursor?: string;
+    }): Promise<{
+        entries: Array<BlobEntry>;
+        nextCursor: string | null;
+    }>;
+    promoteEntry(entry: Omit<BlobEntryInput, 'state'>, chunks: Array<BlobChunkInput>): Promise<void>;
+    resetTransfer(blobID: string): Promise<void>;
+    fillContentType(blobID: string, contentType: string): Promise<void>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hozon/store-blob",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Content-addressed blob metadata and resumable transfer store for Hozon",
   "repository": {
     "type": "git",
@@ -18,13 +18,14 @@
   ],
   "dependencies": {
     "@hozon/adapter": "^0.1.0",
-    "@hozon/db": "^0.2.1"
+    "@hozon/db": "^0.2.3",
+    "@sozai/codec": "^0.4.3"
   },
   "devDependencies": {
     "@hozon/node-sqlite": "^0.1.0",
-    "@types/node": "^26.6.4",
-    "del-cli": "^7.0.0",
-    "vitest": "5.0.3"
+    "@types/node": "^26.6.5",
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.4"
   },
   "publishConfig": {
     "access": "public"