@bgord/bun 1.23.12 → 1.24.0

package/src/image-resizer.adapter.ts

@@ -1,16 +1,12 @@
 // [BUN DEPENDENCY]
 // cspell:ignore Resizer
 import type * as tools from "@bgord/tools";
-import type { FileRenamerPort } from "./file-renamer.port";
-import type { FileWriterPort } from "./file-writer.port";
+import type { AtomicFileWriterPort } from "./atomic-file-writer.port";
 import type { ImageSupportedType } from "./image.types";
 import type { ImageResizerPort, ImageResizerStrategy } from "./image-resizer.port";
-import type { NonceProviderPort } from "./nonce-provider.port";
 
 type Dependencies = {
-  FileWriter: FileWriterPort;
-  FileRenamer: FileRenamerPort;
-  NonceProvider: NonceProviderPort;
+  AtomicFileWriter: AtomicFileWriterPort;
 };
 
 export class ImageResizerAdapter implements ImageResizerPort {
@@ -18,10 +14,6 @@ export class ImageResizerAdapter implements ImageResizerPort {
 
   async resize(recipe: ImageResizerStrategy): Promise<tools.FilePathRelative | tools.FilePathAbsolute> {
     const final = recipe.strategy === "output_path" ? recipe.output : recipe.input;
-    const filename = final.getFilename();
-    const temporary = final.withFilename(
-      filename.withSuffix(`-resized-${this.deps.NonceProvider.generate()}`),
-    );
 
     const extension = final.getFilename().getExtension();
     const format = (extension === "jpg" ? "jpeg" : extension) as ImageSupportedType;
@@ -32,8 +24,7 @@ export class ImageResizerAdapter implements ImageResizerPort {
       [format]()
       .bytes();
 
-    await this.deps.FileWriter.write(temporary.get(), resized);
-    await this.deps.FileRenamer.rename(temporary, final);
+    await this.deps.AtomicFileWriter.write(final, resized);
 
     return final;
   }

package/src/index.ts

@@ -36,6 +36,10 @@ export * from "./antivirus-with-semaphore.adapter";
 export * from "./antivirus-with-timeout.adapter";
 export * from "./api-version.middleware";
 export * from "./api-version-hono.middleware";
+export * from "./atomic-file-writer.adapter";
+export * from "./atomic-file-writer.port";
+export * from "./atomic-file-writer-collecting.adapter";
+export * from "./atomic-file-writer-noop.adapter";
 export * from "./auth-session-reader.port";
 export * from "./auth-session-reader-better-auth.adapter";
 export * from "./auth-session-reader-noop.adapter";
@@ -311,6 +315,10 @@ export * from "./job-queue-stats-provider-noop.adapter";
 export * from "./job-queue-stats-provider-sqlite.adapter";
 export * from "./job-queue-with-logger.adapter";
 export * from "./job-queue-worker.service";
+export * from "./job-recoverer.port";
+export * from "./job-recoverer-collecting.adapter";
+export * from "./job-recoverer-noop.adapter";
+export * from "./job-recoverer-sqlite.adapter";
 export * from "./job-registry.adapter";
 export * from "./job-registry.port";
 export * from "./job-requeuer.port";
@@ -441,6 +449,9 @@ export * from "./retry-backoff-exponential.strategy";
 export * from "./retry-backoff-jitter.strategy";
 export * from "./retry-backoff-linear.strategy";
 export * from "./retry-backoff-noop.strategy";
+export * from "./runtime-stats-provider.port";
+export * from "./runtime-stats-provider-noop.adapter";
+export * from "./runtime-stats-provider-system.adapter";
 export * from "./sealer.port";
 export * from "./sealer-aes-gcm.adapter";
 export * from "./sealer-noop.adapter";

package/src/job-pruner-sqlite.adapter.ts

@@ -3,6 +3,7 @@ import type { Database } from "bun:sqlite";
 import * as tools from "@bgord/tools";
 import type { ClockPort } from "./clock.port";
 import type { JobPrunerPort } from "./job-pruner.port";
+import { JobStatusEnum } from "./job-status.vo";
 
 type Dependencies = { db: Database; Clock: ClockPort };
 
@@ -14,7 +15,7 @@ export class JobPrunerSqliteAdapter implements JobPrunerPort {
 
     const result = this.deps.db.run<[tools.TimestampValueType]>(
       `DELETE FROM jobs
-         WHERE status IN ('completed', 'failed')
+         WHERE status IN ('${JobStatusEnum.completed}', '${JobStatusEnum.failed}')
            AND createdAt <= ?`,
       [threshold],
     );

package/src/job-queue-stats-provider-sqlite.adapter.ts

@@ -25,10 +25,10 @@ export class JobQueueStatsProviderSqliteAdapter implements JobQueueStatsProvider
     const counts = Object.fromEntries(snapshot.map((row) => [row.status, row.count]));
 
     return {
-      pending: tools.Int.nonNegative(counts["pending"] ?? 0),
-      claimed: tools.Int.nonNegative(counts["claimed"] ?? 0),
-      completed: tools.Int.nonNegative(counts["completed"] ?? 0),
-      failed: tools.Int.nonNegative(counts["failed"] ?? 0),
+      pending: tools.Int.nonNegative(counts[JobStatusEnum.pending] ?? 0),
+      claimed: tools.Int.nonNegative(counts[JobStatusEnum.claimed] ?? 0),
+      completed: tools.Int.nonNegative(counts[JobStatusEnum.completed] ?? 0),
+      failed: tools.Int.nonNegative(counts[JobStatusEnum.failed] ?? 0),
       oldestPending: oldestPending?.createdAt ? tools.Timestamp.fromNumber(oldestPending.createdAt).ms : null,
     };
   }

package/src/job-recoverer-collecting.adapter.ts

@@ -0,0 +1,14 @@
+import * as tools from "@bgord/tools";
+import type { JobRecovererPort } from "./job-recoverer.port";
+
+export class JobRecovererCollectingAdapter implements JobRecovererPort {
+  readonly recovered: Array<tools.IntegerNonNegativeType> = [];
+
+  async recover(): Promise<tools.IntegerNonNegativeType> {
+    const count = tools.Int.nonNegative(0);
+
+    this.recovered.push(count);
+
+    return count;
+  }
+}

package/src/job-recoverer-noop.adapter.ts

@@ -0,0 +1,8 @@
+import * as tools from "@bgord/tools";
+import type { JobRecovererPort } from "./job-recoverer.port";
+
+export class JobRecovererNoopAdapter implements JobRecovererPort {
+  async recover(): Promise<tools.IntegerNonNegativeType> {
+    return tools.Int.nonNegative(0);
+  }
+}

package/src/job-recoverer-sqlite.adapter.ts

@@ -0,0 +1,20 @@
+// [BUN DEPENDENCY]
+import type { Database } from "bun:sqlite";
+import * as tools from "@bgord/tools";
+import type { JobRecovererPort } from "./job-recoverer.port";
+import { JobStatusEnum } from "./job-status.vo";
+
+type Dependencies = { db: Database };
+
+// Single-process only: at boot, every claimed job was left behind by a dead process.
+export class JobRecovererSqliteAdapter implements JobRecovererPort {
+  constructor(private readonly deps: Dependencies) {}
+
+  async recover(): Promise<tools.IntegerNonNegativeType> {
+    const result = this.deps.db.run(
+      `UPDATE jobs SET status = '${JobStatusEnum.pending}' WHERE status = '${JobStatusEnum.claimed}'`,
+    );
+
+    return tools.Int.nonNegative(result.changes);
+  }
+}

package/src/job-recoverer.port.ts

@@ -0,0 +1,5 @@
+import type * as tools from "@bgord/tools";
+
+export interface JobRecovererPort {
+  recover(): Promise<tools.IntegerNonNegativeType>;
+}

package/src/memory-consumption.service.ts

@@ -1,6 +1,9 @@
 import * as tools from "@bgord/tools";
 
-type MemoryConsumptionSnapshotType = { total: tools.Size; heap: { used: tools.Size; total: tools.Size } };
+export type MemoryConsumptionSnapshotType = {
+  total: tools.Size;
+  heap: { used: tools.Size; total: tools.Size };
+};
 
 // RSS - resident set size - how much memory this process uses
 // Heap total - how much memory is reserved for the JS heap

package/src/path-matcher.service.ts

@@ -0,0 +1,14 @@
+export type PathMatcherRule = string | URLPattern;
+
+export class PathMatcher {
+  static matches(rules: ReadonlyArray<PathMatcherRule> | undefined, path: string): boolean {
+    return rules?.some((rule) => PathMatcher.matchesRule(rule, path)) ?? false;
+  }
+
+  private static matchesRule(rule: PathMatcherRule, path: string): boolean {
+    if (rule instanceof URLPattern) return rule.test({ pathname: path });
+    if (path === rule) return true;
+
+    return path.startsWith(rule.endsWith("/") ? rule : `${rule}/`);
+  }
+}

package/src/remote-file-storage-disk.adapter.ts

@@ -1,13 +1,11 @@
 // [BUN DEPENDENCY]
 import * as tools from "@bgord/tools";
 import * as v from "valibot";
+import type { AtomicFileWriterPort } from "./atomic-file-writer.port";
 import type { DirectoryEnsurerPort } from "./directory-ensurer.port";
 import type { FileCleanerPort } from "./file-cleaner.port";
-import type { FileCopierPort } from "./file-copier.port";
 import type { FileInspectionPort } from "./file-inspection.port";
-import type { FileRenamerPort } from "./file-renamer.port";
 import type { HashFilePort } from "./hash-file.port";
-import type { NonceProviderPort } from "./nonce-provider.port";
 import type {
   RemoteFileStoragePort,
   RemoteHeadResult,
@@ -16,13 +14,11 @@ import type {
 } from "./remote-file-storage.port";
 
 type Dependencies = {
+  AtomicFileWriter: AtomicFileWriterPort;
   HashFile: HashFilePort;
   FileInspection: FileInspectionPort;
   FileCleaner: FileCleanerPort;
-  FileRenamer: FileRenamerPort;
-  FileCopier: FileCopierPort;
   DirectoryEnsurer: DirectoryEnsurerPort;
-  NonceProvider: NonceProviderPort;
 };
 
 type Config = { root: tools.DirectoryPathAbsoluteType };
@@ -47,19 +43,9 @@ export class RemoteFileStorageDiskAdapter implements RemoteFileStoragePort {
 
   async putFromPath(input: RemotePutFromPathInput): Promise<RemotePutFromPathResult> {
     const final = this.resolveKeyToAbsoluteFilePath(input.key);
-    const temporary = final.withFilename(
-      final.getFilename().withSuffix(`-part-${this.deps.NonceProvider.generate()}`),
-    );
 
     await this.deps.DirectoryEnsurer.ensure(final.getDirectory());
-    await this.deps.FileCopier.copy(input.path, temporary);
-
-    try {
-      await this.deps.FileRenamer.rename(temporary, final);
-    } catch (error) {
-      await this.deps.FileCleaner.delete(temporary);
-      throw error;
-    }
+    await this.deps.AtomicFileWriter.write(final, Bun.file(input.path.get()));
 
     return this.deps.HashFile.hash(final);
   }

package/src/request-context-hono.adapter.ts

@@ -4,8 +4,7 @@ import type { Context } from "hono";
 import { getConnInfo } from "hono/bun";
 import { getCookie } from "hono/cookie";
 import { HTTPException } from "hono/http-exception";
-import type { RequestContext } from "./request-context.port";
-import { ShieldAuthStrategyError } from "./shield-auth.strategy";
+import { type RequestContext, RequestIdentityError } from "./request-context.port";
 
 export class RequestContextHonoAdapter implements RequestContext {
   readonly request: RequestContext["request"];
@@ -58,8 +57,8 @@ export class RequestContextHonoAdapter implements RequestContext {
       authenticatedUserId: () => {
         const user = context.get("user");
 
-        if (user === undefined) throw new Error(ShieldAuthStrategyError.NotAttached);
-        if (user === null) throw new HTTPException(401, { message: ShieldAuthStrategyError.Rejected });
+        if (user === undefined) throw new Error(RequestIdentityError.NotAttached);
+        if (user === null) throw new HTTPException(401, { message: RequestIdentityError.Rejected });
         return user.id;
       },
       ip: () =>

package/src/request-context.port.ts

@@ -1,6 +1,11 @@
 import type * as tools from "@bgord/tools";
 import type { UUIDType } from "./uuid.vo";
 
+export const RequestIdentityError = {
+  Rejected: "shield.auth.rejected",
+  NotAttached: "shield.auth.not.attached",
+};
+
 export interface RequestContext {
   readonly request: {
     readonly path: string;

package/src/runtime-stats-provider-noop.adapter.ts

@@ -0,0 +1,16 @@
+import * as tools from "@bgord/tools";
+import type { RuntimeStatsProviderPort, RuntimeStatsSnapshot } from "./runtime-stats-provider.port";
+
+export class RuntimeStatsProviderNoopAdapter implements RuntimeStatsProviderPort {
+  getStats(): RuntimeStatsSnapshot {
+    const zero = tools.Duration.Ms(0);
+    const empty = tools.Size.fromBytes(0);
+
+    return {
+      uptime: { duration: zero, formatted: "0 seconds ago" },
+      memory: { total: empty, heap: { used: empty, total: empty } },
+      eventLoop: { lag: { p50: zero, p95: zero, p99: zero }, utilization: 0 },
+      inFlight: tools.Int.of(0),
+    };
+  }
+}

package/src/runtime-stats-provider-system.adapter.ts

@@ -0,0 +1,24 @@
+import type { ClockPort } from "./clock.port";
+import { EventLoopLag } from "./event-loop-lag.service";
+import { EventLoopUtilization } from "./event-loop-utilization.service";
+import { InFlightRequestsTracker } from "./in-flight-requests-tracker.service";
+import { MemoryConsumption } from "./memory-consumption.service";
+import type { RuntimeStatsProviderPort, RuntimeStatsSnapshot } from "./runtime-stats-provider.port";
+import { Uptime } from "./uptime.service";
+
+type Dependencies = { Clock: ClockPort };
+
+export class RuntimeStatsProviderSystemAdapter implements RuntimeStatsProviderPort {
+  constructor(private readonly deps: Dependencies) {
+    EventLoopLag.start();
+  }
+
+  getStats(): RuntimeStatsSnapshot {
+    return {
+      uptime: Uptime.get(this.deps.Clock),
+      memory: MemoryConsumption.snapshot(),
+      eventLoop: { lag: EventLoopLag.snapshot(), utilization: EventLoopUtilization.snapshot() },
+      inFlight: InFlightRequestsTracker.get(),
+    };
+  }
+}

package/src/runtime-stats-provider.port.ts

@@ -0,0 +1,16 @@
+import type * as tools from "@bgord/tools";
+import type { EventLoopLagSnapshotType } from "./event-loop-lag.service";
+import type { EventLoopUtilizationSnapshot } from "./event-loop-utilization.service";
+import type { MemoryConsumptionSnapshotType } from "./memory-consumption.service";
+import type { UptimeResultType } from "./uptime.service";
+
+export type RuntimeStatsSnapshot = {
+  uptime: UptimeResultType;
+  memory: MemoryConsumptionSnapshotType;
+  eventLoop: { lag: EventLoopLagSnapshotType; utilization: EventLoopUtilizationSnapshot };
+  inFlight: tools.IntegerType;
+};
+
+export interface RuntimeStatsProviderPort {
+  getStats(): RuntimeStatsSnapshot;
+}

package/src/security-rule-violation-threshold.strategy.ts

@@ -31,12 +31,12 @@ export class SecurityRuleViolationThresholdStrategy implements SecurityRuleStrat
 
   // Best-effort increment, occasional lost increments are acceptable for concurrent requests.
   async isViolated(context: RequestContext): Promise<boolean> {
-    const subject = await this.resolver.resolve(context);
-
     const violated = await this.rule.isViolated(context);
 
     if (!violated) return false;
 
+    const subject = await this.resolver.resolve(context);
+
     try {
       const cached = await this.deps.CacheRepository.get(subject.hex);
       const count = typeof cached === "number" ? cached : 0;

package/src/setup-hono.service.ts

@@ -50,9 +50,9 @@ export class SetupHono {
     deps: Dependencies,
   ): Array<MiddlewareHandler> {
     return [
+      new CorrelationHonoMiddleware(deps).handle(),
       new ShieldMaintenanceHonoStrategy(config.maintenanceMode).handle(),
       new TrailingSlashHonoMiddleware().handle(),
-      new CorrelationHonoMiddleware(deps).handle(),
       new TimingHonoMiddleware(deps).handle(),
       new ApiVersionHonoMiddleware(deps).handle(),
       new ShieldCsrfHonoStrategy(config.csrf).handle(),

package/src/shield-auth-hono.strategy.ts

@@ -2,8 +2,9 @@ import type hono from "hono";
 import { createMiddleware } from "hono/factory";
 import { HTTPException } from "hono/http-exception";
 import type { AuthSessionReaderPort } from "./auth-session-reader.port";
+import { RequestIdentityError } from "./request-context.port";
 import { RequestContextHonoAdapter } from "./request-context-hono.adapter";
-import { ShieldAuthStrategy, ShieldAuthStrategyError } from "./shield-auth.strategy";
+import { ShieldAuthStrategy } from "./shield-auth.strategy";
 
 type Dependencies<User, Session> = { AuthSessionReader: AuthSessionReaderPort<User, Session> };
 
@@ -27,13 +28,13 @@ export class ShieldAuthHonoStrategy<User, Session> {
     const user = c.get("user");
 
     if (this.strategy.verify(user)) return next();
-    throw new HTTPException(401, { message: ShieldAuthStrategyError.Rejected });
+    throw new HTTPException(401, { message: RequestIdentityError.Rejected });
   });
 
   reverse = createMiddleware(async (c: hono.Context, next: hono.Next) => {
     const user = c.get("user");
 
     if (this.strategy.reverse(user)) return next();
-    throw new HTTPException(403, { message: ShieldAuthStrategyError.Rejected });
+    throw new HTTPException(403, { message: RequestIdentityError.Rejected });
   });
 }

package/src/shield-auth.strategy.ts

@@ -1,13 +1,8 @@
 import type { AuthSessionReaderPort, AuthSessionType } from "./auth-session-reader.port";
-import type { HasRequestHeaders } from "./request-context.port";
+import { type HasRequestHeaders, RequestIdentityError } from "./request-context.port";
 
 type Dependencies<User, Session> = { AuthSessionReader: AuthSessionReaderPort<User, Session> };
 
-export const ShieldAuthStrategyError = {
-  Rejected: "shield.auth.rejected",
-  NotAttached: "shield.auth.not.attached",
-};
-
 export class ShieldAuthStrategy<User, Session> {
   constructor(private readonly deps: Dependencies<User, Session>) {}
 
@@ -16,12 +11,12 @@ export class ShieldAuthStrategy<User, Session> {
   }
 
   verify(user: User | null | undefined): boolean {
-    if (user === undefined) throw new Error(ShieldAuthStrategyError.NotAttached);
+    if (user === undefined) throw new Error(RequestIdentityError.NotAttached);
     return user !== null;
   }
 
   reverse(user: User | null | undefined): boolean {
-    if (user === undefined) throw new Error(ShieldAuthStrategyError.NotAttached);
+    if (user === undefined) throw new Error(RequestIdentityError.NotAttached);
     return user === null;
   }
 }

package/src/shield-maintenance.strategy.ts

@@ -1,5 +1,6 @@
 import * as tools from "@bgord/tools";
 import * as v from "valibot";
+import { PathMatcher } from "./path-matcher.service";
 import type { ReactiveConfigPort } from "./reactive-config.port";
 import type { HasRequestPath } from "./request-context.port";
 
@@ -31,12 +32,7 @@ export class ShieldMaintenanceStrategy {
   }
 
   shouldSkip(context: HasRequestPath): boolean {
-    return (
-      this.config?.skip?.some((rule) => {
-        if (rule instanceof URLPattern) return rule.test({ pathname: context.request.path });
-        return context.request.path.startsWith(rule);
-      }) ?? false
-    );
+    return PathMatcher.matches(this.config?.skip, context.request.path);
   }
 
   async evaluate(): Promise<ShieldMaintenanceResult> {

package/src/temporary-file-absolute.adapter.ts

@@ -1,15 +1,11 @@
 import * as tools from "@bgord/tools";
+import type { AtomicFileWriterPort } from "./atomic-file-writer.port";
 import type { FileCleanerPort } from "./file-cleaner.port";
-import type { FileRenamerPort } from "./file-renamer.port";
-import type { FileWriterPort } from "./file-writer.port";
-import type { NonceProviderPort } from "./nonce-provider.port";
 import type { TemporaryFilePort } from "./temporary-file.port";
 
 type Dependencies = {
+  AtomicFileWriter: AtomicFileWriterPort;
   FileCleaner: FileCleanerPort;
-  FileRenamer: FileRenamerPort;
-  FileWriter: FileWriterPort;
-  NonceProvider: NonceProviderPort;
 };
 
 export class TemporaryFileAbsoluteAdapter implements TemporaryFilePort {
@@ -19,20 +15,9 @@ export class TemporaryFileAbsoluteAdapter implements TemporaryFilePort {
   ) {}
 
   async write(filename: tools.Filename, content: File): Promise<tools.FilePathAbsolute> {
-    const temporary = tools.FilePathAbsolute.fromPartsSafe(
-      this.directory,
-      filename.withSuffix(`-part-${this.deps.NonceProvider.generate()}`),
-    );
     const final = tools.FilePathAbsolute.fromPartsSafe(this.directory, filename);
 
-    await this.deps.FileWriter.write(temporary.get(), content);
-
-    try {
-      await this.deps.FileRenamer.rename(temporary, final);
-    } catch (error) {
-      await this.deps.FileCleaner.delete(temporary);
-      throw error;
-    }
+    await this.deps.AtomicFileWriter.write(final, content);
 
     return final;
   }

package/src/timing.middleware.ts

@@ -1,4 +1,5 @@
 import type { ClockPort } from "./clock.port";
+import { EventStreamAccept } from "./event-stream-accept.service";
 import type { HasRequestHeader } from "./request-context.port";
 import { Stopwatch } from "./stopwatch.service";
 
@@ -10,7 +11,7 @@ export class TimingMiddleware {
   constructor(private readonly deps: TimingMiddlewareDependencies) {}
 
   async measure(context: HasRequestHeader, action: () => void | Promise<void>): Promise<string | null> {
-    if (TimingMiddleware.isEventStream(context.request.header("accept"))) return null;
+    if (EventStreamAccept.matches(context.request.header("accept"))) return null;
 
     const stopwatch = new Stopwatch(this.deps);
 
@@ -18,13 +19,4 @@ export class TimingMiddleware {
 
     return `total;dur=${Math.max(0, stopwatch.stop().ms)}`;
   }
-
-  private static isEventStream(accept: string | undefined): boolean {
-    if (!accept) return false;
-
-    return accept
-      .toLowerCase()
-      .split(",")
-      .some((type) => type.split(";")[0]?.trim() === "text/event-stream");
-  }
 }