update

2026-09-18 22:03:10 +07:00
parent b57403d373
commit 743928c63b
8 changed files with 725 additions and 43 deletions
@@ -0,0 +1,141 @@
+# Walkthrough: natsClient_JS
+
+One section per system participant. Here the single participant is the **consuming app** that
+imports `natsClient.js`. Each step traces the complete flow and cites the Solution Design decision
+(SD-XXX) and Requirement (FR/NFR) it implements.
+
+## Consuming App
+
+### Session Start — Connect
+
+**WT-001**: App calls `getNats()` / `connectNATS()` and the connection goes `connecting` →
+`connected`.
+
+> Cross-reference: `1-requirements.md:FR-001`, `2-solution_design.md:SD-001, SD-002, SD-004`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    App->>C: getNats({ servers })
+    C->>C: resolve URL (SD-002)
+    C->>Nats: connect (SD-001)
+    Nats-->>C: connected
+    C->>App: connectionStatus = { state: "connected" } (SD-004, SD-007)
+```
+
+**WT-002**: App subscribes to a subject and receives decoded messages.
+
+> Cross-reference: `1-requirements.md:FR-002`, `2-solution_design.md:SD-003`
+
+| Step | Action | System Response | Traceability |
+|------|--------|-----------------|--------------|
+| WT-002.1 | `subscribe('subj', onMessage)` | `nc.subscribe`, tracked in Map (SD-005) | FR-002 |
+| WT-002.2 | Broker sends a message | `StringCodec` decode, `JSON.parse` (SD-003) | FR-002 |
+| WT-002.3 | Payload is valid JSON | `onMessage(parsed)` called | FR-002 |
+| WT-002.4 | Payload is not JSON | `{ text }` fallback, `onMessage` called | FR-002 |
+
+**WT-003**: App publishes a message (object or string).
+
+> Cross-reference: `1-requirements.md:FR-003`, `2-solution_design.md:SD-001, SD-003`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    App->>C: publish('subj', {a:1})
+    C->>C: JSON.stringify (SD-003)
+    C->>C: nc.publish
+    C->>Nats: publish
+```
+
+**WT-004**: App issues a request and awaits the reply.
+
+> Cross-reference: `1-requirements.md:FR-004`, `2-solution_design.md:SD-003`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    App->>C: request('subj', payload, { timeout })
+    C->>Nats: request + encode
+    Nats-->>C: reply
+    C->>C: decode + JSON.parse
+    C-->>App: responseJson
+```
+
+**WT-005**: App registers a reply handler to serve requests.
+
+> Cross-reference: `1-requirements.md:FR-005`, `2-solution_design.md:SD-005`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    App->>C: reply('subj', handler)
+    C->>Nats: subscribe
+    Nats->>C: request
+    C->>C: handler(parsed, msg)
+    C->>Nats: publish(reply, responseMsg)
+```
+
+**WT-006**: App calls `sendMsghandlerRequest` to talk to the sommpanion db backend.
+
+> Cross-reference: `1-requirements.md:FR-006`, `2-solution_design.md:SD-006`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Msg as msghandler-csr.js
+    participant Nats as NATS broker
+
+    App->>C: sendMsghandlerRequest('subj', 'fn', args, config)
+    C->>Msg: smartpack([db_request, {functioncall,args}, dictionary])
+    C->>Nats: request(envelope)
+    Nats-->>C: reply envelope
+    C->>Msg: smartunpack
+    C-->>App: data (dictionary/jsontable) or throw on text
+```
+
+### Error Paths
+
+**WT-007**: Broker disconnects; status transitions then auto-reconnects.
+
+> Cross-reference: `1-requirements.md:FR-007`, `2-solution_design.md:SD-004`, `NFR-102`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    Nats->>C: disconnect event
+    C->>App: connectionStatus = disconnected (SD-004)
+    Nats->>C: reconnect event
+    C->>App: connectionStatus = connected (SD-004)
+```
+
+**WT-008**: App closes the connection.
+
+> Cross-reference: `1-requirements.md:FR-008`, `2-solution_design.md:SD-005`, `NFR-501`
+
+```mermaid
+sequenceDiagram
+    participant App as Consuming App
+    participant C as natsClient.js
+    participant Nats as NATS broker
+
+    App->>C: closeNats()
+    C->>C: unsubscribe all tracked subs (SD-005)
+    C->>Nats: close
+    C->>App: connectionStatus = disconnected
+```