73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# Runbook: natsClient_JS
|
|
|
|
## Connection Issues
|
|
|
|
### `getNats` fails to connect
|
|
|
|
**Symptom**: `connectionStatus` lands in `error`, `getNats` throws.
|
|
|
|
**Steps**:
|
|
1. Check the resolved URL precedence: `opts.servers` → `VITE_NATS_URL` → `config.nats_server_info.url` → `wss://natsws.yiem.cc` (`4-specification.md:SP-001`).
|
|
2. Verify broker reachability: `nc -z -w5 <nats-host> <nats-port>`.
|
|
3. Confirm `nats.ws` is available (browser/WSS transport, `NFR-101`).
|
|
4. Retry after fixing config; the consumer should call `getNats` again.
|
|
|
|
### Connection stuck after a disconnect
|
|
|
|
**Symptom**: Status stays `disconnected` and does not return to `connected`.
|
|
|
|
**Steps**:
|
|
1. Confirm `nc.status()` is wired to emit `disconnect`/`reconnect` (`2-solution_design.md:SD-004`).
|
|
2. Check `nc.closed()` for a permanent close (`4-specification.md:SP-001`).
|
|
3. Restart the consuming app to re-establish the shared socket.
|
|
|
|
**References**: `4-specification.md:SP-001` (connection), `3-walkthrough.md:#wt-007`.
|
|
|
|
## Message Issues
|
|
|
|
### Subscribe receives no messages
|
|
|
|
**Symptom**: No `onMessage` callbacks fire.
|
|
|
|
**Steps**:
|
|
1. Verify the subject string matches the broker's subject exactly.
|
|
2. Confirm the connection reached `connected` before subscribing.
|
|
3. Check the subscription is tracked in the `Map` (`4-specification.md:SP-002`).
|
|
|
|
### `sendMsghandlerRequest` throws
|
|
|
|
**Symptom**: `throw new Error(data)` or `No valid response found`.
|
|
|
|
**Steps**:
|
|
1. Confirm the backend returns a `jsontable`/`dictionary` payload, not `text` (`4-specification.md:SP-011`).
|
|
2. Verify `msghandlerCSR.smartpack`/`smartunpack` are in use (`2-solution_design.md:SD-006`).
|
|
3. Check the broker envelope format (`4-specification.md:SP-010`, `SP-011`).
|
|
|
|
### `reply` handler produces no response
|
|
|
|
**Symptom**: Requests to the subject time out.
|
|
|
|
**Steps**:
|
|
1. Confirm `handler` returns a value that gets published on `m.subject` (`4-specification.md:SP-005`).
|
|
2. Verify the subject is not also consumed by a `request` on the same endpoint.
|
|
|
|
## Error Code Reference
|
|
|
|
| Error | Symptom | Action | Reference |
|
|
|-------|---------|--------|-----------|
|
|
| `error` status | `getNats` failed | Fix URL/config, retry | `4-specification.md:SP-001` |
|
|
| `text` msghandler payload | `sendMsghandlerRequest` throws | Confirm backend returns dictionary/jsontable | `4-specification.md:SP-011` |
|
|
| decode error | subscription message dropped | Handled by per-message guard (NFR-302) | `4-specification.md:SP-002` |
|
|
|
|
## Escalation
|
|
|
|
- If the shared socket never reconnects (NFR-102), treat the broker as down and page the backend
|
|
team; the library only reports state via `connectionStatus`.
|
|
- Contact: backend/NATS on-call via the `nats_client_reconnect_rate` alert.
|
|
|
|
## Post-Incident
|
|
|
|
- [ ] Review logs for root cause (`[NATS] ...` lines).
|
|
- [ ] Update this runbook if a new failure mode appears.
|
|
- [ ] Link findings to `6-validation.md` so the case is covered by a test.
|