@saeeol/core 7.3.1

package/src/util/flock.ts

@@ -0,0 +1,358 @@
+import path from "path"
+import os from "os"
+import { randomBytes, randomUUID } from "crypto"
+import { mkdir, readFile, rm, stat, utimes, writeFile } from "fs/promises"
+import { Hash } from "./hash"
+import { Effect } from "effect"
+
+export type FlockGlobal = {
+  state: string
+}
+
+export namespace Flock {
+  let global: FlockGlobal | undefined
+
+  export function setGlobal(g: FlockGlobal) {
+    global = g
+  }
+
+  const root = () => {
+    if (!global) throw new Error("Flock global not set")
+    return path.join(global.state, "locks")
+  }
+
+  // Defaults for callers that do not provide timing options.
+  const defaultOpts = {
+    staleMs: 60_000,
+    timeoutMs: 5 * 60_000,
+    baseDelayMs: 100,
+    maxDelayMs: 2_000,
+  }
+
+  export interface WaitEvent {
+    key: string
+    attempt: number
+    delay: number
+    waited: number
+  }
+
+  export type Wait = (input: WaitEvent) => void | Promise<void>
+
+  export interface Options {
+    dir?: string
+    signal?: AbortSignal
+    staleMs?: number
+    timeoutMs?: number
+    baseDelayMs?: number
+    maxDelayMs?: number
+    onWait?: Wait
+  }
+
+  type Opts = {
+    staleMs: number
+    timeoutMs: number
+    baseDelayMs: number
+    maxDelayMs: number
+  }
+
+  type Owned = {
+    acquired: true
+    startHeartbeat: (intervalMs?: number) => void
+    release: () => Promise<void>
+  }
+
+  export interface Lease {
+    release: () => Promise<void>
+    [Symbol.asyncDispose]: () => Promise<void>
+  }
+
+  function code(err: unknown) {
+    if (typeof err !== "object" || err === null || !("code" in err)) return
+    const value = err.code
+    if (typeof value !== "string") return
+    return value
+  }
+
+  function sleep(ms: number, signal?: AbortSignal) {
+    return new Promise<void>((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(signal.reason ?? new Error("Aborted"))
+        return
+      }
+
+      let timer: NodeJS.Timeout | undefined
+
+      const done = () => {
+        signal?.removeEventListener("abort", abort)
+        resolve()
+      }
+
+      const abort = () => {
+        if (timer) {
+          clearTimeout(timer)
+        }
+        signal?.removeEventListener("abort", abort)
+        reject(signal?.reason ?? new Error("Aborted"))
+      }
+
+      signal?.addEventListener("abort", abort, { once: true })
+      timer = setTimeout(done, ms)
+    })
+  }
+
+  function jitter(ms: number) {
+    const j = Math.floor(ms * 0.3)
+    const d = Math.floor(Math.random() * (2 * j + 1)) - j
+    return Math.max(0, ms + d)
+  }
+
+  function mono() {
+    return performance.now()
+  }
+
+  function wall() {
+    return performance.timeOrigin + mono()
+  }
+
+  async function stats(file: string) {
+    try {
+      return await stat(file)
+    } catch (err) {
+      const errCode = code(err)
+      if (errCode === "ENOENT" || errCode === "ENOTDIR") return
+      throw err
+    }
+  }
+
+  async function stale(lockDir: string, heartbeatPath: string, metaPath: string, staleMs: number) {
+    // Stale detection allows automatic recovery after crashed owners.
+    const now = wall()
+    const heartbeat = await stats(heartbeatPath)
+    if (heartbeat) {
+      return now - heartbeat.mtimeMs > staleMs
+    }
+
+    const meta = await stats(metaPath)
+    if (meta) {
+      return now - meta.mtimeMs > staleMs
+    }
+
+    const dir = await stats(lockDir)
+    if (!dir) {
+      return false
+    }
+
+    return now - dir.mtimeMs > staleMs
+  }
+
+  async function tryAcquireLockDir(lockDir: string, opts: Opts): Promise<Owned | { acquired: false }> {
+    const token = randomUUID?.() ?? randomBytes(16).toString("hex")
+    const metaPath = path.join(lockDir, "meta.json")
+    const heartbeatPath = path.join(lockDir, "heartbeat")
+
+    try {
+      await mkdir(lockDir, { mode: 0o700 })
+    } catch (err) {
+      if (code(err) !== "EEXIST") {
+        throw err
+      }
+
+      if (!(await stale(lockDir, heartbeatPath, metaPath, opts.staleMs))) {
+        return { acquired: false }
+      }
+
+      const breakerPath = lockDir + ".breaker"
+      try {
+        await mkdir(breakerPath, { mode: 0o700 })
+      } catch (claimErr) {
+        const errCode = code(claimErr)
+        if (errCode === "EEXIST") {
+          const breaker = await stats(breakerPath)
+          if (breaker && wall() - breaker.mtimeMs > opts.staleMs) {
+            await rm(breakerPath, { recursive: true, force: true }).catch(() => undefined)
+          }
+          return { acquired: false }
+        }
+
+        if (errCode === "ENOENT" || errCode === "ENOTDIR") {
+          return { acquired: false }
+        }
+
+        throw claimErr
+      }
+
+      try {
+        // Breaker ownership ensures only one contender performs stale cleanup.
+        if (!(await stale(lockDir, heartbeatPath, metaPath, opts.staleMs))) {
+          return { acquired: false }
+        }
+
+        await rm(lockDir, { recursive: true, force: true })
+
+        try {
+          await mkdir(lockDir, { mode: 0o700 })
+        } catch (retryErr) {
+          const errCode = code(retryErr)
+          if (errCode === "EEXIST" || errCode === "ENOTEMPTY") {
+            return { acquired: false }
+          }
+          throw retryErr
+        }
+      } finally {
+        await rm(breakerPath, { recursive: true, force: true }).catch(() => undefined)
+      }
+    }
+
+    const meta = {
+      token,
+      pid: process.pid,
+      hostname: os.hostname(),
+      createdAt: new Date().toISOString(),
+    }
+
+    await writeFile(heartbeatPath, "", { flag: "wx" }).catch(async () => {
+      await rm(lockDir, { recursive: true, force: true })
+      throw new Error("Lock acquired but heartbeat already existed (possible compromise).")
+    })
+
+    await writeFile(metaPath, JSON.stringify(meta, null, 2), { flag: "wx" }).catch(async () => {
+      await rm(lockDir, { recursive: true, force: true })
+      throw new Error("Lock acquired but meta.json already existed (possible compromise).")
+    })
+
+    let timer: NodeJS.Timeout | undefined
+
+    const startHeartbeat = (intervalMs = Math.max(100, Math.floor(opts.staleMs / 3))) => {
+      if (timer) return
+      // Heartbeat prevents long critical sections from being evicted as stale.
+      timer = setInterval(() => {
+        const t = new Date()
+        void utimes(heartbeatPath, t, t).catch(() => undefined)
+      }, intervalMs)
+      timer.unref?.()
+    }
+
+    const release = async () => {
+      if (timer) {
+        clearInterval(timer)
+        timer = undefined
+      }
+
+      const current = await readFile(metaPath, "utf8")
+        .then((raw) => {
+          const parsed = JSON.parse(raw)
+          if (!parsed || typeof parsed !== "object") return {}
+          return {
+            token: "token" in parsed && typeof parsed.token === "string" ? parsed.token : undefined,
+          }
+        })
+        .catch((err) => {
+          const errCode = code(err)
+          if (errCode === "ENOENT" || errCode === "ENOTDIR") {
+            throw new Error("Refusing to release: lock is compromised (metadata missing).")
+          }
+          if (err instanceof SyntaxError) {
+            throw new Error("Refusing to release: lock is compromised (metadata invalid).")
+          }
+          throw err
+        })
+      // Token check prevents deleting a lock that was re-acquired by another process.
+      if (current.token !== token) {
+        throw new Error("Refusing to release: lock token mismatch (not the owner).")
+      }
+
+      await rm(lockDir, { recursive: true, force: true })
+    }
+
+    return {
+      acquired: true,
+      startHeartbeat,
+      release,
+    }
+  }
+
+  async function acquireLockDir(
+    lockDir: string,
+    input: { key: string; onWait?: Wait; signal?: AbortSignal },
+    opts: Opts,
+  ) {
+    const stop = mono() + opts.timeoutMs
+    let attempt = 0
+    let waited = 0
+    let delay = opts.baseDelayMs
+
+    while (true) {
+      input.signal?.throwIfAborted()
+
+      const res = await tryAcquireLockDir(lockDir, opts)
+      if (res.acquired) {
+        return res
+      }
+
+      if (mono() > stop) {
+        throw new Error(`Timed out waiting for lock: ${input.key}`)
+      }
+
+      attempt += 1
+      const ms = jitter(delay)
+      await input.onWait?.({
+        key: input.key,
+        attempt,
+        delay: ms,
+        waited,
+      })
+      await sleep(ms, input.signal)
+      waited += ms
+      delay = Math.min(opts.maxDelayMs, Math.floor(delay * 1.7))
+    }
+  }
+
+  export async function acquire(key: string, input: Options = {}): Promise<Lease> {
+    input.signal?.throwIfAborted()
+    const cfg: Opts = {
+      staleMs: input.staleMs ?? defaultOpts.staleMs,
+      timeoutMs: input.timeoutMs ?? defaultOpts.timeoutMs,
+      baseDelayMs: input.baseDelayMs ?? defaultOpts.baseDelayMs,
+      maxDelayMs: input.maxDelayMs ?? defaultOpts.maxDelayMs,
+    }
+    const dir = input.dir ?? root()
+
+    await mkdir(dir, { recursive: true })
+    const lockfile = path.join(dir, Hash.fast(key) + ".lock")
+    const lock = await acquireLockDir(
+      lockfile,
+      {
+        key,
+        onWait: input.onWait,
+        signal: input.signal,
+      },
+      cfg,
+    )
+    lock.startHeartbeat()
+
+    const release = () => lock.release()
+    return {
+      release,
+      [Symbol.asyncDispose]() {
+        return release()
+      },
+    }
+  }
+
+  export async function withLock<T>(key: string, fn: () => Promise<T>, input: Options = {}) {
+    await using _ = await acquire(key, input)
+    input.signal?.throwIfAborted()
+    return await fn()
+  }
+
+  export const effect = Effect.fn("Flock.effect")(function* (key: string, input: Options = {}) {
+    return yield* Effect.acquireRelease(
+      Effect.promise((signal) => Flock.acquire(key, { ...input, signal })).pipe(
+        Effect.withSpan("Flock.acquire", {
+          attributes: { key },
+        }),
+      ),
+      (lock) => Effect.promise(() => lock.release()).pipe(Effect.withSpan("Flock.release")),
+    ).pipe(Effect.asVoid)
+  })
+}

package/src/util/glob.ts

@@ -0,0 +1,34 @@
+import { glob, globSync, type GlobOptions } from "glob"
+import { minimatch } from "minimatch"
+
+export namespace Glob {
+  export interface Options {
+    cwd?: string
+    absolute?: boolean
+    include?: "file" | "all"
+    dot?: boolean
+    symlink?: boolean
+  }
+
+  function toGlobOptions(options: Options): GlobOptions {
+    return {
+      cwd: options.cwd,
+      absolute: options.absolute,
+      dot: options.dot,
+      follow: options.symlink ?? false,
+      nodir: options.include !== "all",
+    }
+  }
+
+  export async function scan(pattern: string, options: Options = {}): Promise<string[]> {
+    return glob(pattern, toGlobOptions(options)) as Promise<string[]>
+  }
+
+  export function scanSync(pattern: string, options: Options = {}): string[] {
+    return globSync(pattern, toGlobOptions(options)) as string[]
+  }
+
+  export function match(pattern: string, filepath: string): boolean {
+    return minimatch(filepath, pattern, { dot: true })
+  }
+}

package/src/util/hash.ts

@@ -0,0 +1,7 @@
+import { createHash } from "crypto"
+
+export namespace Hash {
+  export function fast(input: string | Buffer): string {
+    return createHash("sha1").update(input).digest("hex")
+  }
+}

package/src/util/identifier.ts

@@ -0,0 +1,48 @@
+import { randomBytes } from "crypto"
+
+export namespace Identifier {
+  const LENGTH = 26
+
+  // State for monotonic ID generation
+  let lastTimestamp = 0
+  let counter = 0
+
+  export function ascending() {
+    return create(false)
+  }
+
+  export function descending() {
+    return create(true)
+  }
+
+  function randomBase62(length: number): string {
+    const chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    let result = ""
+    const bytes = randomBytes(length)
+    for (let i = 0; i < length; i++) {
+      result += chars[bytes[i] % 62]
+    }
+    return result
+  }
+
+  export function create(descending: boolean, timestamp?: number): string {
+    const currentTimestamp = timestamp ?? Date.now()
+
+    if (currentTimestamp !== lastTimestamp) {
+      lastTimestamp = currentTimestamp
+      counter = 0
+    }
+    counter++
+
+    let now = BigInt(currentTimestamp) * BigInt(0x1000) + BigInt(counter)
+
+    now = descending ? ~now : now
+
+    const timeBytes = Buffer.alloc(6)
+    for (let i = 0; i < 6; i++) {
+      timeBytes[i] = Number((now >> BigInt(40 - 8 * i)) & BigInt(0xff))
+    }
+
+    return timeBytes.toString("hex") + randomBase62(LENGTH - 12)
+  }
+}

package/src/util/iife.ts

@@ -0,0 +1,3 @@
+export function iife<T>(fn: () => T) {
+  return fn()
+}

package/src/util/lazy.ts

@@ -0,0 +1,11 @@
+export function lazy<T>(fn: () => T) {
+  let value: T | undefined
+  let loaded = false
+
+  return (): T => {
+    if (loaded) return value as T
+    loaded = true
+    value = fn()
+    return value as T
+  }
+}

package/src/util/log.ts

@@ -0,0 +1,208 @@
+import path from "path"
+import { existsSync, writeFileSync } from "fs" 
+import fs from "fs/promises"
+import * as Global from "../global"
+import z from "zod"
+import { Glob } from "./glob"
+import { createStream } from "rotating-file-stream" 
+
+export const Level = z.enum(["DEBUG", "INFO", "WARN", "ERROR"]).meta({ ref: "LogLevel", description: "Log level" })
+export type Level = z.infer<typeof Level>
+
+const levelPriority: Record<Level, number> = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+}
+const keep = 10
+
+let level: Level = "INFO"
+
+function shouldLog(input: Level): boolean {
+  return levelPriority[input] >= levelPriority[level]
+}
+
+export type Logger = {
+  debug(message?: any, extra?: Record<string, any>): void
+  info(message?: any, extra?: Record<string, any>): void
+  error(message?: any, extra?: Record<string, any>): void
+  warn(message?: any, extra?: Record<string, any>): void
+  tag(key: string, value: string): Logger
+  clone(): Logger
+  time(
+    message: string,
+    extra?: Record<string, any>,
+  ): {
+    stop(): void
+    [Symbol.dispose](): void
+  }
+}
+
+const loggers = new Map<string, Logger>()
+
+export const Default = create({ service: "default" })
+
+export interface Options {
+  print: boolean
+  dev?: boolean
+  level?: Level
+}
+
+let logpath = ""
+export function file() {
+  return logpath
+}
+let write = (msg: any) => {
+  process.stderr.write(msg)
+  return msg.length
+}
+
+export async function init(options: Options) {
+  if (options.level) level = options.level
+  void cleanup(Global.Path.log)
+  if (options.print) return
+  logpath = path.join(
+    Global.Path.log,
+    options.dev ? "dev.log" : new Date().toISOString().split(".")[0].replace(/:/g, "") + ".log",
+  )
+  await fs.truncate(logpath).catch(() => {})
+  const dir = path.dirname(logpath)
+  const stream = createStream(path.basename(logpath), {
+    size: "50M",
+    maxFiles: 10,
+    history: ".log-history",
+    path: dir,
+  })
+  stream.on("rotation", () => {
+    if (!existsSync(dir)) return
+
+    try {
+      // RATIONALE: If current log path was deleted while stream still holds the fd,
+      // rotating-file-stream will try to rename a missing path and emit ENOENT.
+      writeFileSync(logpath, "", { flag: "wx" })
+    } catch (err) {
+      if (typeof err === "object" && err && "code" in err && err.code === "EEXIST") return
+
+      const msg = err instanceof Error ? err.message : String(err)
+      process.stderr.write("log stream warning: " + msg + "\n")
+    }
+  })
+  stream.on("error", (err: Error) => {
+    process.stderr.write("log stream error: " + err.message + "\n")
+  })
+  stream.on("warning", (err: Error) => {
+    process.stderr.write("log stream warning: " + err.message + "\n")
+  })
+  write = (msg: any) => {
+    stream.write(msg)
+    return msg.length
+  }
+}
+
+async function cleanup(dir: string) {
+  const files = (
+    await Glob.scan("????-??-??T??????.log", {
+      cwd: dir,
+      absolute: false,
+      include: "file",
+    }).catch(() => [])
+  )
+    .filter((file) => path.basename(file) === file)
+    .sort()
+  if (files.length <= keep) return
+
+  const doomed = files.slice(0, -keep)
+  await Promise.all(doomed.map((file) => fs.unlink(path.join(dir, file)).catch(() => {})))
+}
+
+function formatError(error: Error, depth = 0): string {
+  const result = error.message
+  return error.cause instanceof Error && depth < 10
+    ? result + " Caused by: " + formatError(error.cause, depth + 1)
+    : result
+}
+
+let last = Date.now()
+export function create(tags?: Record<string, any>) {
+  tags = tags || {}
+
+  const service = tags["service"]
+  if (service && typeof service === "string") {
+    const cached = loggers.get(service)
+    if (cached) {
+      return cached
+    }
+  }
+
+  function build(message: any, extra?: Record<string, any>) {
+    const prefix = Object.entries({
+      ...tags,
+      ...extra,
+    })
+      .filter(([_, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => {
+        const prefix = `${key}=`
+        if (value instanceof Error) return prefix + formatError(value)
+        if (typeof value === "object") return prefix + JSON.stringify(value)
+        return prefix + value
+      })
+      .join(" ")
+    const next = new Date()
+    const diff = next.getTime() - last
+    last = next.getTime()
+    return [next.toISOString().split(".")[0], "+" + diff + "ms", prefix, message].filter(Boolean).join(" ") + "\n"
+  }
+  const result: Logger = {
+    debug(message?: any, extra?: Record<string, any>) {
+      if (shouldLog("DEBUG")) {
+        write("DEBUG " + build(message, extra))
+      }
+    },
+    info(message?: any, extra?: Record<string, any>) {
+      if (shouldLog("INFO")) {
+        write("INFO  " + build(message, extra))
+      }
+    },
+    error(message?: any, extra?: Record<string, any>) {
+      if (shouldLog("ERROR")) {
+        write("ERROR " + build(message, extra))
+      }
+    },
+    warn(message?: any, extra?: Record<string, any>) {
+      if (shouldLog("WARN")) {
+        write("WARN  " + build(message, extra))
+      }
+    },
+    tag(key: string, value: string) {
+      if (tags) tags[key] = value
+      return result
+    },
+    clone() {
+      return create({ ...tags })
+    },
+    time(message: string, extra?: Record<string, any>) {
+      const now = Date.now()
+      result.info(message, { status: "started", ...extra })
+      function stop() {
+        result.info(message, {
+          status: "completed",
+          duration: Date.now() - now,
+          ...extra,
+        })
+      }
+      return {
+        stop,
+        [Symbol.dispose]() {
+          stop()
+        },
+      }
+    },
+  }
+
+  if (service && typeof service === "string") {
+    loggers.set(service, result)
+  }
+
+  return result
+}

package/src/util/module.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module"
+import path from "node:path"
+
+export namespace Module {
+  export function resolve(id: string, dir: string) {
+    try {
+      return createRequire(path.join(dir, "package.json")).resolve(id)
+    } catch {}
+  }
+}