@smthrs/plugin 0.0.0-stage → 1.0.0-rc.4

package/src/internal/Boundary.ts

@@ -0,0 +1,252 @@
+/**
+ * Inert JSON admission for plugin configuration and cache identity.
+ *
+ * Reflection is descriptor-only: accessors never execute, hostile proxies are
+ * refused, and accepted values are detached before they are frozen.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+
+import * as BoundedJson from "@smthrs/canonical/BoundedJson"
+
+/**
+ * Strict JSON value accepted by the boundary.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Json = BoundedJson.Json
+
+/**
+ * Resource bounds for one admitted tree.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Limits = BoundedJson.StrictLimits
+
+/**
+ * Successful admission.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface AdmissionSuccess {
+  readonly ok: true
+  readonly value: Json
+}
+
+/**
+ * Refusal with a stable value path.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface AdmissionFailure {
+  readonly ok: false
+  readonly path: string
+  readonly complaint: string
+}
+
+/**
+ * Result of inert JSON admission.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Admission = AdmissionSuccess | AdmissionFailure
+
+/**
+ * Default configuration bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const defaultLimits: Limits = Object.freeze({
+  maxBytes: 1024 * 1024,
+  maxDepth: 64,
+  maxMembers: 4_096,
+  maxNodes: 8_192,
+  maxStringBytes: 64 * 1024,
+  maxKeyBytes: 1_024
+})
+
+/**
+ * Tests whether a string contains paired UTF-16 surrogate units.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const isWellFormedText = (value: string): boolean => value.isWellFormed()
+
+const childPath = (path: string, key: string): string =>
+  /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`
+
+const encodedStringBytes = (value: string): number => BoundedJson.encodedStringBytes(value)!
+
+// Paths contain only well-formed text and JSON-escaped keys. Count their JSON
+// bytes without encoding the whole path, reserving quotes and a truncation marker.
+const boundedPath = (path: string): string => {
+  let bytes = 2 + 3
+  let prefix = ""
+  for (const character of path) {
+    const point = character.codePointAt(0)!
+    bytes += character === "\"" || character === "\\"
+      ? 2
+      : point <= 0x7f
+      ? 1
+      : point <= 0x7ff
+      ? 2
+      : point <= 0xffff
+      ? 3
+      : 4
+    if (bytes > 192) return `${prefix}...`
+    prefix += character
+  }
+  return path
+}
+
+interface Totals {
+  bytes: number
+  members: number
+  nodes: number
+  depth: number
+}
+
+interface Entry {
+  readonly keyBytes: number
+  readonly totals: Totals
+}
+
+interface Snapshot {
+  readonly totals: Totals
+  readonly entries: Map<string, Entry>
+}
+
+// Only detached containers constructed here enter this map. Mutable caller
+// objects and Object.freeze alone never establish admission.
+const snapshots = new WeakMap<object, Snapshot>()
+
+const scalarTotals = (bytes: number): Totals => ({ bytes, members: 0, nodes: 1, depth: 0 })
+
+const total = (entries: ReadonlyMap<string, Entry>): Totals => {
+  const totals: Totals = { bytes: 2 + Math.max(0, entries.size - 1), members: entries.size, nodes: 1, depth: 1 }
+  for (const entry of entries.values()) {
+    totals.bytes += entry.keyBytes + entry.totals.bytes
+    totals.members += entry.totals.members
+    totals.nodes += entry.totals.nodes
+    totals.depth = Math.max(totals.depth, 1 + entry.totals.depth)
+  }
+  return totals
+}
+
+const remember = (value: ReadonlyArray<Json> | { readonly [key: string]: Json }): void => {
+  const entries = new Map<string, Entry>()
+  for (const [key, child] of Object.entries(value)) {
+    entries.set(key, {
+      keyBytes: Array.isArray(value) ? 0 : encodedStringBytes(key) + 1,
+      totals: typeof child === "object" && child !== null ?
+        snapshots.get(child)!.totals
+        : scalarTotals(typeof child === "string" ? encodedStringBytes(child) : String(child).length)
+    })
+  }
+  snapshots.set(value, { totals: total(entries), entries })
+}
+
+/**
+ * Copies one strict JSON tree under explicit resource bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const admit = (input: unknown, limits: Limits = defaultLimits): Admission => {
+  const result = BoundedJson.admitStrict(input, limits, {
+    ordinaryRecords: true,
+    boundedText: true,
+    onContainer: remember
+  })
+  return result.ok ? result : {
+    ...result,
+    path: boundedPath(result.path),
+    complaint: result.complaint === "must be dense and have no extra properties"
+      ? "must be a dense array with no extra properties" :
+      result.complaint
+  }
+}
+
+/**
+ * Admits only a JSON record at the root.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const record = (
+  input: unknown,
+  limits: Limits = defaultLimits
+): AdmissionSuccess | AdmissionFailure => {
+  const admitted = admit(input, limits)
+  return admitted.ok && (admitted.value === null || Array.isArray(admitted.value) || typeof admitted.value !== "object")
+    ? { ok: false, path: "$", complaint: "must be a JSON record" }
+    : admitted
+}
+
+/**
+ * Merges two independently admitted records, retaining unchanged subtrees.
+ * Both operands must come from successful admission, and the patch must be a
+ * fresh copy: their trees must be disjoint. Each output branch then comes from
+ * at most one location in either tree, preserving the no-repeated-reference
+ * invariant without walking retained subtrees. Limits apply to the result.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const mergeRecords = (
+  base: { readonly [key: string]: Json },
+  patch: { readonly [key: string]: Json },
+  limits: Limits = defaultLimits
+): Admission => {
+  const merge = (
+    left: { readonly [key: string]: Json },
+    right: { readonly [key: string]: Json },
+    path: string
+  ): Admission => {
+    const entries = new Map(snapshots.get(left)!.entries)
+    const result = { ...left }
+    for (const [key, entry] of snapshots.get(right)!.entries) {
+      const previous = left[key]
+      const next = right[key]!
+      if (
+        typeof previous === "object" && previous !== null && !Array.isArray(previous) &&
+        typeof next === "object" && next !== null && !Array.isArray(next)
+      ) {
+        const merged = merge(
+          previous as { readonly [key: string]: Json },
+          next as { readonly [key: string]: Json },
+          childPath(path, key)
+        )
+        if (!merged.ok) return merged
+        result[key] = merged.value
+        entries.set(key, { keyBytes: entry.keyBytes, totals: snapshots.get(merged.value as object)!.totals })
+      } else {
+        result[key] = next
+        entries.set(key, entry)
+      }
+    }
+    const totals = total(entries)
+    const complaint = totals.members > limits.maxMembers ?
+      `exceeds the ${limits.maxMembers}-member limit`
+      : totals.nodes > limits.maxNodes ?
+      `exceeds the ${limits.maxNodes}-node limit`
+      : totals.bytes > limits.maxBytes ?
+      `exceeds the ${limits.maxBytes}-byte limit`
+      : totals.depth > limits.maxDepth ?
+      `exceeds the depth limit of ${limits.maxDepth}`
+      : undefined
+    if (complaint !== undefined) return { ok: false, path: boundedPath(path), complaint }
+    Object.freeze(result)
+    snapshots.set(result, { totals, entries })
+    return { ok: true, value: result }
+  }
+  return merge(base, patch, "$")
+}

package/src/internal/mergePluginLayers.ts

@@ -0,0 +1,57 @@
+/**
+ * Effect layer composition for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+
+import { Action } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type { FlowsPlugin } from "../Plugin.ts"
+import { PluginError } from "../PluginError.ts"
+
+/**
+ * Merges plugin layers left-to-right, wrapping each build failure as
+ * `layer_failed`, then seals the cache environment: it is supplied beneath
+ * the plugin layers and overrides anything they output, and an absent
+ * declaration stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const mergePluginLayers = <H>(
+  plugins: ReadonlyArray<FlowsPlugin<H>>,
+  cacheEnvironment: Action.CacheEnvironment | undefined
+): Layer.Layer<any, PluginError, any> => {
+  const layers = plugins.flatMap((plugin) =>
+    plugin.layer
+      ? [
+        Layer.catchCause(plugin.layer, (cause) =>
+          Layer.effectDiscard(
+            Effect.fail(
+              new PluginError({
+                code: "layer_failed",
+                message: `plugin "${plugin.name}" failed to build its layer`,
+                plugin: plugin.name,
+                cause
+              })
+            )
+          )) as Layer.Layer<any, PluginError, any>
+      ]
+      : []
+  )
+  const merged = (layers.length === 0
+    ? Layer.empty
+    : layers.reduce((accumulated, next) => Layer.provideMerge(next, accumulated))) as Layer.Layer<any, PluginError, any>
+  // The sealed environment is provided beneath the plugin layers so they can
+  // read it, then merged last so it overrides any plugin output. An absent
+  // declaration is sealed as `undefined`, so no plugin layer can declare or
+  // replace the composition's cache identity.
+  const environment = Layer.succeed(Action.CurrentCacheEnvironment)(cacheEnvironment) as unknown as Layer.Layer<
+    any,
+    PluginError,
+    any
+  >
+  return Layer.merge(Layer.provideMerge(merged, environment), environment)
+}

package/src/internal/snapshotCacheEnvironment.ts

@@ -0,0 +1,77 @@
+/**
+ * Cache identity admission for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+
+import { Action } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FlowsPlugin } from "../Plugin.ts"
+import { PluginError } from "../PluginError.ts"
+import * as Boundary from "./Boundary.ts"
+
+const escapePluginIdentityPart = (value: string): string =>
+  // Percent must be escaped first so literal escape-looking text remains distinct from the `@` escape added next.
+  value.replaceAll("%", "%25").replaceAll("@", "%40")
+
+/**
+ * Admits a caller cache environment and prepends one escaped `name@version`
+ * identity per plugin, in resolved order. An absent input stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const snapshotCacheEnvironment = <H>(
+  input: unknown,
+  plugins: ReadonlyArray<FlowsPlugin<H>>
+): Effect.Effect<Action.CacheEnvironment | undefined, PluginError> => {
+  if (input === undefined) return Effect.succeed(undefined)
+  const pluginIdentities: Array<string> = []
+  for (const plugin of plugins) {
+    if (plugin.version === undefined) {
+      return Effect.fail(
+        new PluginError({
+          code: "cache_environment_invalid",
+          message: `cache environment requires a version for plugin "${plugin.name}"`,
+          path: "$.version",
+          plugin: plugin.name
+        })
+      )
+    }
+    pluginIdentities.push(`${escapePluginIdentityPart(plugin.name)}@${escapePluginIdentityPart(plugin.version)}`)
+  }
+  const admitted = Boundary.record(input)
+  if (!admitted.ok) {
+    return Effect.fail(
+      new PluginError({
+        code: "cache_environment_invalid",
+        message: `cache environment ${admitted.complaint}`,
+        path: `$options.cacheEnvironment${admitted.path.slice(1)}`
+      })
+    )
+  }
+  return Schema.decodeUnknownEffect(Action.CacheEnvironment)(admitted.value).pipe(
+    Effect.mapError(() =>
+      new PluginError({
+        code: "cache_environment_invalid",
+        message: "cache environment does not match the complete cache identity schema",
+        path: "$options.cacheEnvironment"
+      })
+    ),
+    Effect.map((environment) => {
+      const capabilities: Record<string, ReadonlyArray<string>> = {}
+      for (const name of Object.keys(environment.capabilities)) {
+        Object.defineProperty(capabilities, name, {
+          value: Object.freeze([...environment.capabilities[name]!]),
+          enumerable: true
+        })
+      }
+      return Object.freeze({
+        layers: Object.freeze([...pluginIdentities, ...environment.layers]),
+        capabilities: Object.freeze(capabilities)
+      })
+    })
+  )
+}