Catálogo y almacenamiento grande (catalog, storageLarge, apiVersion 13)¶
Disponible desde Kino 0.9.74
apiVersion 13 llega en Kino 0.9.74, junto con apiVersion 12. Todo Kino anterior a 0.9.74 rechaza un manifiesto con
"apiVersion": 13 ("Este plugin necesita una versión más nueva de Kino").
Un plugin cuya fuente es una biblioteca grande (todos los videos de un canal de Telegram, el archivo completo de un sitio,
una carpeta de medios propia) necesita encontrar cosas entre miles de registros. Guardarlos en kino.storage y filtrar en
JavaScript obliga a cargar la lista entera en los 64 MB de memoria QuickJS de tu plugin en cada búsqueda. kino.catalog
los guarda en una base de datos SQLite que Kino tiene para tu plugin, y busca ahí: tu código solo tiene en la mano la
página que pidió.
Qué almacén usar¶
| Guardas | Usa | Por qué |
|---|---|---|
| Ajustes, un token, un cursor, unos pocos valores JSON pequeños | kino.storage |
256 KB, síncrono, va en una copia de seguridad con contraseña |
| Unos pocos blobs grandes y opacos que lees enteros (un índice en caché, un paquete de llaves) | kino.storage con storageLarge |
16 MB, un archivo por valor, solo en el aparato |
| Miles de registros que buscas, ordenas y paginas | kino.catalog |
hasta 100.000 ítems en un archivo de 64 MiB (unos 670 bytes por ítem en promedio, así que mantén data pequeño), buscados por Kino, nunca cargados enteros |
Cómo se declara¶
"apiVersion": 13,
"capabilities": ["search", "resolve", "catalog"]
catalog es declarativa: nada que exportar, sin línea de consentimiento y sin aprobación (es espacio en este aparato, no
alcance hacia nadie). Un Kino más viejo rechaza el manifiesto ("Este plugin necesita una versión más nueva de Kino"), y un
manifiesto por debajo de apiVersion 13 se rechaza con "The \"catalog\" capability needs apiVersion 13". Un plugin que no
la declara no tiene kino.catalog (typeof kino.catalog === "undefined"), y sign() tampoco.
Las operaciones¶
Cada operación es async (usa await) y responde valores JSON simples. Las seis, con su forma exacta:
| Llamada | Recibe | Responde |
|---|---|---|
kino.catalog.upsert(items) |
una lista de máximo 500 { id, title, sort?, data? } |
{ count }: cuántos ítems se escribieron |
kino.catalog.search(options?) |
{ q?, limit?, offset?, order? }: q por defecto "" (todo), limit por defecto 50 (de 1 a 100), offset por defecto 0 (de 0 a 1.000.000), order por defecto "newest" |
{ items, total }: una página de { id, title, sort, data } y el número de todas las coincidencias |
kino.catalog.get(ids) |
una lista de máximo 500 ids | los ítems encontrados, en el orden pedido; los ids que faltan se saltan, un id repetido sale una vez |
kino.catalog.remove(ids) |
una lista de máximo 500 ids | { count }: cuántos estaban y ya no están |
kino.catalog.clear() |
nada | nada: todos los ítems se van y Kino borra el archivo |
kino.catalog.count() |
nada | el número de ítems |
Un mini-plugin completo, que corre tal como está (las pruebas del kit de Node corren este mismo código contra una fuente
de mentira). Indexa una fuente que pagina sus videos del más nuevo al más viejo, unas pocas páginas por cada llamada a
Inicio para que ninguna llamada pase su límite de tiempo; responde search solo desde el catálogo; quita un video que la
fuente borró cuando alguien intenta reproducirlo; y empieza de nuevo una vez por semana (eso también quita lo que la
fuente borró) o cuando el catálogo vuelve vacío después de una restauración o un reinicio.
// kino-plugin.json (the parts that matter): {"apiVersion": 13, "capabilities": ["home", "search", "resolve", "catalog"], "hosts": ["api.example.org"]}
const BATCH = 500; // maxUpsertBatch
const MAX_TITLE = 300; // maxTitleChars
const PAGES_PER_CALL = 3; // a few source pages per Home call
const ID_RE = /^[A-Za-z0-9._~-]{1,120}$/; // fits a Kino Item id (128 characters) once prefixed with "v"
const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
async function sourcePage(cursor) {
const url = "https://api.example.org/videos" + (cursor ? "?after=" + encodeURIComponent(cursor) : "");
const r = await kino.fetch(url);
if (!r.ok) throw kino.error("unavailable", "the source answered " + r.status);
return r.json(); // { videos: [{ id, caption, date, file, poster }], next }, newest first
}
// At most `max` characters (JavaScript's length, as Kino counts them), never cutting a character in two.
function clip(text, max) {
let t = String(text).slice(0, max);
if (/[\uD800-\uDBFF]$/.test(t)) t = t.slice(0, -1);
return t;
}
// One source video as a catalog item, or null to skip it. A caption can be missing or far longer than 300 characters,
// and one bad item would refuse its whole batch of 500: the title is never empty and always fits, the id fits Kino's
// Item id, and `data` holds only small fields.
function toItem(v) {
const id = String(v.id);
if (!ID_RE.test(id)) return null;
const title = clip(String(v.caption || "").replace(/\s+/g, " ").trim(), MAX_TITLE) || "Video " + id;
return {
id,
title,
sort: Number.isSafeInteger(v.date) ? v.date : 0, // "newest" = the biggest date first
data: { file: clip(v.file || "", 200), poster: v.poster ? clip(v.poster, 500) : null },
};
}
async function upsertAll(items) {
for (let i = 0; i < items.length; i += BATCH) await kino.catalog.upsert(items.slice(i, i + BATCH));
}
// The catalog stays on this device, but kino.storage travels in a backup: after a restore, on a new device or after a
// "damaged" reset the catalog is empty while the markers still say it was indexed. Start over then.
async function forgetIndexIfEmpty() {
if (kino.storage.get("indexedAt") !== null && (await kino.catalog.count()) === 0) {
kino.storage.remove("indexedAt");
kino.storage.remove("cursor");
}
}
// One step of indexing, from Home (20 s per call), never from search (15 s, and the person is waiting):
// - not complete yet: go on with the full pass where the last step stopped (a cursor in kino.storage);
// - complete: read from the newest video and stop at the first page holding an item already indexed;
// - a week after the last full pass: clear and index again.
async function indexStep() {
const at = Number(kino.storage.get("indexedAt"));
if (at && Date.now() - at > WEEK_MS) {
await kino.catalog.clear();
kino.storage.remove("indexedAt");
kino.storage.remove("cursor");
}
const complete = kino.storage.get("indexedAt") !== null;
let cursor = complete ? null : kino.storage.get("cursor");
for (let i = 0; i < PAGES_PER_CALL; i++) {
const page = await sourcePage(cursor);
const items = page.videos.map(toItem).filter((it) => it !== null);
const known = complete && items.length > 0 && (await kino.catalog.get(items.slice(0, BATCH).map((it) => it.id))).length > 0;
await upsertAll(items);
if (known || !page.next) {
if (!complete) {
kino.storage.set("indexedAt", String(Date.now()));
kino.storage.remove("cursor");
}
return;
}
cursor = page.next;
if (!complete) kino.storage.set("cursor", cursor);
}
}
const toKinoItem = (it) => ({ id: "v" + it.id, ref: it.id, title: it.title, kind: "movie", poster: (it.data && it.data.poster) || undefined });
export async function home() {
try {
await forgetIndexIfEmpty();
await indexStep();
} catch (e) {
// The source or the catalog is unavailable right now: show what the catalog already has; the next Home goes on.
if (e.code !== "unavailable") throw e;
kino.log("indexing paused: " + e.message);
}
const newest = await kino.catalog.search({ limit: 20 });
return [{ id: "newest", title: "Newest", items: newest.items.map(toKinoItem) }];
}
export async function search(query) {
// The catalog only: cheap enough for every keystroke, and never the network.
const page = await kino.catalog.search({ q: String(query.q || "").slice(0, 256), limit: 50 });
return page.items.map(toKinoItem);
}
export async function resolve(ref) {
const [item] = await kino.catalog.get([ref]);
if (!item) throw kino.error("not_found", "no longer in the catalog");
const r = await kino.fetch("https://api.example.org/files/" + encodeURIComponent(item.data.file));
if (r.status === 404) {
await kino.catalog.remove([ref]); // the source deleted it: drop it now, not at the weekly rebuild
throw kino.error("not_found", "the source deleted this video");
}
return { url: r.json().url };
}
El id de un Item de Kino tiene que cumplir ^[A-Za-z0-9._~-]{1,128}$; el id de un ítem del catálogo puede ser
cualquier texto de 1 a 128 caracteres, así que conviértelo cuando el tuyo tenga otros caracteres o pase de 128 con el
prefijo (el ejemplo se salta esos videos; un hash del id también sirve).
Cómo busca¶
- Las mayúsculas y las tildes no importan. Kino guarda cada título en minúsculas y sin tildes (Unicode NFD sin las
marcas combinables) y hace lo mismo con
q:"pelicula","PELÍCULA"y"Película"encuentran "Película";"nandu"encuentra "Ñandú". Los caracteres de control que no son espacios (un NUL, un código de escape) se quitan de los dos, así que"ab\u0000zz"y"abzz"encuentran los mismos ítems. - Cada palabra tiene que estar, en cualquier orden, como parte del título.
qse parte por los espacios; cada palabra tiene que aparecer en alguna parte del título:"rojo gato"y"gato rojo"encuentran "El gato ROJO", y"gat roj"también. No hay ranking ni búsqueda aproximada: un ítem coincide o no. %,_y\son caracteres normales. Nunca son comodines:"50%"encuentra "50% off" y no "50 off";"a_b"encuentra "a_b" y no "axb". Ninguna búsqueda puede ejecutar nada: de tu lado no hay SQL en absoluto.- Un
qvacío, en blanco o ausente lista todo (en el orden pedido). - Solo se busca en
title, nunca enidni endata. Pon en el título cada palabra que alguien podría escribir. - Orden.
"newest"(por defecto):sortde mayor a menor;"oldest": de menor a mayor;"title": por el título sin mayúsculas ni tildes, luego el título tal como está escrito, luego el id. Los empates siempre se resuelven porid, así que la misma búsqueda pagina igual todas las veces. itemsytotal.itemses la página (máximolimit);totales cuántos ítems coinciden en total. Hay más cuandooffset + items.length < total.- Paginar.
limitva de 1 a 100 (50 por defecto) yoffsetde 0 a 1.000.000, números enteros (NaNoInfinityesinvalid_request); unoffsetmás allá del final responde sin ítems y con el mismototal.qtiene máximo 256 caracteres.
await kino.catalog.search({ q: "gato rojo" }); // newest first, 50 at most
await kino.catalog.search({ q: "gato", order: "title", limit: 20, offset: 40 }); // the third page of 20, A to Z
const { total } = await kino.catalog.search({ q: "2001", limit: 1 }); // just the count of matches
El modelo de datos¶
Una tabla, una fila por ítem: id (tu llave, de 1 a 128 caracteres), title (máximo 300 caracteres; lo único en que se
busca), sort (un número entero, 0 por defecto: una fecha en milisegundos, un número de mensaje, un número de episodio)
y data (un objeto simple opcional cuyo JSON tiene máximo 4.096 bytes en UTF-8, devuelto tal como lo guardaste). Pon en
data los pocos campos que muestras o necesitas para reproducir (la URL de un póster, una duración, la referencia de un
archivo), nunca blobs, páginas de HTML ni credenciales. upsert con un id que ya está reemplaza el ítem completo:
un campo que no mandas se pierde (también data). Un lote es una transacción: si se rechaza un ítem del lote, no se
escribe nada de él, así que limpia tus ítems antes (como hace toItem arriba) en lugar de mandar lo que te dio la fuente
tal cual.
Cuántos ítems caben¶
Valen dos límites a la vez: 100.000 ítems y un archivo de 64 MiB. Los 100.000 ítems caben solo cuando un ítem ocupa en
promedio máximo unos 670 bytes del archivo: su id, su título dos veces (tal como está escrito y sin mayúsculas ni tildes),
su data y los dos índices de búsqueda. Medido en las pruebas de Kino con un título de 50 caracteres: unos 370 bytes sin
data (caben 100.000, en 37 MB), unos 690 bytes con 300 bytes de data (caben unos 96.000), unos 920 bytes con 500
bytes (unos 72.000), y unos 4.850 bytes con 4.000 bytes (unos 13.800). Mantén data pequeño: la referencia de un archivo
y la URL de un póster, no una descripción.
Límites y errores¶
| Límite | Valor |
|---|---|
| Ítems por plugin | 100.000, si caben en el archivo (mira "Cuántos ítems caben") |
id |
de 1 a 128 caracteres |
title |
máximo 300 caracteres |
data |
máximo 4.096 bytes de JSON (UTF-8) |
Ítems por upsert, ids por get o remove |
500 |
limit de search |
50 por defecto, máximo 100 |
offset de search |
máximo 1.000.000 |
q de search |
máximo 256 caracteres |
| El archivo de la base de datos | máximo 64 MiB |
Cada rechazo es un KinoError cuyo code dice qué hacer, y cuyo mensaje nombra el límite:
code |
Cuándo | Qué hacer |
|---|---|---|
invalid_request |
Una forma o un tipo equivocado: upsert sin una lista, un ítem sin id o title de texto, un sort con decimales o no finito, un data que no es un objeto, un limit de 0 o NaN, un order desconocido. |
Corrige la llamada; el mensaje dice qué ítem (item 3) y qué campo. |
too_large |
Un valor o un lote sobre su límite: "kino.catalog.upsert: at most 500 items per call (maxUpsertBatch)", "kino.catalog.upsert: item 0 data is over 4096 bytes as JSON (maxDataBytes)", un id o un title largo, "kino.catalog.search: limit is over 100 (maxSearchLimit)", un offset o un q sobre su límite. |
Parte el lote, acorta el valor, pide una página más pequeña. |
limit |
El catálogo está lleno: "kino.catalog.upsert: the catalog is full (maxItems 100000)" o "kino.catalog.upsert: the catalog file is full (maxDbBytes 64 MiB)". |
Quita ítems que ya no necesitas (o clear e indexa menos, con data más pequeño), y vuelve a intentar. |
unavailable |
Kino no pudo leer ni escribir el archivo en este momento (el almacenamiento del aparato falló o está lleno), o el plugin se acaba de quitar. Cuando el archivo estaba dañado, Kino lo borra y empieza uno vacío, y esa llamada dice "kino.catalog: the catalog file was damaged and has been reset to empty; rebuild it". Un archivo que escribió un Kino más nuevo (después de que la persona volvió a un Kino más viejo) dice "kino.catalog: the catalog file was made by a newer Kino" en cada llamada hasta que lo borres con clear(). |
Intenta más tarde; después de "damaged", indexa otra vez desde tu fuente; después de "made by a newer Kino", clear() (borra ese archivo y empieza uno nuevo) e indexa otra vez. |
Un upsert rechazado no escribe nada de su lote, así que reintentar con uno más pequeño es seguro. Kino nunca borra tu
catálogo por un error de lectura o escritura: solo se reemplaza un archivo que SQLite reporta como dañado.
Aislamiento y privacidad¶
- Un archivo de base de datos por plugin. Tu catálogo es
catalog.dbdentro de la carpeta de datos de tu plugin, con un nombre que sale solo del id de tu plugin; Kino lo elige cuando arranca tu plugin, y ningún argumento que pases puede nombrar otro plugin u otro archivo. Ningún otro plugin puede leer ni cambiar tus ítems, y tú no puedes leer los suyos. - Nunca SQL desde los plugins. Solo tienes las seis operaciones de arriba; cada valor que mandas va como parámetro.
- Se queda en este aparato: nunca se sincroniza y no va en las copias de seguridad. Es un caché de tu fuente que se
puede reconstruir. Ninguna copia de seguridad lo lleva, así que en otro aparato, después de una restauración ahí, o
después de que la persona desinstala y reinstala tu plugin, está vacío: revisa
kino.catalog.count()(como haceforgetIndexIfEmptyarriba) e indexa otra vez desde tu fuente. - Desinstalar el plugin borra el archivo, y una llamada tuya que siga corriendo en ese momento no lo puede crear otra vez.
- Las credenciales NO van aquí. Guarda tokens y sesiones en secretos sellados, en los ajustes
de la persona o en
kino.storage, nunca endata.
Rendimiento¶
- Escribe en lotes de hasta 500 ítems: cada
upsertes una transacción, mucho más rápido que una llamada por ítem. - Nunca cargues el catálogo entero en memoria para filtrarlo tú: pídele a
searchuna página y deja que Kino busque. Una página tiene máximo 100 ítems. - Pagina los resultados grandes con
limit/offseten lugar de pedirlo todo; leetotalconlimit: 1cuando solo necesitas la cuenta. - Lo que cuesta: una búsqueda lee cada título una vez (una búsqueda por partes de palabra no puede usar un índice para
encontrar palabras; los índices llevan el texto buscado, así que las filas solo se leen para las coincidencias) más la
página pedida. Medido en las pruebas JVM de Kino en un computador de escritorio (un Mac con Apple Silicon), no en un
teléfono ni en una caja de TV: dos búsquedas con sus totales sobre 50.000 ítems tomaron de 68 a 86 ms, sin
datay con 500 o 4.000 bytes dedatapor ítem por igual. Un teléfono o una caja de TV de 1 GB es más lento por un factor que nadie ha medido todavía: prueba tu plugin en el aparato más lento que soportes. - Indexa desde Inicio o desde un refresco propio, unas pocas páginas de la fuente por llamada, nunca dentro de
search: cada llamada tiene su propio límite de tiempo (15 s parasearch, 20 s parahome) y la persona espera una búsqueda.
Recetas¶
- Indexar una biblioteca remota de a poco. Como
indexSteparriba: una pasada completa la primera vez, unas pocas páginas por llamada con un cursor enkino.storage; después, leer desde el ítem más nuevo y parar en la primera página que tenga un ítem ya indexado (kino.catalog.getlo responde), haciendoupsertde cada página en el camino. Una reconstrucción completa (cleary volver a indexar) es para un horario (una vez por semana quita lo que la fuente borró) o cuando tu fuente cambió de forma. - Buscar mientras la persona escribe. En una página "Ver más" con
scopedSearch, Kino espera 400 ms después de que la persona deja de escribir antes de llamar tusearch, y una búsqueda nueva puede venir enseguida: responde cada llamada directo desdekino.catalog.search({ q: query.q }), nunca desde la red. Mientras el catálogo siga vacío, responde lo que tenga (nada): Inicio lo llena. - Decir cuando los ítems más viejos todavía no cargan. Mientras la pasada completa no ha terminado (el marcador
cursorde arriba sigue ahí), agrega un ítem a tu fila de Inicio, o unuserMessagea una búsqueda vacía, que diga que la biblioteca todavía se está leyendo; quítalo cuando ya estéindexedAt.
Un almacenamiento más grande, en su lugar: storageLarge¶
Un plugin que indexa un catálogo (miles de videos de un canal, una biblioteca que arma desde su fuente) se queda sin los
256 KB después de unos cientos de entradas. Para buscar entre miles de registros, usa kino.catalog:
nunca los carga en tu memoria. Declara storageLarge y el mismo kino.storage guarda 16 MB en total (16.777.216
bytes: cada llave y cada valor, en UTF-8), máximo 2 MB por valor (2.097.152 bytes) y máximo 1.000 llaves de máximo 256
caracteres:
"apiVersion": 13,
"capabilities": ["search", "resolve", "storageLarge"]
- La misma API y las mismas reglas de
ttlMs. Declarativa (nada que exportar) y sin línea de consentimiento: es espacio en el aparato, no alcance. - Parte el catálogo en valores de máximo unos 512 KB (
catalog:0,catalog:1, ... más una llave pequeña que dice cuántos hay). Cada texto que tiene tu plugin cuesta memoria de QuickJS (un texto de 2 MB son 4 MB de tus 64 MB), y Kino guarda cada valor en su propio archivo: ungetlee un valor, unsetescribe un valor, así que los pedazos pequeños siguen rápidos en una caja de TV de 1 GB. - Pasarse lanza un
KinoErrorconcode"too_large":"plugin storage full (2 MB per value)","plugin storage full (16 MB)"cuando todo el almacén pasaría de 16 MB,"plugin storage full (1000 keys)". Una llave de más de 256 caracteres es"invalid_request". Una escritura rechazada no cambia nada. - Es solo del aparato: nunca se sincroniza y NO va en ninguna copia de seguridad. Un plugin sin la capacidad tiene
sus 256 KB de
kino.storageen una copia de seguridad con contraseña; un plugin constorageLargeno tiene nada de sukino.storageen una copia de seguridad, y restaurar una lo deja vacío. Trátalo como un caché que reconstruyes desde tu fuente. - Declarar
storageLargemueve tus llaves existentes a ese almacén del aparato. La primera llamada después de una actualización que lo agrega mueve todo lo que tu plugin tenía guardado (tokens y sesiones incluidos) fuera del almacén que va en las copias de seguridad, máximo 1.000 llaves de máximo 256 caracteres (el resto se descarta). Guarda las credenciales y las sesiones en secretos sellados o en los ajustes de la persona, o en un plugin que no declarestorageLarge. - Una actualización que quita
storageLargevuelve a empezar desde un almacén vacío de 256 KB (el más grande se queda en el aparato hasta que la capacidad vuelva o se desinstale el plugin). - Un Kino más viejo rechaza un manifiesto con
storageLarge("Este plugin necesita una versión más nueva de Kino").