@serve.zone/coremail 1.0.0

package/ts/classes.storage.ts

@@ -0,0 +1,448 @@
+import * as plugins from './plugins.js';
+
+type TCoreMailSha256 = plugins.serveZoneInterfaces.data.TCoreMailSha256;
+
+const digestBuffer = (bufferArg: Uint8Array): TCoreMailSha256 =>
+  plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+    `sha256:${plugins.nodeCrypto.createHash('sha256').update(bufferArg).digest('hex')}`,
+  );
+
+const hashAndBoundStream = (
+  streamArg: ReadableStream<Uint8Array>,
+  maximumBytesArg: number,
+  expectedLengthArg?: number,
+  expectedSha256Arg?: TCoreMailSha256,
+  signalArg?: AbortSignal,
+  idleTimeoutMsArg?: number,
+): {
+  stream: ReadableStream<Uint8Array>;
+  completion: Promise<{ lengthBytes: number; sha256: TCoreMailSha256 }>;
+  cancel: (reasonArg?: unknown) => Promise<void>;
+} => {
+  const hash = plugins.nodeCrypto.createHash('sha256');
+  let lengthBytes = 0;
+  let resolveCompletion!: (valueArg: {
+    lengthBytes: number;
+    sha256: TCoreMailSha256;
+  }) => void;
+  let rejectCompletion!: (errorArg: Error) => void;
+  const completion = new Promise<{
+    lengthBytes: number;
+    sha256: TCoreMailSha256;
+  }>((resolveArg, rejectArg) => {
+    resolveCompletion = resolveArg;
+    rejectCompletion = rejectArg;
+  });
+  const reader = streamArg.getReader();
+  let settled = false;
+  let readerReleased = false;
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  const releaseReader = () => {
+    if (!readerReleased) {
+      try {
+        reader.releaseLock();
+        readerReleased = true;
+      } catch {
+        // A pending read releases the lock after cancellation settles.
+      }
+    }
+  };
+  const cancelReader = async (reasonArg: Error): Promise<void> => {
+    const cancellation = reader.cancel(reasonArg).catch(() => undefined);
+    releaseReader();
+    const timeout = new Promise<void>((resolveArg) => {
+      const timer = setTimeout(resolveArg, 1_000);
+      timer.unref?.();
+      void cancellation.finally(() => clearTimeout(timer));
+    });
+    await Promise.race([cancellation, timeout]);
+    releaseReader();
+    void cancellation.finally(releaseReader);
+  };
+  const settleError = (errorArg: Error) => {
+    if (!settled) {
+      settled = true;
+      rejectCompletion(errorArg);
+    }
+  };
+  const cancel = async (reasonArg?: unknown): Promise<void> => {
+    signalArg?.removeEventListener('abort', onAbort);
+    if (settled) {
+      releaseReader();
+      return;
+    }
+    const error = reasonArg instanceof Error
+      ? reasonArg
+      : new Error('CoreMail transfer was cancelled.');
+    settleError(error);
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    await cancelReader(error);
+  };
+  const onAbort = () => {
+    void cancel(signalArg?.reason);
+  };
+  if (signalArg) {
+    if (signalArg.aborted) {
+      void cancel(signalArg.reason);
+    } else {
+      signalArg.addEventListener('abort', onAbort, { once: true });
+    }
+  }
+  const stream = new ReadableStream<Uint8Array>({
+    async pull(controllerArg) {
+      try {
+        signalArg?.throwIfAborted();
+        if (idleTimeoutMsArg !== undefined) {
+          idleTimer = setTimeout(() => {
+            void cancel(new Error('CoreMail transfer exceeded its idle deadline.'));
+          }, idleTimeoutMsArg);
+          idleTimer.unref?.();
+        }
+        const next = await reader.read();
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          idleTimer = null;
+        }
+        if (!next.done) {
+          if (!(next.value instanceof Uint8Array)) {
+            throw new Error('CoreMail transfer emitted a non-byte chunk.');
+          }
+          lengthBytes += next.value.byteLength;
+          if (lengthBytes > maximumBytesArg) {
+            throw new Error('CoreMail transfer exceeded its byte budget.');
+          }
+          hash.update(next.value);
+          controllerArg.enqueue(next.value);
+          return;
+        }
+        const sha256 = plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+          `sha256:${hash.digest('hex')}`,
+        );
+        if (
+          (expectedLengthArg !== undefined && lengthBytes !== expectedLengthArg)
+          || (expectedSha256Arg !== undefined && sha256 !== expectedSha256Arg)
+        ) {
+          throw new Error('CoreMail object integrity verification failed.');
+        }
+        settled = true;
+        resolveCompletion({ lengthBytes, sha256 });
+        controllerArg.close();
+        signalArg?.removeEventListener('abort', onAbort);
+        releaseReader();
+      } catch (error) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        if (idleTimer) {
+          clearTimeout(idleTimer);
+          idleTimer = null;
+        }
+        settleError(normalized);
+        controllerArg.error(normalized);
+        await cancelReader(normalized);
+        signalArg?.removeEventListener('abort', onAbort);
+      }
+    },
+    async cancel(reasonArg) {
+      signalArg?.removeEventListener('abort', onAbort);
+      await cancel(reasonArg);
+    },
+  });
+  void completion.catch(() => undefined);
+  return {
+    stream,
+    completion,
+    cancel,
+  };
+};
+
+export class CoreMailStorage {
+  public readonly smartBucket: plugins.smartbucket.SmartBucket;
+  public bucket!: plugins.smartbucket.Bucket;
+  private exactUploadCapability?:
+    plugins.smartbucket.IExactUploadCapability;
+  private exactPurgeCapability?:
+    plugins.smartbucket.IExactPathPurgeCapability;
+
+  public constructor(
+    storageDescriptorArg: Record<string, unknown>,
+    public readonly bucketName: string,
+  ) {
+    this.smartBucket = new plugins.smartbucket.SmartBucket(
+      storageDescriptorArg as never,
+    );
+  }
+
+  public async start(): Promise<void> {
+    try {
+      const readiness = await this.smartBucket.checkReadiness(this.bucketName, {
+        timeoutMs: 5_000,
+      });
+      if (!readiness.ready) {
+        throw new Error(`CoreMail object storage is unavailable: ${readiness.reason}`);
+      }
+      this.bucket = await this.smartBucket.getBucketByName(this.bucketName);
+      const exactUpload = await this.bucket.probeExactUploadCapability({
+        signal: AbortSignal.timeout(30_000),
+      });
+      if (!exactUpload.supported) {
+        throw new Error(`CoreMail requires exact object publication: ${exactUpload.reason}`);
+      }
+      this.exactUploadCapability = exactUpload.capability;
+      const exactPurge = await this.bucket.probeExactPathPurgeCapability({
+        signal: AbortSignal.timeout(30_000),
+      });
+      if (!exactPurge.supported) {
+        throw new Error(`CoreMail requires exact object retention: ${exactPurge.reason}`);
+      }
+      this.exactPurgeCapability = exactPurge.capability;
+    } catch (error) {
+      await this.smartBucket.close().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  public async checkReadiness(): Promise<boolean> {
+    const readiness = await this.smartBucket.checkReadiness(this.bucketName, {
+      timeoutMs: 1_500,
+    });
+    return readiness.ready
+      && Boolean(this.exactUploadCapability)
+      && Boolean(this.exactPurgeCapability);
+  }
+
+  public async stop(): Promise<void> {
+    await this.smartBucket.close();
+  }
+
+  public async purgeExact(
+    objectKeyArg: string,
+    signalArg?: AbortSignal,
+  ): Promise<void> {
+    if (
+      !this.exactPurgeCapability
+      || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,1023}$/.test(objectKeyArg)
+      || objectKeyArg.startsWith('/')
+      || objectKeyArg.includes('//')
+      || objectKeyArg.split('/').some((partArg) => partArg === '..')
+    ) {
+      throw new Error('CoreMail exact purge capability or object key is invalid.');
+    }
+    await this.bucket.purgeExactPath({
+      capability: this.exactPurgeCapability,
+      path: objectKeyArg,
+      timeoutMs: 30_000,
+      signal: signalArg,
+    });
+  }
+
+  public async putExact(
+    objectKeyArg: string,
+    streamArg: ReadableStream<Uint8Array>,
+    lengthBytesArg: number,
+    sha256Arg: TCoreMailSha256,
+    contentTypeArg: string,
+    maximumBytesArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<void> {
+    if (!this.exactUploadCapability) {
+      throw new Error('CoreMail exact upload capability is unavailable.');
+    }
+    if (
+      !Number.isSafeInteger(lengthBytesArg)
+      || lengthBytesArg < 0
+      || lengthBytesArg > maximumBytesArg
+    ) {
+      throw new Error('CoreMail exact upload length is outside its byte budget.');
+    }
+    const monitored = hashAndBoundStream(
+      streamArg,
+      maximumBytesArg,
+      lengthBytesArg,
+      sha256Arg,
+      signalArg,
+      plugins.serveZoneInterfaces.data.coreMailLimits.transferIdleTimeoutMs,
+    );
+    let uploadError: unknown;
+    try {
+      await this.bucket.fastPutStreamExact({
+        capability: this.exactUploadCapability,
+        path: objectKeyArg,
+        readableStream: monitored.stream,
+        contentLength: lengthBytesArg,
+        nativeMetadata: {
+          'coremail-sha256': sha256Arg.slice('sha256:'.length),
+        },
+        nativeObjectProperties: {
+          contentType: contentTypeArg,
+        },
+        requestedPartSize: 5 * 1024 * 1024,
+        requestedConcurrency: 2,
+        failureSettlementTimeoutMs: 30_000,
+        signal: signalArg,
+      });
+      await monitored.completion;
+    } catch (error) {
+      uploadError = error;
+      await monitored.cancel(error);
+      await monitored.completion.catch(() => undefined);
+    }
+    if (uploadError) {
+      try {
+        await this.verifyObject(
+          objectKeyArg,
+          lengthBytesArg,
+          sha256Arg,
+          maximumBytesArg,
+          signalArg,
+        );
+        return;
+      } catch {
+        throw uploadError;
+      }
+    }
+    await this.verifyObject(
+      objectKeyArg,
+      lengthBytesArg,
+      sha256Arg,
+      maximumBytesArg,
+      signalArg,
+    );
+  }
+
+  public async putBytesExact(
+    objectKeyArg: string,
+    bytesArg: Uint8Array,
+    contentTypeArg: string,
+    maximumBytesArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<{ lengthBytes: number; sha256: TCoreMailSha256 }> {
+    if (bytesArg.byteLength > maximumBytesArg) {
+      throw new Error('CoreMail object exceeds its byte budget.');
+    }
+    const sha256 = digestBuffer(bytesArg);
+    await this.putExact(
+      objectKeyArg,
+      new ReadableStream<Uint8Array>({
+        start(controllerArg) {
+          controllerArg.enqueue(bytesArg);
+          controllerArg.close();
+        },
+      }),
+      bytesArg.byteLength,
+      sha256,
+      contentTypeArg,
+      maximumBytesArg,
+      signalArg,
+    );
+    return { lengthBytes: bytesArg.byteLength, sha256 };
+  }
+
+  public async getVerifiedStream(
+    objectKeyArg: string,
+    lengthBytesArg: number,
+    sha256Arg: TCoreMailSha256,
+    maximumBytesArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    completion: Promise<{ lengthBytes: number; sha256: TCoreMailSha256 }>;
+    cancel: (reasonArg?: unknown) => Promise<void>;
+  }> {
+    signalArg?.throwIfAborted();
+    const stat = await this.bucket.fastStat({
+      path: objectKeyArg,
+      signal: signalArg,
+    });
+    if (stat.ContentLength !== lengthBytesArg || lengthBytesArg > maximumBytesArg) {
+      throw new Error('CoreMail object length does not match persisted integrity.');
+    }
+    return hashAndBoundStream(
+      await this.bucket.fastGetStream({
+        path: objectKeyArg,
+        signal: signalArg,
+      }, 'webstream') as
+        ReadableStream<Uint8Array>,
+      maximumBytesArg,
+      lengthBytesArg,
+      sha256Arg,
+      signalArg,
+      plugins.serveZoneInterfaces.data.coreMailLimits.transferIdleTimeoutMs,
+    );
+  }
+
+  public async getVerifiedBytes(
+    objectKeyArg: string,
+    lengthBytesArg: number,
+    sha256Arg: TCoreMailSha256,
+    maximumBytesArg: number,
+  ): Promise<Uint8Array> {
+    const verified = await this.getVerifiedStream(
+      objectKeyArg,
+      lengthBytesArg,
+      sha256Arg,
+      maximumBytesArg,
+      AbortSignal.timeout(
+        plugins.serveZoneInterfaces.data.coreMailLimits.transferOverallTimeoutMs,
+      ),
+    );
+    const reader = verified.stream.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+      while (true) {
+        const next = await reader.read();
+        if (next.done) break;
+        chunks.push(next.value);
+        total += next.value.byteLength;
+      }
+      await verified.completion;
+    } finally {
+      await reader.cancel().catch(() => undefined);
+      reader.releaseLock();
+    }
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return result;
+  }
+
+  public async verifyObject(
+    objectKeyArg: string,
+    lengthBytesArg: number,
+    sha256Arg: TCoreMailSha256,
+    maximumBytesArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<void> {
+    signalArg?.throwIfAborted();
+    const verified = await this.getVerifiedStream(
+      objectKeyArg,
+      lengthBytesArg,
+      sha256Arg,
+      maximumBytesArg,
+      signalArg,
+    );
+    const reader = verified.stream.getReader();
+    try {
+      while (!(await reader.read()).done) {
+        signalArg?.throwIfAborted();
+      }
+      await verified.completion;
+    } finally {
+      await reader.cancel().catch(() => undefined);
+      reader.releaseLock();
+    }
+  }
+}
+
+export const createSha256 = (valueArg: Uint8Array | string): TCoreMailSha256 =>
+  plugins.serveZoneInterfaces.data.normalizeCoreMailSha256(
+    `sha256:${plugins.nodeCrypto.createHash('sha256').update(valueArg).digest('hex')}`,
+  );
+
+export const createOpaqueToken = (): string =>
+  plugins.nodeCrypto.randomBytes(32).toString('base64url');