@bgord/bun 1.9.0 → 1.9.2

package/src/cache-resolver.strategy.ts

@@ -0,0 +1,17 @@
+import type { Hash } from "./hash.vo";
+
+export enum CacheSourceEnum {
+  hit = "hit",
+  miss = "miss",
+}
+
+export interface CacheResolverStrategy {
+  resolve<T>(subject: Hash, producer: () => Promise<T>): Promise<T>;
+
+  resolveWithContext<T>(
+    subject: Hash,
+    producer: () => Promise<T>,
+  ): Promise<{ value: T; source: CacheSourceEnum }>;
+
+  flush(): Promise<void>;
+}

package/src/cache-response.middleware.ts

@@ -0,0 +1,51 @@
+import { createMiddleware } from "hono/factory";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { CacheResolverStrategy } from "./cache-resolver.strategy";
+import type { CacheSubjectRequestResolver } from "./cache-subject-request-resolver.vo";
+
+type Dependencies = { CacheResolver: CacheResolverStrategy };
+
+type CacheResponseOptions = { enabled: boolean; resolver: CacheSubjectRequestResolver };
+
+type CachedResponse = {
+  body: string;
+  headers: Record<string, string>;
+  status: ContentfulStatusCode;
+};
+
+export class CacheResponse {
+  static readonly CACHE_HIT_HEADER = "Cache-Hit";
+
+  constructor(
+    private readonly config: CacheResponseOptions,
+    private readonly deps: Dependencies,
+  ) {}
+
+  handle = createMiddleware(async (context, next) => {
+    if (!this.config.enabled) return next();
+
+    const subject = await this.config.resolver.resolve(context);
+
+    const result = await this.deps.CacheResolver.resolveWithContext<CachedResponse>(subject.hex, async () => {
+      await next();
+
+      const response = context.res.clone();
+
+      return {
+        body: await response.text(),
+        headers: response.headers.toJSON(),
+        status: response.status as ContentfulStatusCode,
+      };
+    });
+
+    context.header(CacheResponse.CACHE_HIT_HEADER, result.source);
+
+    return context.newResponse(result.value.body, result.value.status, result.value.headers);
+  });
+
+  clear = createMiddleware(async (_, next) => {
+    await this.deps.CacheResolver.flush();
+
+    return next();
+  });
+}

package/src/cache-subject-application-resolver.vo.ts

@@ -0,0 +1,34 @@
+import type { CacheSubjectSegmentApplicationStrategy } from "./cache-subject-segment-application.strategy";
+import type { CacheSubjectSegmentType } from "./cache-subject-segment-request.strategy";
+import type { Hash } from "./hash.vo";
+import type { HashContentStrategy } from "./hash-content.strategy";
+
+type Dependencies = { HashContent: HashContentStrategy };
+
+export const CacheSubjectApplicationResolverError = {
+  NoSegments: "cache.subject.application.no.segments",
+  TooManySegments: "cache.subject.application.too.many.segments",
+};
+
+export class CacheSubjectApplicationResolver {
+  private readonly SEPARATOR = "|";
+
+  constructor(
+    private readonly segments: CacheSubjectSegmentApplicationStrategy[],
+    private readonly deps: Dependencies,
+  ) {
+    if (this.segments.length === 0) throw new Error(CacheSubjectApplicationResolverError.NoSegments);
+    if (this.segments.length > 10) throw new Error(CacheSubjectApplicationResolverError.TooManySegments);
+  }
+
+  async resolve(): Promise<{ hex: Hash; raw: CacheSubjectSegmentType[] }> {
+    const segments = this.segments.map((segment) =>
+      segment.create().replaceAll(this.SEPARATOR, encodeURIComponent(this.SEPARATOR)),
+    );
+    const subject = segments.join(this.SEPARATOR);
+
+    const hex = await this.deps.HashContent.hash(subject);
+
+    return { hex, raw: segments };
+  }
+}

package/src/cache-subject-request-resolver.vo.ts

@@ -0,0 +1,37 @@
+import type { Context } from "hono";
+import type {
+  CacheSubjectSegmentRequestStrategy,
+  CacheSubjectSegmentType,
+} from "./cache-subject-segment-request.strategy";
+import type { Hash } from "./hash.vo";
+import type { HashContentStrategy } from "./hash-content.strategy";
+
+type Dependencies = { HashContent: HashContentStrategy };
+
+export const CacheSubjectRequestResolverError = {
+  NoSegments: "cache.subject.request.no.segments",
+  TooManySegments: "cache.subject.request.too.many.segments",
+};
+
+export class CacheSubjectRequestResolver {
+  private readonly SEPARATOR = "|";
+
+  constructor(
+    private readonly segments: CacheSubjectSegmentRequestStrategy[],
+    private readonly deps: Dependencies,
+  ) {
+    if (this.segments.length === 0) throw new Error(CacheSubjectRequestResolverError.NoSegments);
+    if (this.segments.length > 10) throw new Error(CacheSubjectRequestResolverError.TooManySegments);
+  }
+
+  async resolve(context: Context): Promise<{ hex: Hash; raw: CacheSubjectSegmentType[] }> {
+    const segments = this.segments.map((segment) =>
+      segment.create(context).replaceAll(this.SEPARATOR, encodeURIComponent(this.SEPARATOR)),
+    );
+    const subject = segments.join(this.SEPARATOR);
+
+    const hex = await this.deps.HashContent.hash(subject);
+
+    return { hex, raw: segments };
+  }
+}

package/src/cache-subject-segment-application.strategy.ts

@@ -0,0 +1,7 @@
+import type { CacheSubjectSegmentType } from "./cache-subject-segment-request.strategy";
+
+export const CacheSubjectSegmentApplicationEmpty: CacheSubjectSegmentType = "__absent__";
+
+export interface CacheSubjectSegmentApplicationStrategy {
+  create(): CacheSubjectSegmentType;
+}

package/src/cache-subject-segment-build.strategy.ts

@@ -0,0 +1,14 @@
+import type * as tools from "@bgord/tools";
+import {
+  CacheSubjectSegmentApplicationEmpty,
+  type CacheSubjectSegmentApplicationStrategy,
+} from "./cache-subject-segment-application.strategy";
+
+export class CacheSubjectSegmentBuildStrategy implements CacheSubjectSegmentApplicationStrategy {
+  constructor(private readonly build?: tools.PackageVersion) {}
+
+  create() {
+    if (!this.build) return CacheSubjectSegmentApplicationEmpty;
+    return this.build.toString();
+  }
+}

package/src/cache-subject-segment-cookie.strategy.ts

@@ -0,0 +1,14 @@
+import type { Context } from "hono";
+import { getCookie } from "hono/cookie";
+import {
+  CacheSubjectSegmentRequestEmpty,
+  type CacheSubjectSegmentRequestStrategy,
+} from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentCookieStrategy implements CacheSubjectSegmentRequestStrategy {
+  constructor(private readonly name: string) {}
+
+  create(context: Context) {
+    return getCookie(context, this.name) ?? CacheSubjectSegmentRequestEmpty;
+  }
+}

package/src/cache-subject-segment-env.strategy.ts

@@ -0,0 +1,10 @@
+import type { CacheSubjectSegmentApplicationStrategy } from "./cache-subject-segment-application.strategy";
+import type { NodeEnvironmentEnum } from "./node-env.vo";
+
+export class CacheSubjectSegmentEnvStrategy implements CacheSubjectSegmentApplicationStrategy {
+  constructor(private readonly type: NodeEnvironmentEnum) {}
+
+  create() {
+    return this.type;
+  }
+}

package/src/cache-subject-segment-fixed.strategy.ts

@@ -0,0 +1,12 @@
+import type { CacheSubjectSegmentApplicationStrategy } from "./cache-subject-segment-application.strategy";
+import type { CacheSubjectSegmentRequestStrategy } from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentFixedStrategy
+  implements CacheSubjectSegmentRequestStrategy, CacheSubjectSegmentApplicationStrategy
+{
+  constructor(private readonly value: string) {}
+
+  create() {
+    return this.value;
+  }
+}

package/src/cache-subject-segment-header.strategy.ts

@@ -0,0 +1,13 @@
+import type { Context } from "hono";
+import {
+  CacheSubjectSegmentRequestEmpty,
+  type CacheSubjectSegmentRequestStrategy,
+} from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentHeaderStrategy implements CacheSubjectSegmentRequestStrategy {
+  constructor(private readonly name: string) {}
+
+  create(context: Context) {
+    return context.req.header(this.name) ?? CacheSubjectSegmentRequestEmpty;
+  }
+}

package/src/cache-subject-segment-ip.strategy.ts

@@ -0,0 +1,9 @@
+import type { Context } from "hono";
+import type { CacheSubjectSegmentRequestStrategy } from "./cache-subject-segment-request.strategy";
+import { ClientFromHono } from "./client-from-hono.adapter";
+
+export class CacheSubjectSegmentIpStrategy implements CacheSubjectSegmentRequestStrategy {
+  create(context: Context) {
+    return ClientFromHono.translate(context).ip;
+  }
+}

package/src/cache-subject-segment-path.strategy.ts

@@ -0,0 +1,8 @@
+import type { Context } from "hono";
+import type { CacheSubjectSegmentRequestStrategy } from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentPathStrategy implements CacheSubjectSegmentRequestStrategy {
+  create(context: Context) {
+    return context.req.path;
+  }
+}

package/src/cache-subject-segment-query.strategy.ts

@@ -0,0 +1,18 @@
+import type { Context } from "hono";
+import {
+  CacheSubjectSegmentRequestEmpty,
+  type CacheSubjectSegmentRequestStrategy,
+} from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentQueryStrategy implements CacheSubjectSegmentRequestStrategy {
+  create(context: Context) {
+    const query = context.req.query() ?? {};
+
+    const keys = Object.keys(query).toSorted();
+
+    const result = keys.map((key) => `${key}=${query[key]}`).join("&");
+
+    if (!result) return CacheSubjectSegmentRequestEmpty;
+    return result;
+  }
+}

package/src/cache-subject-segment-request.strategy.ts

@@ -0,0 +1,9 @@
+import type { Context } from "hono";
+
+export const CacheSubjectSegmentRequestEmpty: CacheSubjectSegmentType = "__absent__";
+
+export type CacheSubjectSegmentType = string;
+
+export interface CacheSubjectSegmentRequestStrategy {
+  create(context: Context): CacheSubjectSegmentType;
+}

package/src/cache-subject-segment-user.strategy.ts

@@ -0,0 +1,8 @@
+import type { Context } from "hono";
+import type { CacheSubjectSegmentRequestStrategy } from "./cache-subject-segment-request.strategy";
+
+export class CacheSubjectSegmentUserStrategy implements CacheSubjectSegmentRequestStrategy {
+  create(context: Context) {
+    return context.get("user")?.id ?? "anon";
+  }
+}

package/src/certificate-inspector-noop.adapter.ts

@@ -0,0 +1,10 @@
+import type * as tools from "@bgord/tools";
+import type { CertificateInspection, CertificateInspectorPort } from "./certificate-inspector.port";
+
+export class CertificateInspectorNoopAdapter implements CertificateInspectorPort {
+  constructor(private readonly remaining: tools.Duration) {}
+
+  async inspect(_hostname: string): Promise<CertificateInspection> {
+    return { success: true, remaining: this.remaining };
+  }
+}

package/src/certificate-inspector-tls.adapter.ts

@@ -0,0 +1,42 @@
+import tls from "node:tls";
+import * as tools from "@bgord/tools";
+import type { CertificateInspection, CertificateInspectorPort } from "./certificate-inspector.port";
+import type { ClockPort } from "./clock.port";
+
+type Dependencies = { Clock: ClockPort };
+
+// Stryker disable all
+export class CertificateInspectorTLSAdapter implements CertificateInspectorPort {
+  constructor(private readonly deps: Dependencies) {}
+
+  async inspect(hostname: string): Promise<CertificateInspection> {
+    return new Promise((resolve) => {
+      const settle = (value: CertificateInspection) => {
+        try {
+          socket.end();
+          socket.destroy();
+        } finally {
+          resolve(value);
+        }
+      };
+
+      const socket = tls.connect(
+        { host: hostname, port: 443, servername: hostname, rejectUnauthorized: false },
+        () => {
+          const certificate = socket.getPeerCertificate();
+
+          if (!certificate?.valid_to) return settle({ success: false });
+
+          const remaining = tools.Timestamp.fromDateLike(certificate.valid_to).difference(
+            this.deps.Clock.now(),
+          );
+
+          settle({ success: true, remaining });
+        },
+      );
+
+      socket.once("error", () => settle({ success: false }));
+    });
+  }
+}
+// Stryker restore all

package/src/certificate-inspector.port.ts

@@ -0,0 +1,7 @@
+import type * as tools from "@bgord/tools";
+
+export type CertificateInspection = { success: true; remaining: tools.Duration } | { success: false };
+
+export interface CertificateInspectorPort {
+  inspect(hostname: string): Promise<CertificateInspection>;
+}

package/src/checksum.service.ts

@@ -0,0 +1,12 @@
+import type { HashFileResult } from "./hash-file.port";
+
+export class Checksum {
+  static compare(first: HashFileResult, second: HashFileResult): boolean {
+    return (
+      first.etag.matches(second.etag) &&
+      first.size.toBytes() === second.size.toBytes() &&
+      first.lastModified.equals(second.lastModified) &&
+      first.mime.isSatisfiedBy(second.mime)
+    );
+  }
+}

package/src/client-from-hono.adapter.ts

@@ -0,0 +1,20 @@
+import type { Context } from "hono";
+import { getConnInfo } from "hono/bun";
+import { Client } from "./client.vo";
+
+export class ClientFromHono {
+  static translate(context: Context): Client {
+    const info = ClientFromHono.retrieveConnInfo(context);
+
+    const ip =
+      context.req.header("x-real-ip") || context.req.header("x-forwarded-for") || info?.remote?.address;
+
+    const ua = context.req.header("user-agent");
+
+    return Client.fromParts(ip, ua);
+  }
+
+  static retrieveConnInfo(context: Context) {
+    return getConnInfo(context);
+  }
+}

package/src/client-ip.vo.ts

@@ -0,0 +1,17 @@
+import * as z from "zod/v4";
+
+export const ClientIpError = { Type: "client.ip.type", Empty: "client.ip.empty" };
+
+// Stryker disable all
+export const ClientIp = z
+  // Stryker restore all
+  .string(ClientIpError.Type)
+  .min(1, ClientIpError.Empty)
+  .transform((value) => {
+    const result = z.ipv4().safeParse(value);
+
+    return result.success ? result.data : "anon";
+  })
+  .brand("ClientIp");
+
+export type ClientIpType = z.infer<typeof ClientIp>;

package/src/client-user-agent.vo.ts

@@ -0,0 +1,17 @@
+import * as z from "zod/v4";
+
+export const ClientUserAgentError = {
+  Type: "client.user.agent.type",
+  Empty: "client.user.agent.empty",
+  TooLong: "client.user.agent.too.long",
+};
+
+// Stryker disable all
+export const ClientUserAgent = z
+  // Stryker restore all
+  .string(ClientUserAgentError.Type)
+  .min(1, ClientUserAgentError.Empty)
+  .max(128, ClientUserAgentError.TooLong)
+  .brand("ClientUserAgent");
+
+export type ClientUserAgentType = z.infer<typeof ClientUserAgent>;

package/src/client.vo.ts

@@ -0,0 +1,52 @@
+import { ClientIp, type ClientIpType } from "./client-ip.vo";
+import { ClientUserAgent, type ClientUserAgentType } from "./client-user-agent.vo";
+
+export type ClientType = { ip: ClientIpType; ua: ClientUserAgentType };
+
+export class Client {
+  private static DEFAULT_IP = ClientIp.parse("anon");
+  private static DEFAULT_UA = ClientUserAgent.parse("anon");
+
+  private constructor(private readonly value: ClientType) {}
+
+  static fromPartsSafe(
+    ip: ClientIpType | null | undefined,
+    ua: ClientUserAgentType | null | undefined,
+  ): Client {
+    return new Client({
+      ip: ip ?? Client.DEFAULT_IP,
+      ua: ClientUserAgent.parse((ua ?? Client.DEFAULT_UA).toLowerCase()),
+    });
+  }
+
+  static fromParts(ip: string | null | undefined, ua: string | null | undefined): Client {
+    return new Client({
+      ip: ClientIp.parse(ip ?? Client.DEFAULT_IP),
+      ua: ClientUserAgent.parse((ua ?? Client.DEFAULT_UA).toLowerCase()),
+    });
+  }
+
+  equals(another: Client): boolean {
+    return this.value.ip === another.value.ip && this.value.ua === another.value.ua;
+  }
+
+  matchesUa(ua: ClientUserAgentType): boolean {
+    return this.value.ua.includes(ua.toLowerCase());
+  }
+
+  matchesIp(ip: ClientIpType): boolean {
+    return this.value.ip.includes(ip.toLowerCase());
+  }
+
+  get ip(): ClientIpType {
+    return this.value.ip;
+  }
+
+  get ua(): ClientUserAgentType {
+    return this.value.ua;
+  }
+
+  toJSON(): ClientType {
+    return this.value;
+  }
+}

package/src/clock-fixed.adapter.ts

@@ -0,0 +1,14 @@
+import type * as tools from "@bgord/tools";
+import type { ClockPort } from "./clock.port";
+
+export class ClockFixedAdapter implements ClockPort {
+  constructor(private value: tools.Timestamp) {}
+
+  now() {
+    return this.value;
+  }
+
+  advanceBy(duration: tools.Duration): void {
+    this.value = this.value.add(duration);
+  }
+}

package/src/clock-offset.adapter.ts

@@ -0,0 +1,15 @@
+import type * as tools from "@bgord/tools";
+import type { ClockPort } from "./clock.port";
+
+type Dependencies = { Clock: ClockPort };
+
+export class ClockOffsetAdapter implements ClockPort {
+  constructor(
+    private readonly offset: tools.Duration,
+    private readonly deps: Dependencies,
+  ) {}
+
+  now() {
+    return this.deps.Clock.now().add(this.offset);
+  }
+}

package/src/clock-system.adapter.ts

@@ -0,0 +1,8 @@
+import * as tools from "@bgord/tools";
+import type { ClockPort } from "./clock.port";
+
+export class ClockSystemAdapter implements ClockPort {
+  now() {
+    return tools.Timestamp.fromNumber(Date.now());
+  }
+}

package/src/clock.port.ts

@@ -0,0 +1,5 @@
+import type * as tools from "@bgord/tools";
+
+export interface ClockPort {
+  now(): tools.Timestamp;
+}

package/src/command-envelope.ts

@@ -0,0 +1,16 @@
+import * as tools from "@bgord/tools";
+import type { ClockPort } from "./clock.port";
+import { CorrelationStorage } from "./correlation-storage.service";
+import type { IdProviderPort } from "./id-provider.port";
+import { UUID } from "./uuid.vo";
+
+type Dependencies = { IdProvider: IdProviderPort; Clock: ClockPort };
+
+export const CommandEnvelopeSchema = { id: UUID, correlationId: UUID, createdAt: tools.TimestampValue };
+
+export const createCommandEnvelope = (deps: Dependencies) =>
+  ({
+    id: deps.IdProvider.generate(),
+    correlationId: CorrelationStorage.get(),
+    createdAt: deps.Clock.now().ms,
+  }) as const;

package/src/command-logger.service.ts

@@ -0,0 +1,23 @@
+import type { LoggerPort } from "./logger.port";
+
+type Dependencies = { Logger: LoggerPort };
+
+export class CommandLogger {
+  private readonly base = { component: "infra", operation: "command_emitted" };
+
+  constructor(private readonly deps: Dependencies) {}
+
+  private _handle(
+    type: string,
+    _debugName: string,
+    commandName: string | undefined,
+    commandData: Record<string, any> | undefined,
+  ) {
+    if (type === "subscribe") return;
+    if (typeof commandName === "symbol") return;
+
+    this.deps.Logger.info({ message: `${commandName} emitted`, metadata: commandData, ...this.base });
+  }
+
+  handle = this._handle.bind(this);
+}

package/src/command.types.ts

@@ -0,0 +1,13 @@
+import type * as z from "zod/v4";
+
+export type GenericCommandSchema = z.ZodObject<{
+  id: z.ZodType<string>;
+  correlationId: z.ZodType<string>;
+  createdAt: z.ZodType<number>;
+  name: z.ZodLiteral<string>;
+  payload: z.ZodType<any>;
+}>;
+
+export type GenericParsedCommandSchema = z.ZodObject<
+  Omit<GenericCommandSchema["shape"], "payload"> & { payload: z.ZodString }
+>;

package/src/commit-sha-value.vo.ts

@@ -0,0 +1,18 @@
+import * as z from "zod/v4";
+
+export const CommitShaValueError = {
+  Type: "commit.sha.value.type",
+  InvalidHex: "commit.sha.value.invalid.hex",
+};
+
+// 40 hex chars allowed
+const CHARS_WHITELIST = /^[a-fA-F0-9]{40}$/;
+
+// Stryker disable all
+export const CommitShaValue = z
+  // Stryker restore all
+  .string(CommitShaValueError.Type)
+  .regex(CHARS_WHITELIST, CommitShaValueError.InvalidHex)
+  .brand("CommitShaValue");
+
+export type CommitShaValueType = z.infer<typeof CommitShaValue>;

package/src/commit-sha.vo.ts

@@ -0,0 +1,29 @@
+import { CommitShaValue, type CommitShaValueType } from "./commit-sha-value.vo";
+
+export class CommitSha {
+  private constructor(private readonly value: CommitShaValueType) {}
+
+  static fromString(candidate: string): CommitSha {
+    return new CommitSha(CommitShaValue.parse(candidate));
+  }
+
+  static fromStringSafe(value: CommitShaValueType): CommitSha {
+    return new CommitSha(value);
+  }
+
+  equals(another: CommitSha): boolean {
+    return this.value === another.value;
+  }
+
+  toShortString(length = 7): string {
+    return this.value.slice(0, length);
+  }
+
+  toString(): CommitShaValueType {
+    return this.value;
+  }
+
+  toJSON(): string {
+    return this.value;
+  }
+}

package/src/context.middleware.ts

@@ -0,0 +1,24 @@
+import { createMiddleware } from "hono/factory";
+import type { CorrelationIdType } from "./correlation-id.vo";
+import type { TimeZoneOffsetVariables } from "./time-zone-offset.middleware";
+
+export type ContextType = {
+  requestId: CorrelationIdType;
+  timeZoneOffset: TimeZoneOffsetVariables["timeZoneOffset"];
+};
+
+export type ContextVariables = {
+  context: ContextType;
+  requestId: CorrelationIdType;
+} & TimeZoneOffsetVariables;
+
+export class Context {
+  static attach = createMiddleware(async (context, next) => {
+    context.set("context", {
+      requestId: context.get("requestId"),
+      timeZoneOffset: context.get("timeZoneOffset"),
+    });
+
+    await next();
+  });
+}

package/src/correlation-id.vo.ts

@@ -0,0 +1,6 @@
+import type * as z from "zod/v4";
+import { UUID } from "./uuid.vo";
+
+export const CorrelationId = UUID;
+
+export type CorrelationIdType = z.infer<typeof CorrelationId>;