dotrino-content 0.2.0

package/src/node.js

@@ -0,0 +1,243 @@
+/**
+ * ContentNode = BlobStore (bytes) + Index (metadatos) + cuota/GC (Fase 1).
+ *
+ * Sigue sin saber de red: quien la pone es `agent.js` (Fase 2), que además le dice
+ * qué `owner` representa —la huella de la maestra del vault, la mitad izquierda de
+ * la referencia compartible `ownerId + cid` (DISENO.md §3)— y usa el `acl` para
+ * decidir qué puede salir del node cuando llegue el modo público (§7.2).
+ */
+import { mkdir } from 'node:fs/promises'
+import { BlobStore, isValidCid } from './blobstore.js'
+import { Index } from './db.js'
+
+export { isValidCid }
+
+export class ContentNode {
+  /**
+   * @param {{ dir: string, maxBytes?: number, maxBlobBytes?: number, owner?: string|null,
+   *           store?: any, log?: (m:string)=>void }} opts
+   *   dir: raíz de datos · maxBytes: cuota total de disco (0 = sin límite)
+   *   maxBlobBytes: tamaño máximo por blob (0 = sin límite)
+   *   owner: `ownerId` de la maestra (lo pone el agente al enlazar; null sin vault)
+   *   store: almacén ya montado (`storage.js`); por defecto, disco
+   */
+  constructor (opts) {
+    if (!opts?.dir) throw new Error('falta opts.dir')
+    this.dir = opts.dir
+    this.maxBytes = opts.maxBytes || 0
+    this.maxBlobBytes = opts.maxBlobBytes || 0
+    this.owner = opts.owner || null
+    // El almacén se puede INYECTAR (`storage.js` monta el de bucket cuando toca). Por
+    // defecto, disco: sin configuración, un node funciona con lo que hay en la máquina.
+    this.store = opts.store || new BlobStore(opts.dir)
+    this.index = null
+    /** Subidas al bucket en curso, por cid: para no lanzar dos veces la misma. */
+    this._uploading = new Map()
+    this.log = opts.log || (() => {})
+  }
+
+  async init () {
+    await mkdir(this.dir, { recursive: true })
+    await this.store.init()
+    this.index = new Index(this.dir)
+    return this
+  }
+
+  /**
+   * Sube un stream. Si la cuota no alcanza, intenta GC de no-pineados; si aun
+   * así no cabe, rechaza con code ENOSPC (no borra pineados jamás).
+   */
+  async put (readable, { mime = 'application/octet-stream', enc = 0, ttl = null, acl = null, meta = null } = {}) {
+    const { cid, size, existed } = await this.store.put(readable, {
+      maxBytes: this.maxBlobBytes || undefined
+    })
+    if (this.maxBytes && !existed) {
+      // La cuota es del DISCO, así que cuenta lo que está cacheado aquí, no el
+      // inventario: con bucket detrás, lo desalojado sigue existiendo (§15.11)
+      // pero ya no ocupa nada — contarlo dejaría la cuota excedida para siempre.
+      const over = (this.index.cachedBytes() + size) - this.maxBytes
+      if (over > 0 && this.gc({ needBytes: over }).freed < over) {
+        await this.store.remove(cid)
+        throw Object.assign(new Error('cuota de disco excedida'), { code: 'ENOSPC' })
+      }
+    }
+    this.index.upsert({ cid, size, mime, owner: this.owner, enc, acl, ttl, meta })
+    // Con bucket detrás, la subida va DESPUÉS de responder: quien sube no espera a la
+    // red. Hasta que el bucket confirme, este blob no es desalojable (§15.11).
+    if (!existed) this.backup(cid, { size, mime, public: acl === 'public' })
+    return { cid, size, mime, existed }
+  }
+
+  /** Metadatos de un blob (o null). */
+  stat (cid) {
+    return isValidCid(cid) ? this.index.get(cid) : null
+  }
+
+  /**
+   * Marca un blob como público o privado (`acl`). Es lo único que autoriza a que
+   * los bytes salgan del node cuando esté encendido el modo público (DISENO.md
+   * §7.2); sin `public` explícito, no sale.
+   */
+  setAcl (cid, acl) {
+    const ok = this.index.setAcl(cid, acl)
+    // Publicar mueve los bytes al bucket público, que es OTRO bucket (§15.1). Sin esto
+    // el blob quedaría marcado público y sin estar donde se sirve lo público.
+    if (ok && acl === 'public' && this.store.backed) {
+      const m = this.index.get(cid)
+      if (m && !m.enc) this.backup(cid, { size: m.size, mime: m.mime, public: true })
+    }
+    return ok
+  }
+
+  /**
+   * Sube un blob a su bucket y lo marca `remote` **solo cuando el bucket confirma**.
+   * Marcar al lanzar la subida es exactamente el error que deja perder contenido: un
+   * GC oportuno se llevaría la única copia que existe.
+   *
+   * No espera nadie a esto (se lanza y se olvida), pero un fallo se REPORTA: lo que no
+   * subió sigue siendo la cola pendiente del índice, y se reintenta al arrancar.
+   */
+  backup (cid, meta) {
+    if (!this.store.backed || this._uploading.has(cid)) return null
+    const p = this.store.upload(cid, meta)
+      .then(() => { this.index.setRemote(cid, true) })
+      .catch((e) => { this.log(`[almacén] no se pudo subir ${cid.slice(0, 14)}…: ${e.message}`) })
+      .finally(() => this._uploading.delete(cid))
+    this._uploading.set(cid, p)
+    return p
+  }
+
+  /**
+   * Reintenta lo que quedó sin subir. Se llama al arrancar: un reinicio a media subida
+   * no debe perder el pendiente, y por eso la cola es una consulta al índice y no una
+   * lista en memoria.
+   */
+  async backupPending (limit = 100) {
+    if (!this.store.backed) return { pending: 0 }
+    const rows = this.index.pendingUpload(limit)
+    for (const r of rows) {
+      const m = this.index.get(r.cid)
+      if (m) await this.backup(r.cid, { size: m.size, mime: m.mime, public: m.acl === 'public' })
+    }
+    return { pending: rows.length }
+  }
+
+  /**
+   * Metadatos de presentación (nombre/título/descripción). Es lo único con lo que
+   * el permalink público arma su tarjeta (DISENO.md §7.3): sin esto una vista
+   * previa solo puede decir el tipo y el tamaño.
+   */
+  setMeta (cid, meta) {
+    return this.index.setMeta(cid, meta)
+  }
+
+  /** Enlaza la miniatura pública de un blob (la genera la app, no el node). */
+  setThumbnail (cid, thumbnailCid) {
+    return this.index.setThumbnail(cid, thumbnailCid)
+  }
+
+  /** Índice de lo servible al mundo (público y en claro). */
+  listPublic (opts) {
+    return this.index.listPublic(opts)
+  }
+
+  /**
+   * ¿Puede este blob salir del node por el HTTP público? Dos condiciones, y las
+   * dos se comprueban aquí —en el único sitio por donde salen los bytes— aunque
+   * `ops.acl` ya impida marcar público lo cifrado: un índice traído de otra
+   * versión, o tocado a mano, no debe poder abrir una puerta.
+   * @returns {any|null} los metadatos si es servible, null si no.
+   */
+  publicStat (cid) {
+    const meta = this.stat(cid)
+    if (!meta || meta.acl !== 'public' || meta.enc) return null
+    return meta
+  }
+
+  /**
+   * ReadStream del blob; range = { start, end } inclusivo.
+   *
+   * Anota el acceso (`lastRead`), que es lo que ordena el desalojo de la caché
+   * (§15.11): sin esto, el GC tira lo más antiguo, y lo antiguo y muy pedido es
+   * justo lo que hay que conservar.
+   */
+  read (cid, range) {
+    this.index.touch(cid)
+    return this.store.read(cid, range)
+  }
+
+  async remove (cid) {
+    await this.store.remove(cid)
+    this.index.remove(cid)
+  }
+
+  list () {
+    return this.index.list()
+  }
+
+  pin (cid, pinned = true) {
+    return this.index.setPinned(cid, pinned)
+  }
+
+  stats () {
+    const cached = this.index.cachedBytes()
+    return {
+      blobs: this.index.count(),
+      // `bytes` es lo que ocupa el disco (lo que mira la cuota); `totalBytes` es
+      // el inventario entero, que con bucket es mayor porque incluye lo desalojado.
+      bytes: cached,
+      totalBytes: this.index.totalBytes(),
+      maxBytes: this.maxBytes || null,
+      backed: this.store.backed === true,
+      dir: this.dir
+    }
+  }
+
+  /**
+   * GC: borra vencidos (ttl) siempre; si `needBytes`, además desaloja
+   * no-pineados más viejos hasta liberar esa cantidad.
+   * Síncrono sobre el índice; el borrado de disco es fire-and-forget seguro
+   * (los bytes huérfanos se re-borran en el próximo GC vía índice… el índice
+   * es la fuente de verdad de qué existe).
+   */
+  /**
+   * Libera espacio. Hace DOS cosas distintas y conviene no confundirlas (§15.11):
+   *
+   *  · **Caducar** (`ttl` vencido) es borrar de verdad: se va la fila, los bytes
+   *    locales y —si hay bucket— también los de allí. Es lo que se pidió al subir.
+   *  · **Desalojar** por cuota es tirar una copia caliente. Con bucket detrás solo
+   *    toca lo que el bucket YA confirmó (`remote = 1`) y **la fila se queda** con
+   *    `cached = 0`: si se fuera, el blob quedaría en el bucket sin ACL, sin dueño
+   *    y sin tipo. Sin bucket no hay segunda copia, así que desalojar ES destruir
+   *    y se comporta como hasta ahora.
+   */
+  gc ({ needBytes = 0, now = Date.now() } = {}) {
+    let freed = 0
+    const backed = this.store.backed === true
+
+    const destroy = ({ cid, size }) => {
+      this.index.remove(cid)
+      this.store.remove(cid).catch(() => {})
+      freed += size
+    }
+    const evict = ({ cid, size }) => {
+      if (!backed) return destroy({ cid, size })
+      this.store.evict(cid).catch(() => {})
+      this.index.setCached(cid, false)
+      freed += size
+    }
+
+    for (const b of this.index.expired(now)) destroy(b)
+    if (needBytes > freed) {
+      for (const b of this.index.evictable({ requireRemote: backed })) {
+        if (freed >= needBytes) break
+        evict(b)
+      }
+    }
+    return { freed }
+  }
+
+  close () {
+    this.index?.close()
+  }
+}

package/src/ops.js

@@ -0,0 +1,207 @@
+/**
+ * ops.js — las operaciones del PLANO DE CONTROL del node (DISENO.md §5.1 y §7).
+ *
+ * Es lo que tus propias apps pueden pedirle a este node a distancia: ver qué
+ * guarda, retener, soltar, borrar y marcar qué es público. Módulo PURO: no sabe de
+ * red, de sesiones ni de firmas — recibe un objeto ya descifrado y autorizado, y
+ * devuelve la respuesta. Así se prueba entero sin levantar nada, y quien autoriza
+ * (`agent.js`, vía `@dotrino/remote-agent`) queda en un solo sitio.
+ *
+ * SOBRE `put` Y `get`: existen, pero con un TOPE DURO de un mensaje (256 KB), y
+ * eso no es una limitación técnica que haya que levantar después — es la frontera
+ * (§7.1). El plano de control es el proxy del ecosistema: sus tramas son de 1 MB y
+ * su cola es de mensajes, no un almacén, y meter contenido por ahí sería usar la
+ * infraestructura de Dotrino como transporte, que es la regla dura 3. Por eso NO
+ * hay subida por partes: si algo no cabe en un mensaje, es que no es un mensaje.
+ *
+ * Lo que sí es un mensaje y por eso pasa: **un post** (un eco pesa cientos de
+ * bytes) y **una miniatura** (decenas de KB). Los originales suben en local por
+ * HTTP y, entre aparatos, por P2P — que es lo que este tope deja pendiente a
+ * propósito en vez de disimularlo con un troceado.
+ *
+ * El contrato de errores es `code`, no la frase: quien recibe compara `code`
+ * (`bad-request`, `not-found`, `unknown-op`, `failed`), que es lo estable. La frase
+ * es para un humano leyendo una bitácora.
+ */
+
+/** Valores admitidos de ACL. Público es OPT-IN explícito; lo que no se dice, privado. */
+export const ACL = Object.freeze({ PUBLIC: 'public', PRIVATE: 'private' })
+
+/**
+ * Tope de lo que puede entrar o salir por el plano de control, en bytes crudos.
+ * En base64 dentro del sobre cifrado son ~350 KB, cómodos bajo la trama de 1 MB
+ * del proxy. **Es una frontera de diseño, no un parámetro a subir**: lo que no
+ * cabe aquí no es un mensaje y va por el otro camino.
+ */
+export const CONTROL_PLANE_MAX_BYTES = 256 * 1024
+
+import { Readable } from 'node:stream'
+import { isValidCid } from './blobstore.js'
+
+const ok = (rid, result) => ({ rid, ok: true, ...result })
+const fail = (rid, code, error) => ({ rid, ok: false, code, error })
+
+/**
+ * Metadatos de presentación, quedándose SOLO con los campos conocidos y
+ * recortados. Esto acaba en un HTML público (§7.3), así que no se guarda lo que
+ * llegue: ni campos de más ni textos sin fin.
+ * @returns {{name?:string,title?:string,description?:string}|null}
+ */
+function cleanMeta (src) {
+  if (!src || typeof src !== 'object') return null
+  const out = Object.fromEntries(['name', 'title', 'description']
+    .map((k) => [k, typeof src[k] === 'string' ? src[k].trim().slice(0, 300) : null])
+    .filter(([, v]) => v))
+  return Object.keys(out).length ? out : null
+}
+
+/**
+ * Construye el despachador de operaciones de un node.
+ *
+ * @param {import('./node.js').ContentNode} node
+ * @param {{ owner?: string|null, version?: string }} [meta]
+ *   owner: `ownerId` (huella de la maestra) que este node representa — es la mitad
+ *   de la referencia compartible `ownerId + cid` (§3).
+ * @returns {(msg: any) => Promise<any>}
+ */
+export function createOps (node, { owner = null, version = null } = {}) {
+  /** Operaciones que exigen un `cid` válido y que el blob exista. */
+  const withBlob = (fn) => async (msg) => {
+    const cid = typeof msg.cid === 'string' ? msg.cid : null
+    if (!cid) return fail(msg.rid, 'bad-request', 'cid is required')
+    const meta = node.stat(cid)
+    if (!meta) return fail(msg.rid, 'not-found', 'no such cid')
+    return fn(msg, cid, meta)
+  }
+
+  const handlers = {
+    /** Quién es este node: sirve de saludo y de comprobación de vida. */
+    hello: async (msg) => ok(msg.rid, {
+      owner, version, stats: node.stats(), maxBytes: CONTROL_PLANE_MAX_BYTES
+    }),
+
+    /**
+     * Guardar algo pequeño desde otro aparato tuyo. Los bytes llegan en base64
+     * dentro del sobre ya cifrado de la sesión, en UN mensaje: no hay subida por
+     * partes y no la va a haber (ver la cabecera del archivo).
+     *
+     * Que el aparato esté autorizado ya lo comprobó `verifyChain` antes de que
+     * esto se llame; aquí solo se comprueba la forma y el tamaño.
+     */
+    put: async (msg) => {
+      if (typeof msg.data !== 'string') return fail(msg.rid, 'bad-request', 'data (base64) is required')
+      let buf
+      try { buf = Buffer.from(msg.data, 'base64') } catch { return fail(msg.rid, 'bad-request', 'data is not valid base64') }
+      if (!buf.length) return fail(msg.rid, 'bad-request', 'empty payload')
+      if (buf.length > CONTROL_PLANE_MAX_BYTES) {
+        return fail(msg.rid, 'too-large',
+          `the control plane carries up to ${CONTROL_PLANE_MAX_BYTES} bytes; upload larger blobs locally or peer to peer`)
+      }
+      const enc = msg.enc ? 1 : 0
+      // Mismo cerrojo que en `acl`, y por lo mismo: decir que algo cifrado es
+      // público solo engaña a quien lo mire, porque nadie sin la llave lo lee.
+      const acl = msg.acl === ACL.PUBLIC && !enc ? ACL.PUBLIC : ACL.PRIVATE
+      const ttlMs = Number(msg.ttl) || 0
+      const out = await node.put(Readable.from(buf), {
+        mime: typeof msg.mime === 'string' ? msg.mime : 'application/octet-stream',
+        enc,
+        acl,
+        ttl: ttlMs > 0 ? Date.now() + ttlMs : null,
+        meta: cleanMeta(msg.meta)
+      })
+      return ok(msg.rid, { ...out, acl })
+    },
+
+    /**
+     * Leer algo pequeño de vuelta (otro aparato tuyo, o el mismo tras reinstalar).
+     * Mismo tope, y por la misma razón: esto es el plano de control.
+     */
+    get: withBlob(async (msg, cid, meta) => {
+      if (meta.size > CONTROL_PLANE_MAX_BYTES) {
+        return fail(msg.rid, 'too-large',
+          `${meta.size} bytes do not fit in the control plane; fetch it locally or peer to peer`)
+      }
+      const chunks = []
+      for await (const c of node.read(cid)) chunks.push(c)
+      return ok(msg.rid, {
+        cid, size: meta.size, mime: meta.mime, enc: meta.enc, data: Buffer.concat(chunks).toString('base64')
+      })
+    }),
+
+    list: async (msg) => ok(msg.rid, { blobs: node.list() }),
+
+    stats: async (msg) => ok(msg.rid, { stats: node.stats() }),
+
+    stat: withBlob(async (msg, cid, meta) => ok(msg.rid, { blob: meta })),
+
+    /** Retener: un blob pineado no lo borra el GC ni por cuota ni por ttl. */
+    pin: withBlob(async (msg, cid) => ok(msg.rid, { pinned: node.pin(cid, true) })),
+
+    unpin: withBlob(async (msg, cid) => ok(msg.rid, { pinned: !node.pin(cid, false) })),
+
+    remove: withBlob(async (msg, cid) => {
+      await node.remove(cid)
+      return ok(msg.rid, { removed: cid })
+    }),
+
+    /**
+     * Marcar un blob como público o privado. Es el interruptor que la Fase 3 mira
+     * antes de servir algo por HTTP: sin `public` explícito, no sale del node.
+     */
+    acl: withBlob(async (msg, cid) => {
+      const acl = msg.acl === ACL.PUBLIC ? ACL.PUBLIC : msg.acl === ACL.PRIVATE ? ACL.PRIVATE : null
+      if (!acl) return fail(msg.rid, 'bad-request', `acl must be "${ACL.PUBLIC}" or "${ACL.PRIVATE}"`)
+      const meta = node.stat(cid)
+      // Un blob cifrado no se puede marcar público: nadie sin la llave podría leerlo,
+      // así que decir que lo es solo engaña a quien lo mire.
+      if (acl === ACL.PUBLIC && meta.enc) return fail(msg.rid, 'bad-request', 'an encrypted blob cannot be public')
+      node.setAcl(cid, acl)
+      return ok(msg.rid, { cid, acl })
+    }),
+
+    /**
+     * Metadatos de PRESENTACIÓN (nombre, título, descripción). Es lo único con lo
+     * que la vista previa pública arma su tarjeta (§7.3): sin esto, una tarjeta
+     * solo puede decir el tipo y el tamaño. No forma parte del `cid` —dos nombres
+     * para los mismos bytes son el mismo blob—, por eso se pone aparte.
+     */
+    meta: withBlob(async (msg, cid) => {
+      if (msg.meta !== null && (!msg.meta || typeof msg.meta !== 'object')) {
+        return fail(msg.rid, 'bad-request', 'meta must be an object or null')
+      }
+      const clean = cleanMeta(msg.meta)
+      node.setMeta(cid, clean)
+      return ok(msg.rid, { cid, meta: clean })
+    }),
+
+    /**
+     * Enlaza la miniatura de un blob. La miniatura es OTRO blob (subido por la
+     * app) y tiene que ser pública por su cuenta: enlazarla no la publica.
+     */
+    thumb: withBlob(async (msg, cid) => {
+      const t = msg.thumbnailCid
+      if (t !== null && !isValidCid(t)) return fail(msg.rid, 'bad-request', 'thumbnailCid must be a valid cid or null')
+      if (t && !node.stat(t)) return fail(msg.rid, 'not-found', 'the thumbnail is not in this node')
+      node.setThumbnail(cid, t)
+      return ok(msg.rid, { cid, thumbnailCid: t })
+    }),
+
+    /** Recolección de vencidos (lo que el temporizador hace solo, a pedido). */
+    gc: async (msg) => ok(msg.rid, node.gc())
+  }
+
+  return async function dispatch (msg) {
+    if (!msg || typeof msg !== 'object' || typeof msg.op !== 'string') {
+      return fail(msg?.rid, 'bad-request', 'op is required')
+    }
+    const handler = handlers[msg.op]
+    if (!handler) return fail(msg.rid, 'unknown-op', `unknown op: ${msg.op}`)
+    try {
+      return await handler(msg)
+    } catch (e) {
+      return fail(msg.rid, e?.code === 'ENOSPC' ? 'no-space' : 'failed', e?.message || 'failed')
+    }
+  }
+}
+
+export default { createOps, ACL, CONTROL_PLANE_MAX_BYTES }