74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# Decisions
|
|
|
|
Architecture-level decisions taken during the v2 implementation, captured
|
|
once and referenced from feature docs / PR descriptions / ADR-style
|
|
follow-ups. Each entry lists the decision, the alternatives we considered,
|
|
and the rationale that tipped the call.
|
|
|
|
## FOCAS write-path opt-in
|
|
|
|
**Issue:** [#268](https://github.com/dohertj2/lmxopcua/issues/268). **Plan PR:** F4-a.
|
|
|
|
### Decision
|
|
|
|
The FOCAS driver ships writes behind two independent opt-ins, both default
|
|
off:
|
|
|
|
1. **Driver-level master switch** — `FocasDriverOptions.Writes.Enabled`,
|
|
default `false`. When off, every entry in a `WriteAsync` batch short-
|
|
circuits to `BadNotWritable` with status text `writes disabled at
|
|
driver level`. The wire client is never touched.
|
|
2. **Per-tag opt-in** — `FocasTagDefinition.Writable`, default `false`
|
|
(flipped from `true` in F4-a). A `Writable = false` tag returns
|
|
`BadNotWritable` even when the driver-level flag is on.
|
|
|
|
`BadNotSupported` is reserved for kinds the wire client hasn't yet
|
|
implemented; F4-b/c land actual macro / parameter / PMC writes that
|
|
currently dispatch to `BadNotSupported` (or to `Good` against the F4-a
|
|
fake) for unimplemented branches.
|
|
|
|
### Alternatives considered
|
|
|
|
- **Always-on writes (the pre-F4-a default).** Rejected: a single
|
|
misconfigured tag flipping `Writable = true` by accident would let an
|
|
operator overwrite a CNC parameter from any OPC UA client. The two-
|
|
opt-in posture means an accidental tag flip alone isn't enough.
|
|
- **Driver-level switch only.** Rejected: doesn't protect against an
|
|
operator with admin rights flipping the master switch to do bulk diag
|
|
reads but inheriting write capability for tags that were intended
|
|
read-only.
|
|
- **Per-tag opt-in only.** Rejected: doesn't give the deployment an "all
|
|
writes off" emergency lever — useful during a CNC commissioning where
|
|
writes are unsafe across the board for a period.
|
|
|
|
### Rationale
|
|
|
|
CNC writes are non-idempotent in the field's worst-case shape: feed
|
|
overrides, M-code pulses, alarm acks, recipe-step advances. Two opt-ins
|
|
is the cheapest defence-in-depth posture that still lets writes ship.
|
|
Both default off so a fresh deployment is read-only — the explicit choice
|
|
to enable writes lands at config time where it's reviewable, not at
|
|
runtime where it's invisible.
|
|
|
|
`WriteIdempotent` plumbs through `CapabilityInvoker.ExecuteWriteAsync`
|
|
into the Polly retry pipeline; default `false` means failed writes are
|
|
not auto-retried (plan decisions #44 / #45). Per-tag flip required for
|
|
genuinely-idempotent writes.
|
|
|
|
### CLI carve-out
|
|
|
|
`otopcua-focas-cli write` sets `Writes.Enabled = true` locally for the
|
|
lifetime of one process and synthesises a `Writable = true` tag. The CLI
|
|
is a per-operator direct-to-CNC tool — not a long-lived process bound to
|
|
the central config DB. Configuring the server still requires both opt-ins
|
|
to be set explicitly in the DriverInstance JSON. The bypass is documented
|
|
in `docs/Driver.FOCAS.Cli.md` so operators understand the asymmetry.
|
|
|
|
### Migration
|
|
|
|
Pre-F4-a deployments that relied on the `Writable = true` default need to
|
|
add `"Writable": true` to every tag they intend to write + an enclosing
|
|
`"Writes": { "Enabled": true }` block in their DriverInstance JSON.
|
|
Bootstrap rows seeded before F4-a get `Writable = false` after upgrade —
|
|
this is intentional; review-then-flip is the safer migration path.
|