@noeva/etl-core 1.0.0-next.3 → 1.0.0-next.5

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.
Files changed (145) hide show
  1. package/README.md +7 -11
  2. package/deploy/deploy-ecr.sh +4 -7
  3. package/dist/chunk-BVUOUBLW.js +1 -0
  4. package/dist/chunk-CRR3Q2C7.js +2 -0
  5. package/dist/chunk-J3PBMWSP.js +2 -0
  6. package/dist/{chunk-KMUNED7K.js → chunk-LJ7DVP5F.js} +1 -1
  7. package/dist/{chunk-ZBKP2UOF.js → chunk-P6B2KLNJ.js} +2 -2
  8. package/dist/chunk-PKBSETMV.js +2 -0
  9. package/dist/chunk-QPJC4GWR.js +1 -0
  10. package/dist/chunk-RCRMQPFH.js +5 -0
  11. package/dist/chunk-RS5SGDUU.js +1 -0
  12. package/dist/chunk-RWPHH4E2.js +1 -0
  13. package/dist/chunk-SRFFKE5W.js +6 -0
  14. package/dist/chunk-WVODQB6Z.js +1 -0
  15. package/dist/chunk-XZMCC6VQ.js +1 -0
  16. package/dist/chunk-ZCYGHS7P.js +2 -0
  17. package/dist/cli.js +3 -3
  18. package/dist/connector-kit.d.ts +4 -2
  19. package/dist/connector-kit.js +1 -1
  20. package/dist/connectors/file.js +1 -1
  21. package/dist/connectors/http.js +1 -1
  22. package/dist/connectors/imap.js +1 -1
  23. package/dist/connectors/jira.js +2 -2
  24. package/dist/connectors/mail.js +1 -1
  25. package/dist/connectors/noeva.js +1 -1
  26. package/dist/connectors/oauth.js +1 -1
  27. package/dist/connectors/postgres.js +1 -1
  28. package/dist/connectors/process.js +1 -1
  29. package/dist/connectors/sendgrid.d.ts +1 -1
  30. package/dist/connectors/sendgrid.js +1 -1
  31. package/dist/connectors/smtp.js +1 -1
  32. package/dist/connectors/sqlserver.js +1 -1
  33. package/dist/connectors/zoho.d.ts +304 -0
  34. package/dist/connectors/zoho.js +2 -0
  35. package/dist/etl.config.js +7 -15
  36. package/dist/guida/404.html +2 -2
  37. package/dist/guida/GUIDA_SVILUPPO.html +6 -6
  38. package/dist/guida/TECHNICAL_OVERVIEW.html +5 -5
  39. package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.js → GUIDA_SVILUPPO.md.CrN52ZDN.js} +1 -1
  40. package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.js} +1 -1
  41. package/dist/guida/assets/{app.lWZ5GK2m.js → app.BrI3mcoI.js} +1 -1
  42. package/dist/guida/assets/chunks/@localSearchIndexroot.DjrQYH6x.js +1 -0
  43. package/dist/guida/assets/chunks/{VPLocalSearchBox.C0h2R-Ih.js → VPLocalSearchBox.BlKLVNlB.js} +1 -1
  44. package/dist/guida/assets/chunks/{theme.BYWumH0G.js → theme.Cuah39Zj.js} +2 -2
  45. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +1 -0
  46. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +1 -0
  47. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.js +7 -0
  48. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.lean.js +1 -0
  49. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.js +17 -0
  50. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.lean.js +1 -0
  51. package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.js → conventions_node-descriptor.md.MQaGlm8a.js} +1 -1
  52. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.js → nodes_source.md.DP2i3GFv.js} +3 -3
  53. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.lean.js → nodes_source.md.DP2i3GFv.lean.js} +1 -1
  54. package/dist/guida/assets/{runbooks_deploy-ecr.md.6M67F85S.js → runbooks_deploy-ecr.md.4jQypInn.js} +2 -2
  55. package/dist/guida/assets/{runbooks_deploy-ecr.md.6M67F85S.lean.js → runbooks_deploy-ecr.md.4jQypInn.lean.js} +1 -1
  56. package/dist/guida/connectors/README.html +5 -5
  57. package/dist/guida/connectors/file.html +4 -4
  58. package/dist/guida/connectors/http.html +4 -4
  59. package/dist/guida/connectors/imap.html +4 -4
  60. package/dist/guida/connectors/jira.html +4 -4
  61. package/dist/guida/connectors/noeva.html +5 -5
  62. package/dist/guida/connectors/oauth.html +6 -6
  63. package/dist/guida/connectors/postgres.html +5 -5
  64. package/dist/guida/connectors/process.html +4 -4
  65. package/dist/guida/connectors/sendgrid.html +4 -4
  66. package/dist/guida/connectors/smtp.html +4 -4
  67. package/dist/guida/connectors/sqlserver.html +5 -5
  68. package/dist/guida/connectors/zoho.html +43 -0
  69. package/dist/guida/conventions/node-columns.html +4 -4
  70. package/dist/guida/conventions/node-descriptor.html +6 -6
  71. package/dist/guida/conventions/run-report.html +4 -4
  72. package/dist/guida/conventions/run-trace.html +4 -4
  73. package/dist/guida/conventions/variabili-del-core.html +4 -4
  74. package/dist/guida/conventions/versioni-di-pipeline.html +4 -4
  75. package/dist/guida/guide/claude-code/index.html +4 -4
  76. package/dist/guida/guide/claude-code/prompt.html +5 -5
  77. package/dist/guida/guide/claude-code/strumenti.html +4 -4
  78. package/dist/guida/guide/grafo.html +4 -4
  79. package/dist/guida/guide/usare/app-desktop.html +4 -4
  80. package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
  81. package/dist/guida/guide/usare/index.html +4 -4
  82. package/dist/guida/hashmap.json +1 -1
  83. package/dist/guida/index.html +4 -4
  84. package/dist/guida/nodes/README.html +4 -4
  85. package/dist/guida/nodes/action.html +4 -4
  86. package/dist/guida/nodes/ai.html +4 -4
  87. package/dist/guida/nodes/join.html +4 -4
  88. package/dist/guida/nodes/lookup.html +4 -4
  89. package/dist/guida/nodes/pipeline.html +4 -4
  90. package/dist/guida/nodes/route.html +4 -4
  91. package/dist/guida/nodes/sink.html +4 -4
  92. package/dist/guida/nodes/source.html +6 -6
  93. package/dist/guida/nodes/task.html +4 -4
  94. package/dist/guida/nodes/transform.html +4 -4
  95. package/dist/guida/nodes/try-catch.html +4 -4
  96. package/dist/guida/nodes/union.html +4 -4
  97. package/dist/guida/pagine.json +1 -0
  98. package/dist/guida/pipelines/README.html +5 -5
  99. package/dist/guida/pipelines/crm-leads-sync.html +4 -4
  100. package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
  101. package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
  102. package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
  103. package/dist/guida/pipelines/test-posta.html +4 -4
  104. package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
  105. package/dist/guida/runbooks/deploy-ecr.html +6 -6
  106. package/dist/guida/runbooks/deployment.html +4 -4
  107. package/dist/guida/runbooks/etl-worker.html +4 -4
  108. package/dist/guida/runbooks/graph-server.html +4 -4
  109. package/dist/guida/runbooks/mask-key.html +4 -4
  110. package/dist/guida/runbooks/oauth-google-posta.html +4 -4
  111. package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
  112. package/dist/guida/runbooks/scd2-rehash.html +4 -4
  113. package/dist/guida/runbooks/sql-task-truncate-swap.html +4 -4
  114. package/dist/guida/runbooks/stato-incrementale.html +4 -4
  115. package/dist/guida/sub-pipelines/README.html +4 -4
  116. package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
  117. package/dist/index.js +1 -1
  118. package/dist/pipelines.js +1 -1
  119. package/dist/testing.js +1 -1
  120. package/docs/.vitepress/lib/published-docs.ts +1 -7
  121. package/kit/skills/etl-graph/references/wiring.md +4 -3
  122. package/kit/skills/new-connector/SKILL.md +1 -1
  123. package/package.json +8 -3
  124. package/dist/chunk-5B2425TT.js +0 -1
  125. package/dist/chunk-BFW7HTF6.js +0 -2
  126. package/dist/chunk-BPRH262Y.js +0 -2
  127. package/dist/chunk-DPWGI266.js +0 -1
  128. package/dist/chunk-H75NY6Z4.js +0 -1
  129. package/dist/chunk-HMED2UDJ.js +0 -2
  130. package/dist/chunk-MOHJWOCB.js +0 -1
  131. package/dist/chunk-MXSKD3Z4.js +0 -2
  132. package/dist/chunk-PGJWGJEB.js +0 -5
  133. package/dist/chunk-R53642SH.js +0 -1
  134. package/dist/chunk-RU6CZIDB.js +0 -1
  135. package/dist/chunk-UN3BPCPA.js +0 -1
  136. package/dist/chunk-XFHTODDW.js +0 -6
  137. package/dist/chunk-ZCYSL5A6.js +0 -1
  138. package/dist/guida/assets/chunks/@localSearchIndexroot.B5zFGbAC.js +0 -1
  139. package/dist/guida/assets/connectors_README.md.ChyXSf73.js +0 -1
  140. package/dist/guida/assets/connectors_README.md.ChyXSf73.lean.js +0 -1
  141. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.js +0 -7
  142. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.lean.js +0 -1
  143. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.lean.js → GUIDA_SVILUPPO.md.CrN52ZDN.lean.js} +0 -0
  144. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.lean.js} +0 -0
  145. /package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.lean.js → conventions_node-descriptor.md.MQaGlm8a.lean.js} +0 -0
@@ -0,0 +1,7 @@
1
+ import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,c,l,h){return o(),i("div",null,[...e[0]||(e[0]=[a(`<h1 id="oauth2-per-i-connettori" tabindex="-1">OAuth2 per i connettori <a class="header-anchor" href="#oauth2-per-i-connettori" aria-label="Permalink to &quot;OAuth2 per i connettori&quot;">​</a></h1><p>Non è un connettore: è <strong>l&#39;identità</strong> che IMAP e SMTP usano per autenticarsi dove la password non basta più — Gmail, Google Workspace, Microsoft 365. Lo usa anche il connettore <a href="./zoho">Zoho CRM</a>, che autentica ogni richiesta alla Records API con il token che questa identità rinnova. Procedura passo passo nel runbook <a href="./../runbooks/oauth-google-posta">oauth-google-posta.md</a>.</p><h2 id="perche-esiste" tabindex="-1">Perché esiste <a class="header-anchor" href="#perche-esiste" aria-label="Permalink to &quot;Perché esiste&quot;">​</a></h2><p>I connettori sapevano già parlare XOAUTH2, ma un access token vive un&#39;ora: incollarne uno in <code>IMAP_ACCESS_TOKEN</code> è una configurazione che funziona per un&#39;ora e poi torna rossa. Questo modulo tiene il <strong>refresh token</strong> e scambia un access token nuovo quando serve.</p><h2 id="un-identita-due-connettori" tabindex="-1">Un&#39;identità, due connettori <a class="header-anchor" href="#un-identita-due-connettori" aria-label="Permalink to &quot;Un&#39;identità, due connettori&quot;">​</a></h2><p>La stessa casella Google si legge e si scrive con lo stesso consenso, quindi l&#39;identità sta in un registry suo e IMAP e SMTP la referenziano per id. Duplicare <code>CLIENT_SECRET</code> e <code>REFRESH_TOKEN</code> nei due blocchi significherebbe, prima o poi, ruotarne uno solo.</p><h2 id="variabili" tabindex="-1">Variabili <a class="header-anchor" href="#variabili" aria-label="Permalink to &quot;Variabili&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>OAUTH_CLIENT_ID</code></td><td>—</td><td>obbligatoria se il registry è usato</td></tr><tr><td><code>OAUTH_CLIENT_SECRET</code></td><td>—</td><td>obbligatoria</td></tr><tr><td><code>OAUTH_REFRESH_TOKEN</code></td><td>—</td><td>obbligatoria; ottenuto una volta sola, vedi runbook</td></tr><tr><td><code>OAUTH_TOKEN_ENDPOINT</code></td><td><code>https://oauth2.googleapis.com/token</code></td><td><strong>deve essere <code>https://</code></strong>; Microsoft 365 si configura qui</td></tr><tr><td><code>OAUTH_SCOPE</code></td><td>—</td><td>solo se il provider lo vuole al refresh; Google no</td></tr><tr><td><code>OAUTH_INSTANCES</code></td><td>—</td><td>più caselle: <code>ordini,notifiche</code> → <code>OAUTH_&lt;ID&gt;_*</code></td></tr></tbody></table><p>Chi le usa:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>IMAP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>IMAP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>IMAP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>quale identità rinnova il token di quella casella</td></tr><tr><td><code>SMTP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>SMTP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>SMTP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>di norma la stessa di IMAP</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>l&#39;identità di un&#39;organizzazione <a href="./zoho">Zoho CRM</a>, con il token endpoint di Zoho</td></tr></tbody></table><p>Zoho risponde <code>200</code> anche a un refresh rifiutato, con <code>{ &quot;error&quot;: … }</code> nel corpo: il fornitore lo tratta come un rifiuto, un <code>ConfigError</code> con il codice di Zoho (per esempio <code>invalid_code</code>).</p><p>Le variabili sono dichiarate in <code>MANIFEST_OAUTH</code>: un&#39;identità incompleta dà un <code>ConfigError</code> che elenca <strong>tutte</strong> le variabili mancanti.</p><h3 id="nel-piano" tabindex="-1">Nel piano <a class="header-anchor" href="#nel-piano" aria-label="Permalink to &quot;Nel piano&quot;">​</a></h3><p>Un&#39;identità OAuth2 non è un nodo. Nel piano compare nella riga <code>credenziale</code> delle caselle IMAP e dei server SMTP che la usano: <code>OAuth · identità default · impostata</code>, oppure <code>… · mancano OAUTH_CLIENT_SECRET, OAUTH_REFRESH_TOKEN</code> con origine <code>mancante</code> e la variabile che punta alla prima da impostare. Un&#39;identità che non è in <code>OAUTH_INSTANCES</code> la run non la trova, anche se le sue variabili ci sono: il piano lo dice con <code>· manca OAUTH_INSTANCES</code>. Il piano la risolve con <code>risolviIdentitaOauth(id, env)</code>, che non lancia e dei segreti restituisce solo lo stato.</p><p>Per <code>etl env check</code>, <code>identitaOauthDichiarate(caselle, env)</code> dà le sole identità che le caselle date usano davvero, cioè quelle su <code>&lt;PREFIX&gt;AUTH=oauth2</code> senza <code>&lt;PREFIX&gt;ACCESS_TOKEN</code>, da aggiungere alle istanze di <code>ambienteDellaPipeline</code>: una pipeline con caselle su password non chiede variabili <code>OAUTH_*</code>.</p><h2 id="il-registry-puo-essere-vuoto" tabindex="-1">Il registry può essere vuoto <a class="header-anchor" href="#il-registry-puo-essere-vuoto" aria-label="Permalink to &quot;Il registry può essere vuoto&quot;">​</a></h2><p>È l&#39;unico, ed è deliberato. Un <code>PG_HOST</code> mancante è una configurazione rotta; OAuth2 invece è una <strong>scelta</strong>, e la maggioranza delle installazioni continuerà con una password. Senza <code>OAUTH_INSTANCES</code> né <code>OAUTH_CLIENT_ID</code> il registry esce vuoto e i connettori non cambiano comportamento.</p><p>La tolleranza finisce lì. Un&#39;istanza <strong>dichiarata</strong> in <code>OAUTH_INSTANCES</code> e incompleta è un errore, e un <code>IMAP_OAUTH_INSTANCE</code> che nomina un id inesistente pure: ricadere in silenzio sul token statico significherebbe autenticarsi con una credenziale diversa da quella che si crede.</p><h2 id="come-si-usa-dal-codice" tabindex="-1">Come si usa dal codice <a class="header-anchor" href="#come-si-usa-dal-codice" aria-label="Permalink to &quot;Come si usa dal codice&quot;">​</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:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> oauth</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fornitoriOauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadOauthRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(env));</span></span>
2
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tokenImap</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> oauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap.auth, imap.oauthInstance);</span></span>
3
+ <span class="line"></span>
4
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">imapSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap, {</span></span>
5
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // …</span></span>
6
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tokenImap </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { client: { accessToken: tokenImap } } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {}),</span></span>
7
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><strong>Un risolutore per run, non per nodo.</strong> <code>fornitoriOauth</code> memoizza per id d&#39;istanza: i nodi che condividono l&#39;identità condividono la cache del token. Una pipeline di posta può toccare la stessa casella in tre punti — sorgente, sessione delle action IMAP, notifiche SMTP — e senza la memoizzazione la stessa run chiederebbe tre token invece di uno. Il guaio non è lo spreco: è che funzionerebbe, quindi nessuno se ne accorgerebbe fino al primo rate limit.</p><p>Il fornitore serializza anche le richieste: due nodi che chiedono il token insieme sulla cache fredda fanno una chiamata sola.</p><h2 id="come-tratta-le-credenziali" tabindex="-1">Come tratta le credenziali <a class="header-anchor" href="#come-tratta-le-credenziali" aria-label="Permalink to &quot;Come tratta le credenziali&quot;">​</a></h2><ul><li><strong>Niente redirect.</strong> La <code>fetch</code> verso il token endpoint usa <code>redirect: &quot;error&quot;</code>. Il default di <code>fetch</code> è seguirli, e su un <code>307</code> il body — client secret e refresh token — viene ripetuto verso l&#39;host nuovo, anche in <code>http://</code>. Il vincolo <code>https://</code> guarda solo il primo URL: da solo non basterebbe.</li><li><strong>Niente credenziali nei messaggi d&#39;errore.</strong> Il testo che arriva dal provider viene redatto (client secret e refresh token sostituiti) e troncato a 160 caratteri: più d&#39;un IdP rieccheggia il valore rifiutato, e la CLI stampa gli errori su stderr.</li><li><strong>Nessuna <code>cause</code></strong>, come in IMAP e SMTP: <code>console.error</code> segue la catena delle cause per intero.</li><li><strong>Timeout di 30 secondi</strong>, come gli altri connettori: un endpoint muto non blocca la run.</li><li>La cache del token vive <strong>in memoria, per la durata della run</strong>. Mai su disco.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Messaggio</th><th>Che cosa vuol dire</th></tr></thead><tbody><tr><td><code>OAuth2: refresh token rifiutato (invalid_grant)</code></td><td>Non più valido. Su un progetto Internal la causa prima è il <strong>cambio password della casella</strong>: lo scope è un ambito Gmail. Le altre cause sono nel runbook</td></tr><tr><td><code>OAuth2: il provider ha rifiutato la richiesta (invalid_client…)</code></td><td>Client ID o secret sbagliati</td></tr><tr><td><code>OAuth2: il token endpoint non risponde</code></td><td>Rete, DNS, timeout, o un redirect rifiutato</td></tr><tr><td><code>OAuth2: risposta del provider senza access_token utilizzabile</code></td><td>Il provider ha risposto 200 con un corpo che non contiene un token</td></tr><tr><td><code>Identità OAuth2 &quot;…&quot; non configurata</code></td><td><code>IMAP_OAUTH_INSTANCE</code> o <code>SMTP_OAUTH_INSTANCE</code> nomina un id che non esiste</td></tr></tbody></table>`,26)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};
@@ -0,0 +1 @@
1
+ import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,c,l,h){return o(),i("div",null,[...e[0]||(e[0]=[a("",26)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};
@@ -0,0 +1,17 @@
1
+ import{_ as o,o as i,c as t,a5 as d}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/zoho.md","filePath":"connectors/zoho.md"}'),a={name:"connectors/zoho.md"};function n(s,e,c,r,l,h){return i(),t("div",null,[...e[0]||(e[0]=[d(`<h1 id="connettore-zoho-crm-record-di-un-modulo-con-i-campi-dichiarati" tabindex="-1">Connettore: Zoho CRM (record di un modulo, con i campi dichiarati) <a class="header-anchor" href="#connettore-zoho-crm-record-di-un-modulo-con-i-campi-dichiarati" aria-label="Permalink to &quot;Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)&quot;">​</a></h1><p>Legge i record di un modulo di <strong>Zoho CRM</strong> dentro il grafo: <code>zohoCrmRecords</code> è un <code>Source</code> che restituisce tutti i record del modulo, con i soli campi che il nodo dichiara, convertiti in colonne tipizzate. Codice in <code>src/connectors/zoho/</code>, subpath <code>@noeva/etl-core/connectors/zoho</code>; decisioni in ADR-0106.</p><p>Legge con la <strong>Records API v8</strong>, oppure, per i moduli oltre i 100.000 record, con la <strong>Query API (COQL)</strong>. Come <a href="./jira">Jira</a> (ADR-0100) il connettore non ha un trasporto suo: parla con <a href="./http#trasporto-condiviso--richiestahttp"><code>richiestaHttp</code></a>, e ne eredita timeout, tetto sui byte, abort, validazione Zod e retry di 429 e 5xx. Il token lo rinnova un&#39;identità del modulo <a href="./oauth">OAuth2</a>, con il refresh token di Zoho.</p><table tabindex="0"><thead><tr><th>Funzione</th><th>Tipo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>zohoCrmRecords</code></td><td><code>Source</code></td><td>I record di un modulo, con i campi dichiarati, in colonne</td></tr><tr><td><code>loadZohoRegistry</code></td><td>registry</td><td>Le organizzazioni configurate, per istanza (ADR-0030)</td></tr><tr><td><code>loadZohoConfig</code></td><td>config</td><td>Una sola organizzazione, da variabili con prefisso</td></tr><tr><td><code>loadZohoInstance</code></td><td>config</td><td>Una sola organizzazione del registry, senza le altre</td></tr><tr><td><code>istanzaZohoPerIlPiano</code></td><td>piano</td><td>L&#39;organizzazione per il piano, con la sua ricaduta</td></tr><tr><td><code>trasportoZoho</code></td><td>config</td><td>La config del trasporto <code>http</code> per una richiesta, col token</td></tr><tr><td><code>MANIFEST_ZOHO</code></td><td>config</td><td>Le variabili di un&#39;organizzazione, per il piano (ADR-0089)</td></tr><tr><td><code>valoreZoho</code>, <code>colonnaZoho</code></td><td>utilità</td><td>La conversione di un valore e il nome della sua colonna</td></tr><tr><td><code>schemaRecordZoho</code></td><td>contratto</td><td>Lo schema Zod <code>strict</code> di un record letto con quei campi</td></tr><tr><td><code>nomiColonneZoho</code></td><td>utilità</td><td>Le colonne di un record, <code>id</code> compreso: quelle di un sink</td></tr><tr><td><code>colonneZoho</code>, <code>tipoColonnaZoho</code></td><td>utilità</td><td>Le colonne con il campo da cui vengono, e il loro tipo</td></tr><tr><td><code>dettaglioCredenzialeZoho</code></td><td>descriptor</td><td>La riga <code>credenziale</code>, per un nodo Zoho</td></tr><tr><td><code>maxCampiDi</code>, <code>eCampoUtente</code></td><td>utilità</td><td>I campi ammessi da una lettura; se un campo è un utente</td></tr><tr><td><code>LetturaZoho</code>, <code>CampoZoho</code>, …</td><td>tipi</td><td>La lettura (<code>records</code> o <code>coql</code>), un campo, un record</td></tr><tr><td><code>MAX_*</code>, <code>DEFAULT_ZOHO_*</code>, <code>CAMPO_*</code>, <code>SUFFISSO_NOME</code></td><td>costanti</td><td>I tetti di Zoho, i default del connettore, i nomi fissi</td></tr></tbody></table><h2 id="configurazione" tabindex="-1">Configurazione <a class="header-anchor" href="#configurazione" aria-label="Permalink to &quot;Configurazione&quot;">​</a></h2><p><code>loadZohoRegistry(env?)</code> risolve le organizzazioni: con <code>ZOHO_INSTANCES=vendite</code> ognuna ha le sue <code>ZOHO_&lt;ID&gt;_*</code>, senza lista valgono le variabili base <code>ZOHO_*</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>ZOHO_INSTANCES</code></td><td>—</td><td>elenco delle organizzazioni; senza, l&#39;istanza <code>default</code> dalle variabili base</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_BASE_URL</code></td><td>—</td><td>obbligatoria; la base delle API v8 del data center, <code>https://www.zohoapis.eu/crm/v8</code></td></tr><tr><td><code>ZOHO_&lt;ID&gt;_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>l&#39;identità <code>OAUTH_&lt;ID&gt;_*</code> che rinnova il token</td></tr><tr><td><code>ZOHO_&lt;ID&gt;_TIMEOUT_MS</code></td><td><code>60000</code></td><td>tempo massimo di una richiesta, in millisecondi</td></tr></tbody></table><p>Qui non c&#39;è nessun segreto. Client id, client secret e refresh token stanno nell&#39;identità OAuth2, con il token endpoint del data center di Zoho:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">OAUTH_INSTANCES</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">zoho_vendite</span></span>
2
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_TOKEN_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">https://accounts.zoho.eu/oauth/v2/token</span></span>
3
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_CLIENT_ID</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> della</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Zoho</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> API</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Consol</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
4
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_CLIENT_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nel</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker,</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mai</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repositor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
5
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">OAUTH_ZOHO_VENDITE_REFRESH_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nel</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> del</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker,</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mai</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> repositor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>Il refresh token vuole gli scope <code>ZohoCRM.modules.READ</code> (i record) e <code>ZohoCRM.settings.fields.READ</code> (il catalogo dei campi), più <code>ZohoCRM.coql.READ</code> se un nodo legge con COQL: tutti e tre di sola lettura. Il data center della base delle API e quello del token endpoint devono essere lo stesso: un token di <code>accounts.zoho.eu</code> vale solo su <code>zohoapis.eu</code>.</p><p><code>BASE_URL</code> vuole <code>https</code> e deve finire con <code>/crm/v8</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-—-zohocrmrecords" tabindex="-1">Source — <code>zohoCrmRecords</code> <a class="header-anchor" href="#source-—-zohocrmrecords" aria-label="Permalink to &quot;Source — \`zohoCrmRecords\`&quot;">​</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:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> token</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fornitoreToken</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadOauthRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(config.oauthInstance));</span></span>
6
+ <span class="line"></span>
7
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">zohoCrmRecords</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
8
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> config, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// loadZohoRegistry().get(&quot;vendite&quot;)</span></span>
9
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> token, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// un fornitore per run, condiviso fra i nodi</span></span>
10
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vendite&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
11
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> modulo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Deals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
12
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> campi: [</span></span>
13
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Stage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;picklist&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
14
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Owner&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ownerlookup&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
15
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { nome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Modified_Time&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, tipo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;datetime&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
16
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
17
+ <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>l&#39;organizzazione</td></tr><tr><td><code>token</code></td><td>—</td><td><code>() =&gt; Promise&lt;string&gt;</code>, da <code>fornitoreToken</code></td></tr><tr><td><code>modulo</code></td><td>—</td><td>il nome API del modulo (<code>Deals</code>, <code>omniconnectforzohocrm__Chat_Messages</code>)</td></tr><tr><td><code>campi</code></td><td>—</td><td>i campi, con il <code>data_type</code> di Zoho: 48 oltre a <code>Modified_Time</code> con <code>records</code>; con <code>coql</code> 499, nome e cognome di ogni utente compresi, e al più 15 collegamenti a utenti</td></tr><tr><td><code>lettura</code></td><td><code>records</code></td><td><code>records</code> (Records API, fino a 100.000 record) o <code>coql</code> (Query API, senza tetto)</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>perPagina</code></td><td><code>200</code></td><td><code>records</code>: record per pagina, fra 1 e 200</td></tr><tr><td><code>maxPerInterrogazione</code></td><td><code>100000</code></td><td><code>records</code>: il tetto di Zoho per interrogazione; più basso solo nei test</td></tr><tr><td><code>perQuery</code></td><td><code>2000</code></td><td><code>coql</code>: record per query, fra 1 e 2000</td></tr><tr><td><code>retry</code>, <code>fetchImpl</code></td><td>—</td><td>retry di ogni richiesta (default 5 tentativi, attese fino a 60 s); <code>fetch</code> finto nei test</td></tr></tbody></table><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 &quot;I campi sono la regola di privacy&quot;">​</a></h3><p>Il source chiede a Zoho <strong>solo</strong> i campi dichiarati, più <code>id</code> (e, con <code>records</code>, <code>Modified_Time</code>; con <code>coql</code> anche nome e cognome degli utenti, vedi sotto), ed emette solo le loro colonne: un campo che Zoho manda senza che lo si chieda non esce. Un campo nuovo in Zoho non entra finché qualcuno non lo dichiara. Per la stessa ragione lo schema di <code>schemaRecordZoho</code> è <code>strict</code>: un record con una colonna in più non passa il contratto.</p><p>A ogni run il source legge prima il catalogo dei campi del modulo (<code>GET /settings/fields</code>): un campo dichiarato che Zoho non conosce più è un <code>ConfigError</code> che lo nomina, <strong>prima</strong> della prima pagina. Un tipo cambiato si segnala nel log (<code>zoho-source.tipo-cambiato</code>).</p><h3 id="colonne-e-valori" tabindex="-1">Colonne e valori <a class="header-anchor" href="#colonne-e-valori" aria-label="Permalink to &quot;Colonne e valori&quot;">​</a></h3><p>Il nome della colonna è il nome API in minuscolo, con i caratteri non di parola in <code>_</code> (<code>Account_Name</code> → <code>account_name</code>). La conversione è quella dello script che leggeva il CRM del primo cliente prima di questo connettore:</p><table tabindex="0"><thead><tr><th>Tipo Zoho</th><th>Colonna</th></tr></thead><tbody><tr><td><code>lookup</code></td><td>il solo <code>id</code> del record collegato, mai il nome</td></tr><tr><td><code>userlookup</code>, <code>ownerlookup</code></td><td>l&#39;<code>id</code>, e il nome dell&#39;utente Zoho in <code>&lt;colonna&gt;_nome</code></td></tr><tr><td><code>multiselectpicklist</code> e liste</td><td>le voci unite da <code>&quot;; &quot;</code></td></tr><tr><td><code>datetime</code></td><td>l&#39;ora locale come la dà Zoho, senza fuso: <code>AAAA-MM-GGTHH:MM:SS</code></td></tr><tr><td><code>date</code></td><td><code>AAAA-MM-GG</code></td></tr><tr><td><code>boolean</code></td><td>booleano</td></tr><tr><td><code>integer</code></td><td>intero</td></tr><tr><td><code>double</code>, <code>currency</code>, <code>decimal</code>, <code>percent</code></td><td>numero</td></tr><tr><td>il resto (testo, picklist, formule)</td><td>testo</td></tr></tbody></table><p>Un valore vuoto è <code>null</code>. Un valore che non si converte nel tipo del suo campo è un <code>ExtractError</code> che nomina modulo, campo e <code>id</code> del record, mai il valore.</p><h3 id="le-due-letture" tabindex="-1">Le due letture <a class="header-anchor" href="#le-due-letture" aria-label="Permalink to &quot;Le due letture&quot;">​</a></h3><p>Entrambe leggono il modulo <strong>in ordine di <code>id</code></strong>, in sequenza: un blocco si chiede solo quando chi legge ha consumato il precedente, e in memoria restano gli <code>id</code> visti, non i record. Un modulo vuoto (Zoho risponde <code>204</code>) non dà record.</p><p>L&#39;ordine è per <code>id</code> perché un <code>id</code> non cambia mai. La prima versione ordinava per <code>Modified_Time</code>, e nella prima prova su un CRM reale perdeva fra lo 0,1% e il 13% dei record per modulo: un record modificato durante la lettura passa in fondo all&#39;ordinamento, compare due volte e fa scivolare il confine fra due pagine, così un altro record salta.</p><ul><li><strong><code>records</code></strong> (default): la Records API, <code>GET /{modulo}?sort_by=id&amp;sort_order=asc</code>, pagine da 200 con <code>page_token</code>. Non va oltre 100.000 record per interrogazione: arrivato al tetto, il source si ferma con un <code>ExtractError</code> che indica la lettura <code>coql</code>, invece di lasciare un modulo troncato. <code>more_records</code> senza <code>next_page_token</code>, o un token già visto, è un <code>ExtractError</code>.</li><li><strong><code>coql</code></strong>: la Query API, <code>POST /coql</code> con <code>select &#39;id&#39;, &#39;Campo&#39;, … from Modulo where id &gt; &#39;&lt;ultimo&gt;&#39; order by id asc limit 2000</code>. Ogni query riparte dall&#39;ultimo <code>id</code> del blocco prima, come raccomanda Zoho per andare oltre i 100.000 record: nessun tetto, e dieci volte meno chiamate della Records API. Fino a 499 campi per query, quindi un modulo largo non si divide in passate. I nomi dei campi e del modulo sono nomi API già validati, e l&#39;<code>id</code> che entra nella query è di sole cifre: un <code>id</code> che non lo è, o un blocco i cui <code>id</code> non crescono, è un <code>ExtractError</code>. COQL restituisce un utente come <code>{ id, name }</code>, ma in <code>name</code> mette il solo cognome (e per alcuni utenti niente), mentre la Records API dà nome e cognome. Per ogni collegamento a un utente la query chiede quindi anche <code>&#39;&lt;Campo&gt;.first_name&#39;</code> e <code>&#39;&lt;Campo&gt;.last_name&#39;</code>, con una join sul modulo degli utenti, e la colonna <code>_nome</code> è «Nome Cognome», come con la Records API (<code>full_name</code> COQL non lo accetta). Senza nome né cognome resta il <code>name</code> di COQL; se manca anche quello la colonna resta vuota e il log lo segnala (<code>zoho-source.nome-utente-assente</code>). Nome e cognome contano fra i 499 campi della query, e i collegamenti a utenti sono al più 15, le join che COQL ammette. COQL non ammette i campi multi-select lookup, upload di file e immagini, e al più cinque campi formula dinamici.</li></ul><h3 id="token-ed-errori" tabindex="-1">Token ed errori <a class="header-anchor" href="#token-ed-errori" aria-label="Permalink to &quot;Token ed errori&quot;">​</a></h3><p>Il token si chiede al fornitore a <strong>ogni</strong> richiesta, con l&#39;header <code>Authorization: Zoho-oauthtoken &lt;token&gt;</code>: una lettura che dura più della vita del token si rinnova da sé. Zoho risponde <code>200</code> anche a un refresh rifiutato, con <code>{ &quot;error&quot;: … }</code> nel corpo: il fornitore lo tratta come un rifiuto e lo dice con il codice di Zoho, come un <code>ConfigError</code>.</p><p>Gli errori di lettura sono <code>ExtractError</code> con metodo, percorso e status, più un suggerimento per <code>400</code>, <code>401</code>, <code>403</code> e <code>404</code>. Mai il token, mai il corpo della risposta.</p><h3 id="nel-dag" tabindex="-1">Nel DAG <a class="header-anchor" href="#nel-dag" aria-label="Permalink to &quot;Nel DAG&quot;">​</a></h3><p>Il descriptor ha <code>kind: &quot;zoho-source&quot;</code>, l&#39;istanza, poi <code>api</code> (la base delle API, con la sua variabile), <code>modulo</code>, <code>lettura</code>, <code>campi</code>, e in fondo la <code>credenziale</code>: quale identità OAuth2 rinnova il token e, nel piano, se le sue variabili ci sono tutte o quali mancano. Mai un segreto.</p><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p><code>src/connectors/zoho/*.test.ts</code>: configurazione e registry, descriptor senza segreti, conversione e nomi di colonna, paginazione per <code>id</code> con <code>page_token</code> e il tetto che indica COQL, lettura COQL a chiavi crescenti di <code>id</code> (query, blocchi, <code>id</code> non crescenti o non numerici), campo sconosciuto prima della prima pagina, privacy (nessun campo non dichiarato esce), token chiesto a ogni richiesta, retry di un 429. Nessuna chiamata a Zoho vero: <code>fetchImpl</code> finto e dati sintetici.</p>`,32)])])}const k=o(a,[["render",n]]);export{u as __pageData,k as default};
@@ -0,0 +1 @@
1
+ import{_ as o,o as i,c as t,a5 as d}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Connettore: Zoho CRM (record di un modulo, con i campi dichiarati)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/zoho.md","filePath":"connectors/zoho.md"}'),a={name:"connectors/zoho.md"};function n(s,e,c,r,l,h){return i(),t("div",null,[...e[0]||(e[0]=[d("",32)])])}const k=o(a,[["render",n]]);export{u as __pageData,k as default};
@@ -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. &quot;postgres&quot;, &quot;sqlserver&quot;, &quot;noeva-file&quot;, &quot;file&quot;, &quot;memory&quot;</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&#39;è 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&#39;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, 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&#39;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&#39;<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 &quot;Le tre regole vincolanti&quot;">​</a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l&#39;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&#39;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&#39;è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l&#39;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 &quot;Campi esposti oggi, per connettore&quot;">​</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&#39;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&#39;header</td><td>config + opzioni dell&#39;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&#39;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&#39;endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l&#39;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&#39;action Jira</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&#39;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&#39;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 &quot;puntamento&quot;, non il payload. Nel piano, dove non c&#39;è un pool, host, porta e database vengono dalla risoluzione dell&#39;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 &quot;Aggiungere un descriptor a un nuovo connettore&quot;">​</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&#39;è 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&#39;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&#39;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&#39;<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 &quot;Le tre regole vincolanti&quot;">​</a></h2><ol><li><strong>Whitelist esplicita, mai un dump.</strong> <code>details</code> elenca campi scelti a mano. Non serializzare l&#39;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&#39;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&#39;è <code>etl catalog check</code> (regola <code>piano-senza-segreti</code>), che prende l&#39;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 &quot;Campi esposti oggi, per connettore&quot;">​</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&#39;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&#39;header</td><td>config + opzioni dell&#39;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&#39;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&#39;endpoint, senza la chiave della issue), su errore, idempotenza, limite (chiamate al secondo, letture comprese), ID esterno e creazione (solo l&#39;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&#39;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&#39;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&#39;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&#39;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 &quot;puntamento&quot;, non il payload. Nel piano, dove non c&#39;è un pool, host, porta e database vengono dalla risoluzione dell&#39;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 &quot;Aggiungere un descriptor a un nuovo connettore&quot;">​</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;">&quot;mio-sistema&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -1,10 +1,10 @@
1
- import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),p={name:"nodes/source.md"};function h(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.source(id, source, { after?, purpose?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>0</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>no: un errore di estrazione ferma la run</td></tr><tr><td>Codice</td><td><code>Source&lt;T&gt;</code> in <code>src/core/connector.ts</code></td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><p>Per ogni sistema da cui il processo <strong>parte</strong>: una tabella, un file, una cartella, una casella di posta, un workspace Noeva. Se invece i dati esterni servono ad <strong>arricchire</strong> record che scorrono già nel grafo, e vanno letti solo per le chiavi presenti, è un <a href="./lookup"><code>lookup</code></a>.</p><h2 id="il-contratto" tabindex="-1">Il contratto <a class="header-anchor" href="#il-contratto" aria-label="Permalink to &quot;Il contratto&quot;">​</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:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; {</span></span>
1
+ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),h={name:"nodes/source.md"};function p(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d(`<table tabindex="0"><thead><tr><th>Metodo</th><th><code>.source(id, source, { after?, purpose?, writeReport? })</code></th></tr></thead><tbody><tr><td>Ingressi</td><td>0</td></tr><tr><td>Uscite</td><td>≥1 (fan-out libero)</td></tr><tr><td>Dead-letter</td><td>no: un errore di estrazione ferma la run</td></tr><tr><td>Codice</td><td><code>Source&lt;T&gt;</code> in <code>src/core/connector.ts</code></td></tr></tbody></table><h2 id="quando-usarlo" tabindex="-1">Quando usarlo <a class="header-anchor" href="#quando-usarlo" aria-label="Permalink to &quot;Quando usarlo&quot;">​</a></h2><p>Per ogni sistema da cui il processo <strong>parte</strong>: una tabella, un file, una cartella, una casella di posta, un workspace Noeva. Se invece i dati esterni servono ad <strong>arricchire</strong> record che scorrono già nel grafo, e vanno letti solo per le chiavi presenti, è un <a href="./lookup"><code>lookup</code></a>.</p><h2 id="il-contratto" tabindex="-1">Il contratto <a class="header-anchor" href="#il-contratto" aria-label="Permalink to &quot;Il contratto&quot;">​</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:#D73A49;--shiki-dark:#F97583;">interface</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; {</span></span>
2
2
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</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>
3
3
  <span class="line"><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:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> RunContext</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">incremental</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> IncrementalExtract</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AsyncIterable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">T</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;;</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;"> descriptor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ConnectorDescriptor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// che cos&#39;è e dove punta, per il DAG</span></span>
5
5
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> columns</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;"> PlanColumn</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[]; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// campi emessi, se non c&#39;è uno schema Zod</span></span>
6
6
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> readonly</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> watermark</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> SourceWatermark</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// presente se la source è incrementale</span></span>
7
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to &quot;Source pronte&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to &quot;Esempio&quot;">​</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;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture-giornaliere&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
7
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>La source si <strong>inietta</strong> nella funzione che costruisce il grafo, non si istanzia dentro: così la pipeline si prova con <code>arraySource</code> e <code>getSpec()</code> mostra la topologia senza credenziali.</p><h2 id="source-pronte" tabindex="-1">Source pronte <a class="header-anchor" href="#source-pronte" aria-label="Permalink to &quot;Source pronte&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Funzione</th><th>Sistema</th><th>Scheda</th></tr></thead><tbody><tr><td><code>postgresSource</code></td><td>PostgreSQL (cursor)</td><td><a href="./../connectors/postgres">postgres</a></td></tr><tr><td><code>mssqlSource</code></td><td>SQL Server</td><td><a href="./../connectors/sqlserver">sqlserver</a></td></tr><tr><td><code>fileSource</code>, <code>localFolderSource</code></td><td>File (storage × codec)</td><td><a href="./../connectors/file">file</a></td></tr><tr><td><code>noevaFileSource</code>, <code>noevaFolderSource</code></td><td>Workspace Noeva</td><td><a href="./../connectors/noeva">noeva</a></td></tr><tr><td><code>imapSource</code></td><td>Casella di posta</td><td><a href="./../connectors/imap">imap</a></td></tr><tr><td><code>jiraIssues</code></td><td>Jira Cloud (issue di una JQL)</td><td><a href="./../connectors/jira">jira</a></td></tr><tr><td><code>zohoCrmRecords</code></td><td>Zoho CRM (record di un modulo)</td><td><a href="./../connectors/zoho">zoho</a></td></tr><tr><td><code>arraySource(name, rows)</code></td><td>In memoria: test e configurazione</td><td>—</td></tr></tbody></table><h2 id="esempio" tabindex="-1">Esempio <a class="header-anchor" href="#esempio" aria-label="Permalink to &quot;Esempio&quot;">​</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;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture-giornaliere&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
8
8
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatture&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.fatture) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Source&lt;unknown&gt;: il contratto lo fa il nodo dopo</span></span>
9
9
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;clienti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sources.clienti)</span></span>
10
10
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
@@ -30,4 +30,4 @@ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qd
30
30
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> lookback: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> *</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 60_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// opzionale, in millisecondi: copre le transazioni lunghe</span></span>
31
31
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
32
32
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Esito della run</th><th>Il watermark avanza?</th></tr></thead><tbody><tr><td><code>success</code></td><td>sì</td></tr><tr><td><code>partial</code></td><td>no, salvo <code>graph(nome, { commitOn: &quot;partial&quot; })</code>, e solo se ogni scarto è una dead-letter per record</td></tr><tr><td><code>failed</code></td><td>mai</td></tr></tbody></table><p>Regole da tenere a mente:</p><ul><li><strong>Il confine è <code>&gt;=</code></strong>, non <code>&gt;</code>: due run consecutive senza dati nuovi rileggono le righe al confine. Per questo una source incrementale scrive <strong>solo verso sink idempotenti</strong>.</li><li><strong>Senza il segnaposto <code>:watermark</code> la costruzione fallisce</strong> (source SQL): una query incrementale non degrada in silenzio in un full scan.</li><li><strong>Il watermark è testo</strong>, nella precisione del database: i microsecondi di Postgres non si perdono passando da una <code>Date</code>.</li><li><strong>Lo store lo inietta chi lancia la run</strong> (<code>ctx.stateStore</code>): un file locale per <code>etl run</code>, <code>noeva-server-api</code> per il worker e per <code>etl run --workspace &lt;id&gt;</code>. Un grafo con source incrementali non parte senza. Nei test si usa <code>MemoryPipelineStateStore</code>.</li><li><strong>Backfill:</strong> <code>params.watermark.&lt;nodeId&gt;</code> sostituisce in lettura il valore salvato, e non fa arretrare lo stato. <strong>Reset:</strong> <code>etl state reset</code>, l&#39;unico modo di farlo arretrare.</li></ul><p>Oggi sono incrementali <code>postgresSource</code>, <code>mssqlSource</code> e <code>jiraIssues</code> con <code>incremental</code> (il filtro su <code>updated</code> lo scrive il connettore: vedi <a href="./../connectors/jira">jira</a>, «Modalità incrementale»). Operatività, diagnosi e procedure: <a href="./../runbooks/stato-incrementale">runbook</a>.</p><h2 id="partire-dopo-un-altro-nodo-after" tabindex="-1">Partire dopo un altro nodo: <code>after</code> <a class="header-anchor" href="#partire-dopo-un-altro-nodo-after" aria-label="Permalink to &quot;Partire dopo un altro nodo: \`after\`&quot;">​</a></h2><p>Con <code>after</code> la source ha un <strong>gate</strong>: <code>extract()</code> non viene chiamato finché i nodi elencati non sono <strong>riusciti</strong>. Sono <a href="./task"><code>task</code></a> o <code>sink</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:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ordini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, ordini, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;svuota-staging&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un task: pre-task</span></span>
33
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fatti, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica-dimensioni&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un sink: dimensioni prima dei fatti</span></span></code></pre></div><ul><li>Più nodi in <code>after</code> valgono in AND.</li><li>Tutto ciò che sta a valle aspetta con lei: un lookup sui fatti legge le dimensioni già caricate, e un sink a valle non chiama <code>load</code> finché il gate non si apre.</li><li>Se un predecessore non è riuscito la source è <strong>saltata</strong>: <code>extract()</code> non viene mai chiamato, e i nodi a valle sono saltati con lei. Vedi <a href="./task#nodi-saltati"><code>task</code></a>.</li><li><code>build()</code> rifiuta un <code>after</code> che crea un ciclo (il sink alimentato dalla source stessa) o un deadlock su un <code>join</code> o un <code>union</code> a valle.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>extract</code> è un contratto <strong>opaco</strong>: non isola il singolo record. Un errore di estrazione (<code>ExtractError</code>) interrompe la run, anche sotto un <code>try-catch</code>, perché la source sta a monte di ogni scope. Il retry non si applica alle source: rileggere non è sempre senza effetti.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (tipo di connettore, istanza, puntamenti; mai segreti) e le colonne dichiarate in <code>columns</code>. Nel report, <code>extracted</code> conta i record emessi. Una source saltata ha <code>skipped: { because }</code> e <code>startedAt: null</code>. Una source incrementale ha anche una voce in <a href="./../conventions/run-report#stato-di-pipeline-state"><code>state</code></a>: da dove ha letto, cosa propone, se ha committato.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li><code>Array.fromAsync(source.extract(ctx))</code>, o qualunque cosa che legga tutto in memoria: si perde lo streaming e con lui la backpressure.</li><li>Istanziare il client o il pool dentro <code>build…Pipeline</code>: va iniettato.</li></ul>`,29))])}const F=t(p,[["render",h]]);export{m as __pageData,F as default};
33
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fatti&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, fatti, { after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica-dimensioni&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] }) </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// dopo un sink: dimensioni prima dei fatti</span></span></code></pre></div><ul><li>Più nodi in <code>after</code> valgono in AND.</li><li>Tutto ciò che sta a valle aspetta con lei: un lookup sui fatti legge le dimensioni già caricate, e un sink a valle non chiama <code>load</code> finché il gate non si apre.</li><li>Se un predecessore non è riuscito la source è <strong>saltata</strong>: <code>extract()</code> non viene mai chiamato, e i nodi a valle sono saltati con lei. Vedi <a href="./task#nodi-saltati"><code>task</code></a>.</li><li><code>build()</code> rifiuta un <code>after</code> che crea un ciclo (il sink alimentato dalla source stessa) o un deadlock su un <code>join</code> o un <code>union</code> a valle.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><p><code>extract</code> è un contratto <strong>opaco</strong>: non isola il singolo record. Un errore di estrazione (<code>ExtractError</code>) interrompe la run, anche sotto un <code>try-catch</code>, perché la source sta a monte di ogni scope. Il retry non si applica alle source: rileggere non è sempre senza effetti.</p><h2 id="nel-dag-e-nel-report" tabindex="-1">Nel DAG e nel report <a class="header-anchor" href="#nel-dag-e-nel-report" aria-label="Permalink to &quot;Nel DAG e nel report&quot;">​</a></h2><p>Il nodo mostra il <code>descriptor</code> (tipo di connettore, istanza, puntamenti; mai segreti) e le colonne dichiarate in <code>columns</code>. Nel report, <code>extracted</code> conta i record emessi. Una source saltata ha <code>skipped: { because }</code> e <code>startedAt: null</code>. Una source incrementale ha anche una voce in <a href="./../conventions/run-report#stato-di-pipeline-state"><code>state</code></a>: da dove ha letto, cosa propone, se ha committato.</p><h2 id="anti-pattern" tabindex="-1">Anti-pattern <a class="header-anchor" href="#anti-pattern" aria-label="Permalink to &quot;Anti-pattern&quot;">​</a></h2><ul><li><code>Array.fromAsync(source.extract(ctx))</code>, o qualunque cosa che legga tutto in memoria: si perde lo streaming e con lui la backpressure.</li><li>Istanziare il client o il pool dentro <code>build…Pipeline</code>: va iniettato.</li></ul>`,29))])}const F=t(h,[["render",p]]);export{m as __pageData,F as default};
@@ -1 +1 @@
1
- import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),p={name:"nodes/source.md"};function h(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d("",29))])}const F=t(p,[["render",h]]);export{m as __pageData,F as default};
1
+ import{_ as t,C as n,o,c as r,j as i,a,E as l,a5 as d}from"./chunks/framework.qdetmeNX.js";const m=JSON.parse('{"title":"Nodo: source","description":"","frontmatter":{"pageClass":"etl-wide"},"headers":[],"relativePath":"nodes/source.md","filePath":"nodes/source.md"}'),h={name:"nodes/source.md"};function p(c,s,k,u,g,E){const e=n("NodeDemo");return o(),r("div",null,[s[0]||(s[0]=i("h1",{id:"nodo-source",tabindex:"-1"},[a("Nodo: source "),i("a",{class:"header-anchor",href:"#nodo-source","aria-label":'Permalink to "Nodo: source"'},"​")],-1)),s[1]||(s[1]=i("p",null,[a("Il punto d'ingresso di un flusso: estrae record da un sistema esterno e li emette "),i("strong",null,"in streaming"),a(", uno alla volta, senza mai caricarli tutti in memoria. Ogni grafo ne ha almeno uno.")],-1)),l(e,{kind:"source"}),s[2]||(s[2]=d("",29))])}const F=t(h,[["render",p]]);export{m as __pageData,F as default};
@@ -1,4 +1,4 @@
1
- import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-un-cliente-su-ecr-ecs" tabindex="-1">Runbook: un cliente su ECR + ECS <a class="header-anchor" href="#runbook-un-cliente-su-ecr-ecs" aria-label="Permalink to &quot;Runbook: un cliente su ECR + ECS&quot;">​</a></h1><blockquote><p>L&#39;artefatto di un repo cliente è l&#39;immagine su GHCR (<a href="./deployment">deployment.md</a>). Un cliente può scegliere invece <strong>ECR</strong>, con il suo <strong>servizio ECS</strong> e il suo <code>.env</code> in un bucket S3 (ADR-0094 §1, ADR-0104). Lo strumento arriva col pacchetto: <code>etl deploy-ecr</code>, lanciato <strong>dalla radice del repo cliente</strong>, che porta la sua <code>deploy-ecr.conf</code>.</p></blockquote><h2 id="build-pubblicazione-ecr" tabindex="-1">Build &amp; pubblicazione (ECR) <a class="header-anchor" href="#build-pubblicazione-ecr" aria-label="Permalink to &quot;Build &amp; pubblicazione (ECR)&quot;">​</a></h2><p>Si deploya <strong>un cliente per volta</strong>, dalla radice del suo repo:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--ambiente </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">staging]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--env </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">fil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--attendi] [--dry-run]</span></span></code></pre></div><p>Lo script è il <strong>core</strong> del deploy, uguale per tutti: sta nel pacchetto, in <code>deploy/deploy-ecr.sh</code>, accanto al Dockerfile dell&#39;artefatto. Ciò che è del cliente sta nella <code>deploy-ecr.conf</code> alla radice del suo repo, che dichiara soltanto:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Cosa</th></tr></thead><tbody><tr><td><code>ECR_REPOSITORY</code></td><td>il repository dell&#39;immagine del cliente</td></tr><tr><td><code>ECS_CLUSTER_&lt;amb&gt;</code>, <code>ECS_SERVICE_&lt;amb&gt;</code>, <code>ENV_BUCKET_&lt;amb&gt;</code></td><td>servizio e bucket del <code>.env</code> per ambiente; senza, il cliente pubblica solo l&#39;immagine</td></tr><tr><td><code>PIPELINE</code></td><td>il catalogo del deploy, che <code>ETL_PIPELINE_WORKSPACES</code> deve assegnare per intero</td></tr><tr><td><code>ENV_OBBLIGATORIE</code>, <code>ENV_VIETATE</code></td><td>variabili che il <code>.env</code> deve avere, o non deve avere</td></tr><tr><td><code>SUBMODULE</code></td><td>submodule che l&#39;immagine copia, verificati al commit registrato</td></tr><tr><td><code>AWS_ACCOUNT_ATTESO</code>, <code>PIATTAFORME</code></td><td>l&#39;account su cui fermarsi se si è sbagliato profilo, e le architetture</td></tr><tr><td><code>CLIENTE_NOME</code></td><td>il nome leggibile nell&#39;intestazione del deploy</td></tr><tr><td><code>CLIENTE_SLUG</code></td><td>lo slug del cliente: il deploy si ferma se <code>&lt;cliente&gt;</code> è un altro</td></tr></tbody></table><p>Il file è codice bash che lo script legge con <code>source</code>: solo assegnazioni, e <strong>niente segreti</strong>, che stanno nel <code>.env</code> del bucket. Un esempio:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">CLIENTE_NOME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Acme&quot;</span></span>
1
+ import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-un-cliente-su-ecr-ecs" tabindex="-1">Runbook: un cliente su ECR + ECS <a class="header-anchor" href="#runbook-un-cliente-su-ecr-ecs" aria-label="Permalink to &quot;Runbook: un cliente su ECR + ECS&quot;">​</a></h1><blockquote><p>L&#39;artefatto di un repo cliente è l&#39;immagine su GHCR (<a href="./deployment">deployment.md</a>). Un cliente può scegliere invece <strong>ECR</strong>, con il suo <strong>servizio ECS</strong> e il suo <code>.env</code> in un bucket S3 (ADR-0094 §1, ADR-0104). Lo strumento arriva col pacchetto: <code>etl deploy-ecr</code>, lanciato <strong>dalla radice del repo cliente</strong>, che porta la sua <code>deploy-ecr.conf</code>.</p></blockquote><h2 id="build-pubblicazione-ecr" tabindex="-1">Build &amp; pubblicazione (ECR) <a class="header-anchor" href="#build-pubblicazione-ecr" aria-label="Permalink to &quot;Build &amp; pubblicazione (ECR)&quot;">​</a></h2><p>Si deploya <strong>un cliente per volta</strong>, dalla radice del suo repo:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--ambiente </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">staging]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--env </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">fil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--attendi] [--dry-run]</span></span></code></pre></div><p>Lo script è il <strong>core</strong> del deploy, uguale per tutti: sta nel pacchetto, in <code>deploy/deploy-ecr.sh</code>, accanto al Dockerfile dell&#39;artefatto. Ciò che è del cliente sta nella <code>deploy-ecr.conf</code> alla radice del suo repo, che dichiara soltanto:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Cosa</th></tr></thead><tbody><tr><td><code>ECR_REPOSITORY</code></td><td>il repository dell&#39;immagine del cliente</td></tr><tr><td><code>ECS_CLUSTER_&lt;amb&gt;</code>, <code>ECS_SERVICE_&lt;amb&gt;</code>, <code>ENV_BUCKET_&lt;amb&gt;</code></td><td>servizio e bucket del <code>.env</code> per ambiente; senza, il cliente pubblica solo l&#39;immagine</td></tr><tr><td><code>PIPELINE</code></td><td>il catalogo del deploy, che <code>ETL_PIPELINE_WORKSPACES</code> deve assegnare per intero</td></tr><tr><td><code>ENV_OBBLIGATORIE</code>, <code>ENV_VIETATE</code></td><td>variabili che il <code>.env</code> deve avere, o non deve avere</td></tr><tr><td><code>SUBMODULE</code></td><td>submodule che l&#39;immagine copia, verificati al commit registrato</td></tr><tr><td><code>AWS_ACCOUNT_ATTESO</code>, <code>PIATTAFORME</code></td><td>l&#39;account su cui fermarsi se si è sbagliato profilo, e le architetture</td></tr><tr><td><code>CLIENTE_NOME</code></td><td>il nome leggibile nell&#39;intestazione del deploy</td></tr><tr><td><code>CLIENTE_SLUG</code></td><td>lo slug del cliente: il deploy si ferma se <code>&lt;cliente&gt;</code> è un altro</td></tr></tbody></table><p>Il file è codice bash che lo script legge con <code>source</code>: solo assegnazioni, e <strong>niente segreti</strong>, che stanno nel <code>.env</code> del bucket. Un esempio:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</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;">CLIENTE_NOME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Acme&quot;</span></span>
2
2
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CLIENTE_SLUG</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme&quot;</span></span>
3
3
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">AWS_ACCOUNT_ATTESO</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;123456789012&quot;</span></span>
4
4
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ECR_REPOSITORY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;noeva-etl-acme&quot;</span></span>
@@ -42,4 +42,4 @@ import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
42
42
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> kms_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">kms</span></span>
43
43
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alb_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">alb</span></span>
44
44
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ecs_cluster_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ecs_cluster_production</span></span>
45
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>I nomi devono coincidere con quelli della <code>deploy-ecr.conf</code> del cliente. <code>service_name</code> ha al massimo 37 caratteri: il modulo ne ricava il ruolo IAM <code>&lt;service_name&gt;-eventbridge-start-pipeline</code>, e un nome di ruolo ne ha al massimo 64. Per questo il servizio può chiamarsi diversamente dal suo repository ECR. Dopo l&#39;<code>apply</code>:</p><ol><li>il <code>.env</code> del cliente, preparato da <code>.env.example</code> con <code>ETL_PIPELINE_WORKSPACES</code> sulle sue pipeline, va nel bucket al primo deploy (<code>--env</code>);</li><li><code>pnpm exec etl deploy-ecr &lt;cliente&gt; --dry-run</code> deve chiudere verde;</li><li>il primo deploy vero, con <code>--attendi</code>, poi una run di prova da Noeva.</li></ol><h2 id="la-release-nel-report" tabindex="-1">La release nel report <a class="header-anchor" href="#la-release-nel-report" aria-label="Permalink to &quot;La release nel report&quot;">​</a></h2><p>L&#39;immagine porta <code>ETL_RELEASE=git:&lt;sha12&gt;</code>, il commit buildato (sempre un commit pubblicato e a working tree pulito), così il report registra quale release ha eseguito la run (campo <code>release</code>; la versione di pipeline sta in <code>pipelineVersion</code>, ADR-0086). Accanto alla release il report porta la versione del core (<code>core</code>) e il cliente (<code>client</code>): vedi <a href="./../conventions/run-report#versione-di-pipeline-e-release">report di run § Versione di pipeline e release</a>.</p><h2 id="dal-repo-del-core" tabindex="-1">Dal repo del core <a class="header-anchor" href="#dal-repo-del-core" aria-label="Permalink to &quot;Dal repo del core&quot;">​</a></h2><p>Finché un cliente su ECR non ha il suo repo, la sua configurazione sta nel core, in <code>clienti/&lt;cliente&gt;/deploy-ecr.conf</code>, e si deploya dalla radice del core con <code>./deploy-ecr.sh &lt;cliente&gt;</code>, che lancia lo stesso script del pacchetto. Lì il gate è <code>pnpm run check</code> e l&#39;immagine si costruisce col <code>Dockerfile</code> del core. Lo script cerca prima la <code>deploy-ecr.conf</code> alla radice, poi quella in <code>clienti/&lt;cliente&gt;/</code>.</p>`,28)])])}const E=s(l,[["render",t]]);export{k as __pageData,E as default};
45
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>I nomi devono coincidere con quelli della <code>deploy-ecr.conf</code> del cliente. <code>service_name</code> ha al massimo 37 caratteri: il modulo ne ricava il ruolo IAM <code>&lt;service_name&gt;-eventbridge-start-pipeline</code>, e un nome di ruolo ne ha al massimo 64. Per questo il servizio può chiamarsi diversamente dal suo repository ECR. Dopo l&#39;<code>apply</code>:</p><ol><li>il <code>.env</code> del cliente, preparato da <code>.env.example</code> con <code>ETL_PIPELINE_WORKSPACES</code> sulle sue pipeline, va nel bucket al primo deploy (<code>--env</code>);</li><li><code>pnpm exec etl deploy-ecr &lt;cliente&gt; --dry-run</code> deve chiudere verde;</li><li>il primo deploy vero, con <code>--attendi</code>, poi una run di prova da Noeva.</li></ol><h2 id="la-release-nel-report" tabindex="-1">La release nel report <a class="header-anchor" href="#la-release-nel-report" aria-label="Permalink to &quot;La release nel report&quot;">​</a></h2><p>L&#39;immagine porta <code>ETL_RELEASE=git:&lt;sha12&gt;</code>, il commit buildato (sempre un commit pubblicato e a working tree pulito), così il report registra quale release ha eseguito la run (campo <code>release</code>; la versione di pipeline sta in <code>pipelineVersion</code>, ADR-0086). Accanto alla release il report porta la versione del core (<code>core</code>) e il cliente (<code>client</code>): vedi <a href="./../conventions/run-report#versione-di-pipeline-e-release">report di run § Versione di pipeline e release</a>.</p>`,26)])])}const E=s(l,[["render",t]]);export{c as __pageData,E as default};
@@ -1 +1 @@
1
- import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n("",28)])])}const E=s(l,[["render",t]]);export{k as __pageData,E as default};
1
+ import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n("",26)])])}const E=s(l,[["render",t]]);export{c as __pageData,E as default};