@noeva/etl-core 1.0.1 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +134 -0
- package/README.md +6 -11
- package/dist/{ai-BoTwcmUg.d.ts → ai-DyDIf-hQ.d.ts} +1 -1
- package/dist/{ambiente-della-pipeline-BoymQ6uN.d.ts → ambiente-della-pipeline-BhWsyLUR.d.ts} +2 -2
- package/dist/chunk-47NVGHUY.js +2 -0
- package/dist/chunk-5OE6F2MK.js +2 -0
- package/dist/{chunk-NZR6TZ42.js → chunk-5XVANFXO.js} +1 -1
- package/dist/chunk-672L5BGQ.js +1 -0
- package/dist/{chunk-4NPSBPBY.js → chunk-6QVYBDIS.js} +1 -1
- package/dist/{chunk-PE2QKU34.js → chunk-CEAMQIRO.js} +1 -1
- package/dist/chunk-DHQ3YOPX.js +5 -0
- package/dist/chunk-FBSNZG34.js +1 -0
- package/dist/{chunk-J3PBMWSP.js → chunk-GZWYRO3V.js} +1 -1
- package/dist/chunk-IODXIHU2.js +1 -0
- package/dist/{chunk-P6B2KLNJ.js → chunk-KEFIGSRS.js} +2 -2
- package/dist/chunk-KGWA46Y6.js +2 -0
- package/dist/chunk-L25W2QNS.js +1 -0
- package/dist/{chunk-JLPK6MMQ.js → chunk-OK3XRTGA.js} +1 -1
- package/dist/chunk-UHGHK6NP.js +1 -0
- package/dist/chunk-VL7DZWWO.js +2 -0
- package/dist/chunk-VVXT66DC.js +1 -0
- package/dist/chunk-ZKDCUSM2.js +6 -0
- package/dist/cli.js +2 -2
- package/dist/{client-DYA3wIyb.d.ts → client-BC_mLuT2.d.ts} +2 -2
- package/dist/config-BSdGSRPG.d.ts +37 -0
- package/dist/{config-BSUwK4p_.d.ts → config-DMafsY4H.d.ts} +3 -3
- package/dist/connector-kit.d.ts +14 -9
- package/dist/connector-kit.js +1 -1
- package/dist/connectors/excel.d.ts +391 -0
- package/dist/connectors/excel.js +10 -0
- package/dist/connectors/file.d.ts +12 -5
- package/dist/connectors/file.js +1 -1
- package/dist/connectors/http.d.ts +7 -7
- package/dist/connectors/http.js +1 -1
- package/dist/connectors/imap.d.ts +6 -6
- package/dist/connectors/imap.js +1 -1
- package/dist/connectors/jira.d.ts +6 -6
- package/dist/connectors/jira.js +2 -2
- package/dist/connectors/mail.d.ts +7 -7
- package/dist/connectors/mail.js +1 -1
- package/dist/connectors/mysql.d.ts +238 -0
- package/dist/connectors/mysql.js +2 -0
- package/dist/connectors/noeva.d.ts +6 -6
- package/dist/connectors/noeva.js +1 -1
- package/dist/connectors/oauth.d.ts +5 -5
- package/dist/connectors/oauth.js +1 -1
- package/dist/connectors/odoo.d.ts +309 -0
- package/dist/connectors/odoo.js +3 -0
- package/dist/connectors/postgres.d.ts +7 -6
- package/dist/connectors/postgres.js +1 -1
- package/dist/connectors/process.d.ts +1 -1
- package/dist/connectors/process.js +1 -1
- package/dist/connectors/sendgrid.d.ts +7 -7
- package/dist/connectors/sendgrid.js +1 -1
- package/dist/connectors/smtp.d.ts +8 -8
- package/dist/connectors/smtp.js +1 -1
- package/dist/connectors/sqlserver.d.ts +7 -6
- package/dist/connectors/sqlserver.js +1 -1
- package/dist/connectors/zoho.d.ts +6 -6
- package/dist/connectors/zoho.js +1 -1
- package/dist/contract.d.ts +2 -2
- package/dist/{credenziali-posta-f7HB2cYW.d.ts → credenziali-posta-C0az04uV.d.ts} +2 -2
- package/dist/{errors-bgSO6lGO.d.ts → errors-CRq1uNYZ.d.ts} +8 -1
- package/dist/etl.config.js +3 -3
- package/dist/guida/404.html +2 -2
- package/dist/guida/GUIDA_SVILUPPO.html +7 -7
- package/dist/guida/TECHNICAL_OVERVIEW.html +7 -7
- package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.js → GUIDA_SVILUPPO.md.Bvr7RKHN.js} +2 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.C6HYc5_h.js +10 -0
- package/dist/guida/assets/{app.DeVEBaIz.js → app.uK-5scpr.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.AxYI9rrX.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.CsTQzJUK.js → VPLocalSearchBox.CB5vaMvW.js} +1 -1
- package/dist/guida/assets/chunks/{theme.Dfy0C_Zf.js → theme.z6u0J2Ii.js} +2 -2
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.js +1 -0
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.lean.js +1 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.js +92 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.lean.js +1 -0
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.js → connectors_file.md.Dbofo9W5.js} +3 -3
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.lean.js → connectors_file.md.Dbofo9W5.lean.js} +1 -1
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.js +34 -0
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.lean.js +1 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.js +19 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.lean.js +1 -0
- package/dist/guida/assets/{conventions_node-descriptor.md.MQaGlm8a.js → conventions_node-descriptor.md.C19dB-Tb.js} +4 -4
- package/dist/guida/assets/conventions_node-descriptor.md.C19dB-Tb.lean.js +1 -0
- package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.js → conventions_run-report.md.iVSN9fNV.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.js → conventions_versioni-di-pipeline.md.DJPSthZ8.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.lean.js → conventions_versioni-di-pipeline.md.DJPSthZ8.lean.js} +1 -1
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.js → nodes_README.md.BNAiSoJJ.js} +2 -2
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.lean.js → nodes_README.md.BNAiSoJJ.lean.js} +1 -1
- package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.js → nodes_lookup.md.DrJFsfOJ.js} +1 -1
- package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.js → nodes_sink.md.C1S-lAh2.js} +2 -2
- package/dist/guida/assets/{nodes_source.md.DP2i3GFv.js → nodes_source.md.BitUNtug.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.js → nodes_task.md.CejEQZcD.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.lean.js → nodes_task.md.CejEQZcD.lean.js} +1 -1
- package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.js → nodes_transform.md.Ciycywnb.js} +1 -1
- package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js} +1 -1
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.js +16 -0
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.lean.js +1 -0
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.js → runbooks_sql-task-truncate-swap.md.DAz41942.js} +5 -3
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.lean.js → runbooks_sql-task-truncate-swap.md.DAz41942.lean.js} +1 -1
- package/dist/guida/connectors/README.html +5 -5
- package/dist/guida/connectors/excel.html +118 -0
- package/dist/guida/connectors/file.html +7 -7
- package/dist/guida/connectors/http.html +4 -4
- package/dist/guida/connectors/imap.html +4 -4
- package/dist/guida/connectors/jira.html +5 -5
- package/dist/guida/connectors/mysql.html +60 -0
- package/dist/guida/connectors/noeva.html +5 -5
- package/dist/guida/connectors/oauth.html +5 -5
- package/dist/guida/connectors/odoo.html +45 -0
- package/dist/guida/connectors/postgres.html +5 -5
- package/dist/guida/connectors/process.html +4 -4
- package/dist/guida/connectors/sendgrid.html +4 -4
- package/dist/guida/connectors/smtp.html +4 -4
- package/dist/guida/connectors/sqlserver.html +4 -4
- package/dist/guida/connectors/zoho.html +4 -4
- package/dist/guida/conventions/node-columns.html +4 -4
- package/dist/guida/conventions/node-descriptor.html +8 -8
- package/dist/guida/conventions/run-report.html +6 -6
- package/dist/guida/conventions/run-trace.html +4 -4
- package/dist/guida/conventions/variabili-del-core.html +4 -4
- package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
- package/dist/guida/guide/claude-code/index.html +4 -4
- package/dist/guida/guide/claude-code/prompt.html +5 -5
- package/dist/guida/guide/claude-code/strumenti.html +4 -4
- package/dist/guida/guide/grafo.html +4 -4
- package/dist/guida/guide/usare/app-desktop.html +4 -4
- package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
- package/dist/guida/guide/usare/index.html +4 -4
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +4 -4
- package/dist/guida/nodes/README.html +5 -5
- package/dist/guida/nodes/action.html +4 -4
- package/dist/guida/nodes/ai.html +4 -4
- package/dist/guida/nodes/join.html +4 -4
- package/dist/guida/nodes/lookup.html +6 -6
- package/dist/guida/nodes/pipeline.html +4 -4
- package/dist/guida/nodes/route.html +4 -4
- package/dist/guida/nodes/sink.html +7 -7
- package/dist/guida/nodes/source.html +7 -7
- package/dist/guida/nodes/task.html +6 -6
- package/dist/guida/nodes/transform.html +6 -6
- package/dist/guida/nodes/try-catch.html +4 -4
- package/dist/guida/nodes/union.html +4 -4
- package/dist/guida/pagine.json +4 -0
- package/dist/guida/pipelines/README.html +4 -4
- package/dist/guida/pipelines/crm-leads-sync.html +4 -4
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
- package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
- package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
- package/dist/guida/pipelines/test-posta.html +4 -4
- package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
- package/dist/guida/runbooks/deploy-ecr.html +4 -4
- package/dist/guida/runbooks/deployment.html +6 -6
- package/dist/guida/runbooks/etl-worker.html +5 -5
- package/dist/guida/runbooks/excel-operazioni-distruttive.html +42 -0
- package/dist/guida/runbooks/graph-server.html +5 -5
- package/dist/guida/runbooks/mask-key.html +4 -4
- package/dist/guida/runbooks/oauth-google-posta.html +4 -4
- package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
- package/dist/guida/runbooks/scd2-rehash.html +4 -4
- package/dist/guida/runbooks/sql-task-truncate-swap.html +8 -6
- package/dist/guida/runbooks/stato-incrementale.html +4 -4
- package/dist/guida/sub-pipelines/README.html +4 -4
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
- package/dist/index.d.ts +9 -9
- package/dist/index.js +1 -1
- package/dist/{invio-Dwz3J7sP.d.ts → invio-9Ubb_cdR.d.ts} +3 -3
- package/dist/{istanza-per-il-piano-CucqUF7b.d.ts → istanza-per-il-piano-74NYhIHc.d.ts} +1 -1
- package/dist/{manifest-variabili-U1UfPDfF.d.ts → manifest-variabili-DRWUzmxU.d.ts} +1 -1
- package/dist/pipelines.d.ts +3 -3
- package/dist/pipelines.js +1 -1
- package/dist/{runnable-pipeline-CArkLzfv.d.ts → runnable-pipeline-CWgPwi6w.d.ts} +2 -2
- package/dist/{config-DIthC7n7.d.ts → sql-watermark-CQVvxhPZ.d.ts} +9 -40
- package/dist/testing.d.ts +3 -3
- package/dist/testing.js +1 -1
- package/dist/{trasporto-DpPLCEQ1.d.ts → trasporto-BaRdP6Wl.d.ts} +4 -4
- package/dist/{types-BVA7BIou.d.ts → types-_3rgLhje.d.ts} +21 -2
- package/dist/{variabili-dichiarate-DmfcxsT9.d.ts → variabili-dichiarate-CS-eC53K.d.ts} +1 -1
- package/kit/skills/etl-graph/SKILL.md +6 -3
- package/kit/skills/etl-graph/references/data-patterns.md +1 -1
- package/kit/skills/etl-graph/references/error-handling.md +3 -3
- package/kit/skills/etl-graph/references/wiring.md +10 -10
- package/kit/skills/new-connector/SKILL.md +2 -2
- package/package.json +16 -1
- package/dist/chunk-BVUOUBLW.js +0 -1
- package/dist/chunk-CRR3Q2C7.js +0 -2
- package/dist/chunk-LJ7DVP5F.js +0 -2
- package/dist/chunk-PKBSETMV.js +0 -2
- package/dist/chunk-QPJC4GWR.js +0 -1
- package/dist/chunk-RCRMQPFH.js +0 -5
- package/dist/chunk-RS5SGDUU.js +0 -1
- package/dist/chunk-RWPHH4E2.js +0 -1
- package/dist/chunk-SRFFKE5W.js +0 -6
- package/dist/chunk-WVODQB6Z.js +0 -1
- package/dist/chunk-XZMCC6VQ.js +0 -1
- package/dist/chunk-ZCYGHS7P.js +0 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.DTIhkkg9.js +0 -10
- package/dist/guida/assets/chunks/@localSearchIndexroot.NgfCNDyz.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +0 -1
- package/dist/guida/assets/conventions_node-descriptor.md.MQaGlm8a.lean.js +0 -1
- /package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.lean.js → GUIDA_SVILUPPO.md.Bvr7RKHN.lean.js} +0 -0
- /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js → TECHNICAL_OVERVIEW.md.C6HYc5_h.lean.js} +0 -0
- /package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.lean.js → conventions_run-report.md.iVSN9fNV.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.lean.js → nodes_lookup.md.DrJFsfOJ.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.lean.js → nodes_sink.md.C1S-lAh2.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_source.md.DP2i3GFv.lean.js → nodes_source.md.BitUNtug.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.lean.js → nodes_transform.md.Ciycywnb.lean.js} +0 -0
- /package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.lean.js → runbooks_deployment.md.BV8Izw4I.lean.js} +0 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import{_ as e,o as t,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Odoo (record di un modello, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/odoo.md","filePath":"connectors/odoo.md"}'),d={name:"connectors/odoo.md"};function n(s,o,c,r,l,p){return t(),i("div",null,[...o[0]||(o[0]=[a(`<h1 id="connettore-odoo-record-di-un-modello-con-i-campi-dichiarati" tabindex="-1">Connettore: Odoo (record di un modello, con i campi dichiarati) <a class="header-anchor" href="#connettore-odoo-record-di-un-modello-con-i-campi-dichiarati" aria-label="Permalink to "Connettore: Odoo (record di un modello, con i campi dichiarati)""></a></h1><p>Legge i record di un modello di <strong>Odoo</strong> dentro il grafo: <code>odooRecords</code> è un <code>Source</code> che restituisce tutti i record del modello (o quelli di un dominio), con i soli campi che il nodo dichiara, convertiti in colonne tipizzate. <code>odooConteggi</code> dà i conteggi di Odoo, per confrontarli con le righe caricate. Codice in <code>src/connectors/odoo/</code>, subpath <code>@noeva/etl-core/connectors/odoo</code>; decisioni in ADR-0108.</p><p>Il connettore <strong>legge e basta</strong>: chiama solo <code>search_read</code>, <code>search_count</code>, <code>read</code>, <code>fields_get</code> e <code>read_group</code>, e rifiuta qualunque altro metodo prima di toccare la rete. La chiave può essere quella di un utente che scrive, ma da qui non si scrive.</p><p>Parla <strong>XML-RPC</strong> (<code>/xmlrpc/2/object</code>, <code>execute_kw</code>), l'unica API delle versioni fino alla 18, con l'API key al posto della password. Odoo l'ha deprecata e la toglie con Online 21.1 e Odoo 22; dalla 19 c'è <strong>JSON-2</strong>, che la config prevede (<code>ODOO_<ID>_PROTOCOL=json2</code>) ma che oggi rifiuta.</p><table tabindex="0"><thead><tr><th>Funzione</th><th>Tipo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>odooRecords</code></td><td><code>Source</code></td><td>I record di un modello, con i campi dichiarati, in colonne</td></tr><tr><td><code>odooConteggi</code></td><td><code>Source</code></td><td>Un record per modello con il <code>search_count</code> di Odoo</td></tr><tr><td><code>loadOdooRegistry</code></td><td>registry</td><td>I database configurati, per istanza (ADR-0030)</td></tr><tr><td><code>loadOdooConfig</code></td><td>config</td><td>Un solo database, da variabili con prefisso</td></tr><tr><td><code>loadOdooInstance</code></td><td>config</td><td>Un solo database del registry, senza gli altri</td></tr><tr><td><code>istanzaOdooPerIlPiano</code></td><td>piano</td><td>Il database per il piano, con la sua ricaduta</td></tr><tr><td><code>istanzaOdooDichiarata</code></td><td>ambiente</td><td>Il database come lo vede <code>etl env check</code></td></tr><tr><td><code>MANIFEST_ODOO</code></td><td>config</td><td>Le variabili di un database, per il piano (ADR-0089)</td></tr><tr><td><code>valoreOdoo</code>, <code>tipoColonnaOdoo</code></td><td>utilità</td><td>La conversione di un valore e il tipo della sua colonna</td></tr><tr><td><code>schemaRecordOdoo</code></td><td>contratto</td><td>Lo schema Zod <code>strict</code> di un record letto con quei campi</td></tr><tr><td><code>nomiColonneOdoo</code></td><td>utilità</td><td>Le colonne di un record, <code>id</code> compreso: quelle di un sink</td></tr><tr><td><code>dettaglioCredenzialeOdoo</code></td><td>descriptor</td><td>La riga <code>credenziale</code>, per un nodo Odoo</td></tr><tr><td><code>nuovaPortaOdoo</code></td><td>test</td><td>Una porta con un altro intervallo, per i test</td></tr><tr><td><code>CampoOdoo</code>, <code>TipoOdoo</code>, <code>RecordOdoo</code>, …</td><td>tipi</td><td>Un campo, i tipi letti, un record</td></tr><tr><td><code>METODI_LETTURA_ODOO</code>, <code>TIPI_ODOO</code>, <code>DEFAULT_*</code></td><td>costanti</td><td>I metodi ammessi, i tipi letti, i default del connettore</td></tr></tbody></table><h2 id="configurazione" tabindex="-1">Configurazione <a class="header-anchor" href="#configurazione" aria-label="Permalink to "Configurazione""></a></h2><p><code>loadOdooRegistry(env?)</code> risolve i database: con <code>ODOO_INSTANCES=erp</code> ognuno ha le sue <code>ODOO_<ID>_*</code>, senza lista valgono le variabili base <code>ODOO_*</code> come istanza <code>default</code>.</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>ODOO_INSTANCES</code></td><td>—</td><td>elenco dei database; senza, l'istanza <code>default</code> dalle variabili base</td></tr><tr><td><code>ODOO_<ID>_URL</code></td><td>—</td><td>obbligatoria; l'istanza, solo origine: <code>https://<istanza>.odoo.com</code></td></tr><tr><td><code>ODOO_<ID>_DATABASE</code></td><td>—</td><td>obbligatoria; il nome del database</td></tr><tr><td><code>ODOO_<ID>_LOGIN</code></td><td>—</td><td>obbligatoria; il login dell'utente della chiave</td></tr><tr><td><code>ODOO_<ID>_API_KEY</code></td><td>—</td><td>obbligatoria, segreta; l'API key, da Preferenze → Sicurezza account</td></tr><tr><td><code>ODOO_<ID>_PROTOCOL</code></td><td><code>xmlrpc</code></td><td><code>xmlrpc</code>; <code>json2</code> è previsto per Odoo 19 e oggi è un errore di configurazione</td></tr><tr><td><code>ODOO_<ID>_TIMEOUT_MS</code></td><td><code>120000</code></td><td>tempo massimo di una chiamata, in millisecondi</td></tr></tbody></table><p>Su Odoo.sh il nome del database <strong>non</strong> è il sottodominio (segue <code>progetto-ramo-build</code>): si legge con <code>POST /web/database/list</code>, che risponde senza autenticazione. Una API key dura al più tre mesi: va ruotata, e una chiave scaduta si presenta come un <code>ConfigError</code> all'autenticazione.</p><p>La chiave giusta è quella di un <strong>utente di servizio</strong> con il solo diritto di lettura sui modelli che servono: Odoo non ha un ruolo di sola lettura predefinito, si crea un gruppo apposta. I gruppi delle app («Vendite: utente») danno anche la scrittura.</p><p><code>URL</code> vuole <code>https</code>; <code>http</code> è ammesso solo verso la macchina locale, per un server di test. Gli errori nominano le variabili, mai i valori.</p><h2 id="source-—-odoorecords" tabindex="-1">Source — <code>odooRecords</code> <a class="header-anchor" href="#source-—-odoorecords" aria-label="Permalink to "Source — \`odooRecords\`""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">odooRecords</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> config, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// loadOdooRegistry().get("erp")</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"erp"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> modello: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"account.move"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> dominio: [[</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"move_type"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"in"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"out_invoice"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"out_refund"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]]],</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> campi: [</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"name"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"char"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"partner_id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"many2one"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"amount_total_signed"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"monetary"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"invoice_date"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"date"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Opzione</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>config</code></td><td>—</td><td>il database</td></tr><tr><td><code>modello</code></td><td>—</td><td>il nome tecnico: <code>sale.order</code>, <code>x_bi_sql_view.portafoglio_ordini_v5</code></td></tr><tr><td><code>campi</code></td><td>—</td><td>i campi, con il <code>type</code> di <code>fields_get</code>; <code>id</code> non si dichiara, c'è sempre</td></tr><tr><td><code>dominio</code></td><td><code>[]</code></td><td>il dominio Odoo che restringe il modello</td></tr><tr><td><code>contesto</code></td><td>—</td><td>il contesto di ogni chiamata (<code>tz</code>, <code>lang</code>, <code>allowed_company_ids</code>); <code>active_test: false</code> c'è sempre</td></tr><tr><td><code>perPagina</code></td><td><code>500</code></td><td>righe per <code>search_read</code>, fra 1 e 5000</td></tr><tr><td><code>name</code>, <code>instanceId</code></td><td>—</td><td>nome del nodo e istanza mostrata nel DAG</td></tr><tr><td><code>retry</code>, <code>fetchImpl</code></td><td>—</td><td>retry di ogni chiamata (default 5 tentativi, attese fino a 60 s); <code>fetch</code> finto nei test</td></tr><tr><td><code>porta</code></td><td>—</td><td>la porta del database; default quella condivisa del processo (vedi sotto)</td></tr></tbody></table><h3 id="come-legge" tabindex="-1">Come legge <a class="header-anchor" href="#come-legge" aria-label="Permalink to "Come legge""></a></h3><ol><li><strong>Autentica</strong> una volta per processo e database (<code>authenticate</code> su <code>/xmlrpc/2/common</code>).</li><li><strong><code>fields_get</code></strong> del modello, una volta per run: un campo dichiarato che il database non ha, o che non è <strong>stored</strong> (un campo calcolato al volo), è un <code>ConfigError</code> che lo nomina, prima del primo record. Un tipo diverso da quello dichiarato si segnala nel log (<code>odoo-source.tipo-cambiato</code>), e la conversione decide se il valore regge.</li><li><strong><code>search_read</code> a pagine in ordine di <code>id</code></strong>, con paginazione keyset: il dominio più <code>["id", ">", <ultimo>]</code>, <code>order: "id asc"</code>, <code>load: ""</code> (i many2one come solo <code>id</code>, senza nome) e <code>context: {active_test: false}</code> (anche gli archiviati, come le opportunità perse). Niente <code>offset</code>: con le scritture in corso salta o ripete record. Una pagina si chiede solo quando la precedente è stata consumata, e un record fuori ordine ferma la lettura. La lettura finisce a una pagina <strong>vuota</strong>, non a una corta: su alcuni modelli (<code>mail.activity</code>) Odoo toglie dopo il <code>limit</code> i record che l'utente non può vedere, e una pagina corta ha altri record dopo di sé. Costa una chiamata in più per modello. Qualche modello ridefinisce <code>search_read</code> senza accettare <code>load</code> (in Odoo 18 <code>project.tags</code>): al rifiuto la pagina si richiede senza, e così il resto della lettura di quel modello. I many2one arrivano come <code>[id, nome]</code> e la conversione tiene l'<code>id</code>; il log lo segnala (<code>odoo-source.senza-load</code>). Ogni altro errore di Odoo resta un errore.</li></ol><h3 id="i-campi-sono-la-regola-di-privacy" tabindex="-1">I campi sono la regola di privacy <a class="header-anchor" href="#i-campi-sono-la-regola-di-privacy" aria-label="Permalink to "I campi sono la regola di privacy""></a></h3><p>Il source chiede a Odoo <strong>solo</strong> i campi dichiarati (più <code>id</code>) ed emette solo le loro colonne. Un campo nuovo in Odoo non entra finché qualcuno non lo dichiara. <code>schemaRecordOdoo(campi)</code> è il contratto stretto da mettere in un nodo <code>validate</code>: una colonna in più ferma la run.</p><h3 id="tipi-e-conversione" tabindex="-1">Tipi e conversione <a class="header-anchor" href="#tipi-e-conversione" aria-label="Permalink to "Tipi e conversione""></a></h3><table tabindex="0"><thead><tr><th>Tipo Odoo</th><th>Colonna</th><th>Valore</th></tr></thead><tbody><tr><td><code>integer</code>, <code>many2one</code>, <code>many2one_reference</code></td><td><code>integer</code></td><td>il numero; di un many2one il solo <code>id</code></td></tr><tr><td><code>float</code>, <code>monetary</code></td><td><code>number</code></td><td>il numero</td></tr><tr><td><code>boolean</code></td><td><code>boolean</code></td><td><code>true</code> / <code>false</code>, mai <code>null</code></td></tr><tr><td><code>char</code>, <code>text</code>, <code>selection</code>, <code>reference</code></td><td><code>string</code></td><td>il testo</td></tr><tr><td><code>date</code></td><td><code>date</code></td><td><code>AAAA-MM-GG</code></td></tr><tr><td><code>datetime</code></td><td><code>datetime</code></td><td><code>AAAA-MM-GG HH:MM:SS</code>, in <strong>UTC senza fuso</strong>, come lo salva Odoo</td></tr><tr><td><code>many2many</code></td><td><code>ids</code></td><td>l'array degli <code>id</code></td></tr><tr><td><code>json</code>, <code>properties</code></td><td><code>json</code></td><td>il valore com'è (<code>analytic_distribution</code>: <code>{"12,34": 100}</code>)</td></tr></tbody></table><p>Il vuoto di Odoo è <code>false</code>: diventa <code>null</code>, tranne sui <code>boolean</code>. Un valore che non si converte è un <code>ExtractError</code> che nomina modello, campo e <code>id</code> del record, mai il valore. <code>one2many</code>, <code>binary</code> e <code>html</code> non si dichiarano.</p><p>Un sink SQL scrive gli array e gli oggetti come li serializza il suo driver: per una colonna <code>jsonb</code> di Postgres un many2many va passato come testo JSON (<code>JSON.stringify</code>), altrimenti <code>pg</code> lo manda come array di Postgres.</p><h2 id="source-—-odooconteggi" tabindex="-1">Source — <code>odooConteggi</code> <a class="header-anchor" href="#source-—-odooconteggi" aria-label="Permalink to "Source — \`odooConteggi\`""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">odooConteggi</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> config,</span></span>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"erp"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> modelli: [</span></span>
|
|
16
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { modello: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sale.order"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { modello: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"account.move"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, dominio: [[</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"move_type"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"="</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"out_invoice"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]] },</span></span>
|
|
18
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
|
|
19
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Un record per modello, <code>{ modello, attese, contato_il }</code>: il <code>search_count</code> con il dominio (e gli archiviati), e l'istante del conteggio in UTC. Serve a una tabella di controllo accanto al carico, dove le righe caricate si confrontano con quelle attese.</p><h2 id="limiti-di-odoo-la-porta" tabindex="-1">Limiti di Odoo: la porta <a class="header-anchor" href="#limiti-di-odoo-la-porta" aria-label="Permalink to "Limiti di Odoo: la porta""></a></h2><p>L'<strong>Acceptable Use Policy</strong> di Odoo ammette circa una chiamata al secondo, <strong>mai in parallelo</strong>, e chi la viola rischia la sospensione dell'abbonamento del cliente senza preavviso. Per questo ogni chiamata passa da una <strong>porta</strong> del database, condivisa da tutti i nodi del processo che parlano con la stessa istanza e lo stesso database: una chiamata alla volta, a distanza di almeno un secondo dall'inizio della precedente. Due source in parallelo non raddoppiano il ritmo, si mettono in fila. Un carico di 90.000 righe a pagine di 500 dura qualche minuto.</p><p>Su 429 e 5xx, timeout e rete la chiamata si riprova con backoff (da 5 s, al più 60 s fra un tentativo e l'altro), rispettando <code>Retry-After</code>. Un <code>fault</code> di Odoo non si riprova: diventa un <code>ExtractError</code> con l'ultima riga del messaggio di Odoo e un suggerimento («chiave rifiutata», «nessun diritto di lettura sul modello», «campo inesistente»).</p><p>Due run sovrapposte della stessa pipeline sono due processi, con due porte: non lanciarle insieme.</p><h2 id="sicurezza" tabindex="-1">Sicurezza <a class="header-anchor" href="#sicurezza" aria-label="Permalink to "Sicurezza""></a></h2><ul><li>La chiave sta solo nella config: mai nei log, negli errori, nel piano o nel descriptor, che dice soltanto se è impostata. Il corpo delle chiamate, che la porta, non entra mai in un errore.</li><li>Una risposta con un <code>DOCTYPE</code> si rifiuta prima del parser XML.</li><li>La risposta ha un tetto di byte (50 MB) e ogni chiamata un timeout.</li></ul><h2 id="descriptor" tabindex="-1">Descriptor <a class="header-anchor" href="#descriptor" aria-label="Permalink to "Descriptor""></a></h2><p><code>kind: "odoo-source"</code>, con le righe <code>istanza</code> e <code>database</code> (con le loro variabili), poi <code>modello</code>, <code>dominio</code> (se c'è, troncato), <code>lettura</code>, <code>campi</code> e in fondo la <code>credenziale</code>: il protocollo e se login e chiave sono impostati, o quali mancano.</p><h2 id="quello-che-non-fa-ancora" tabindex="-1">Quello che non fa (ancora) <a class="header-anchor" href="#quello-che-non-fa-ancora" aria-label="Permalink to "Quello che non fa (ancora)""></a></h2><ul><li><strong>Incrementale</strong>: oggi ogni run rilegge tutto. Il passo dopo è un watermark su <code>write_date</code> con lookback (le transazioni lunghe committano dopo), e una riconciliazione periodica degli <code>id</code> per le cancellazioni, che in Odoo sono fisiche.</li><li><strong>JSON-2</strong>: con Odoo 19, sullo stesso connettore.</li><li><strong>Lookup e aggregazioni</strong> (<code>read</code>, <code>read_group</code>): ammessi dalla lista dei metodi, non ancora esposti come nodi.</li></ul>`,35)])])}const g=e(d,[["render",n]]);export{u as __pageData,g as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as e,o as t,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Odoo (record di un modello, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/odoo.md","filePath":"connectors/odoo.md"}'),d={name:"connectors/odoo.md"};function n(s,o,c,r,l,p){return t(),i("div",null,[...o[0]||(o[0]=[a("",35)])])}const g=e(d,[["render",n]]);export{u as __pageData,g as default};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as e,o as
|
|
1
|
+
import{_ as e,o as a,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Descriptor dei nodi per la UI del DAG","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/node-descriptor.md","filePath":"conventions/node-descriptor.md"}'),n={name:"conventions/node-descriptor.md"};function t(l,i,d,r,c,p){return a(),s("div",null,[...i[0]||(i[0]=[o(`<h1 id="descriptor-dei-nodi-per-la-ui-del-dag" tabindex="-1">Descriptor dei nodi per la UI del DAG <a class="header-anchor" href="#descriptor-dei-nodi-per-la-ui-del-dag" aria-label="Permalink to "Descriptor dei nodi per la UI del DAG""></a></h1><blockquote><p>Come "dettagliare" un nodo del DAG affinché <code>noeva-etl-ui</code> mostri <strong>che connettore è e dove punta</strong>, senza mai esporre segreti. Campo <strong>gemello</strong> dello stesso <code>PlanNode</code>: le colonne del dato — quali campi scorrono nel nodo — vivono in <code>columns</code>, vedi <a href="./node-columns">node-columns.md</a>.</p></blockquote><h2 id="il-contratto" tabindex="-1">Il contratto <a class="header-anchor" href="#il-contratto" aria-label="Permalink to "Il contratto""></a></h2><p>Ogni nodo <code>source</code>/<code>sink</code>/<code>lookup</code>/<code>ai</code>/<code>action</code>/<code>task</code> può esporre un <strong><code>ConnectorDescriptor</code></strong> (<code>src/core/connector.ts</code>):</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> OrigineValore</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "env"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "default"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "mancante"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "non impostata"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
2
2
|
<span class="line"></span>
|
|
3
3
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDetail</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
4
4
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> label</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// es. "host", "database", "table", "query"</span></span>
|
|
@@ -16,7 +16,7 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
16
16
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> kind</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// es. "postgres", "sqlserver", "noeva-file", "file", "memory"</span></span>
|
|
17
17
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> connection</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorConnectionRef</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// assente senza registry</span></span>
|
|
18
18
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> details</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDetail</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[];</span></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un segreto non entra nel descriptor in nessuna forma, nemmeno mascherata: non c'è un valore da svelare, e quindi nemmeno un flag <code>sensitive</code>. Di una credenziale si dice solo <strong>quale variante</strong> è in uso e se è impostata, in una riga <code>credenziale</code>: <code>password · impostata</code>, <code>access token · impostato</code>, <code>token · impostato</code> (HTTP), <code>chiave API · impostata</code> (Noeva), <code>OAuth · identità default · impostata</code>. Se non ne è impostata nessuna, la riga elenca le alternative ammesse ed è <code>mancante</code>; se mancano variabili della variante scelta, le nomina (<code>basic · mancano HTTP_USERNAME, HTTP_PASSWORD</code>) e la sua variabile è la prima da impostare, quella che il badge deve indicare. Con OAuth2 dice anche se l'identità che rinnova il token è completa, o quali sue variabili mancano. Un utente di posta non si mostra mai, quindi se manca lo dice questa riga (<code>… · manca IMAP_USER</code>): senza, il nodo sembrerebbe sano. <strong>La riga <code>credenziale</code> non è mai il primo dettaglio</strong>: la card del nodo mostra il primo, e lì va il sistema a cui il nodo punta.</p><p>Anche un valore non segreto che sia un URL perde le credenziali scritte nella userinfo (<code>utente:password@</code>): lo fanno <code>dettaglioVariabile</code> per le righe dei nodi e <code>variabileDelPiano</code> per <code>PlanSpec.configuration</code> (<code>withoutCredentials</code>, <code>src/connectors/shared/credenziali-url.ts</code>). Un descriptor che compone un URL a mano passa da lì.</p><p><code>env</code> e <code>origine</code> dicono <strong>quale variabile</strong> del <code>.env</code> ha prodotto un dettaglio e <strong>da dove</strong> arriva il valore: <code>env</code> (impostata), <code>default</code> (presa dal codice), <code>mancante</code> (obbligatoria e assente), <code>non impostata</code> (facoltativa, senza default). Servono al pannello del nodo per indicare la riga del <code>.env</code> da correggere e il nodo che ha davvero un problema. Un dettaglio corrisponde a una variabile: <code>host</code> e <code>porta</code> sono righe separate. Restano assenti sui dettagli che non vengono da una variabile (query, tabella, cartella scritte nella pipeline). Oggi li popolano IMAP, SMTP, SendGrid, HTTP, Jira, Zoho, Noeva, Postgres e SQL Server, che leggono la configurazione dal manifest (sotto); gli altri connettori arrivano un tipo alla volta. Le righe che vengono da variabili della pipeline (la cartella di <code>salva-eml</code> in <code>test-posta</code>) le annota la pipeline stessa, con <code>conVariabili</code>.</p><p>Il campo è <strong>opzionale</strong> su <code>Source</code>/<code>Sink</code> (<code>descriptor?</code>). <code>toPlanSpec</code> (<code>src/core/plan-spec.ts</code>) lo proietta su <code>PlanNode.descriptor</code>, da cui viaggia in <code>etl plan</code> → <code>plans.generated.json</code> → UI.</p><p><strong>Solo i nodi che parlano con l'esterno: <code>source</code>, <code>sink</code>, <code>lookup</code>, <code>ai</code>, <code>action</code> e <code>task</code>.</strong> Il <code>lookup</code> (e allo stesso modo il nodo <code>ai</code>, per esempio <code>noevaAiExtract</code> con kind <code>noeva-ai-extract</code>) prende il descriptor dal suo <code>LookupResolver</code> (<code>mssqlLookup</code>: kind <code>sqlserver-lookup</code>; <code>postgresLookup</code>: kind <code>postgres-lookup</code>; entrambi con la query; <code>httpLookup</code>: kind <code>http-lookup</code>, con base, metodo ed endpoint col segnaposto <code>{chiave}</code>; <code>jiraIssueLookup</code> e i lookup delle liste Jira: kind <code>jira-lookup</code>, con sito, operazione e campi). L'<code>action</code> dalla sua <code>Action</code>, dove è <strong>obbligatorio</strong>. Il <code>task</code> dal suo <code>Task</code> (<code>postgresSqlTask</code>: kind <code>postgres-task</code>; <code>mssqlSqlTask</code>: kind <code>sqlserver-task</code>). <code>transform</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>try-catch</code> non sono connettori e non ricevono un descriptor (<code>planNodeDescriptor</code> ritorna <code>undefined</code> per quei kind).</p><h2 id="le-tre-regole-vincolanti" tabindex="-1">Le tre regole vincolanti <a class="header-anchor" href="#le-tre-regole-vincolanti" aria-label="Permalink to "Le tre regole vincolanti""></a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l'oggetto opzioni: conterrebbe <code>password</code>/<code>apiKey</code>/pool.</li><li><strong>Niente segreti.</strong> host/porta/database si leggono dalla config <strong>pubblica</strong> del pool, o dalla risoluzione dell'istanza nel piano, mai da campi credenziale. Se un valore non è derivabile si <strong>omette</strong> il detail — non si inventa e non si mette <code>undefined</code>.</li><li><strong>Un test anti-segreto per connettore.</strong> Ogni connettore ha un <code>descriptor.test.ts</code> che verifica <code>kind</code>, i campi attesi e che nessun <code>value</code> contenga il segreto della fixture (vedi esempi in <code>src/connectors/*/</code>). Sopra c'è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l'ambiente da <code>.env.example</code>, mette un valore riconoscibile al posto di ogni segreto e verifica che il piano di <strong>ogni</strong> pipeline del catalogo non lo contenga, anche con le credenziali alternative commentate. Vale in ogni repo: nel core lo lancia <code>pnpm run check</code>, e <code>.env.example</code> del core porta le variabili di tutte le pipeline del suo catalogo.</li></ol><h2 id="campi-esposti-oggi-per-connettore" tabindex="-1">Campi esposti oggi, per connettore <a class="header-anchor" href="#campi-esposti-oggi-per-connettore" aria-label="Permalink to "Campi esposti oggi, per connettore""></a></h2><table tabindex="0"><thead><tr><th>Connettore</th><th><code>kind</code></th><th><code>details</code> (label) — solo non sensibili</th><th>Fonte</th></tr></thead><tbody><tr><td>Postgres</td><td><code>postgres</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.options</code> + query/table</td></tr><tr><td>SQL Server</td><td><code>sqlserver</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.config</code> (runtime) + query/table</td></tr><tr><td>HTTP lookup</td><td><code>http-lookup</code></td><td>base, richiesta, modalità, credenziale (la variante di <code>HTTP_AUTH</code>). Mai token, chiave, utente né nome dell'header</td><td>config + opzioni del lookup</td></tr><tr><td>HTTP action</td><td><code>http-action</code></td><td>base, richiesta, su errore, scrittura, credenziale. Mai token, chiave, utente né nome dell'header</td><td>config + opzioni dell'action</td></tr><tr><td>Jira source</td><td><code>jira-source</code></td><td>sito, gateway (token con scope), jql, campi (come dichiarati, per id o per nome, <code>updated</code> compreso), raw (solo con <code>raw: true</code>), watermark (solo in incrementale: <code>updated (timestamp)</code> e la sovrapposizione), credenziale («token classico» o «token con scope» e lo stato). Mai token, email né header</td><td>config + opzioni di <code>jiraIssues</code></td></tr><tr><td>Jira lookup</td><td><code>jira-lookup</code></td><td>sito, gateway (token con scope), operazione (<code>issue per chiave</code>; per le liste <code>changelog per issue</code>, <code>commenti per issue</code>, <code>worklog per issue</code> con l'endpoint), campi (come dichiarati, per id o per nome, <code>updated</code> compreso; per il changelog i <code>fieldIds</code>, se filtra), raw (solo con <code>raw: true</code>), credenziale («token classico» o «token con scope» e lo stato). Mai token, email, header né chiavi</td><td>config + opzioni di <code>jiraIssueLookup</code>, <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td></tr><tr><td>Jira action</td><td><code>jira-action</code></td><td>sito, gateway (token con scope), operazione (con l'endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l'upsert: il campo con la sua variabile, e la creazione mai ritentata), deduplica (solo commenti e worklog: la proprietà che porta la chiave e dove si cerca, mai la chiave), verso (solo i link: partenza → arrivo), testo ricco (i campi che accettano markdown), credenziale. Mai token, email, header né valori dei campi</td><td>config + opzioni dell'action Jira</td></tr><tr><td>Zoho source</td><td><code>zoho-source</code></td><td>api (la base delle API, con la sua variabile), modulo, lettura (Records API o COQL), campi (i nomi API dichiarati), credenziale (l'identità OAuth2 che rinnova il token e, nel piano, se è completa). Mai token, client secret né refresh token</td><td>config + opzioni di <code>zohoCrmRecords</code></td></tr><tr><td>Noeva file</td><td><code>noeva-file</code></td><td>baseUrl, workspace, fileName/fileId/fuzzyQuery (source) / fileName, mode, folderId (sink)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>File</td><td><code>file</code></td><td>storage, codec, path/prefix</td><td>nome storage/codec + opzioni</td></tr><tr><td>Noeva cartella</td><td><code>noeva-folder</code></td><td>baseUrl, workspace, folderId, includeSubfolders, skipIfMetadataKey, maxFiles, skipVersion (se attivo)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva multi-file</td><td><code>noeva-files</code></td><td>baseUrl, workspace, mode, folderId</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva upload</td><td><code>noeva-upload</code></td><td>baseUrl, workspace, se già presente, elaborazione AI, folderId, categoria</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva elaborazione</td><td><code>noeva-elaborazione</code></td><td>baseUrl, workspace, pronto (la definizione usata)</td><td>getter pubblici del client</td></tr><tr><td>Noeva testo</td><td><code>noeva-contenuto</code></td><td>baseUrl, workspace</td><td>getter pubblici del client</td></tr><tr><td>Noeva estrazione AI</td><td><code>noeva-ai-extract</code></td><td>baseUrl, workspace, modello, campi, temperature, maxTokens (mai prompt né testi)</td><td>getter pubblici del client + schema</td></tr><tr><td>Cartella locale</td><td><code>local-folder</code></td><td>cartella (come configurata, non risolta), estensioni, età minima, maxFiles</td><td>opzioni di <code>localFolderSource</code></td></tr><tr><td>IMAP</td><td><code>imap</code></td><td>host, porta; cartella, filtro, maxMessages (sorgente); aggiunge/toglie (flag); destinazione (spostamento); credenziale. Mai utente né segreti</td><td>config + opzioni di sorgente e action</td></tr><tr><td>SMTP</td><td><code>smtp</code></td><td>host, porta, mittente (<code>SMTP_FROM</code>), credenziale. Mai utente, segreti né destinatari</td><td>config</td></tr><tr><td>SendGrid</td><td><code>sendgrid</code></td><td>mittente (<code>SENDGRID_FROM</code>), base, sandbox, credenziale (solo lo stato). Mai la chiave né i destinatari</td><td>config</td></tr><tr><td>Solo log</td><td><code>log</code></td><td>esito</td><td>sink che registrano e non scrivono</td></tr><tr><td>SQL Server lookup</td><td><code>sqlserver-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.config</code> (runtime) + query</td></tr><tr><td>Postgres lookup</td><td><code>postgres-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.options</code> + query</td></tr><tr><td>Postgres task</td><td><code>postgres-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.options</code> + opzioni del task</td></tr><tr><td>SQL Server task</td><td><code>sqlserver-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.config</code> (runtime) + opzioni</td></tr><tr><td>Array (mem.)</td><td><code>memory</code></td><td>— (nessuno)</td><td><code>arraySource</code>/<code>arraySink</code></td></tr><tr><td>Processo esterno</td><td><code>processo-esterno</code></td><td>eseguibile, argomenti fissi, versione, timeout, ambiente (solo i <strong>nomi</strong> delle variabili in allowlist, mai i valori)</td><td>opzioni dell'action</td></tr></tbody></table><p>Tutte le righe Noeva della tabella cominciano con baseUrl e workspace, da <code>clientDetails</code>. Con un client costruito dal manifest, subito dopo ci sono la riga <code>configurazione</code> (solo nel client d'esempio, per un valore non valido) e la riga <code>credenziale</code> con lo stato della chiave API (<code>NOEVA_API_KEY</code>). Un client scritto a mano non ha la credenziale.</p><p>La <code>query</code> è mostrata <strong>troncata a 120 caratteri</strong> (<code>queryDetail</code>): è un "puntamento", non il payload. Nel piano, dove non c'è un pool, host, porta e database vengono dalla risoluzione dell'istanza (vedi sotto).</p><h2 id="aggiungere-un-descriptor-a-un-nuovo-connettore" tabindex="-1">Aggiungere un descriptor a un nuovo connettore <a class="header-anchor" href="#aggiungere-un-descriptor-a-un-nuovo-connettore" aria-label="Permalink to "Aggiungere un descriptor a un nuovo connettore""></a></h2><ol><li><p>Nel factory del <code>Source</code>/<code>Sink</code>, costruisci il descriptor con i <strong>soli</strong> campi non sensibili noti alla costruzione:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
19
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Un segreto non entra nel descriptor in nessuna forma, nemmeno mascherata: non c'è un valore da svelare, e quindi nemmeno un flag <code>sensitive</code>. Di una credenziale si dice solo <strong>quale variante</strong> è in uso e se è impostata, in una riga <code>credenziale</code>: <code>password · impostata</code>, <code>access token · impostato</code>, <code>token · impostato</code> (HTTP), <code>chiave API · impostata</code> (Noeva), <code>OAuth · identità default · impostata</code>. Se non ne è impostata nessuna, la riga elenca le alternative ammesse ed è <code>mancante</code>; se mancano variabili della variante scelta, le nomina (<code>basic · mancano HTTP_USERNAME, HTTP_PASSWORD</code>) e la sua variabile è la prima da impostare, quella che il badge deve indicare. Con OAuth2 dice anche se l'identità che rinnova il token è completa, o quali sue variabili mancano. Un utente di posta non si mostra mai, quindi se manca lo dice questa riga (<code>… · manca IMAP_USER</code>): senza, il nodo sembrerebbe sano. <strong>La riga <code>credenziale</code> non è mai il primo dettaglio</strong>: la card del nodo mostra il primo, e lì va il sistema a cui il nodo punta.</p><p>Anche un valore non segreto che sia un URL perde le credenziali scritte nella userinfo (<code>utente:password@</code>): lo fanno <code>dettaglioVariabile</code> per le righe dei nodi e <code>variabileDelPiano</code> per <code>PlanSpec.configuration</code> (<code>withoutCredentials</code>, <code>src/connectors/shared/credenziali-url.ts</code>). Un descriptor che compone un URL a mano passa da lì.</p><p><code>env</code> e <code>origine</code> dicono <strong>quale variabile</strong> del <code>.env</code> ha prodotto un dettaglio e <strong>da dove</strong> arriva il valore: <code>env</code> (impostata), <code>default</code> (presa dal codice), <code>mancante</code> (obbligatoria e assente), <code>non impostata</code> (facoltativa, senza default). Servono al pannello del nodo per indicare la riga del <code>.env</code> da correggere e il nodo che ha davvero un problema. Un dettaglio corrisponde a una variabile: <code>host</code> e <code>porta</code> sono righe separate. Restano assenti sui dettagli che non vengono da una variabile (query, tabella, cartella scritte nella pipeline). Oggi li popolano IMAP, SMTP, SendGrid, HTTP, Jira, Zoho, Odoo, Noeva, Postgres, SQL Server e MySQL, che leggono la configurazione dal manifest (sotto); gli altri connettori arrivano un tipo alla volta. Le righe che vengono da variabili della pipeline (la cartella di <code>salva-eml</code> in <code>test-posta</code>) le annota la pipeline stessa, con <code>conVariabili</code>.</p><p>Il campo è <strong>opzionale</strong> su <code>Source</code>/<code>Sink</code> (<code>descriptor?</code>). <code>toPlanSpec</code> (<code>src/core/plan-spec.ts</code>) lo proietta su <code>PlanNode.descriptor</code>, da cui viaggia in <code>etl plan</code> → <code>plans.generated.json</code> → UI.</p><p><strong>Solo i nodi che parlano con l'esterno: <code>source</code>, <code>sink</code>, <code>lookup</code>, <code>ai</code>, <code>action</code> e <code>task</code>.</strong> Il <code>lookup</code> (e allo stesso modo il nodo <code>ai</code>, per esempio <code>noevaAiExtract</code> con kind <code>noeva-ai-extract</code>) prende il descriptor dal suo <code>LookupResolver</code> (<code>mssqlLookup</code>: kind <code>sqlserver-lookup</code>; <code>postgresLookup</code>: kind <code>postgres-lookup</code>; entrambi con la query; <code>httpLookup</code>: kind <code>http-lookup</code>, con base, metodo ed endpoint col segnaposto <code>{chiave}</code>; <code>jiraIssueLookup</code> e i lookup delle liste Jira: kind <code>jira-lookup</code>, con sito, operazione e campi). L'<code>action</code> dalla sua <code>Action</code>, dove è <strong>obbligatorio</strong>. Il <code>task</code> dal suo <code>Task</code> (<code>postgresSqlTask</code>: kind <code>postgres-task</code>; <code>mssqlSqlTask</code>: kind <code>sqlserver-task</code>). <code>transform</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>try-catch</code> non sono connettori e non ricevono un descriptor (<code>planNodeDescriptor</code> ritorna <code>undefined</code> per quei kind).</p><h2 id="le-tre-regole-vincolanti" tabindex="-1">Le tre regole vincolanti <a class="header-anchor" href="#le-tre-regole-vincolanti" aria-label="Permalink to "Le tre regole vincolanti""></a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l'oggetto opzioni: conterrebbe <code>password</code>/<code>apiKey</code>/pool.</li><li><strong>Niente segreti.</strong> host/porta/database si leggono dalla config <strong>pubblica</strong> del pool, o dalla risoluzione dell'istanza nel piano, mai da campi credenziale. Se un valore non è derivabile si <strong>omette</strong> il detail — non si inventa e non si mette <code>undefined</code>.</li><li><strong>Un test anti-segreto per connettore.</strong> Ogni connettore ha un <code>descriptor.test.ts</code> che verifica <code>kind</code>, i campi attesi e che nessun <code>value</code> contenga il segreto della fixture (vedi esempi in <code>src/connectors/*/</code>). Sopra c'è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l'ambiente da <code>.env.example</code>, mette un valore riconoscibile al posto di ogni segreto e verifica che il piano di <strong>ogni</strong> pipeline del catalogo non lo contenga, anche con le credenziali alternative commentate. Vale in ogni repo: nel core lo lancia <code>pnpm run check</code>, e <code>.env.example</code> del core porta le variabili di tutte le pipeline del suo catalogo.</li></ol><h2 id="campi-esposti-oggi-per-connettore" tabindex="-1">Campi esposti oggi, per connettore <a class="header-anchor" href="#campi-esposti-oggi-per-connettore" aria-label="Permalink to "Campi esposti oggi, per connettore""></a></h2><table tabindex="0"><thead><tr><th>Connettore</th><th><code>kind</code></th><th><code>details</code> (label) — solo non sensibili</th><th>Fonte</th></tr></thead><tbody><tr><td>Postgres</td><td><code>postgres</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.options</code> + query/table</td></tr><tr><td>SQL Server</td><td><code>sqlserver</code></td><td>host, porta, database, query (source) / table (sink)</td><td><code>pool.config</code> (runtime) + query/table</td></tr><tr><td>MySQL, MariaDB</td><td><code>mysql</code></td><td>host, porta, database, query (source) / table (sink)</td><td></td></tr><tr><td>HTTP lookup</td><td><code>http-lookup</code></td><td>base, richiesta, modalità, credenziale (la variante di <code>HTTP_AUTH</code>). Mai token, chiave, utente né nome dell'header</td><td>config + opzioni del lookup</td></tr><tr><td>HTTP action</td><td><code>http-action</code></td><td>base, richiesta, su errore, scrittura, credenziale. Mai token, chiave, utente né nome dell'header</td><td>config + opzioni dell'action</td></tr><tr><td>Jira source</td><td><code>jira-source</code></td><td>sito, gateway (token con scope), jql, campi (come dichiarati, per id o per nome, <code>updated</code> compreso), raw (solo con <code>raw: true</code>), watermark (solo in incrementale: <code>updated (timestamp)</code> e la sovrapposizione), credenziale («token classico» o «token con scope» e lo stato). Mai token, email né header</td><td>config + opzioni di <code>jiraIssues</code></td></tr><tr><td>Jira lookup</td><td><code>jira-lookup</code></td><td>sito, gateway (token con scope), operazione (<code>issue per chiave</code>; per le liste <code>changelog per issue</code>, <code>commenti per issue</code>, <code>worklog per issue</code> con l'endpoint), campi (come dichiarati, per id o per nome, <code>updated</code> compreso; per il changelog i <code>fieldIds</code>, se filtra), raw (solo con <code>raw: true</code>), credenziale («token classico» o «token con scope» e lo stato). Mai token, email, header né chiavi</td><td>config + opzioni di <code>jiraIssueLookup</code>, <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code>, <code>jiraWorklogsLookup</code></td></tr><tr><td>Jira action</td><td><code>jira-action</code></td><td>sito, gateway (token con scope), operazione (con l'endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l'upsert: il campo con la sua variabile, e la creazione mai ritentata), deduplica (solo commenti e worklog: la proprietà che porta la chiave e dove si cerca, mai la chiave), verso (solo i link: partenza → arrivo), testo ricco (i campi che accettano markdown), credenziale. Mai token, email, header né valori dei campi</td><td>config + opzioni dell'action Jira</td></tr><tr><td>Zoho source</td><td><code>zoho-source</code></td><td>api (la base delle API, con la sua variabile), modulo, lettura (Records API o COQL), campi (i nomi API dichiarati), credenziale (l'identità OAuth2 che rinnova il token e, nel piano, se è completa). Mai token, client secret né refresh token</td><td>config + opzioni di <code>zohoCrmRecords</code></td></tr><tr><td>Odoo source</td><td><code>odoo-source</code></td><td>istanza e database (con le loro variabili), modello, dominio (se c'è, troncato), lettura, campi (i nomi tecnici dichiarati), credenziale (il protocollo e se login e chiave sono impostati). Mai la chiave né il login; <code>odooConteggi</code> mostra i modelli al posto di modello e campi</td><td>config + opzioni di <code>odooRecords</code> / <code>odooConteggi</code></td></tr><tr><td>Noeva file</td><td><code>noeva-file</code></td><td>baseUrl, workspace, fileName/fileId/fuzzyQuery (source) / fileName, mode, folderId (sink)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>File</td><td><code>file</code></td><td>storage, codec, path/prefix</td><td>nome storage/codec + opzioni</td></tr><tr><td>Excel</td><td><code>excel</code></td><td>storage, path o prefix, foglio, riga d'intestazione (source); storage, path, foglio, modalità, destructive, e con <code>cancellaQuando</code> il campo e <code>cancellaRighe</code> (sink). Mai valori dei record</td><td></td></tr><tr><td>Excel task</td><td><code>excel-task</code></td><td>storage, path, una voce per operazione, destructive (<code>true</code> se c'è <code>deleteSheet</code> o <code>deleteColumns</code>)</td><td></td></tr><tr><td>Noeva cartella</td><td><code>noeva-folder</code></td><td>baseUrl, workspace, folderId, includeSubfolders, skipIfMetadataKey, maxFiles, skipVersion (se attivo)</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva multi-file</td><td><code>noeva-files</code></td><td>baseUrl, workspace, mode, folderId</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva upload</td><td><code>noeva-upload</code></td><td>baseUrl, workspace, se già presente, elaborazione AI, folderId, categoria</td><td>getter pubblici del client + opzioni</td></tr><tr><td>Noeva elaborazione</td><td><code>noeva-elaborazione</code></td><td>baseUrl, workspace, pronto (la definizione usata)</td><td>getter pubblici del client</td></tr><tr><td>Noeva testo</td><td><code>noeva-contenuto</code></td><td>baseUrl, workspace</td><td>getter pubblici del client</td></tr><tr><td>Noeva estrazione AI</td><td><code>noeva-ai-extract</code></td><td>baseUrl, workspace, modello, campi, temperature, maxTokens (mai prompt né testi)</td><td>getter pubblici del client + schema</td></tr><tr><td>Cartella locale</td><td><code>local-folder</code></td><td>cartella (come configurata, non risolta), estensioni, età minima, maxFiles</td><td>opzioni di <code>localFolderSource</code></td></tr><tr><td>IMAP</td><td><code>imap</code></td><td>host, porta; cartella, filtro, maxMessages (sorgente); aggiunge/toglie (flag); destinazione (spostamento); credenziale. Mai utente né segreti</td><td>config + opzioni di sorgente e action</td></tr><tr><td>SMTP</td><td><code>smtp</code></td><td>host, porta, mittente (<code>SMTP_FROM</code>), credenziale. Mai utente, segreti né destinatari</td><td>config</td></tr><tr><td>SendGrid</td><td><code>sendgrid</code></td><td>mittente (<code>SENDGRID_FROM</code>), base, sandbox, credenziale (solo lo stato). Mai la chiave né i destinatari</td><td>config</td></tr><tr><td>Solo log</td><td><code>log</code></td><td>esito</td><td>sink che registrano e non scrivono</td></tr><tr><td>SQL Server lookup</td><td><code>sqlserver-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.config</code> (runtime) + query</td></tr><tr><td>MySQL lookup</td><td><code>mysql-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td></td></tr><tr><td>Postgres lookup</td><td><code>postgres-lookup</code></td><td>host, porta, database, query (+ <code>connection</code> dal registry)</td><td><code>pool.options</code> + query</td></tr><tr><td>Postgres task</td><td><code>postgres-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.options</code> + opzioni del task</td></tr><tr><td>SQL Server task</td><td><code>sqlserver-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td><code>pool.config</code> (runtime) + opzioni</td></tr><tr><td>MySQL task</td><td><code>mysql-task</code></td><td>host, porta, database, statement o statement 1…N (letterali mascherati), params (soli nomi), destructive (+ <code>connection</code>)</td><td></td></tr><tr><td>Array (mem.)</td><td><code>memory</code></td><td>— (nessuno)</td><td><code>arraySource</code>/<code>arraySink</code></td></tr><tr><td>Processo esterno</td><td><code>processo-esterno</code></td><td>eseguibile, argomenti fissi, versione, timeout, ambiente (solo i <strong>nomi</strong> delle variabili in allowlist, mai i valori)</td><td>opzioni dell'action</td></tr></tbody></table><p>Tutte le righe Noeva della tabella cominciano con baseUrl e workspace, da <code>clientDetails</code>. Con un client costruito dal manifest, subito dopo ci sono la riga <code>configurazione</code> (solo nel client d'esempio, per un valore non valido) e la riga <code>credenziale</code> con lo stato della chiave API (<code>NOEVA_API_KEY</code>). Un client scritto a mano non ha la credenziale.</p><p>La <code>query</code> è mostrata <strong>troncata a 120 caratteri</strong> (<code>queryDetail</code>): è un "puntamento", non il payload. Nel piano, dove non c'è un pool, host, porta e database vengono dalla risoluzione dell'istanza (vedi sotto).</p><h2 id="aggiungere-un-descriptor-a-un-nuovo-connettore" tabindex="-1">Aggiungere un descriptor a un nuovo connettore <a class="header-anchor" href="#aggiungere-un-descriptor-a-un-nuovo-connettore" aria-label="Permalink to "Aggiungere un descriptor a un nuovo connettore""></a></h2><ol><li><p>Nel factory del <code>Source</code>/<code>Sink</code>, costruisci il descriptor con i <strong>soli</strong> campi non sensibili noti alla costruzione:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
20
20
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name,</span></span>
|
|
21
21
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> descriptor: {</span></span>
|
|
22
22
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> kind: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"mio-sistema"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
@@ -28,7 +28,7 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
28
28
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">extract</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
29
29
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> /* ... */</span></span>
|
|
30
30
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div></li><li><p>Se i campi vengono da un client/pool con credenziali, esponi <strong>getter pubblici</strong> solo per i valori non sensibili (vedi <code>NoevaHttpClient.baseUrl</code>/<code>workspaceId</code>) e un helper dedicato (<code>src/connectors/<sistema>/descriptor.ts</code>).</p></li><li><p>Scrivi il test anti-segreto colocato (<code>descriptor.test.ts</code>).</p></li><li><p>Aggiorna la riga di questo file e la scheda del connettore in <code>docs/connectors/</code>.</p></li></ol><h2 id="getspec-senza-credenziali-connettori-stub" tabindex="-1"><code>getSpec()</code> senza credenziali: connettori stub <a class="header-anchor" href="#getspec-senza-credenziali-connettori-stub" aria-label="Permalink to "\`getSpec()\` senza credenziali: connettori stub""></a></h2><p><code>etl plan</code> non apre connessioni, quindi le pipeline con connettori a DB o API derivano il piano dal grafo reale costruito con connettori <strong>stub</strong> (vedi <code>crm-leads-sync/run.ts</code>). Il descriptor sta sullo stub, coi campi noti senza connessione (kind, query, tabella). Riusa <code>queryDetail</code> dal barrel del connettore per troncare la query in modo coerente con il connettore vero. Non si scrive un <code>PlanSpec</code> letterale a mano.</p><p>Host, porta e database di uno stub Postgres o SQL Server non vengono da un pool, ma dalla <strong>risoluzione dell'istanza</strong> del registry: <code>istanzaPgPerIlPiano</code> / <code>istanzaMssqlPerIlPiano</code> danno la <code>ConnessioneSql</code> dell'istanza, e <code>dettagliConnessioneSql</code> (<code>src/connectors/shared/connessione-sql.ts</code>) ne fa le righe <code>host</code>, <code>porta</code> e <code>database</code> con variabile e origine, poi quelle del nodo e in fondo la <code>credenziale</code> (<code>password · impostata</code>). L'istanza si carica con <code>loadPgConnessione</code> / <code>loadMssqlConnessione</code>, che non leggono le altre: un'istanza <code>dwh</code> incompleta non porta all'esempio la <code>default</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> configurazioneDelPiano</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div></li><li><p>Se i campi vengono da un client/pool con credenziali, esponi <strong>getter pubblici</strong> solo per i valori non sensibili (vedi <code>NoevaHttpClient.baseUrl</code>/<code>workspaceId</code>) e un helper dedicato (<code>src/connectors/<sistema>/descriptor.ts</code>).</p></li><li><p>Scrivi il test anti-segreto colocato (<code>descriptor.test.ts</code>).</p></li><li><p>Aggiorna la riga di questo file e la scheda del connettore in <code>docs/connectors/</code>.</p></li></ol><h2 id="getspec-senza-credenziali-connettori-stub" tabindex="-1"><code>getSpec()</code> senza credenziali: connettori stub <a class="header-anchor" href="#getspec-senza-credenziali-connettori-stub" aria-label="Permalink to "\`getSpec()\` senza credenziali: connettori stub""></a></h2><p><code>etl plan</code> non apre connessioni, quindi le pipeline con connettori a DB o API derivano il piano dal grafo reale costruito con connettori <strong>stub</strong> (vedi <code>crm-leads-sync/run.ts</code>). Il descriptor sta sullo stub, coi campi noti senza connessione (kind, query, tabella). Riusa <code>queryDetail</code> dal barrel del connettore per troncare la query in modo coerente con il connettore vero. Non si scrive un <code>PlanSpec</code> letterale a mano.</p><p>Host, porta e database di uno stub Postgres o SQL Server non vengono da un pool, ma dalla <strong>risoluzione dell'istanza</strong> del registry: <code>istanzaPgPerIlPiano</code> / <code>istanzaMssqlPerIlPiano</code> / <code>istanzaMysqlPerIlPiano</code> danno la <code>ConnessioneSql</code> dell'istanza, e <code>dettagliConnessioneSql</code> (<code>src/connectors/shared/connessione-sql.ts</code>) ne fa le righe <code>host</code>, <code>porta</code> e <code>database</code> con variabile e origine, poi quelle del nodo e in fondo la <code>credenziale</code> (<code>password · impostata</code>). L'istanza si carica con <code>loadPgConnessione</code> / <code>loadMssqlConnessione</code>, che non leggono le altre: un'istanza <code>dwh</code> incompleta non porta all'esempio la <code>default</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> configurazioneDelPiano</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
32
32
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pg: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">istanzaPgPerIlPiano</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">PG_INSTANCE</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, process.env),</span></span>
|
|
33
33
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mssql: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">istanzaMssqlPerIlPiano</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">MSSQL_INSTANCE</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, process.env),</span></span>
|
|
34
34
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
|
|
@@ -76,4 +76,4 @@ import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
76
76
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
77
77
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// risoluzione.variabili: { variabile, origine, segreta, valore? } per ogni variabile</span></span>
|
|
78
78
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// risoluzione.mancanti: tutte le variabili obbligatorie assenti</span></span>
|
|
79
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">richiediCompleta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(risoluzione); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// la run: ConfigError con \`mancanti\` strutturato</span></span></code></pre></div><ul><li><strong>Segreti:</strong> di una variabile <code>segreta</code> la risoluzione restituisce solo l'origine, mai il valore — nemmeno al default calcolato di un'altra variabile.</li><li><strong>Gruppi «una fra»</strong> (<code>unaFra</code>): credenziali alternative; ne va impostata una sola. Più di una è un problema (<code>alternative multiple</code>), nessuna è <code>mancante</code> se il gruppo è obbligatorio. Ogni alternativa porta l'elenco del gruppo in <code>alternative</code>.</li><li><strong>Varianti</strong> (<code>selettore</code> + <code>varianti</code>): variabili scelte dal valore di un'altra, come <code>HTTP_AUTH</code>. Si risolvono solo quelle della variante scelta; un valore fuori elenco è un problema (<code>variante sconosciuta</code>). Con <code>senzaSelettore</code> si dichiarano le voci per il selettore assente: <code>IMAP_AUTH</code> è facoltativa, e senza vale una fra password e token.</li><li><strong>Obbligatorietà calcolata</strong>: <code>obbligatoria</code> accetta una funzione dei valori non segreti precedenti, come il default. Le credenziali SMTP servono solo se <code>SMTP_USER</code> è impostato.</li><li>I <strong>prefissi base</strong> sono costanti di <code>src/connectors/shared/prefissi.ts</code> (<code>PREFISSO_PG</code>, <code>PREFISSO_IMAP</code>…), le stesse che usano registry e loader.</li></ul><p>La funzione è pura: il piano mostra la risoluzione com'è, la run chiama <code>richiediCompleta</code> e si ferma con <code>ConfigError</code> come prima. Il loader mette <code>risoluzione.variabili</code> sulla config (<code>ImapConfig.variabili</code>), e il descriptor ne ricava le righe con <code>dettaglioVariabile(label, valore, variabileDi(config.variabili, "HOST"))</code>: valore, variabile e origine. Le credenziali di posta hanno la loro riga, <code>dettaglioCredenzialiPosta</code>; Postgres
|
|
79
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">richiediCompleta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(risoluzione); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// la run: ConfigError con \`mancanti\` strutturato</span></span></code></pre></div><ul><li><strong>Segreti:</strong> di una variabile <code>segreta</code> la risoluzione restituisce solo l'origine, mai il valore — nemmeno al default calcolato di un'altra variabile.</li><li><strong>Gruppi «una fra»</strong> (<code>unaFra</code>): credenziali alternative; ne va impostata una sola. Più di una è un problema (<code>alternative multiple</code>), nessuna è <code>mancante</code> se il gruppo è obbligatorio. Ogni alternativa porta l'elenco del gruppo in <code>alternative</code>.</li><li><strong>Varianti</strong> (<code>selettore</code> + <code>varianti</code>): variabili scelte dal valore di un'altra, come <code>HTTP_AUTH</code>. Si risolvono solo quelle della variante scelta; un valore fuori elenco è un problema (<code>variante sconosciuta</code>). Con <code>senzaSelettore</code> si dichiarano le voci per il selettore assente: <code>IMAP_AUTH</code> è facoltativa, e senza vale una fra password e token.</li><li><strong>Obbligatorietà calcolata</strong>: <code>obbligatoria</code> accetta una funzione dei valori non segreti precedenti, come il default. Le credenziali SMTP servono solo se <code>SMTP_USER</code> è impostato.</li><li>I <strong>prefissi base</strong> sono costanti di <code>src/connectors/shared/prefissi.ts</code> (<code>PREFISSO_PG</code>, <code>PREFISSO_IMAP</code>…), le stesse che usano registry e loader.</li></ul><p>La funzione è pura: il piano mostra la risoluzione com'è, la run chiama <code>richiediCompleta</code> e si ferma con <code>ConfigError</code> come prima. Il loader mette <code>risoluzione.variabili</code> sulla config (<code>ImapConfig.variabili</code>), e il descriptor ne ricava le righe con <code>dettaglioVariabile(label, valore, variabileDi(config.variabili, "HOST"))</code>: valore, variabile e origine. Le credenziali di posta hanno la loro riga, <code>dettaglioCredenzialiPosta</code>; Postgres, SQL Server e MySQL, che hanno la sola password, la mettono in fondo a <code>dettagliConnessioneSql</code>. <code>ConfigError.mancanti</code> elenca <strong>tutte</strong> le variabili mancanti, non solo la prima, ed è vuoto per gli errori che non riguardano variabili assenti.</p><h2 id="nodi-dead-letter" tabindex="-1">Nodi dead-letter <a class="header-anchor" href="#nodi-dead-letter" aria-label="Permalink to "Nodi dead-letter""></a></h2><p><code>toPlanSpec</code> proietta il <code>deadLetter</code> di un nodo transform/join in un nodo sintetico <code>stepType: "dead-letter"</code> + edge <code>kind: "dead-letter"</code>. Quel nodo <strong>riusa il descriptor del sink di scarto</strong> per dire <em>dove</em> finiscono gli errori (kind + destinazione), esattamente come un sink normale — nessuna regola nuova qui, solo un altro <code>stepType</code> che porta lo stesso <code>descriptor?</code>.</p><h2 id="sync-con-la-ui" tabindex="-1">Sync con la UI <a class="header-anchor" href="#sync-con-la-ui" aria-label="Permalink to "Sync con la UI""></a></h2><p>Il contratto è duplicato in <code>noeva-etl-ui</code> (submodule indipendente): tipo <code>ConnectorDescriptor</code>, schema Zod in <code>plan-loader.ts</code>, rendering in <code>DatasetNode</code>/<code>DetailPanel</code>. Modifiche al descriptor vanno propagate su entrambi i lati nello stesso PR-set. Lato UI: <code>noeva-etl-ui/docs/dag-node-visualization.md</code>.</p>`,45)])])}const g=e(n,[["render",t]]);export{k as __pageData,g as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as e,o as a,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Descriptor dei nodi per la UI del DAG","description":"","frontmatter":{},"headers":[],"relativePath":"conventions/node-descriptor.md","filePath":"conventions/node-descriptor.md"}'),n={name:"conventions/node-descriptor.md"};function t(l,i,d,r,c,p){return a(),s("div",null,[...i[0]||(i[0]=[o("",45)])])}const g=e(n,[["render",t]]);export{k as __pageData,g as default};
|
|
@@ -42,7 +42,7 @@ import{_ as i,o as a,c as e,a5 as t}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
42
42
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "durationMs"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1360</span></span>
|
|
43
43
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
44
44
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
45
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><p><code>etl runs show</code> mostra la sezione «Istanze» dopo la tabella dei nodi: una riga per istanza, indentata per profondità, con entrati, usciti per uscita, rifiutati e durata («mai avviata» o «interrotta» quando l'istanza è partita ma nessun suo nodo si è concluso). Senza istanze la sezione non compare.</p><h3 id="task" tabindex="-1">Task <a class="header-anchor" href="#task" aria-label="Permalink to "Task""></a></h3><p>Un <code>task</code> è un nodo del report con <code>kind: "task"</code>. Non vede record: <code>extracted</code>, <code>written</code> e <code>rejected</code> restano a 0, e non entra nei totali della run. <code>startedAt</code> è l'ingresso in <code>run()</code>, <code>finishedAt</code> l'uscita. I dettagli, per esempio le righe toccate da un task SQL, stanno in <code>nodeReports</code>. <code>retries</code> compare con una policy di <code>retry</code>.</p><p><code>startedAt: null</code> <strong>non è un dato mancante</strong>: significa che il nodo non ha mai attraversato un record — input vuoto, filtro che scarta tutto a monte, o run abortita prima che il nodo partisse. È il corollario documentato su <code>ProgressReporter.onNodeStart</code>. In quel caso <code>durationMs</code> è <code>0</code>: una durata non misurata si dichiara zero, non si deriva da un solo estremo.</p><h3 id="run-fallita-topologia-e-conteggi-parziali" tabindex="-1">Run fallita: topologia e conteggi parziali <a class="header-anchor" href="#run-fallita-topologia-e-conteggi-parziali" aria-label="Permalink to "Run fallita: topologia e conteggi parziali""></a></h3><p>Al primo errore fatale il runner <strong>annulla tutti i rami</strong> e aspetta che ogni sink e ogni task chiuda, poi assembla il report: una run <code>failed</code> non scrive più niente dopo essere stata riportata tale. <code>error</code> è il primo errore, quello del nodo che è fallito; i nodi degli altri rami risultano interrotti.</p><p>Un report <code>failed</code> prodotto da una run che è <strong>partita</strong> contiene la topologia reale e i conteggi accumulati fino all'abort — è proprio la run che più serve ispezionare, e lasciarla come guscio vuoto sarebbe un difetto.</p><p>Un report <code>failed</code> prodotto da <code>buildFailedGraphReport</code> (fallimento <strong>prima</strong> del grafo) ha invece <code>nodes: []</code> / <code>edges: []</code>, perché non c'è alcuna topologia eseguita da riportare, e <code>instances: []</code>.</p><p>Il report allegato all'errore porta anche <code>instances</code>, col riepilogo di quanto contato fino all'interruzione.</p><h3 id="nodereports-e-writereport" tabindex="-1"><code>nodeReports</code> e <code>writeReport</code> <a class="header-anchor" href="#nodereports-e-writereport" aria-label="Permalink to "\`nodeReports\` e \`writeReport\`""></a></h3><p>Ogni nodo del grafo (source/transform/lookup/ai/action/route/join/union/sink/try-catch/task) può ricevere un'opzione <code>writeReport: (ctx, stats) => Record<string, unknown></code> in fase di costruzione: <code>GraphBuilder.source/transform/lookup/ai/action/route/join/union/sink/tryCatch/task(..., { writeReport })</code>. <code>stats</code> espone i conteggi del nodo (<code>extracted</code>/<code>written</code>/ <code>rejected</code>/<code>rejectedReasons</code>) così un nodo può riassumere i volumi senza scrivere il payload grezzo (es. <code>{ recordsFetched: 1_000_000 }</code> invece del milione di record). Se né il nodo né la sua transform (o il suo task) dichiarano un <code>writeReport</code>, o se quello in uso lancia, il runner scrive il default <code>{ name: node.name, success }</code>, dove <code>success</code> è <code>true</code> se il nodo non ha abortito la run (uno scarto isolato a dead-letter non conta come fallimento).</p><p>Una <strong>transform può dichiarare il proprio <code>writeReport</code> di default</strong> (<code>Transform.writeReport</code>): è il modo in cui <code>profile</code> porta il profilo delle colonne, <code>assert</code> l'esito dei suoi check, e i nodi <code>lookup</code> e <code>ai</code> i propri contatori (sotto <code>lookup</code>), nel report senza che la pipeline cabli nulla. Un <strong>task</strong> fa lo stesso con <code>Task.writeReport</code>: il task SQL ci porta le righe toccate da ogni statement. L'ordine è: <code>writeReport</code> del nodo, poi quello della transform, poi il default. Quello del nodo <strong>sostituisce</strong> quello della transform, non lo unisce. Il report dichiarato dalla transform si calcola anche quando il nodo fallisce, e un suo errore ricade sul default con un warning, come per quello del nodo. La forma di <code>nodeReports</code> non cambia (resta una mappa di oggetti liberi), quindi non ha inciso su <code>reportSchemaVersion</code>.</p><p>Sui nodi <code>lookup</code>, <code>ai</code> e <code>action</code>, l'opzione <strong><code>recordReport: { row, key?, maxRows? }</code></strong> aggiunge al report del nodo una riga a campi semplici per ogni record riuscito, sotto <code>key</code> (default <code>records</code>), <strong>accanto</strong> al report della transform (o a <code>{ name }</code>, se la transform non ne ha uno). Un <code>writeReport</code> sullo stesso nodo è un errore di composizione. Al più <code>maxRows</code> righe (default 500, il resto in <code>rowsOmitted</code>; le righe che <code>row</code> non è riuscita a scrivere in <code>rowsFailed</code>), stringhe tagliate a 500 caratteri. I campi che <code>row</code> restituisce sono persistiti: la scheda della pipeline li elenca. Anche questo non tocca <code>reportSchemaVersion</code>.</p><p><code>processes.output_data</code> riceve gli stessi report <strong>incrementalmente</strong>, durante l'esecuzione (non solo a fine run). Accanto a <code>nodeReports</code> viaggia <code>runningNodes: string[]</code> — i nodi che stanno elaborando <strong>adesso</strong> (partiti e non ancora completati), da <code>ProgressReporter.onNodeStart</code>. È ciò che permette alla UI di distinguere un nodo che lavora da uno in attesa, e quindi di mostrare due rami concorrenti. Assente sulle run concluse.</p><p>Con loro viaggia <code>skippedNodes: { [nodeId]: { because } }</code>, i nodi <strong>saltati</strong> fin qui. È sempre presente, <code>{}</code> se nessun nodo è saltato: una chiave assente vuol dire un motore precedente. Sta in una mappa a sé e non dentro <code>nodeReports[nodeId]</code>, che è l'output di <code>writeReport</code> e ha le chiavi scelte dalla pipeline. Come <code>runningNodes</code> è assente sulle run concluse, dove <code>nodes[].skipped</code> del report dice la stessa cosa.</p><p>La quarta chiave è <code>nodeCounts: { [nodeId]: { entered, exited, errored, caught?, held? } }</code>, i contatori dal vivo. Anche lei sempre presente, <code>{}</code> finché nessun nodo ha contato nulla, e assente sulle run concluse, dove valgono i conteggi di <code>nodes[]</code>. <code>noeva-server-api</code> sostituisce <code>output_data</code> a ogni scrittura invece di fonderlo, quindi il worker rimanda ogni volta tutte e quattro le chiavi.</p><p><code>nodes</code> ed <code>edges</code> sono la topologia <strong>reale</strong> del grafo eseguito: un nodo per ogni <code>source</code>/<code>transform</code>/<code>lookup</code>/<code>ai</code>/<code>action</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>sink</code>/<code>try-catch</code>/<code>task</code> dichiarato nel builder. Non esiste un nodo sintetico che collassa la catena.</p><h3 id="contatori-dal-vivo" tabindex="-1">Contatori dal vivo <a class="header-anchor" href="#contatori-dal-vivo" aria-label="Permalink to "Contatori dal vivo""></a></h3><p>Mentre la run è in corso ogni nodo ha tre contatori, più due che hanno solo alcuni nodi. I primi quattro sono gli stessi numeri del report, letti prima che la run finisca:</p><table tabindex="0"><thead><tr><th>Contatore</th><th>Campo di <code>NodeCounts</code></th><th>A fine run, nel report</th></tr></thead><tbody><tr><td>Entrati</td><td><code>entered</code></td><td><code>extracted</code></td></tr><tr><td>Usciti</td><td><code>exited</code></td><td><code>written</code></td></tr><tr><td>In errore</td><td><code>errored</code></td><td><code>rejected</code> + i <code>caughtErrors</code> di tutti i guard con <code>sourceNodeId</code> = il nodo</td></tr><tr><td>Catturati</td><td><code>caught</code>, solo guard</td><td><code>caught</code> del <code>try-catch</code></td></tr><tr><td>In lavorazione</td><td><code>held</code>, solo chi lo dichiara</td><td>— (non c'è: a fine run vale zero)</td></tr></tbody></table><p>«In errore» conta un errore catturato da un <code>try-catch</code> sul nodo <strong>in cui è nato</strong>, non sul guard: il guard mostra a parte i suoi catturati. Un retry poi riuscito non è un errore. In circuit-breaker, e su un sink opaco, la cattura è <strong>una per evento</strong> e non per record: il nodo segna un errore anche se lo stream interrotto ne portava di più, come <code>caught</code> sul guard.</p><p><strong>In lavorazione</strong> (<code>held</code>) sono i record che il nodo sta trattenendo ora. Non si ricava per differenza: c'è solo sui nodi che lo sanno, e <strong>assente non vuol dire zero</strong>.</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Cosa conta</th></tr></thead><tbody><tr><td><code>join</code></td><td>i record del probe letti in anticipo e non ancora confrontati</td></tr><tr><td><code>try-catch</code></td><td>gli errori in coda che il ramo <code>catch</code> non ha ancora preso</td></tr><tr><td>un nodo con più edge in uscita (fan-out), un <code>route</code></td><td>i record nel buffer del <code>tee</code> che il ramo più lento non ha ancora preso</td></tr><tr><td>una transform che dichiara <code>Transform.held</code></td><td>i record ricevuti e non ancora fatti uscire</td></tr><tr><td><code>lookup</code>, <code>ai</code></td><td>i record della finestra: accumulati, in volo col round-trip, non ancora emessi</td></tr><tr><td><code>action</code></td><td>il record in volo: uno mentre l'azione non ha risposto</td></tr><tr><td>un sink con <code>retry</code> o <code>rateLimit</code></td><td>il blocco del runner, in riempimento o in scrittura; un <code>loadOne</code> in volo</td></tr><tr><td>un sink senza policy che dichiara <code>Sink.held</code></td><td>le righe nel batch del sink non ancora scritte</td></tr></tbody></table><p>Le transform di libreria che lo dichiarano oggi sono <code>sort</code>, <code>groupBy</code>, <code>pivot</code>, <code>chunk</code>, <code>serialize</code> e <code>assert</code> in gate. Un nodo che ha due di queste voci (un <code>sort</code> con un fan-out) le somma. Due nodi trattengono record <strong>senza</strong> dichiararlo, e quindi non hanno il campo: <code>dedup</code> con <code>keep: "last"</code> e i buffer di prefetch di un <code>union</code> in <code>concat</code>.</p><p>Su <code>lookup</code>, <code>ai</code> e <code>action</code> conta <strong>record</strong>, non chiamate: un round-trip copre una finestra intera, e un resolver che fa più richieste in parallelo (<code>httpLookup</code> per chiave) non cambia il numero. Dove il runner esegue il nodo record per record (guard per-record, dead-letter di nodo, <code>recordIds</code>) la finestra è da uno. Sui sink <code>Sink.held</code> lo dichiarano Postgres e SQL Server, upsert e SCD2. Con una policy il blocco del runner comprende già il batch del sink, quindi conta solo lui: sommarli conterebbe due volte le stesse righe. Il batch del sink conta finché lo statement non risponde; le righe già scritte ma non ancora confermate dal commit non sono né in lavorazione né uscite. A run conclusa, riuscita o fallita, l'ultima emissione porta <code>held: 0</code> su ogni nodo che lo dichiara, anche se un fallimento ha lasciato un buffer pieno.</p><p>Gli usciti di un <strong>sink</strong> salgono quando il sink dice di aver scritto: a ogni record sotto un guard per-record, a ogni blocco di <code>batchSize</code> con una policy di <code>retry</code>. Senza nessuno dei due il sink scrive in un solo <code>load</code>, e i suoi usciti arrivano tutti a fine scrittura, mentre gli entrati salgono record per record.</p><p>Il runner li emette con <code>ProgressReporter.onProgress</code>: <strong>un evento per run</strong>, al più ogni secondo (<code>PROGRESS_INTERVAL_MS</code>), con i soli nodi cambiati. Un nodo mai partito o saltato non compare mai. A run conclusa, riuscita o fallita, arriva un'ultima emissione prima che <code>runGraph</code> restituisca: l'ultimo valore di ogni nodo è quello del report. Senza un <code>onProgress</code> nel reporter non parte nessun timer.</p><p>I nodi sono quelli del grafo <strong>eseguito</strong>: su una root con sub-pipeline, che l'appiattimento riduce a nodi piatti al <code>build()</code>, i contatori arrivano per <strong>id qualificato</strong> (<code>inst</code>, <code>inst/per-due</code>, <code>inst/dentro/per-due</code>), come nel report. Il nodo di confine d'ingresso di un'istanza ha l'id dell'istanza, ed è lì che un record fuori schema conta «in errore».</p><p>Il worker non inoltra ogni emissione: accumula i contatori nodo per nodo e li scrive su <code>processes</code> al più ogni cinque secondi, la prima volta subito e poi a fine finestra con l'ultimo valore, se nel frattempo un avvio o un completamento di nodo non li ha già portati. Una scrittura fallita si riprova alla finestra dopo. A run conclusa il worker chiude la finestra e aspetta la scrittura in volo prima del report finale: arrivata dopo, lo sostituirebbe. Chi segue una run sul worker col solo polling vede quindi i contatori fino a ~5 s indietro, più i 2 s del polling della UI.</p><table tabindex="0"><thead><tr><th>Canale</th><th>Dove</th></tr></thead><tbody><tr><td><code>ProgressReporter.onProgress</code></td><td><code>update.nodes: NodeCounts[]</code></td></tr><tr><td>Stream SSE <code>GET /runs/:id/events</code></td><td><code>node-progress</code> con <code>nodes</code>; a chi si connette tardi il bus ritrasmette solo l'ultimo valore per nodo</td></tr><tr><td>Polling su <code>processes</code> (<code>noeva-server-api</code>)</td><td><code>output_data.nodeCounts: { [nodeId]: { entered, exited, errored, caught?, held? } }</code>, scritto dal worker al più ogni ~5 s (<code>WORKER_PROGRESS_INTERVAL_MS</code>)</td></tr></tbody></table><p><strong>Il report non cambia</strong>: i contatori dal vivo non aggiungono campi, e lo schema resta quello di <a href="#versione-di-pipeline-e-release">§ «Versione di pipeline e release»</a> (<code>reportSchemaVersion</code> 8). Chi riapre una run conclusa ricava «in errore» da <code>rejected</code> e da <code>caughtErrors[].sourceNodeId</code>. La lista è limitata a <code>caughtErrorsLimit</code> voci per guard (default 100): oltre il tetto, una parte dei catturati non è più attribuibile a un nodo, e il numero ricavato dal report è un minimo. La UI lo segna con «≥».</p><h2 id="scarti-report-vs-payload" tabindex="-1">Scarti: report vs payload <a class="header-anchor" href="#scarti-report-vs-payload" aria-label="Permalink to "Scarti: report vs payload""></a></h2><p>Il report contiene <strong>solo conteggi e categorie</strong> di scarto (niente payload → niente PII). I <strong>record scartati completi</strong> vanno nel <strong>dead-letter sink</strong>, che è <strong>scelto dal chiamante</strong> (file, tabella, coda). Così il servizio resta agnostico e il report è sicuro da archiviare.</p><p>Il <code>DeadLetter</code> porta quindi campi che il report <strong>non</strong> ha, perché contengono payload reale:</p><table tabindex="0"><thead><tr><th>Campo</th><th>Quando</th><th>Nel report?</th></tr></thead><tbody><tr><td><code>raw</code></td><td>catture per-record (transform isolate, sink con <code>loadOne</code>)</td><td>Solo con <code>includeRawInReport</code> sul guard</td></tr><tr><td><code>lastConsumed</code></td><td>nodi non isolabili, durante il <strong>consumo</strong></td><td><strong>Mai</strong></td></tr><tr><td><code>guardSnapshots</code></td><td>record d'ingresso da cui deriva il fallimento, risalendo <code>derivedFrom</code></td><td><strong>Mai</strong></td></tr></tbody></table><p>Sintetici e quindi sicuri da esporre: <code>error.context.recordId</code> (id del record entrato nel nodo che ha fallito) e <code>error.context.derivedFrom</code> (id dei contribuenti, quando il fallimento avviene in emissione di un nodo stateful). Sono id, non dati.</p><p>Nota: <code>guardSnapshots</code> è additivo e opzionale, quindi non ha inciso su <code>reportSchemaVersion</code>.</p><p>Per seguire <strong>quali</strong> record sono passati da un nodo, e com'erano, c'è la <strong>traccia</strong> di una run tracciata (<code>etl run --trace</code>): un documento separato, con i valori in chiaro, che il report non contiene. Vedi <a href="./run-trace">La traccia di una run</a>.</p><h3 id="versione-di-pipeline-e-release" tabindex="-1">Versione di pipeline e release <a class="header-anchor" href="#versione-di-pipeline-e-release" aria-label="Permalink to "Versione di pipeline e release""></a></h3><p>Una run dice con quale codice è girata in quattro campi. Lo <strong>schema v7</strong> ha separato la versione di pipeline dalla release; lo <strong>schema v8</strong> aggiunge la versione del core e il cliente:</p><ul><li><code>pipelineVersion</code> è la <strong>versione di pipeline</strong>: con quale codice della pipeline è girata la run. È l'ultima voce del changelog della pipeline nel catalogo, e la mettono nel <code>RunContext</code><code>etl run</code>, il worker e le run tracciate lanciate da <code>etl serve</code>, non l'ambiente. Una pipeline pronta porta il suo changelog con sé, dal pacchetto del core: la sua versione è quella che il core le ha dato. Un grafo lanciato fuori dal catalogo, come nei test, ha <code>null</code>.</li><li><code>release</code> è la <strong>release</strong> del deploy: con quale artefatto è girata, cioè il commit del repo cliente. Due run con la stessa <code>pipelineVersion</code> e <code>release</code> diverse sono girate sullo stesso codice di pipeline ma su un artefatto diverso. Viene da <code>ETL_RELEASE</code> se è impostata (l'immagine la riceve come build arg); altrimenti, quando il deploy gira da un checkout (sotto PM2), è il commit del repo dell'<code>etl.config.ts</code>, <code>git:<sha></code> con <code>-dirty</code> se ha modifiche non committate a file tracciati (<code>src/release.ts</code>). Si chiede a git nella cartella del config e non in quella del core, che in un repo cliente sta in <code>node_modules</code>; se quella cartella non è la radice del checkout, la release è <code>null</code>. Si calcola una volta all'avvio del processo.</li><li><code>core</code> è la <strong>versione del core</strong>: la <code>version</code> del <code>package.json</code> del pacchetto installato, letta a runtime e mai da un build arg. La release la fissa già, attraverso il lockfile del repo cliente, ma qui si legge senza aprirlo. Se il pacchetto non si trova, l'avvio si ferma con un <code>ConfigError</code> che nomina dove l'ha cercato.</li><li><code>client</code> è il <strong>cliente</strong> del deploy, il <code>client</code> di <code>defineEtlConfig</code>.</li></ul><p><code>etl run</code>, il worker e le run tracciate calcolano i tre campi del deploy dal catalogo caricato (<code>src/deploy-identity.ts</code>), uguali per tutte le run del processo. Un grafo lanciato fuori dalla CLI li ha a <code>null</code>.</p><p>Fino allo schema v6 la release stava in <code>version</code>, un nome ambiguo. È l'unico rename dello schema: un consumer che legge <code>version</code> non lo trova più, e deve leggere <code>release</code> a partire da <code>reportSchemaVersion</code> 7. Il report del worker arriva com'è in <code>processes.output_data</code>, quindi anche lo storico Noeva porta tutti i campi.</p><p>Lo store locale delle run (<code>etl runs</code>, <code>GET /runs/:id</code>) rilegge i report salvati con uno schema precedente nella forma corrente: prima del v7 <code>version</code> diventa <code>release</code> e <code>pipelineVersion</code> vale <code>null</code>, prima del v8 <code>core</code> e <code>client</code> valgono <code>null</code>, perché quelle run non li hanno mai registrati. <code>reportSchemaVersion</code> resta quello con cui il report è nato.</p><h2 id="esempio-successo" tabindex="-1">Esempio (successo) <a class="header-anchor" href="#esempio-successo" aria-label="Permalink to "Esempio (successo)""></a></h2><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
45
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><p><code>etl runs show</code> mostra la sezione «Istanze» dopo la tabella dei nodi: una riga per istanza, indentata per profondità, con entrati, usciti per uscita, rifiutati e durata («mai avviata» o «interrotta» quando l'istanza è partita ma nessun suo nodo si è concluso). Senza istanze la sezione non compare.</p><h3 id="task" tabindex="-1">Task <a class="header-anchor" href="#task" aria-label="Permalink to "Task""></a></h3><p>Un <code>task</code> è un nodo del report con <code>kind: "task"</code>. Non vede record: <code>extracted</code>, <code>written</code> e <code>rejected</code> restano a 0, e non entra nei totali della run. <code>startedAt</code> è l'ingresso in <code>run()</code>, <code>finishedAt</code> l'uscita. I dettagli, per esempio le righe toccate da un task SQL, stanno in <code>nodeReports</code>. <code>retries</code> compare con una policy di <code>retry</code>.</p><p><code>startedAt: null</code> <strong>non è un dato mancante</strong>: significa che il nodo non ha mai attraversato un record — input vuoto, filtro che scarta tutto a monte, o run abortita prima che il nodo partisse. È il corollario documentato su <code>ProgressReporter.onNodeStart</code>. In quel caso <code>durationMs</code> è <code>0</code>: una durata non misurata si dichiara zero, non si deriva da un solo estremo.</p><h3 id="run-fallita-topologia-e-conteggi-parziali" tabindex="-1">Run fallita: topologia e conteggi parziali <a class="header-anchor" href="#run-fallita-topologia-e-conteggi-parziali" aria-label="Permalink to "Run fallita: topologia e conteggi parziali""></a></h3><p>Al primo errore fatale il runner <strong>annulla tutti i rami</strong> e aspetta che ogni sink e ogni task chiuda, poi assembla il report: una run <code>failed</code> non scrive più niente dopo essere stata riportata tale. <code>error</code> è il primo errore, quello del nodo che è fallito; i nodi degli altri rami risultano interrotti.</p><p>Un report <code>failed</code> prodotto da una run che è <strong>partita</strong> contiene la topologia reale e i conteggi accumulati fino all'abort — è proprio la run che più serve ispezionare, e lasciarla come guscio vuoto sarebbe un difetto.</p><p>Un report <code>failed</code> prodotto da <code>buildFailedGraphReport</code> (fallimento <strong>prima</strong> del grafo) ha invece <code>nodes: []</code> / <code>edges: []</code>, perché non c'è alcuna topologia eseguita da riportare, e <code>instances: []</code>.</p><p>Il report allegato all'errore porta anche <code>instances</code>, col riepilogo di quanto contato fino all'interruzione.</p><h3 id="nodereports-e-writereport" tabindex="-1"><code>nodeReports</code> e <code>writeReport</code> <a class="header-anchor" href="#nodereports-e-writereport" aria-label="Permalink to "\`nodeReports\` e \`writeReport\`""></a></h3><p>Ogni nodo del grafo (source/transform/lookup/ai/action/route/join/union/sink/try-catch/task) può ricevere un'opzione <code>writeReport: (ctx, stats) => Record<string, unknown></code> in fase di costruzione: <code>GraphBuilder.source/transform/lookup/ai/action/route/join/union/sink/tryCatch/task(..., { writeReport })</code>. <code>stats</code> espone i conteggi del nodo (<code>extracted</code>/<code>written</code>/ <code>rejected</code>/<code>rejectedReasons</code>) così un nodo può riassumere i volumi senza scrivere il payload grezzo (es. <code>{ recordsFetched: 1_000_000 }</code> invece del milione di record). Se né il nodo né la sua transform (o il suo task) dichiarano un <code>writeReport</code>, o se quello in uso lancia, il runner scrive il default <code>{ name: node.name, success }</code>, dove <code>success</code> è <code>true</code> se il nodo non ha abortito la run (uno scarto isolato a dead-letter non conta come fallimento).</p><p>Una <strong>transform può dichiarare il proprio <code>writeReport</code> di default</strong> (<code>Transform.writeReport</code>): è il modo in cui <code>profile</code> porta il profilo delle colonne, <code>assert</code> l'esito dei suoi check, e i nodi <code>lookup</code> e <code>ai</code> i propri contatori (sotto <code>lookup</code>), nel report senza che la pipeline cabli nulla. Un <strong>task</strong> fa lo stesso con <code>Task.writeReport</code>: il task SQL ci porta le righe toccate da ogni statement. L'ordine è: <code>writeReport</code> del nodo, poi quello della transform, poi il default. Quello del nodo <strong>sostituisce</strong> quello della transform, non lo unisce. Il report dichiarato dalla transform si calcola anche quando il nodo fallisce, e un suo errore ricade sul default con un warning, come per quello del nodo. La forma di <code>nodeReports</code> non cambia (resta una mappa di oggetti liberi), quindi non ha inciso su <code>reportSchemaVersion</code>.</p><p>Sui nodi <code>lookup</code>, <code>ai</code> e <code>action</code>, l'opzione <strong><code>recordReport: { row, key?, maxRows? }</code></strong> aggiunge al report del nodo una riga a campi semplici per ogni record riuscito, sotto <code>key</code> (default <code>records</code>), <strong>accanto</strong> al report della transform (o a <code>{ name }</code>, se la transform non ne ha uno). Un <code>writeReport</code> sullo stesso nodo è un errore di composizione. Al più <code>maxRows</code> righe (default 500, il resto in <code>rowsOmitted</code>; le righe che <code>row</code> non è riuscita a scrivere in <code>rowsFailed</code>), stringhe tagliate a 500 caratteri. I campi che <code>row</code> restituisce sono persistiti: la scheda della pipeline li elenca. Anche questo non tocca <code>reportSchemaVersion</code>.</p><p><code>processes.output_data</code> riceve gli stessi report <strong>incrementalmente</strong>, durante l'esecuzione (non solo a fine run). Accanto a <code>nodeReports</code> viaggia <code>runningNodes: string[]</code> — i nodi che stanno elaborando <strong>adesso</strong> (partiti e non ancora completati), da <code>ProgressReporter.onNodeStart</code>. È ciò che permette alla UI di distinguere un nodo che lavora da uno in attesa, e quindi di mostrare due rami concorrenti. Assente sulle run concluse.</p><p>Con loro viaggia <code>skippedNodes: { [nodeId]: { because } }</code>, i nodi <strong>saltati</strong> fin qui. È sempre presente, <code>{}</code> se nessun nodo è saltato: una chiave assente vuol dire un motore precedente. Sta in una mappa a sé e non dentro <code>nodeReports[nodeId]</code>, che è l'output di <code>writeReport</code> e ha le chiavi scelte dalla pipeline. Come <code>runningNodes</code> è assente sulle run concluse, dove <code>nodes[].skipped</code> del report dice la stessa cosa.</p><p>La quarta chiave è <code>nodeCounts: { [nodeId]: { entered, exited, errored, caught?, held? } }</code>, i contatori dal vivo. Anche lei sempre presente, <code>{}</code> finché nessun nodo ha contato nulla, e assente sulle run concluse, dove valgono i conteggi di <code>nodes[]</code>. <code>noeva-server-api</code> sostituisce <code>output_data</code> a ogni scrittura invece di fonderlo, quindi il worker rimanda ogni volta tutte e quattro le chiavi.</p><p><code>nodes</code> ed <code>edges</code> sono la topologia <strong>reale</strong> del grafo eseguito: un nodo per ogni <code>source</code>/<code>transform</code>/<code>lookup</code>/<code>ai</code>/<code>action</code>/<code>route</code>/<code>join</code>/<code>union</code>/<code>sink</code>/<code>try-catch</code>/<code>task</code> dichiarato nel builder. Non esiste un nodo sintetico che collassa la catena.</p><h3 id="contatori-dal-vivo" tabindex="-1">Contatori dal vivo <a class="header-anchor" href="#contatori-dal-vivo" aria-label="Permalink to "Contatori dal vivo""></a></h3><p>Mentre la run è in corso ogni nodo ha tre contatori, più due che hanno solo alcuni nodi. I primi quattro sono gli stessi numeri del report, letti prima che la run finisca:</p><table tabindex="0"><thead><tr><th>Contatore</th><th>Campo di <code>NodeCounts</code></th><th>A fine run, nel report</th></tr></thead><tbody><tr><td>Entrati</td><td><code>entered</code></td><td><code>extracted</code></td></tr><tr><td>Usciti</td><td><code>exited</code></td><td><code>written</code></td></tr><tr><td>In errore</td><td><code>errored</code></td><td><code>rejected</code> + i <code>caughtErrors</code> di tutti i guard con <code>sourceNodeId</code> = il nodo</td></tr><tr><td>Catturati</td><td><code>caught</code>, solo guard</td><td><code>caught</code> del <code>try-catch</code></td></tr><tr><td>In lavorazione</td><td><code>held</code>, solo chi lo dichiara</td><td>— (non c'è: a fine run vale zero)</td></tr></tbody></table><p>«In errore» conta un errore catturato da un <code>try-catch</code> sul nodo <strong>in cui è nato</strong>, non sul guard: il guard mostra a parte i suoi catturati. Un retry poi riuscito non è un errore. In circuit-breaker, e su un sink opaco, la cattura è <strong>una per evento</strong> e non per record: il nodo segna un errore anche se lo stream interrotto ne portava di più, come <code>caught</code> sul guard.</p><p><strong>In lavorazione</strong> (<code>held</code>) sono i record che il nodo sta trattenendo ora. Non si ricava per differenza: c'è solo sui nodi che lo sanno, e <strong>assente non vuol dire zero</strong>.</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Cosa conta</th></tr></thead><tbody><tr><td><code>join</code></td><td>i record del probe letti in anticipo e non ancora confrontati</td></tr><tr><td><code>try-catch</code></td><td>gli errori in coda che il ramo <code>catch</code> non ha ancora preso</td></tr><tr><td>un nodo con più edge in uscita (fan-out), un <code>route</code></td><td>i record nel buffer del <code>tee</code> che il ramo più lento non ha ancora preso</td></tr><tr><td>una transform che dichiara <code>Transform.held</code></td><td>i record ricevuti e non ancora fatti uscire</td></tr><tr><td><code>lookup</code>, <code>ai</code></td><td>i record della finestra: accumulati, in volo col round-trip, non ancora emessi</td></tr><tr><td><code>action</code></td><td>il record in volo: uno mentre l'azione non ha risposto</td></tr><tr><td>un sink con <code>retry</code> o <code>rateLimit</code></td><td>il blocco del runner, in riempimento o in scrittura; un <code>loadOne</code> in volo</td></tr><tr><td>un sink senza policy che dichiara <code>Sink.held</code></td><td>le righe nel batch del sink non ancora scritte</td></tr></tbody></table><p>Le transform di libreria che lo dichiarano oggi sono <code>sort</code>, <code>groupBy</code>, <code>pivot</code>, <code>chunk</code>, <code>serialize</code> e <code>assert</code> in gate. Un nodo che ha due di queste voci (un <code>sort</code> con un fan-out) le somma. Due nodi trattengono record <strong>senza</strong> dichiararlo, e quindi non hanno il campo: <code>dedup</code> con <code>keep: "last"</code> e i buffer di prefetch di un <code>union</code> in <code>concat</code>.</p><p>Su <code>lookup</code>, <code>ai</code> e <code>action</code> conta <strong>record</strong>, non chiamate: un round-trip copre una finestra intera, e un resolver che fa più richieste in parallelo (<code>httpLookup</code> per chiave) non cambia il numero. Dove il runner esegue il nodo record per record (guard per-record, dead-letter di nodo, <code>recordIds</code>) la finestra è da uno. Sui sink <code>Sink.held</code> lo dichiarano Postgres, SQL Server e MySQL, upsert e SCD2 dove c'è. Con una policy il blocco del runner comprende già il batch del sink, quindi conta solo lui: sommarli conterebbe due volte le stesse righe. Il batch del sink conta finché lo statement non risponde; le righe già scritte ma non ancora confermate dal commit non sono né in lavorazione né uscite. A run conclusa, riuscita o fallita, l'ultima emissione porta <code>held: 0</code> su ogni nodo che lo dichiara, anche se un fallimento ha lasciato un buffer pieno.</p><p>Gli usciti di un <strong>sink</strong> salgono quando il sink dice di aver scritto: a ogni record sotto un guard per-record, a ogni blocco di <code>batchSize</code> con una policy di <code>retry</code>. Senza nessuno dei due il sink scrive in un solo <code>load</code>, e i suoi usciti arrivano tutti a fine scrittura, mentre gli entrati salgono record per record.</p><p>Il runner li emette con <code>ProgressReporter.onProgress</code>: <strong>un evento per run</strong>, al più ogni secondo (<code>PROGRESS_INTERVAL_MS</code>), con i soli nodi cambiati. Un nodo mai partito o saltato non compare mai. A run conclusa, riuscita o fallita, arriva un'ultima emissione prima che <code>runGraph</code> restituisca: l'ultimo valore di ogni nodo è quello del report. Senza un <code>onProgress</code> nel reporter non parte nessun timer.</p><p>I nodi sono quelli del grafo <strong>eseguito</strong>: su una root con sub-pipeline, che l'appiattimento riduce a nodi piatti al <code>build()</code>, i contatori arrivano per <strong>id qualificato</strong> (<code>inst</code>, <code>inst/per-due</code>, <code>inst/dentro/per-due</code>), come nel report. Il nodo di confine d'ingresso di un'istanza ha l'id dell'istanza, ed è lì che un record fuori schema conta «in errore».</p><p>Il worker non inoltra ogni emissione: accumula i contatori nodo per nodo e li scrive su <code>processes</code> al più ogni cinque secondi, la prima volta subito e poi a fine finestra con l'ultimo valore, se nel frattempo un avvio o un completamento di nodo non li ha già portati. Una scrittura fallita si riprova alla finestra dopo. A run conclusa il worker chiude la finestra e aspetta la scrittura in volo prima del report finale: arrivata dopo, lo sostituirebbe. Chi segue una run sul worker col solo polling vede quindi i contatori fino a ~5 s indietro, più i 2 s del polling della UI.</p><table tabindex="0"><thead><tr><th>Canale</th><th>Dove</th></tr></thead><tbody><tr><td><code>ProgressReporter.onProgress</code></td><td><code>update.nodes: NodeCounts[]</code></td></tr><tr><td>Stream SSE <code>GET /runs/:id/events</code></td><td><code>node-progress</code> con <code>nodes</code>; a chi si connette tardi il bus ritrasmette solo l'ultimo valore per nodo</td></tr><tr><td>Polling su <code>processes</code> (<code>noeva-server-api</code>)</td><td><code>output_data.nodeCounts: { [nodeId]: { entered, exited, errored, caught?, held? } }</code>, scritto dal worker al più ogni ~5 s (<code>WORKER_PROGRESS_INTERVAL_MS</code>)</td></tr></tbody></table><p><strong>Il report non cambia</strong>: i contatori dal vivo non aggiungono campi, e lo schema resta quello di <a href="#versione-di-pipeline-e-release">§ «Versione di pipeline e release»</a> (<code>reportSchemaVersion</code> 8). Chi riapre una run conclusa ricava «in errore» da <code>rejected</code> e da <code>caughtErrors[].sourceNodeId</code>. La lista è limitata a <code>caughtErrorsLimit</code> voci per guard (default 100): oltre il tetto, una parte dei catturati non è più attribuibile a un nodo, e il numero ricavato dal report è un minimo. La UI lo segna con «≥».</p><h2 id="scarti-report-vs-payload" tabindex="-1">Scarti: report vs payload <a class="header-anchor" href="#scarti-report-vs-payload" aria-label="Permalink to "Scarti: report vs payload""></a></h2><p>Il report contiene <strong>solo conteggi e categorie</strong> di scarto (niente payload → niente PII). I <strong>record scartati completi</strong> vanno nel <strong>dead-letter sink</strong>, che è <strong>scelto dal chiamante</strong> (file, tabella, coda). Così il servizio resta agnostico e il report è sicuro da archiviare.</p><p>Il <code>DeadLetter</code> porta quindi campi che il report <strong>non</strong> ha, perché contengono payload reale:</p><table tabindex="0"><thead><tr><th>Campo</th><th>Quando</th><th>Nel report?</th></tr></thead><tbody><tr><td><code>raw</code></td><td>catture per-record (transform isolate, sink con <code>loadOne</code>)</td><td>Solo con <code>includeRawInReport</code> sul guard</td></tr><tr><td><code>lastConsumed</code></td><td>nodi non isolabili, durante il <strong>consumo</strong></td><td><strong>Mai</strong></td></tr><tr><td><code>guardSnapshots</code></td><td>record d'ingresso da cui deriva il fallimento, risalendo <code>derivedFrom</code></td><td><strong>Mai</strong></td></tr></tbody></table><p>Sintetici e quindi sicuri da esporre: <code>error.context.recordId</code> (id del record entrato nel nodo che ha fallito) e <code>error.context.derivedFrom</code> (id dei contribuenti, quando il fallimento avviene in emissione di un nodo stateful). Sono id, non dati.</p><p>Nota: <code>guardSnapshots</code> è additivo e opzionale, quindi non ha inciso su <code>reportSchemaVersion</code>.</p><p>Per seguire <strong>quali</strong> record sono passati da un nodo, e com'erano, c'è la <strong>traccia</strong> di una run tracciata (<code>etl run --trace</code>): un documento separato, con i valori in chiaro, che il report non contiene. Vedi <a href="./run-trace">La traccia di una run</a>.</p><h3 id="versione-di-pipeline-e-release" tabindex="-1">Versione di pipeline e release <a class="header-anchor" href="#versione-di-pipeline-e-release" aria-label="Permalink to "Versione di pipeline e release""></a></h3><p>Una run dice con quale codice è girata in quattro campi. Lo <strong>schema v7</strong> ha separato la versione di pipeline dalla release; lo <strong>schema v8</strong> aggiunge la versione del core e il cliente:</p><ul><li><code>pipelineVersion</code> è la <strong>versione di pipeline</strong>: con quale codice della pipeline è girata la run. È l'ultima voce del changelog della pipeline nel catalogo, e la mettono nel <code>RunContext</code><code>etl run</code>, il worker e le run tracciate lanciate da <code>etl serve</code>, non l'ambiente. Una pipeline pronta porta il suo changelog con sé, dal pacchetto del core: la sua versione è quella che il core le ha dato. Un grafo lanciato fuori dal catalogo, come nei test, ha <code>null</code>.</li><li><code>release</code> è la <strong>release</strong> del deploy: con quale artefatto è girata, cioè il commit del repo cliente. Due run con la stessa <code>pipelineVersion</code> e <code>release</code> diverse sono girate sullo stesso codice di pipeline ma su un artefatto diverso. Viene da <code>ETL_RELEASE</code> se è impostata (l'immagine la riceve come build arg); altrimenti, quando il deploy gira da un checkout (sotto PM2), è il commit del repo dell'<code>etl.config.ts</code>, <code>git:<sha></code> con <code>-dirty</code> se ha modifiche non committate a file tracciati (<code>src/release.ts</code>). Si chiede a git nella cartella del config e non in quella del core, che in un repo cliente sta in <code>node_modules</code>; se quella cartella non è la radice del checkout, la release è <code>null</code>. Si calcola una volta all'avvio del processo.</li><li><code>core</code> è la <strong>versione del core</strong>: la <code>version</code> del <code>package.json</code> del pacchetto installato, letta a runtime e mai da un build arg. La release la fissa già, attraverso il lockfile del repo cliente, ma qui si legge senza aprirlo. Se il pacchetto non si trova, l'avvio si ferma con un <code>ConfigError</code> che nomina dove l'ha cercato.</li><li><code>client</code> è il <strong>cliente</strong> del deploy, il <code>client</code> di <code>defineEtlConfig</code>.</li></ul><p><code>etl run</code>, il worker e le run tracciate calcolano i tre campi del deploy dal catalogo caricato (<code>src/deploy-identity.ts</code>), uguali per tutte le run del processo. Un grafo lanciato fuori dalla CLI li ha a <code>null</code>.</p><p>Fino allo schema v6 la release stava in <code>version</code>, un nome ambiguo. È l'unico rename dello schema: un consumer che legge <code>version</code> non lo trova più, e deve leggere <code>release</code> a partire da <code>reportSchemaVersion</code> 7. Il report del worker arriva com'è in <code>processes.output_data</code>, quindi anche lo storico Noeva porta tutti i campi.</p><p>Lo store locale delle run (<code>etl runs</code>, <code>GET /runs/:id</code>) rilegge i report salvati con uno schema precedente nella forma corrente: prima del v7 <code>version</code> diventa <code>release</code> e <code>pipelineVersion</code> vale <code>null</code>, prima del v8 <code>core</code> e <code>client</code> valgono <code>null</code>, perché quelle run non li hanno mai registrati. <code>reportSchemaVersion</code> resta quello con cui il report è nato.</p><h2 id="esempio-successo" tabindex="-1">Esempio (successo) <a class="header-anchor" href="#esempio-successo" aria-label="Permalink to "Esempio (successo)""></a></h2><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
46
46
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "reportSchemaVersion"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
47
47
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "runId"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ebe7d7cc-…"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
48
48
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "pipeline"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sessions-daily"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|