@bgord/bun 1.1.6 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/bun",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "license": "MIT",
   "type": "module",
   "author": "Bartosz Gordon",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "@axiomhq/winston": "1.3.1",
-    "@bgord/tools": "1.1.5",
+    "@bgord/tools": "1.1.6",
     "@hono/ua-blocker": "0.1.15",
     "better-auth": "1.3.34",
     "croner": "9.1.0",

package/readme.md

@@ -41,6 +41,7 @@ src/
 ├── certificate-inspector-noop.adapter.ts
 ├── certificate-inspector-tls.adapter.ts
 ├── certificate-inspector.port.ts
+├── checksum.service.ts
 ├── client-from-hono.adapter.ts
 ├── client.vo.ts
 ├── clock-fixed.adapter.ts
@@ -232,6 +233,7 @@ src/
 ├── timekeeper-google.adapter.ts
 ├── timekeeper-noop.adapter.ts
 ├── timekeeper.port.ts
+├── timeout.service.ts
 ├── to-event-map.types.ts
 ├── translations.service.ts
 ├── uptime.service.ts

package/src/checksum.service.ts

@@ -0,0 +1,23 @@
+import type { FileHashResult } from "./file-hash.port";
+
+export enum ChecksumStrategy {
+  etag = "etag",
+  complex = "complex",
+}
+
+export class Checksum {
+  static compare(first: FileHashResult, second: FileHashResult, strategy: ChecksumStrategy): boolean {
+    switch (strategy) {
+      case ChecksumStrategy.etag:
+        return first.etag === second.etag;
+      case ChecksumStrategy.complex:
+        return (
+          first.etag === second.etag &&
+          first.size === second.size &&
+          first.lastModified &&
+          second.lastModified &&
+          first.mime.isSatisfiedBy(second.mime)
+        );
+    }
+  }
+}

package/src/correlation-storage.service.ts

@@ -15,8 +15,8 @@ export class CorrelationStorage {
   ] ??=
     new AsyncLocalStorage<CorrelationContext>());
 
-  static run<T>(correlationId: CorrelationIdType, fn: () => T | Promise<T>): T | Promise<T> {
-    return CorrelationStorage.als.run({ correlationId }, fn);
+  static run<T>(correlationId: CorrelationIdType, action: () => T | Promise<T>): T | Promise<T> {
+    return CorrelationStorage.als.run({ correlationId }, action);
   }
 
   static get(): CorrelationIdType {

package/src/healthcheck.service.ts

@@ -14,7 +14,7 @@ type HealthcheckResultType = {
   ok: prereqs.PrerequisiteStatusEnum;
   version: string;
   details: { label: prereqs.PrerequisiteLabelType; outcome: prereqs.VerifyOutcome }[];
-  uptime: UptimeResultType;
+  uptime: Omit<UptimeResultType, "duration"> & { durationMs: tools.DurationMsType };
   memory: { bytes: tools.Size["bytes"]; formatted: ReturnType<tools.Size["format"]> };
   durationMs: tools.Duration["ms"];
 };
@@ -40,11 +40,13 @@ export class Healthcheck {
 
       const code = ok === prereqs.PrerequisiteStatusEnum.success ? 200 : 424;
 
+      const uptime = Uptime.get(deps.Clock);
+
       const result: HealthcheckResultType = {
         ok,
         details,
         version: buildInfo.BUILD_VERSION ?? "unknown",
-        uptime: Uptime.get(deps.Clock),
+        uptime: { durationMs: uptime.duration.ms, formatted: uptime.formatted },
         memory: {
           bytes: MemoryConsumption.get().toBytes(),
           formatted: MemoryConsumption.get().format(tools.Size.unit.MB),

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./cache-response.middleware";
 export * from "./certificate-inspector.port";
 export * from "./certificate-inspector-noop.adapter";
 export * from "./certificate-inspector-tls.adapter";
+export * from "./checksum.service";
 export * from "./client.vo";
 export * from "./client-from-hono.adapter";
 export * from "./clock.port";
@@ -155,6 +156,7 @@ export * from "./time-zone-offset.middleware";
 export * from "./timekeeper.port";
 export * from "./timekeeper-google.adapter";
 export * from "./timekeeper-noop.adapter";
+export * from "./timeout.service";
 export * from "./to-event-map.types";
 export * from "./translations.service";
 export * from "./uptime.service";

package/src/prerequisites/clock-drift.ts

@@ -2,6 +2,7 @@ import * as tools from "@bgord/tools";
 import type { ClockPort } from "../clock.port";
 import * as prereqs from "../prerequisites.service";
 import type { TimekeeperPort } from "../timekeeper.port";
+import { Timeout } from "../timeout.service";
 
 export class PrerequisiteClockDrift implements prereqs.Prerequisite {
   readonly kind = "clock-drift";
@@ -10,13 +11,13 @@ export class PrerequisiteClockDrift implements prereqs.Prerequisite {
 
   readonly skew: tools.Duration;
   readonly timekeeper: TimekeeperPort;
-  readonly clock: ClockPort;
+  readonly timeout: tools.Duration;
 
   constructor(
     config: prereqs.PrerequisiteConfigType & {
       skew: tools.Duration;
       timekeeper: TimekeeperPort;
-      clock: ClockPort;
+      timeout?: tools.Duration;
     },
   ) {
     this.label = config.label;
@@ -24,7 +25,7 @@ export class PrerequisiteClockDrift implements prereqs.Prerequisite {
 
     this.skew = config.skew;
     this.timekeeper = config.timekeeper;
-    this.clock = config.clock;
+    this.timeout = config.timeout ?? tools.Duration.Seconds(2);
   }
 
   async verify(clock: ClockPort): Promise<prereqs.VerifyOutcome> {
@@ -32,14 +33,19 @@ export class PrerequisiteClockDrift implements prereqs.Prerequisite {
 
     if (!this.enabled) return prereqs.Verification.undetermined(stopwatch.stop());
 
-    const now = this.clock.now();
+    try {
+      const timestamp = await Timeout.cancellable(
+        (signal: AbortSignal) => this.timekeeper.get(signal),
+        this.timeout,
+      );
+      if (!timestamp) return prereqs.Verification.undetermined(stopwatch.stop());
 
-    const timestamp = await this.timekeeper.get();
-    if (!timestamp) return prereqs.Verification.undetermined(stopwatch.stop());
+      const duration = clock.now().difference(timestamp).toAbsolute();
 
-    const duration = now.difference(timestamp).toAbolute();
-
-    if (duration.isShorterThan(this.skew)) return prereqs.Verification.success(stopwatch.stop());
-    return prereqs.Verification.failure(stopwatch.stop(), { message: `Difference: ${duration.seconds}s` });
+      if (duration.isShorterThan(this.skew)) return prereqs.Verification.success(stopwatch.stop());
+      return prereqs.Verification.failure(stopwatch.stop(), { message: `Difference: ${duration.seconds}s` });
+    } catch (error) {
+      return prereqs.Verification.undetermined(stopwatch.stop());
+    }
   }
 }

package/src/prerequisites/mailer.ts

@@ -2,6 +2,7 @@ import * as tools from "@bgord/tools";
 import type { ClockPort } from "../clock.port";
 import type { MailerPort } from "../mailer.port";
 import * as prereqs from "../prerequisites.service";
+import { Timeout } from "../timeout.service";
 
 export class PrerequisiteMailer implements prereqs.Prerequisite {
   readonly kind = "mailer";
@@ -9,12 +10,14 @@ export class PrerequisiteMailer implements prereqs.Prerequisite {
   readonly enabled?: boolean = true;
 
   private readonly mailer: MailerPort;
+  readonly timeout: tools.Duration;
 
-  constructor(config: prereqs.PrerequisiteConfigType & { mailer: MailerPort }) {
+  constructor(config: prereqs.PrerequisiteConfigType & { mailer: MailerPort; timeout?: tools.Duration }) {
     this.label = config.label;
     this.enabled = config.enabled === undefined ? true : config.enabled;
 
     this.mailer = config.mailer;
+    this.timeout = config.timeout ?? tools.Duration.Seconds(2);
   }
 
   async verify(clock: ClockPort): Promise<prereqs.VerifyOutcome> {
@@ -23,7 +26,7 @@ export class PrerequisiteMailer implements prereqs.Prerequisite {
     if (!this.enabled) return prereqs.Verification.undetermined(stopwatch.stop());
 
     try {
-      await this.mailer.verify();
+      await Timeout.run(this.mailer.verify(), this.timeout);
       return prereqs.Verification.success(stopwatch.stop());
     } catch (error) {
       return prereqs.Verification.failure(stopwatch.stop(), error as Error);

package/src/prerequisites/outside-connectivity.ts

@@ -1,6 +1,7 @@
 import * as tools from "@bgord/tools";
 import type { ClockPort } from "../clock.port";
 import * as prereqs from "../prerequisites.service";
+import { Timeout } from "../timeout.service";
 
 export class PrerequisiteOutsideConnectivity implements prereqs.Prerequisite {
   readonly kind = "outside-connectivity";
@@ -8,10 +9,13 @@ export class PrerequisiteOutsideConnectivity implements prereqs.Prerequisite {
   readonly enabled?: boolean = true;
 
   private readonly url = "https://google.com";
+  readonly timeout: tools.Duration;
 
-  constructor(config: prereqs.PrerequisiteConfigType) {
+  constructor(config: prereqs.PrerequisiteConfigType & { timeout?: tools.Duration }) {
     this.label = config.label;
     this.enabled = config.enabled === undefined ? true : config.enabled;
+
+    this.timeout = config.timeout ?? tools.Duration.Seconds(2);
   }
 
   async verify(clock: ClockPort): Promise<prereqs.VerifyOutcome> {
@@ -20,7 +24,10 @@ export class PrerequisiteOutsideConnectivity implements prereqs.Prerequisite {
     try {
       if (!this.enabled) return prereqs.Verification.undetermined(stopwatch.stop());
 
-      const response = await fetch(this.url, { method: "HEAD" });
+      const response = await Timeout.cancellable(
+        (signal: AbortSignal) => fetch(this.url, { method: "HEAD", signal }),
+        this.timeout,
+      );
 
       if (response.ok) return prereqs.Verification.success(stopwatch.stop());
       return prereqs.Verification.failure(stopwatch.stop(), { message: `HTTP ${response.status}` });

package/src/prerequisites.service.ts

@@ -11,15 +11,15 @@ export enum PrerequisiteStatusEnum {
   undetermined = "undetermined",
 }
 
-export type VerifySuccess = { status: PrerequisiteStatusEnum.success; duration: tools.DurationMsType };
+export type VerifySuccess = { status: PrerequisiteStatusEnum.success; durationMs: tools.DurationMsType };
 export type VerifyFailure = {
   status: PrerequisiteStatusEnum.failure;
-  duration: tools.DurationMsType;
+  durationMs: tools.DurationMsType;
   error?: ErrorInfo;
 };
 export type VerifyUndetermined = {
   status: PrerequisiteStatusEnum.undetermined;
-  duration: tools.DurationMsType;
+  durationMs: tools.DurationMsType;
 };
 export type VerifyOutcome = VerifySuccess | VerifyFailure | VerifyUndetermined;
 
@@ -39,17 +39,17 @@ export type PrerequisiteResult = {
 
 export class Verification {
   static success(duration: tools.Duration): VerifySuccess {
-    return { status: PrerequisiteStatusEnum.success, duration: duration.ms };
+    return { status: PrerequisiteStatusEnum.success, durationMs: duration.ms };
   }
   static failure(duration: tools.Duration, meta?: Error | ErrorInfo): VerifyFailure {
     return {
       status: PrerequisiteStatusEnum.failure,
-      duration: duration.ms,
+      durationMs: duration.ms,
       error: meta instanceof Error ? formatError(meta) : meta,
     };
   }
   static undetermined(duration: tools.Duration): VerifyUndetermined {
-    return { status: PrerequisiteStatusEnum.undetermined, duration: duration.ms };
+    return { status: PrerequisiteStatusEnum.undetermined, durationMs: duration.ms };
   }
 }
 

package/src/timekeeper-google.adapter.ts

@@ -2,9 +2,11 @@ import * as tools from "@bgord/tools";
 import type { TimekeeperPort } from "./timekeeper.port";
 
 export class TimekeeperGoogleAdapter implements TimekeeperPort {
-  async get() {
+  static URL = "https://www.google.com/generate_204";
+
+  async get(signal?: AbortSignal) {
     try {
-      const response = await fetch("https://www.google.com/generate_204");
+      const response = await fetch(TimekeeperGoogleAdapter.URL, { signal });
       if (!response.ok) return null;
 
       const date = response.headers.get("Date");

package/src/timekeeper.port.ts

@@ -1,5 +1,5 @@
 import type * as tools from "@bgord/tools";
 
 export interface TimekeeperPort {
-  get(): Promise<tools.Timestamp | null>;
+  get(signal?: AbortSignal): Promise<tools.Timestamp | null>;
 }

package/src/timeout.service.ts

@@ -0,0 +1,71 @@
+import type * as tools from "@bgord/tools";
+import type { LoggerPort } from "../src/logger.port";
+
+export const TimeoutError = { Exceeded: "timeout.exceeded" };
+
+export class Timeout {
+  static async run<T>(action: Promise<T>, timeout: tools.Duration): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const reason = new Error(TimeoutError.Exceeded);
+
+      const canceller = setTimeout(() => reject(reason), timeout.ms);
+
+      action.then(
+        (value) => {
+          clearTimeout(canceller);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(canceller);
+          reject(error);
+        },
+      );
+    });
+  }
+
+  static async monitor<T>(action: Promise<T>, timeout: tools.Duration, logger: LoggerPort): Promise<T> {
+    const monitor = setTimeout(
+      () =>
+        logger.warn({
+          message: "Timeout",
+          component: "infra",
+          operation: "timeout_monitor",
+          metadata: { timeoutMs: timeout.ms },
+        }),
+      timeout.ms,
+    );
+
+    return action.finally(() => clearTimeout(monitor));
+  }
+
+  static async cancellable<T>(
+    action: (signal: AbortSignal) => Promise<T>,
+    timeout: tools.Duration,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const controller = new AbortController();
+
+      const reason = new Error(TimeoutError.Exceeded);
+
+      const canceller = setTimeout(() => {
+        controller.abort(reason);
+        reject(reason);
+      }, timeout.ms);
+
+      // Promise.resolve.then used to prevent the initial action(controller.signal) call
+      // from throwing before the resulting work-promise is run by promise.then.
+      const promise: Promise<T> = Promise.resolve().then(() => action(controller.signal));
+
+      promise.then(
+        (value) => {
+          clearTimeout(canceller);
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(canceller);
+          reject(error);
+        },
+      );
+    });
+  }
+}