142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
# 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
|
|
```
|