heyquilt 0.0.1 → 0.3.90

package/src/relay-lease.js

@@ -0,0 +1,137 @@
+// One live session per repository and branch (plan §8, addendum 16.6). The session that pushes
+// repo@branch holds its lease in the accounts API (git_sync_leases), which works across relay
+// machines; the relay renews every lease it holds every LEASE_HEARTBEAT_MS, for every session active
+// in the last 24 hours (loaded or not), and keeps the list on its disk so a restart picks them up.
+// A lease lapses LEASE_TTL_MS after its last heartbeat (two missed: a crashed relay's).
+//
+// Fencing: a holder publishes only while its last good heartbeat is younger than LEASE_TTL_MS minus
+// PUSH_MARGIN_MS (a push's whole timeout, plus clock skew), and the API grants the lease to anyone
+// else only once LEASE_TTL_MS has passed since that heartbeat: so a holder cut off from the API has
+// stopped pushing before another can start. Every push is also a compare-and-swap on GitHub's ref
+// (forward from the head the relay read), so two pushes can never both land on the same head, and a
+// grant raises the generation, which the old holder learns at its next heartbeat.
+//
+// Without the API (a relay on its own) the leases live in this process, with the same rules.
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const LEASE_TTL_MS = 2 * 60 * 1000
+export const LEASE_HEARTBEAT_MS = 30 * 1000
+export const LEASE_IDLE_MS = 24 * 60 * 60 * 1000
+export const PUSH_MARGIN_MS = 70 * 1000
+
+const local = new Map() // repo\0branch -> { room, generation, heartbeatAt } (no API: this process only)
+export function resetLocalLeases () { local.clear() }
+
+function localStore (now) {
+  return {
+    async take ({ repo, branch, room, ttlMs }) {
+      const k = `${repo}\0${branch}`
+      const cur = local.get(k)
+      const t = now()
+      if (!cur) { local.set(k, { room, generation: 1, heartbeatAt: t }); return { ok: true, generation: 1, room } }
+      const lapsed = cur.heartbeatAt < t - ttlMs
+      if (cur.room === room && !lapsed) { cur.heartbeatAt = t; return { ok: true, generation: cur.generation, room } }
+      if (!lapsed) return { ok: false, room: cur.room, generation: cur.generation }
+      local.set(k, { room, generation: cur.generation + 1, heartbeatAt: t })
+      return { ok: true, generation: cur.generation + 1, room }
+    },
+    async heartbeat ({ repo, branch, room, generation, ttlMs }) {
+      const cur = local.get(`${repo}\0${branch}`)
+      if (!cur || cur.room !== room || cur.generation !== generation) return { ok: false, lost: true, room: cur ? cur.room : '' }
+      if (cur.heartbeatAt < now() - ttlMs) return { ok: false, expired: true }
+      cur.heartbeatAt = now()
+      return { ok: true, generation }
+    },
+    async release ({ repo, branch, room, generation }) {
+      const k = `${repo}\0${branch}`
+      const cur = local.get(k)
+      if (cur && cur.room === room && cur.generation === generation) local.delete(k)
+      return { ok: true }
+    }
+  }
+}
+
+function apiStore ({ apiUrl, secret, fetch }) {
+  const call = async (what, body) => {
+    const res = await fetch(`${String(apiUrl).replace(/\/+$/, '')}/v1/relay/leases/${what}`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${secret}` }, body: JSON.stringify(body) })
+    if (!res.ok) throw new Error(`the accounts API answered ${res.status}`)
+    return res.json()
+  }
+  return { take: (b) => call('take', b), heartbeat: (b) => call('heartbeat', b), release: (b) => call('release', b) }
+}
+
+/**
+ * The relay's leases. `ensure({ repo, branch, room })` resolves { ok, generation } (taking or
+ * renewing it), or { ok: false, room } naming the session that holds it, or { ok: false, error }
+ * when the API can't be reached (then nobody publishes, rather than two). `valid(...)` is the
+ * fencing check right before a push. `tick()` renews and lets go of idle ones.
+ */
+export function leaseKeeper ({ apiUrl = '', secret = '', fetch = globalThis.fetch, dataDir = null, log = () => {}, now = () => Date.now(), ttlMs = LEASE_TTL_MS, marginMs = PUSH_MARGIN_MS, idleMs = LEASE_IDLE_MS, holder = '' } = {}) {
+  const store = apiUrl && secret ? apiStore({ apiUrl, secret, fetch }) : localStore(now)
+  const file = dataDir ? path.join(dataDir, 'leases.json') : null
+  const held = new Map() // repo\0branch -> { repo, branch, room, generation, okAt, activeAt }
+  try { if (file) for (const e of JSON.parse(fs.readFileSync(file, 'utf8'))) if (e && e.repo && e.branch && e.room) held.set(`${e.repo}\0${e.branch}`, { ...e, okAt: 0 }) } catch {}
+  const save = () => { if (!file) return; try { fs.writeFileSync(`${file}.tmp`, JSON.stringify([...held.values()].map(({ okAt, ...e }) => e))); fs.renameSync(`${file}.tmp`, file) } catch {} }
+  const k = (repo, branch) => `${repo}\0${branch}`
+
+  const valid = ({ repo, branch, room }) => {
+    const e = held.get(k(repo, branch))
+    return !!(e && e.room === room && now() - e.okAt < ttlMs - marginMs)
+  }
+
+  const ensure = async ({ repo, branch, room }) => {
+    const e = held.get(k(repo, branch))
+    if (e && e.room === room) e.activeAt = now()
+    if (valid({ repo, branch, room })) return { ok: true, generation: e.generation }
+    let r
+    try {
+      r = e && e.room === room && e.generation ? await store.heartbeat({ repo, branch, room, generation: e.generation, ttlMs }) : null
+      if (!r || !r.ok) r = await store.take({ repo, branch, room, holder, ttlMs })
+    } catch (err) { return { ok: false, error: err.message } }
+    if (!r.ok) {
+      if (e && e.room === room) { held.delete(k(repo, branch)); save() }
+      return { ok: false, room: r.room || '' }
+    }
+    held.set(k(repo, branch), { repo, branch, room, generation: r.generation, okAt: now(), activeAt: now() })
+    save()
+    return { ok: true, generation: r.generation }
+  }
+
+  const release = async ({ repo, branch, room }) => {
+    const e = held.get(k(repo, branch))
+    if (!e || e.room !== room) return false
+    held.delete(k(repo, branch))
+    save()
+    try { await store.release({ repo, branch, room, generation: e.generation }) } catch {}
+    return true
+  }
+
+  /** Renews every lease held for a session active in the last 24 hours; lets go of the rest. Returns those lost. */
+  const tick = async ({ ended = () => false } = {}) => {
+    const lost = []
+    for (const e of [...held.values()]) {
+      if (ended(e.room) || now() - (e.activeAt || 0) > idleMs) { await release(e); continue }
+      try {
+        const r = await store.heartbeat({ repo: e.repo, branch: e.branch, room: e.room, generation: e.generation, ttlMs })
+        if (r.ok) { e.okAt = now(); continue }
+        const again = r.expired ? await store.take({ repo: e.repo, branch: e.branch, room: e.room, holder, ttlMs }) : null
+        if (again && again.ok) { e.generation = again.generation; e.okAt = now(); save(); continue }
+        held.delete(k(e.repo, e.branch)); save()
+        lost.push({ ...e, to: (again && again.room) || r.room || '' })
+        log(`lease: ${e.repo} ${e.branch} is no longer ${e.room}'s (${(again && again.room) || r.room || 'lapsed'})`)
+      } catch (err) { log(`lease: could not renew ${e.repo} ${e.branch}: ${err.message}`) }
+    }
+    return lost
+  }
+
+  /** The session moved to another relay machine, which renews its leases from now on (same session, same generation): this one stops. */
+  const forget = (room) => {
+    let n = 0
+    for (const [key, e] of held) if (e.room === room) { held.delete(key); n++ }
+    if (n) save()
+    return n
+  }
+
+  return { ensure, valid, release, tick, forget, held: () => [...held.values()], local: !(apiUrl && secret) }
+}

package/src/relay-lfs.js

@@ -0,0 +1,37 @@
+// Git LFS for the relay's commits (plan §10): a file the repository's .gitattributes puts through
+// filter=lfs goes to GitHub's LFS store through the batch API, and the commit carries its pointer.
+import crypto from 'node:crypto'
+
+/** Git's LFS pointer for `bytes` (sha256 oid and size). */
+export function lfsPointer (bytes) {
+  const oid = crypto.createHash('sha256').update(bytes).digest('hex')
+  return { oid, size: bytes.length, text: `version https://git-lfs.github.com/spec/v1\noid sha256:${oid}\nsize ${bytes.length}\n` }
+}
+
+/**
+ * Uploads `bytes` to the LFS store of the repository at `remoteUrl` (https://github.com/owner/name.git),
+ * signed in with `token`: the batch API says where (or that it is there already), then the upload and,
+ * when asked, the verify call. Resolves the pointer text to commit; throws with what went wrong.
+ */
+export async function lfsUpload ({ remoteUrl, token = null, bytes, fetch = globalThis.fetch }) {
+  const p = lfsPointer(bytes)
+  const base = String(remoteUrl).replace(/\/+$/, '').replace(/(\.git)?$/, '.git')
+  const auth = token ? { authorization: `Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}` } : {}
+  const json = { accept: 'application/vnd.git-lfs+json', 'content-type': 'application/vnd.git-lfs+json' }
+  const res = await fetch(`${base}/info/lfs/objects/batch`, { method: 'POST', headers: { ...json, ...auth }, body: JSON.stringify({ operation: 'upload', transfers: ['basic'], objects: [{ oid: p.oid, size: p.size }] }) })
+  if (!res.ok) throw new Error(`Git LFS answered ${res.status}${res.status === 404 ? ' (is LFS on for this repository?)' : ''}`)
+  const body = await res.json().catch(() => ({}))
+  const o = (Array.isArray(body.objects) ? body.objects : [])[0] || {}
+  if (o.error) throw new Error(`Git LFS: ${o.error.message || o.error.code}`)
+  const up = o.actions && o.actions.upload
+  if (up && up.href) {
+    const r = await fetch(up.href, { method: 'PUT', headers: { 'content-type': 'application/octet-stream', ...(up.header || {}) }, body: bytes })
+    if (!r.ok) throw new Error(`Git LFS upload answered ${r.status}`)
+  }
+  const verify = o.actions && o.actions.verify
+  if (verify && verify.href) {
+    const r = await fetch(verify.href, { method: 'POST', headers: { ...json, ...(verify.header || {}) }, body: JSON.stringify({ oid: p.oid, size: p.size }) })
+    if (!r.ok) throw new Error(`Git LFS verify answered ${r.status}`)
+  }
+  return p.text
+}