@pathmx/core 0.5.0

package/actions/transaction.ts

@@ -0,0 +1,164 @@
+import type { ProposedSourceChange } from "../authority/access.ts"
+import { AccessDeniedError } from "../authority/access.ts"
+import type { Engine } from "../host/engine.ts"
+import type { SourceChange, SourceChangeSet } from "../repository.ts"
+import { createSource } from "../source/index.ts"
+import type { Actor } from "../authority/model.ts"
+import { canonicalSourceId } from "../canonical.ts"
+import { createSourceDraft, type SourceDraft } from "./draft.ts"
+
+export type SourceTransaction = {
+  create(path: string, content: string): Promise<void>
+  update(path: string, content: string): Promise<void>
+  delete(path: string): Promise<void>
+  read(path: string): Promise<string>
+  exists(path: string): Promise<boolean>
+  source(path: string): SourceDraft
+}
+
+export type StagedTransaction = SourceTransaction & {
+  changeSet(): Promise<SourceChangeSet>
+}
+
+type TransactionAccess = Readonly<{
+  readable(path: string): boolean
+  authorize(change: ProposedSourceChange): void
+}>
+
+function createStagedTransaction(
+  engine: Engine,
+  access: TransactionAccess,
+): StagedTransaction {
+  const repo = engine.repo
+  const overlay = new Map<string, string | null>()
+  const drafts = new Map<string, ReturnType<typeof createSourceDraft>>()
+
+  const keyFor = (sourceId: string) => {
+    const normalized = canonicalSourceId(sourceId)
+    return repo.get(normalized)?.path ?? `${normalized}.md`
+  }
+
+  const existsKey = async (key: string) => {
+    if (!access.readable(key)) return false
+    if (overlay.has(key)) return overlay.get(key) !== null
+    return Boolean(repo.atPath(key) ?? repo.get(repo.pathToId(key)))
+  }
+
+  const readKey = async (key: string) => {
+    if (!access.readable(key)) throw new AccessDeniedError()
+    if (overlay.has(key)) {
+      const pending = overlay.get(key)
+      if (pending == null) throw new Error(`Path does not exist: ${key}`)
+      return pending
+    }
+    const source = repo.atPath(key) ?? repo.get(repo.pathToId(key))
+    if (source) return source.content
+    throw new Error(`Path does not exist: ${key}`)
+  }
+
+  const createKey = async (key: string, content: string) => {
+    if (await existsKey(key)) throw new Error(`Path already exists: ${key}`)
+    overlay.set(key, content)
+  }
+
+  const updateKey = async (key: string, content: string) => {
+    if (!access.readable(key)) throw new AccessDeniedError()
+    if (!(await existsKey(key))) throw new Error(`Path does not exist: ${key}`)
+    overlay.set(key, content)
+  }
+
+  const tx: StagedTransaction = {
+    create(sourceId, content) {
+      return createKey(keyFor(sourceId), content)
+    },
+    update(sourceId, content) {
+      return updateKey(keyFor(sourceId), content)
+    },
+    async delete(path) {
+      const key = keyFor(path)
+      if (!access.readable(key)) throw new AccessDeniedError()
+      if (!(await existsKey(key)))
+        throw new Error(`Path does not exist: ${key}`)
+      overlay.set(key, null)
+    },
+    read(sourceId) {
+      return readKey(keyFor(sourceId))
+    },
+    exists(sourceId) {
+      return existsKey(keyFor(sourceId))
+    },
+    source(path) {
+      const key = keyFor(path)
+      let draft = drafts.get(key)
+      if (!draft) {
+        draft = createSourceDraft(
+          key,
+          { create: createKey, update: updateKey, read: readKey },
+          engine.environment.yaml,
+        )
+        drafts.set(key, draft)
+      }
+      return draft
+    },
+    async changeSet() {
+      for (const draft of drafts.values()) await draft.flush()
+      const changes: SourceChange[] = []
+      for (const [path, content] of overlay) {
+        const before = repo.atPath(path)
+        const sourceId = before?.id ?? repo.pathToId(path)
+        const proposed =
+          content == null
+            ? before
+              ? { type: "delete" as const, sourceId, before }
+              : undefined
+            : (() => {
+                const after = createSource(
+                  path,
+                  content,
+                  engine.environment.yaml,
+                )
+                if (!before)
+                  return { type: "create" as const, sourceId: after.id, after }
+                return {
+                  type: "update" as const,
+                  operation: "content" as const,
+                  sourceId: before.id,
+                  before,
+                  after,
+                }
+              })()
+        if (!proposed) throw new Error(`Path does not exist: ${sourceId}`)
+        access.authorize(proposed)
+        if (content == null) changes.push({ type: "delete", path })
+        else
+          changes.push({ type: before ? "replace" : "create", path, content })
+      }
+      overlay.clear()
+      drafts.clear()
+      return { changes }
+    },
+  }
+  return tx
+}
+
+export function createTransaction(
+  engine: Engine,
+  actor: Actor,
+): StagedTransaction {
+  return createStagedTransaction(engine, {
+    readable(path) {
+      return (
+        engine.readAccess(
+          { type: "actor", actor },
+          engine.repo.atPath(path) ?? engine.repo.pathToId(path),
+        ) !== "denied"
+      )
+    },
+    authorize(change) {
+      const decision = engine.authorizeChange(actor, change)
+      if (decision.type === "denied") {
+        throw new AccessDeniedError(decision.code)
+      }
+    },
+  })
+}

package/assets.ts

@@ -0,0 +1,149 @@
+const ASSET_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+export const GENERATED_ASSET_LIMIT = 128
+const encoder = new TextEncoder()
+
+export type ServedAsset = Readonly<{
+  body: string | Blob
+  contentType: string
+}>
+
+type StoredAsset = {
+  name: string
+  asset: ServedAsset
+}
+
+function avalanche(value: number) {
+  value ^= value >>> 16
+  value = Math.imul(value, 0x85ebca6b)
+  value ^= value >>> 13
+  value = Math.imul(value, 0xc2b2ae35)
+  return (value ^ (value >>> 16)) >>> 0
+}
+
+/** Fast streaming 64-bit fingerprint; cache identity, not authentication. */
+class AssetFingerprint {
+  private fnv = 0x811c9dc5
+  private djb = 0x1505
+
+  update(bytes: Uint8Array) {
+    for (let index = 0; index < bytes.length; index++) {
+      const byte = bytes[index]!
+      this.fnv = Math.imul(this.fnv ^ byte, 0x01000193)
+      this.djb = Math.imul(this.djb, 33) ^ byte
+    }
+  }
+
+  digest() {
+    return [avalanche(this.fnv), avalanche(this.djb)]
+      .map((value) => value.toString(16).padStart(8, "0"))
+      .join("")
+  }
+}
+
+function fingerprintHeader(fingerprint: AssetFingerprint, contentType: string) {
+  fingerprint.update(encoder.encode(contentType))
+  fingerprint.update(new Uint8Array([0]))
+}
+
+function textFingerprint(text: string, contentType: string) {
+  const fingerprint = new AssetFingerprint()
+  fingerprintHeader(fingerprint, contentType)
+  fingerprint.update(encoder.encode(text))
+  return fingerprint.digest()
+}
+
+export async function blobFingerprint(blob: Blob, contentType: string) {
+  const fingerprint = new AssetFingerprint()
+  fingerprintHeader(fingerprint, contentType)
+  const reader = blob.stream().getReader()
+  try {
+    while (true) {
+      const chunk = await reader.read()
+      if (chunk.done) return fingerprint.digest()
+      fingerprint.update(chunk.value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function validateAssetName(name: string) {
+  if (!ASSET_NAME.test(name)) {
+    throw new Error(`Invalid generated asset name: ${name}`)
+  }
+}
+
+function assetHref(name: string, hash: string) {
+  const dot = name.lastIndexOf(".")
+  const stem = dot === -1 ? name : name.slice(0, dot)
+  const ext = dot === -1 ? "" : name.slice(dot)
+  return `/.pmx/${stem}-${hash}${ext}`
+}
+
+/**
+ * Publishes generated assets into the local bounded cache. A future CDN or
+ * object-storage backend should extract byte retention behind a general
+ * `AssetStore` (`put`, `get`, `href`) while keeping fingerprinting and key
+ * policy here. Repository assets may share that store, but keep their own
+ * routing and access rules; this LRU must not be their durable CDN origin.
+ */
+export class GeneratedAssets {
+  private assets = new Map<string, StoredAsset>()
+  private latest = new Map<string, ServedAsset & { href: string }>()
+
+  constructor(private limit = GENERATED_ASSET_LIMIT) {}
+
+  get(href: string) {
+    const stored = this.assets.get(href)
+    if (!stored) return
+    this.assets.delete(href)
+    this.assets.set(href, stored)
+    return stored.asset
+  }
+
+  entries() {
+    return [...this.assets].map(
+      ([href, stored]) => [href, stored.asset] as const,
+    )
+  }
+
+  publishText(name: string, text: string, contentType: string) {
+    validateAssetName(name)
+    const current = this.latest.get(name)
+    if (current?.body === text && current.contentType === contentType) {
+      this.get(current.href)
+      return current.href
+    }
+    const href = assetHref(name, textFingerprint(text, contentType))
+    this.retain(name, href, { body: text, contentType })
+    return href
+  }
+
+  async publishBlob(name: string, blob: Blob, contentType = blob.type) {
+    validateAssetName(name)
+    contentType ||= "application/octet-stream"
+    const current = this.latest.get(name)
+    if (current?.body === blob && current.contentType === contentType) {
+      this.get(current.href)
+      return current.href
+    }
+    const href = assetHref(name, await blobFingerprint(blob, contentType))
+    this.retain(name, href, { body: blob, contentType })
+    return href
+  }
+
+  private retain(name: string, href: string, asset: ServedAsset) {
+    this.assets.delete(href)
+    this.assets.set(href, { name, asset })
+    this.latest.set(name, { ...asset, href })
+
+    while (this.assets.size > this.limit) {
+      const oldestHref = this.assets.keys().next().value!
+      const { name: oldestName } = this.assets.get(oldestHref)!
+      this.assets.delete(oldestHref)
+      if (this.latest.get(oldestName)?.href === oldestHref) {
+        this.latest.delete(oldestName)
+      }
+    }
+  }
+}