@lacrous/omnicloud 0.2.26 → 0.2.28

package/dist/index.d.cts

@@ -1106,6 +1106,8 @@ interface StorageUploadInput {
     size?: number;
     /** SHA-256 of the spooled bytes, computed while they were written. Required with `path`. */
     sha256?: string;
+    /** Message caption that identifies this upload, so a later search can find it. */
+    caption?: string;
 }
 interface StorageHealth {
     /** Reachable and usable. */
@@ -1137,6 +1139,12 @@ interface StorageProvider {
      * the store and stop once `limit` objects are returned.
      */
     listObjects(limit: number): Promise<StoredObject[]>;
+    /**
+     * Finds stored objects whose content hash and size match, read-only. Used to
+     * recover an upload whose outcome was unknown. Providers that cannot search
+     * omit it, and the caller then treats the outcome as unresolved.
+     */
+    findByCaption?(caption: string, size: number): Promise<StoredObject[]>;
     /** Validates that the backing store is reachable and usable. */
     healthCheck(): Promise<StorageHealth>;
 }
@@ -1186,6 +1194,8 @@ declare class StorageEngine {
     exists(ref: StoredRef): Promise<boolean>;
     /** Read-only listing of stored objects, for reconciliation. Never modifies anything. */
     list(limit: number): Promise<StoredObject[]>;
+    /** Read-only search for stored objects with this content hash and size. */
+    findByCaption(caption: string, size: number): Promise<StoredObject[] | null>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     health(): Promise<StorageHealth>;
     verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
@@ -1294,6 +1304,13 @@ declare class FileService {
      * an operation whose object was already stored is committed without uploading.
      */
     private uploadOnce;
+    /**
+     * Resolves an operation whose Telegram outcome is unknown. The channel is searched
+     * for the object by its content hash and size. Exactly one match is adopted, zero
+     * matches means nothing was stored so the upload is sent again, and anything
+     * ambiguous stays UNKNOWN so that no duplicate is written.
+     */
+    private resolveUnknown;
     /**
      * Follows an operation another request is driving, for a bounded time. Returns
      * the finished file if the winner completes, or the stored object's commit if
@@ -1631,6 +1648,11 @@ declare class TelegramStorageProvider implements StorageProvider {
      * service messages are skipped. Nothing is modified.
      */
     listObjects(limit: number): Promise<StoredObject[]>;
+    /**
+     * Finds stored documents whose caption equals the given caption and whose size
+     * matches. Used to recover an upload whose outcome was unknown.
+     */
+    findByCaption(caption: string, size: number): Promise<StoredObject[]>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     /**
      * Validates that the client is connected and the storage channel is

package/dist/index.d.ts

@@ -1106,6 +1106,8 @@ interface StorageUploadInput {
     size?: number;
     /** SHA-256 of the spooled bytes, computed while they were written. Required with `path`. */
     sha256?: string;
+    /** Message caption that identifies this upload, so a later search can find it. */
+    caption?: string;
 }
 interface StorageHealth {
     /** Reachable and usable. */
@@ -1137,6 +1139,12 @@ interface StorageProvider {
      * the store and stop once `limit` objects are returned.
      */
     listObjects(limit: number): Promise<StoredObject[]>;
+    /**
+     * Finds stored objects whose content hash and size match, read-only. Used to
+     * recover an upload whose outcome was unknown. Providers that cannot search
+     * omit it, and the caller then treats the outcome as unresolved.
+     */
+    findByCaption?(caption: string, size: number): Promise<StoredObject[]>;
     /** Validates that the backing store is reachable and usable. */
     healthCheck(): Promise<StorageHealth>;
 }
@@ -1186,6 +1194,8 @@ declare class StorageEngine {
     exists(ref: StoredRef): Promise<boolean>;
     /** Read-only listing of stored objects, for reconciliation. Never modifies anything. */
     list(limit: number): Promise<StoredObject[]>;
+    /** Read-only search for stored objects with this content hash and size. */
+    findByCaption(caption: string, size: number): Promise<StoredObject[] | null>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     health(): Promise<StorageHealth>;
     verifyIntegrity(data: Buffer, expectedSha256: string): Promise<boolean>;
@@ -1294,6 +1304,13 @@ declare class FileService {
      * an operation whose object was already stored is committed without uploading.
      */
     private uploadOnce;
+    /**
+     * Resolves an operation whose Telegram outcome is unknown. The channel is searched
+     * for the object by its content hash and size. Exactly one match is adopted, zero
+     * matches means nothing was stored so the upload is sent again, and anything
+     * ambiguous stays UNKNOWN so that no duplicate is written.
+     */
+    private resolveUnknown;
     /**
      * Follows an operation another request is driving, for a bounded time. Returns
      * the finished file if the winner completes, or the stored object's commit if
@@ -1631,6 +1648,11 @@ declare class TelegramStorageProvider implements StorageProvider {
      * service messages are skipped. Nothing is modified.
      */
     listObjects(limit: number): Promise<StoredObject[]>;
+    /**
+     * Finds stored documents whose caption equals the given caption and whose size
+     * matches. Used to recover an upload whose outcome was unknown.
+     */
+    findByCaption(caption: string, size: number): Promise<StoredObject[]>;
     stat(ref: StoredRef): Promise<StoredObject | null>;
     /**
      * Validates that the client is connected and the storage channel is

package/dist/index.js

@@ -1219,6 +1219,15 @@ var StorageEngine = class {
       throw mapProviderError("Storage listing failed", error);
     }
   }
+  /** Read-only search for stored objects with this content hash and size. */
+  async findByCaption(caption, size) {
+    if (!this.provider.findByCaption) return null;
+    try {
+      return await this.provider.findByCaption(caption, size);
+    } catch (error) {
+      throw mapProviderError("Storage lookup failed", error);
+    }
+  }
   async stat(ref) {
     try {
       return await this.provider.stat(ref);
@@ -1437,6 +1446,15 @@ function uploadRequestFingerprint(input) {
 }
 
 // ../core/src/services/file-service.ts
+function contentSha256(input) {
+  return input.spooled?.sha256 ?? sha256Hex(input.data ?? Buffer.alloc(0));
+}
+function uploadCaption(sha256, operationId) {
+  return `${sha256}:${operationId}`;
+}
+function contentSize(input) {
+  return input.spooled?.size ?? input.data?.byteLength ?? 0;
+}
 function connectionCausedFailure(error) {
   if (error instanceof TelegramConnectionError) return true;
   if (error instanceof UploadFailedError) {
@@ -1494,6 +1512,9 @@ var FileService = class {
     if (op?.status === "UPLOADING" && op.telegramMessageId !== null) {
       return this.commitStoredObject(userId, input, operations, op);
     }
+    if (op?.status === "UNKNOWN") {
+      return this.resolveUnknown(userId, input, operations, op);
+    }
     if (!op) {
       try {
         op = await operations.create({ userId, operationId, requestFingerprint: fingerprint });
@@ -1512,6 +1533,7 @@ var FileService = class {
     }
     try {
       const record = await this.performUpload(userId, input, {
+        caption: uploadCaption(contentSha256(input), op.operationId),
         onStored: async (stored) => {
           await operations.update(op.id, { telegramMessageId: Number(stored.messageId) });
           await operations.claim(op.id, "UPLOADING", "COMMITTING");
@@ -1523,11 +1545,54 @@ var FileService = class {
       const status = connectionCausedFailure(error) ? "UNKNOWN" : "FAILED";
       await operations.update(op.id, {
         status,
+        sha256: contentSha256(input),
+        size: contentSize(input),
         error: error instanceof Error ? error.message.slice(0, 200) : "upload failed"
       });
       throw error;
     }
   }
+  /**
+   * Resolves an operation whose Telegram outcome is unknown. The channel is searched
+   * for the object by its content hash and size. Exactly one match is adopted, zero
+   * matches means nothing was stored so the upload is sent again, and anything
+   * ambiguous stays UNKNOWN so that no duplicate is written.
+   */
+  async resolveUnknown(userId, input, operations, op) {
+    if (op.sha256 === null || op.size === null) {
+      throw new ConflictError(
+        "This upload's outcome is unknown and cannot be checked automatically. Ask an administrator to reconcile it."
+      );
+    }
+    const engine = await this.engineFor(userId);
+    const matches = await engine.findByCaption(uploadCaption(op.sha256, op.operationId), op.size);
+    if (matches === null) {
+      throw new ConflictError(
+        "This upload's outcome is unknown and the storage backend cannot search for it."
+      );
+    }
+    if (matches.length > 1) {
+      throw new ConflictError(
+        "This upload's outcome is unknown and more than one matching object exists. Nothing was written."
+      );
+    }
+    if (matches.length === 1) {
+      const stored = matches[0];
+      await operations.update(op.id, { telegramMessageId: Number(stored.messageId) });
+      await operations.claim(op.id, "UNKNOWN", "COMMITTING");
+      const record = await this.commitRecord(userId, input, {
+        name: sanitizeFileName(input.name),
+        mimeType: mimeFromFilename(sanitizeFileName(input.name)),
+        size: op.size,
+        sha256: op.sha256,
+        telegramMessageId: Number(stored.messageId)
+      });
+      await operations.update(op.id, { status: "COMPLETED", fileId: record.id });
+      return record;
+    }
+    await operations.claim(op.id, "UNKNOWN", "FAILED");
+    return this.uploadOnce(userId, input, op.operationId, operations);
+  }
   /**
    * Follows an operation another request is driving, for a bounded time. Returns
    * the finished file if the winner completes, or the stored object's commit if
@@ -1605,8 +1670,9 @@ var FileService = class {
         mimeType,
         path: input.spooled.path,
         size: input.spooled.size,
-        sha256: input.spooled.sha256
-      } : { name, mimeType, data: input.data },
+        sha256: input.spooled.sha256,
+        caption: hooks.caption
+      } : { name, mimeType, data: input.data, caption: hooks.caption },
       control
     );
     await hooks.onStored?.(stored);
@@ -2974,6 +3040,7 @@ var TelegramStorageProvider = class {
         file,
         forceDocument: true,
         workers: 1,
+        caption: input.caption,
         // Surface transport-level progress to the caller. GramJS reports a
         // 0..1 fraction. `isCanceled` lets us abort an in-flight upload.
         progressCallback: Object.assign(
@@ -3131,6 +3198,41 @@ var TelegramStorageProvider = class {
     }
     return objects;
   }
+  /**
+   * Finds stored documents whose caption equals the given caption and whose size
+   * matches. Used to recover an upload whose outcome was unknown.
+   */
+  async findByCaption(caption, size) {
+    const matches = [];
+    try {
+      for await (const message of this.client.iterMessages(this.peer, {
+        search: caption,
+        limit: 20
+      })) {
+        if (!(message instanceof Api2.Message)) continue;
+        if (message.message !== caption) continue;
+        const document = message.document;
+        if (!(document instanceof Api2.Document)) continue;
+        if (Number(document.size.toString()) !== size) continue;
+        let fileName;
+        for (const attr of document.attributes) {
+          if (attr instanceof Api2.DocumentAttributeFilename) {
+            fileName = attr.fileName;
+            break;
+          }
+        }
+        matches.push({
+          messageId: message.id.toString(),
+          name: fileName ?? "file",
+          size,
+          mimeType: document.mimeType
+        });
+      }
+    } catch (error) {
+      throw mapTelegramError(error, "Telegram lookup failed");
+    }
+    return matches;
+  }
   async stat(ref) {
     const message = await this.getMessage(ref.messageId);
     if (!message?.media) return null;