Node backend migration guide changes only the DID backend, not the VDR drivers

Aperta Adatta ai principianti
  • Qualcosa non va?
#299 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

Modifica documentation/develop/cloud-agent/node-backend.md. Leggi i riferimenti fissati a application.conf e Modules.scala nella issue per ricostruire cosa seleziona NODE_BACKEND, quali flag VDR abilitano i driver e quali componenti utilizzano le impostazioni PRISM_NODE_*. Aggiorna la guida alla migrazione e la tabella di configurazione affinché corrispondano a questo cablaggio; il lavoro è concluso quando ogni criterio di accettazione è riportato accuratamente e può essere verificato consultando quei file.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

bug documentation ready-for-agent

User impact

The migration guide presents the node backend as the component that also anchors VDR entries, calls the two backends "interchangeable via a simple configuration change", and migrates by changing only NODE_BACKEND and NEOPRISM_BASE_URL. In the pinned code, NODE_BACKEND selects the DID service only; the VDR drivers are independent opt-in flags, all defaulting to false. An operator who follows the guide keeps VDR operations on the old PRISM Node VDR driver, fails after removing that node, or gets DriverNotFound for drid=neoprism because its driver flag was never enabled. The same table also claims PRISM_NODE_HOST, PRISM_NODE_PORT and PRISM_NODE_USE_PLAIN_TEXT are used only when NODE_BACKEND=prism-node, although an independently enabled PRISM Node VDR driver consumes them under any DID backend.

Affected documentation and ownership

  • Page: https://identus.io/documentation/develop/cloud-agent/node-backend/ — GET 200 after trailing-slash resolution, Last-Modified: Tue, 27 Oct 2026 12:51:14 GMT, observed 2026-10-29T10:22Z.
  • Documentation source: node-backend.md lines 9, 26, 40–50 and the migration guide lines 104–119, revision fa985dfa33caefa45bf1e9009e1f6f5a445344fb.
  • Editable owning source: the same Markdown file (ordinary committed source, not generated).
  • Intended component version: Identus Cloud Agent 2.2.1-SNAPSHOT. The docs revision pins its cloud-agent submodule at eee1ff7, which declares the same version and has a byte-identical application.conf; the compare contains only CI-workflow and client-generator lockfile changes. These unversioned pages document that main configuration.
  • Related but separate: the NEOPRISM_BASE_URL wording in this file (line 47) is the same misstatement as in the environment reference; it is reported separately so both files can be repaired consistently.

Observed versus expected

Documented claims:

line 9:  Both backends are interchangeable via a simple configuration change.
line 26: The Cloud Agent uses the node backend not only for DID lifecycle management but also for anchoring VDR entries ...
line 40: Switch between backends by changing the `NODE_BACKEND` variable.
lines 48-50: PRISM_NODE_HOST / PRISM_NODE_PORT / PRISM_NODE_USE_PLAIN_TEXT — "Only used when `NODE_BACKEND` is set to `prism-node`."
lines 108-119: Migration = deploy NeoPRISM, set NODE_BACKEND=neoprism and NEOPRISM_BASE_URL, restart.

Pinned code:

  • application.conf lines 1–11 binds didNode.backend to NODE_BACKEND and the PRISM Node connection fields to the PRISM_NODE_* variables.
  • application.conf lines 312–321 define five VDR driver flags, each defaulting to false, each bound to its own variable (VDR_MEMORY_DRIVER_ENABLED, VDR_DATABASE_DRIVER_ENABLED, VDR_PRISM_DRIVER_ENABLED, VDR_PRISM_NODE_DRIVER_ENABLED, VDR_NEOPRISM_DRIVER_ENABLED) — no NODE_BACKEND involvement.
  • Modules.scala line 237 selects the DID service by didNode.backend; lines 187–194 build the VDR drivers from the independent agent.vdr flags.
  • Modules.scala lines 263–277 build the PRISM Node gRPC channel from didNode.prismNode for the VDR driver regardless of the DID backend.

Expected: the page distinguishes DID backend selection from VDR driver opt-in, does not imply that one variable migrates both, and states accuracies about which code consumes the shared PRISM_NODE_* connection settings.

Evidence and reproduction

Static trace at the revision above, observed 2026-10-29:

grep -n "backend\|DriverEnabled\|NEOPRISM_BASE_URL\|PRISM_NODE_" \
  cloud-agent/service/server/src/main/resources/application.conf
sed -n '162,200p;230,280p' \
  cloud-agent/service/server/src/main/scala/org/hyperledger/identus/agent/server/Modules.scala

Limitations: static module wiring only. No agent was started and no DID or VDR operation was executed; no credentials, chain access or migration was performed. The defect is a claim-vs-wiring contradiction, not a runtime observation.

Existing work checked

GitHub issue/PR search across hyperledger-identus/docs and hyperledger-identus/cloud-agent, open and closed (2026-10-29):

  • NODE_BACKEND → 0 results in both repositories; migration NeoPRISM → 0 results in both.
  • node-backend.md → docs#247 (merged, added the page); no issue or PR covers the migration/VDR-selection gap.
  • VDR driver in docs → docs#230 (open milestone checklist), docs#247, docs#241, docs#228 (closed); none covers this contradiction.

Acceptance criteria

  • The page states what NODE_BACKEND selects and separately how each VDR driver is enabled, and the migration guide lists the VDR flags that must be changed to stop using the old node for VDR operations.
  • The PRISM_NODE_* rows state both consumers (DID node backend and PRISM Node VDR driver).
  • Verification: the corrected statements trace to the same revision's application.conf and Modules.scala; no live chain or credential is required.
Lingua principale
TypeScript
Stelle
15
Fork
8
Merge medio
3g 14h
PR unite (30g)
2

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di hyperledger-identus/docs

Tutte le issue di hyperledger-identus/docs

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.