chore: auto-commit (97 archivos)
- .claude/CLAUDE.md - .claude/agents/fn-recopilador/SKILL.md - .claude/rules/INDEX.md - .claude/rules/cpp_apps.md - bash/functions/infra/build_cpp_windows.sh - cpp/CMakeLists.txt - cpp/PATTERNS.md - cpp/framework/app_base.cpp - cpp/framework/app_base.h - dev/issues/README.md - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,66 @@
|
||||
#include "job_cache_sha256.h"
|
||||
|
||||
#include <cstdio>
|
||||
#include <filesystem>
|
||||
#include <fstream>
|
||||
#include <sstream>
|
||||
|
||||
namespace fs = std::filesystem;
|
||||
|
||||
namespace fn::cache_sha256 {
|
||||
|
||||
namespace {
|
||||
|
||||
std::string subdir_for(const std::string& key) {
|
||||
return key.size() >= 2 ? key.substr(0, 2) : key;
|
||||
}
|
||||
|
||||
} // namespace
|
||||
|
||||
std::string path_for(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix) {
|
||||
fs::path p = fs::path(root) / subdir_for(key) / (key + suffix);
|
||||
return p.string();
|
||||
}
|
||||
|
||||
bool ensure_dir(const std::string& root, const std::string& key) {
|
||||
std::error_code ec;
|
||||
fs::path dir = fs::path(root) / subdir_for(key);
|
||||
fs::create_directories(dir, ec);
|
||||
return !ec;
|
||||
}
|
||||
|
||||
bool read(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix,
|
||||
std::string* out) {
|
||||
if (!out) return false;
|
||||
std::ifstream f(path_for(root, key, suffix), std::ios::binary);
|
||||
if (!f.is_open()) return false;
|
||||
std::ostringstream ss;
|
||||
ss << f.rdbuf();
|
||||
*out = ss.str();
|
||||
return f.good() || f.eof();
|
||||
}
|
||||
|
||||
bool write(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix,
|
||||
const std::string& bytes) {
|
||||
if (!ensure_dir(root, key)) return false;
|
||||
std::ofstream f(path_for(root, key, suffix),
|
||||
std::ios::binary | std::ios::trunc);
|
||||
if (!f.is_open()) return false;
|
||||
f.write(bytes.data(), (std::streamsize)bytes.size());
|
||||
return f.good();
|
||||
}
|
||||
|
||||
bool exists(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix) {
|
||||
std::error_code ec;
|
||||
return fs::exists(path_for(root, key, suffix), ec) && !ec;
|
||||
}
|
||||
|
||||
} // namespace fn::cache_sha256
|
||||
@@ -0,0 +1,48 @@
|
||||
#pragma once
|
||||
|
||||
#include <string>
|
||||
|
||||
// job_cache_sha256 — addressable cache layout helper.
|
||||
//
|
||||
// Layout:
|
||||
// <root>/<key[0:2]>/<key><suffix>
|
||||
//
|
||||
// El caller calcula el `key` (tipicamente SHA-256 hex de algun valor
|
||||
// canonico — URL, parametros, etc.). Esta funcion no hashea: solo
|
||||
// gestiona el path y la I/O.
|
||||
//
|
||||
// Suffix permite multiples blobs por la misma key (`.html`, `.md`,
|
||||
// `.json`). Pasa "" si solo hay un blob.
|
||||
|
||||
namespace fn::cache_sha256 {
|
||||
|
||||
// Pure. Devuelve "<root>/<key[0:2]>/<key><suffix>". No toca disco.
|
||||
// Si key tiene menos de 2 caracteres, usa la key entera como subdir.
|
||||
std::string path_for(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix = "");
|
||||
|
||||
// Impure. Crea el directorio `<root>/<key[0:2]>/` si no existe.
|
||||
// Devuelve true en exito. No falla si ya existe.
|
||||
bool ensure_dir(const std::string& root, const std::string& key);
|
||||
|
||||
// Impure. Lee el archivo en `path_for(root, key, suffix)` entero.
|
||||
// Devuelve true si existia y se leyo; false en caso contrario.
|
||||
bool read(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix,
|
||||
std::string* out);
|
||||
|
||||
// Impure. Escribe `bytes` en `path_for(root, key, suffix)`. Crea el
|
||||
// directorio padre si no existe. Devuelve true en exito.
|
||||
bool write(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix,
|
||||
const std::string& bytes);
|
||||
|
||||
// Impure. true si el archivo existe en `path_for(root, key, suffix)`.
|
||||
bool exists(const std::string& root,
|
||||
const std::string& key,
|
||||
const std::string& suffix);
|
||||
|
||||
} // namespace fn::cache_sha256
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: job_cache_sha256
|
||||
kind: function
|
||||
lang: cpp
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
purity: impure
|
||||
signature: "std::string fn::cache_sha256::path_for(const std::string& root, const std::string& key, const std::string& suffix = \"\"); bool fn::cache_sha256::ensure_dir(const std::string& root, const std::string& key); bool fn::cache_sha256::read(const std::string& root, const std::string& key, const std::string& suffix, std::string* out); bool fn::cache_sha256::write(const std::string& root, const std::string& key, const std::string& suffix, const std::string& bytes); bool fn::cache_sha256::exists(const std::string& root, const std::string& key, const std::string& suffix)"
|
||||
description: "Cache addressable con layout '<root>/<key[0:2]>/<key><suffix>'. El caller hashea (tipicamente SHA-256 hex), esta funcion gestiona path + I/O. Suffix opcional permite multiples blobs por key (.html, .md, .json). Pieza extraida del jobs system de graph_explorer (issue 0026/0027) para reuso entre apps C++ que recolectan datos online."
|
||||
tags: [cache, sha256, addressable, jobs, fs, scraping]
|
||||
uses_functions: []
|
||||
uses_types: []
|
||||
returns: []
|
||||
returns_optional: false
|
||||
error_type: "error_go_core"
|
||||
imports: [string, cstdio, filesystem, fstream, sstream]
|
||||
tested: false
|
||||
tests: []
|
||||
test_file_path: ""
|
||||
file_path: "cpp/functions/infra/job_cache_sha256.cpp"
|
||||
framework: ""
|
||||
params:
|
||||
- name: root
|
||||
desc: "Directorio raiz del cache. Tipicamente <app_dir>/local_files/cache/. La funcion crea subdirectorios on-demand."
|
||||
- name: key
|
||||
desc: "Clave de cache. Tipicamente SHA-256 hex (64 chars) de un valor canonico (URL, hash de params). El caller calcula el hash."
|
||||
- name: suffix
|
||||
desc: "Sufijo del archivo. Permite multiples blobs por la misma key. Ejemplos: '.html', '.md', '.json'. Pasa '' si solo hay un blob por key."
|
||||
- name: out
|
||||
desc: "Buffer de salida para read(). Recibe los bytes del archivo. Devuelve false si no existia."
|
||||
- name: bytes
|
||||
desc: "Contenido a escribir en write(). Se trata como binario (no se anade newline ni se interpreta)."
|
||||
output: "path_for: string con el path absoluto. ensure_dir/read/write/exists: bool true en exito; read tambien rellena out. Ningun error_type custom — fallo de fs se traduce a false (ver fstream/filesystem para detalles)."
|
||||
notes: "1) Pure: solo path_for. Resto impuro (toca filesystem). 2) Layout compatible con el cache que ya usan los enrichers Python de graph_explorer (`<cache_dir>/<sha[0:2]>/<sha>.{html,md}`), por lo que apps C++ pueden leer blobs escritos por subprocess Python sin migrar formato. 3) Si el caller necesita SHA-256 propio, anadir funcion separada `sha256_hex_cpp_core` (no implementada aun)."
|
||||
documentation: "Pieza minima del refactor de issue 0065. El cache es un helper standalone que cualquier app C++ que recolecte datos online puede usar para evitar refetchear. odr_console (issue 0066) lo usa via la cache_dir que pasa al subprocess Python en stdin JSON, manteniendo compatibilidad con enrichers existentes."
|
||||
example: |
|
||||
#include "cpp/functions/infra/job_cache_sha256.h"
|
||||
#include <openssl/sha.h> // o cualquier impl SHA-256
|
||||
|
||||
std::string url = "https://example.com/data.json";
|
||||
// Hash de la URL como key (usuario provee la impl).
|
||||
std::string key = sha256_hex(url);
|
||||
std::string root = "/path/to/app/local_files/cache";
|
||||
|
||||
if (!fn::cache_sha256::exists(root, key, ".json")) {
|
||||
std::string body = fetch_http(url);
|
||||
fn::cache_sha256::write(root, key, ".json", body);
|
||||
}
|
||||
std::string cached;
|
||||
if (fn::cache_sha256::read(root, key, ".json", &cached)) {
|
||||
// ... usar cached ...
|
||||
}
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
Helper de I/O addressable. No hace SHA-256 — el caller provee la key (normalmente hex). Layout `<root>/<key[0:2]>/<key><suffix>` es identico al que usan los enrichers de graph_explorer en sus `run.py`, por lo que C++ y Python pueden leer/escribir el mismo cache.
|
||||
|
||||
### Decisiones de diseño
|
||||
|
||||
- **Hash fuera de la funcion**: separar el hashing del path-handling deja el modulo libre de dependencias criptograficas. Si una app prefiere blake3, xxhash o md5 para keys mas cortas, esta funcion sigue valiendo.
|
||||
- **Suffix opcional**: enrichers de graph_explorer guardan dos blobs por URL (`.html` y `.md`); odr_console probablemente guarde `.json`/`.parquet`. Suffix unifica casos.
|
||||
- **Sin SQLite**: cache es solo files. Si una app necesita metadata por entry (TTL, last-access, content-type), eso vive en operations.db o en una tabla aparte.
|
||||
- **Layout compatible**: identico al Python `cache_paths()` en `enrichers/fetch_webpage/run.py`. C++ puede leer blobs escritos por enrichers Python y viceversa.
|
||||
|
||||
### Que NO incluye
|
||||
|
||||
- No incluye SHA-256 ni ningun hash. Caller responsable.
|
||||
- No incluye TTL ni eviction. Implementar fuera si se necesita.
|
||||
- No incluye locking entre procesos. Si dos workers escriben la misma key concurrente, ultimo gana — para invalidacion atomica usar nombre temporal + rename.
|
||||
Reference in New Issue
Block a user