From b4e4e4b8e07777a30accf2dcdbae5422f8d4b239 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 00:08:32 +0200 Subject: [PATCH 01/13] fix(e2e): run the authorize sweep even when the main sweep fails `e2e` chained the two sweeps with `&&`, so a failing `run-all` skipped the authorize group entirely -- the three TC_023 scenarios that prove `driver provision` seeded any CSMS-side state at all, and therefore the ones worth most precisely when something else has already gone red. Run both, and exit non-zero if either failed. Observed in practice: a sweep whose 44-scenario pass failed still reported TC_023, which is what surfaced a CSMS mapping defect that would otherwise have been invisible that run. --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index b2cebe3..ea02fe8 100644 --- a/package.json +++ b/package.json @@ -106,7 +106,7 @@ "typecheck": "tsc --noEmit", "build:types": "tsc -p tsconfig.build.json", "check:reference-driver": "CSMS_DRIVER=./drivers/steve/index.ts bun bin/ocpp-tck.ts check-driver", - "e2e": "bun bin/ocpp-tck.ts run-all --parallel --retry-failed-isolated && bun bin/ocpp-tck.ts run-all --group authorize", + "e2e": "bun bin/ocpp-tck.ts run-all --parallel --retry-failed-isolated; all=$?; bun bin/ocpp-tck.ts run-all --group authorize; auth=$?; exit $(( all || auth ))", "e2e:smoke": "bun bin/ocpp-tck.ts run cert16-tc023-1-authorize-invalid && bun bin/ocpp-tck.ts run cert16-tc023-2-authorize-expired && bun bin/ocpp-tck.ts run cert16-tc023-3-authorize-blocked && bun bin/ocpp-tck.ts run cert16-tc066-get-composite-schedule && bun bin/ocpp-tck.ts run cert16-tc003-charging-plugin-first", "check:fixture-tags": "bash tools/extract-fixture-tags.sh --diff", "test": "bash tests/vendor-integrity.sh && bash tests/generic-core.sh && bash tests/spec-invariants.sh" From 864a0e414eea406ea62c0ddd4ff95c85488e8d04 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 00:08:47 +0200 Subject: [PATCH 02/13] feat(citrineos): add a CSMS driver for CitrineOS CitrineOS (LF Energy / S44) is the second CSMS this harness drives, and the first one the 47 scenarios were not written against -- which is the point. An abstraction with a single implementation is CSMS-neutral by assertion; this turns that into a measurement. Operations go to the generated OCPP 1.6 message API (`POST /ocpp/1.6//`); observations come from Postgres through `docker exec`, because the REST data endpoints expose none of what the scenarios assert on -- every `@AsDataEndpoint` was read to establish that. records.ts records why the bundled Hasura sidecar was not used instead. Both CitrineOS lines are supported, selected by CITRINE_VARIANT and defaulting to v2. v1.9.1 names the OCPP connection column `stationId` where v2 names it `ocppConnectionName`, and routes no 1.6 local auth list. The variant is declared rather than detected, so the scope table stays readable with no server and no credentials; `driver verify` then compares the declaration against the running schema and refuses to go further on a mismatch. Measured against the pinned images, two runs each, second from `down -v`: v2.0.0-beta1 38 PASS, 7 NOT APPLICABLE, 2 FAIL (of 47) v1.9.1 18 PASS, 13 NOT APPLICABLE, 16 FAIL Every group passes unmodified on v2 -- core, remote trigger, smart charging, local auth list, firmware -- and no scenario needed editing to accommodate the new CSMS. The seven NOT APPLICABLE are one missing capability: CitrineOS routes no OCPP 1.6 reservation endpoint. The OCA test plan gates those cases on a declared "R-0 Support for Reservations: Yes/No", so reporting them out of scope is what the reference intends. The two failures are kept red on purpose -- tck/scope.ts forbids demoting a row to hide a finding -- and both are named, with the source fact that causes them, in the driver's gap table. On v1.9.1 fourteen of the sixteen failures share one cause, upstream citrineos/citrineos#160: no Connectors row can be created for an ad-hoc 1.6 station, so nothing needing a transaction starts. Fixed on the v2 line, which is why v2 is the default. Refs #2 --- VENDOR.md | 151 +++++++- drivers/citrineos/README.md | 320 +++++++++++++++++ drivers/citrineos/api-client.ts | 133 +++++++ drivers/citrineos/compose.v1.yaml | 29 ++ drivers/citrineos/compose.yaml | 142 ++++++++ drivers/citrineos/config.ts | 72 ++++ drivers/citrineos/index.ts | 177 ++++++++++ drivers/citrineos/profiles.ts | 97 +++++ drivers/citrineos/provision.ts | 447 ++++++++++++++++++++++++ drivers/citrineos/records.ts | 359 +++++++++++++++++++ drivers/citrineos/requests.ts | 330 +++++++++++++++++ drivers/citrineos/scope.ts | 244 +++++++++++++ drivers/citrineos/variant.ts | 129 +++++++ package.json | 6 + tsconfig.build.json | 2 +- types/drivers/citrineos/api-client.d.ts | 41 +++ types/drivers/citrineos/config.d.ts | 36 ++ types/drivers/citrineos/index.d.ts | 38 ++ types/drivers/citrineos/profiles.d.ts | 67 ++++ types/drivers/citrineos/provision.d.ts | 102 ++++++ types/drivers/citrineos/records.d.ts | 186 ++++++++++ types/drivers/citrineos/requests.d.ts | 45 +++ types/drivers/citrineos/scope.d.ts | 26 ++ types/drivers/citrineos/variant.d.ts | 62 ++++ 24 files changed, 3237 insertions(+), 4 deletions(-) create mode 100644 drivers/citrineos/README.md create mode 100644 drivers/citrineos/api-client.ts create mode 100644 drivers/citrineos/compose.v1.yaml create mode 100644 drivers/citrineos/compose.yaml create mode 100644 drivers/citrineos/config.ts create mode 100644 drivers/citrineos/index.ts create mode 100644 drivers/citrineos/profiles.ts create mode 100644 drivers/citrineos/provision.ts create mode 100644 drivers/citrineos/records.ts create mode 100644 drivers/citrineos/requests.ts create mode 100644 drivers/citrineos/scope.ts create mode 100644 drivers/citrineos/variant.ts create mode 100644 types/drivers/citrineos/api-client.d.ts create mode 100644 types/drivers/citrineos/config.d.ts create mode 100644 types/drivers/citrineos/index.d.ts create mode 100644 types/drivers/citrineos/profiles.d.ts create mode 100644 types/drivers/citrineos/provision.d.ts create mode 100644 types/drivers/citrineos/records.d.ts create mode 100644 types/drivers/citrineos/requests.d.ts create mode 100644 types/drivers/citrineos/scope.d.ts create mode 100644 types/drivers/citrineos/variant.d.ts diff --git a/VENDOR.md b/VENDOR.md index 8fd0a96..14f58c9 100644 --- a/VENDOR.md +++ b/VENDOR.md @@ -75,6 +75,15 @@ strongest available demonstration that the core names no CSMS. | `drivers/steve/ui-client.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/scope.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/provision.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/index.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/config.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/api-client.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/requests.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/profiles.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/records.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/scope.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/variant.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/citrineos/provision.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | Deliberately **not** imported from upstream: `steve-api.ts` (SteVe 3.13.0 REST client, 763 lines), `capability-probe.ts` (probes a live SteVe container), @@ -151,10 +160,10 @@ Verified on that digest: therefore passes `--entrypoint bun` and runs `src/cli/main.ts` from the image's own embedded sources. See `P0-FINDINGS.md` §9. -## Reference CSMS container images +## CSMS container images Not vendored code — the environment `drivers/steve/compose.yaml` brings up so -that the reference driver can be exercised. Pinned by digest for the same +that the SteVe driver can be exercised. Pinned by digest for the same reason as the simulator: these tags are republished in place, and a conformance run that cannot name the bytes it tested proves nothing. @@ -171,7 +180,7 @@ conformance run that cannot name the bytes it tested proves nothing. ### Validation history -Which SteVe releases the reference driver has actually been run against, and +Which SteVe releases the driver has actually been run against, and what happened. A row is added only for a **full** run — `run-all --parallel --retry-failed-isolated` plus the separate `--group authorize` sweep — never for a version that was merely booted. @@ -240,3 +249,139 @@ TC_052 passes on this digest. If TC_052 ever regresses, read that header first. [sc2069]: https://github.com/steve-community/steve/issues/2069 [sc2100]: https://github.com/steve-community/steve/issues/2100 + +### CitrineOS + +The second driver's environment, pinned on the same terms. Same two-column +shape as the table above, for the same structural reason: a six-column table +anywhere in this file is read as a vendored-file row. + +| field | value | +|---|---| +| image | `ghcr.io/citrineos/citrineos-server` | +| tag resolved | `v2.0.0-beta1` | +| digest | `sha256:58800f45acd82c976e2f55dd9aab85baee61507938bb2cb0d0f81fc70853c6ef` | +| image | `postgis/postgis` | +| tag resolved | `16-3.5` | +| digest | `sha256:4e07b425403ba55c20b541884db2e80c686dd6476bf9265046ac9c163895605d` | +| image | `rabbitmq` | +| tag resolved | `3-management` | +| digest | `sha256:e582c0bc7766f3342496d8485efb5a1df782b5ce3886ad017e2eaae442311f69` | +| resolved on | 2026-08-11, from the registry manifest `Docker-Content-Digest` | +| declared in | `drivers/citrineos/compose.yaml` | + +A **prerelease**, which is the one thing here that needs defending. The OCPP +1.6 `getLocalListVersion` and `sendLocalList` message endpoints exist only from +the v2 line, and six scenarios need them; `v2.0.0-beta1` currently resolves to +the same bytes as `:latest` and will not for long. Pinning by digest is what +makes depending on a moving tag safe — the alternative is `v1.9.1`, whose cost +is spelled out in `drivers/citrineos/README.md`. + +The statements the driver is built on, each read from citrineos-core at +`v2.0.0-beta1` and cross-checked at `v1.9.1` and `main`. Re-check them before +moving the pin — several are the difference between a driver and a fiction: + +- **No `@AsMessageEndpoint` binds `ReserveNow` or `CancelReservation` to + `OCPPVersion.OCPP1_6`.** Confirmed against the running container, whose + `/docs/json` advertises 18 `/ocpp/1.6/` paths with neither among them. Seven + scenarios are `NOT_APPLICABLE` because of this one fact. +- `AuthorizeRequestOcpp16Handler` reaches its status mapper **only** through + the `status === 'Accepted'` branch, and consults `cacheExpiryDateTime` inside + it. So `CERT023-EXP` is provisioned `Accepted`-with-a-past-expiry, and a + stored `Blocked` answers `Invalid`. +- The container registers `authorizers: asValue([])` with no setting that + changes it, which is what makes `Blocked` unreachable. +- More than one `Authorizations` row for an idToken makes that handler answer + `Invalid` outright — the invariant `provision` upserts for and `verify` + counts. +- **Four foreign keys reference `Authorizations`** and none cascades: + `Transactions.authorizationId`, `LocalListAuthorizations.authorizationId`, + `LocalListAuthorizations.groupAuthorizationId`, and the self-reference + `Authorizations.groupAuthorizationId`. `teardown` derives its guards from + `pg_constraint` rather than listing them, so a fifth does not silently break + it. +- `createTransactionByStartTransaction` requires a `Connectors` row matching + the OCPP connectorId and **throws** without one; + `processOcpp16StatusNotification` auto-commissions it for ad-hoc 1.6 stations. +- `LocalAuthListService` refuses a `listVersion` not strictly greater than the + station's stored one, before anything reaches the wire — hence the local-list + reset in `prepareStation`. +- The shipped `docker` app-env selects `LocalBypassAuthProvider`, so the + message API takes no credentials at all. +- **No 1.6 request handler for `FirmwareStatusNotification`**: every one is + answered with a `NotSupported` CALLERROR, which is the only CALLERROR the + CSMS emits anywhere in the suite. OCA `TC_044_{1,2,3}_CSMS` require a + `FirmwareStatusNotification.conf` instead, so this is a non-conformance — + and one the scenarios do not detect, because they assert only on what the + charge point sent. Recorded in `drivers/citrineos/README.md`. + +#### Validation history + +Same rule as SteVe's table above: a row is added only for a full run, and the +table stays at five columns so the structural file-inventory selector does not +pick it up. Two runs are recorded rather than one, the second from `down -v` — +the claim being checked is that the verdict SET is reproducible, and a single +run cannot distinguish a stable result from a lucky one. + +Numbers are the **parallel pass**, before `--retry-failed-isolated`, because +that is what the sweep prints; the retry column says which of those failures +were lane artifacts. + +| CitrineOS | digest | validated | `all` (44), parallel pass | `authorize` (3) | +|---|---|---|---|---| +| `v2.0.0-beta1` — **current pin**, `CITRINE_VARIANT=v2` | `sha256:58800f45…` | 2026-08-11 | 34 PASS, 7 N/A, 3 FAIL — two lane flakes PASS on isolated retry, `tc044-2` confirmed | 2 PASS, 1 FAIL (`tc023-3`) | +| `v1.9.1` — `CITRINE_VARIANT=v1` | `sha256:4f879151…` | 2026-08-11 | 16 PASS, 13 N/A, 15 FAIL — **all 15 confirmed on isolated retry, no flakes** | 2 PASS, 1 FAIL (`tc023-3`) | + +One row, two runs: the second was taken from `down -v` and **agreed exactly in +shape** — 34/7/3 in the parallel pass, two of the three failures reclassified as +lane artifacts by the isolated retry, the same confirmed failure. Only the +identity of the lane flakes differed (`tc056`+`tc044-1`, then `tc013`+`tc044-1`), +which is the same pattern the SteVe table shows across its two versions and the +reason `--retry-failed-isolated` is not optional in CI. Counting the isolated +retry as the verdict, that is **38 PASS, 7 NOT APPLICABLE, 2 FAIL across all +47**. + +**The `v1.9.1` row is a report, not a recommendation.** 18 PASS, 13 NOT +APPLICABLE and 16 FAIL across all 47 — against 38 / 7 / 2 on v2 — and the gap +is one upstream defect, not a driver limitation. + +Fourteen of the fifteen `all`-group failures carry an identical wire signature: +`{"idTagInfo":{"status":"Invalid"},"transactionId":0}` in answer to every +`StartTransaction`, with `Connectors: 0` and `Transactions: 0` in the database +after the whole sweep. That is **citrineos/citrineos#160** — the Connector model +requires non-null `evseId` / `evseTypeConnectorId`, so a 1.6 `StatusNotification` +from an ad-hoc station cannot create a connector row, and nothing that needs a +transaction can start. The issue was closed 2026-05-19, *after* v1.9.1 shipped +on 2026-04-29; the fix is in the v2 line only. Nothing was reported upstream for +this: it is already fixed where it matters. + +The fifteenth, `tc045-1`, fails on an incomplete `DiagnosticsStatusNotification` +train and is **not** attributed to #160 — same shape as `tc044-2` on v2, and +unexplained on both. + +The thirteen NOT APPLICABLE are the seven reservation scenarios plus the six +local-auth-list ones, whose 1.6 endpoints v1.9.1 does not route (16 advertised +`/ocpp/1.6/` paths against v2's 18). + +`tc023-3` fails identically on both lines, which is the useful control: it is a +property of the `Authorize` handler, not of either release. + +**So the pin stays on v2**, and v1 support exists to make that statement +measured rather than asserted. + +`tc044-1` flaked in the parallel pass of *both* runs, and `tc044-2` failed its +isolated retry in both while passing a third standalone run. Neither is +surprising: they are the two thinnest timing margins in the suite (a +90 s +`retrieveDate` against a 115 s and a 110 s hold respectively), so the firmware +status train has 25 s and 20 s to complete. + +The two failures are findings, not driver defects, and both are argued in +`drivers/citrineos/scope.ts` and `drivers/citrineos/README.md`. `tc023-3` is the +one worth reporting upstream: CitrineOS answers +`{"idTagInfo":{"status":"Invalid"}}` where OCPP 1.6 requires `Blocked`. +Reproduced 3 runs out of 3. + +Worth recording because it is the claim the second driver exists to test: +**every other group passed unmodified** — core, remote-trigger, smart charging, +local auth list and firmware — against a CSMS that had no part in writing the +scenarios, and no scenario needed editing to accommodate it. diff --git a/drivers/citrineos/README.md b/drivers/citrineos/README.md new file mode 100644 index 0000000..76b9e69 --- /dev/null +++ b/drivers/citrineos/README.md @@ -0,0 +1,320 @@ +# The CitrineOS driver + +[CitrineOS](https://github.com/citrineos/citrineos-core) (LF Energy / S44) is +the second CSMS this harness drives, and the first one the 47 scenarios were +**not** written against. That is the point of it: an abstraction with a single +implementation is CSMS-neutral by assertion, and this driver is how the +assertion gets tested. + +It reports the answer rather than flattering it. + +**Measured 2026-08-11 against the pinned image: 38 `PASS`, 7 `NOT APPLICABLE`, +2 `FAIL` out of 47.** + +The seven `NOT APPLICABLE` are one missing capability — CitrineOS routes no +OCPP 1.6 reservation endpoints. Of the two failures, one is a deterministic +finding against CitrineOS (TC_023.3, `Blocked` answered as `Invalid`, 3 runs of +3) and one is a flake with a 20-second timing margin (TC_044.2, 1 pass in 3). +Neither is demoted in the scope table: `tck/scope.ts` forbids demoting a row to +`NOT_APPLICABLE` to make a red scenario go away, and a TCK whose second driver +reports 100% green is a TCK that has stopped measuring. Both are below. + +The interesting result is the other 38. The core, remote-trigger, smart-charging, +local-auth-list and firmware groups all pass unmodified against a CSMS that had +no part in writing them — which is the strongest evidence available that the +scenarios test OCPP rather than SteVe. + +## Quick start + +```sh +docker compose -f drivers/citrineos/compose.yaml up -d --wait + +export CSMS_DRIVER=./drivers/citrineos/index.ts +export OCPP_CP_IDS=CERTCP1,CERTCP2,CERTCP3 + +bun bin/ocpp-tck.ts check-driver # offline: no CSMS, no docker +bun bin/ocpp-tck.ts driver provision # seed the idTags TC_023 needs +bun bin/ocpp-tck.ts driver verify # read-only: are they there? + +bun run e2e # both sweeps: 44 + the authorize 3 + +docker compose -f drivers/citrineos/compose.yaml down -v +``` + +`bun run e2e` and not `run-all`, for the reason the root README gives: a full +sweep is **two** invocations, because `all` is 44 scenarios and the `authorize` +group sits outside it to mirror upstream group membership byte-for-byte. Anyone +running `run-all` by hand gets 44/47 and reads "no failures", missing exactly +the three scenarios that prove `driver provision` seeded anything — which for +this driver includes the one deterministic failure. `bun run e2e:smoke` is the +short loop while iterating. + +`CITRINE_API_URL` defaults to `localhost` because the driver runs on your host, +while the simulator container reaches the same CitrineOS as `ws://citrine:8081/` +from inside the compose network. That asymmetry is why the two are separate +settings — the same one SteVe's driver has, for the same reason. + +**No credentials anywhere.** CitrineOS's shipped `docker` app-env selects +`LocalBypassAuthProvider`, which accepts every HTTP request and synthesises an +admin principal; it logs a warning saying so on startup. That is a property of +this development environment, not of CitrineOS in production, and swapping in +the OIDC provider would be a change to [`api-client.ts`](api-client.ts) rather +than a setting. + +## The pinned version + +[`compose.yaml`](compose.yaml) pins **`v2.0.0-beta1`** by digest: + +``` +ghcr.io/citrineos/citrineos-server:v2.0.0-beta1@sha256:58800f45acd82c976e2f55dd9aab85baee61507938bb2cb0d0f81fc70853c6ef +``` + +A prerelease rather than the `v1.9.1` stable, and deliberately: the OCPP 1.6 +`getLocalListVersion` and `sendLocalList` message endpoints exist only from the +v2 line, and six scenarios need them. Pinning by digest is what makes a +prerelease safe to depend on — `:latest` currently resolves to the same bytes, +and will not for long. + +Re-resolve a digest with: + +```sh +T=$(curl -sS "https://ghcr.io/token?scope=repository:citrineos/citrineos-server:pull&service=ghcr.io" \ + | sed -n 's/.*"token":"\([^"]*\)".*/\1/p') +curl -sSI -H "Authorization: Bearer $T" \ + -H "Accept: application/vnd.oci.image.index.v1+json" \ + https://ghcr.io/v2/citrineos/citrineos-server/manifests/v2.0.0-beta1 \ + | grep -i docker-content-digest +``` + +### The v1.9.1 variant + +Both CitrineOS lines are supported. **v2 is the default**; v1.9.1 is one +override file and one environment variable: + +```sh +docker compose -f drivers/citrineos/compose.yaml \ + -f drivers/citrineos/compose.v1.yaml up -d --wait +export CITRINE_VARIANT=v1 +bun bin/ocpp-tck.ts driver provision && bun run e2e +``` + +``` +ghcr.io/citrineos/citrineos-server:v1.9.1@sha256:4f8791510686af47d5a5cbb55bf69eea7435734836e858d8cc983c0a4edaa884 +``` + +Two differences, both read off the running images rather than inferred: + +1. **16 `/ocpp/1.6/` routes instead of 18** — no `evdriver/sendLocalList`, no + `evdriver/getLocalListVersion`. Six local-auth-list scenarios become + `NOT APPLICABLE`, so v1 reports **34 `DRIVABLE` / 13 `NOT_APPLICABLE`** + where v2 reports 40 / 7. +2. **The OCPP connection column is `stationId`**, where v2 names it + `ocppConnectionName` — on `Transactions`, `LocalListVersions` and + `SendLocalLists`. `Authorizations` is untouched, which is why `provision` + was already version-agnostic; only the record reads needed it. + +**Measured, 2026-08-11: 18 `PASS`, 13 `NOT APPLICABLE`, 16 `FAIL` out of 47**, +against 38 / 7 / 2 on v2 — and the gap is one upstream defect rather than a +driver limitation. Fourteen of the fifteen `all`-group failures answer every +`StartTransaction` with `{"idTagInfo":{"status":"Invalid"},"transactionId":0}`, +and the database holds `Connectors: 0` after the whole sweep: that is +[citrineos/citrineos#160][i160], closed 2026-05-19 — *after* v1.9.1 shipped on +2026-04-29 — and fixed on the v2 line only. All fifteen were confirmed on the +isolated retry; there were no flakes. Nothing was reported upstream, because it +is already fixed where it matters. + +`tc023-3` fails identically on both lines, which is the useful control: it is a +property of the `Authorize` handler, not of either release. + +**Use v2.** v1 support exists so that recommendation is measured rather than +asserted. + +[i160]: https://github.com/citrineos/citrineos/issues/160 + +`CITRINE_VARIANT` is **declared, not detected**, because the scope table and +the capability set must be readable with no server and no credentials — that is +what makes `check-driver` and the pre-flight offline. [`variant.ts`](variant.ts) +carries the reasoning; `driver verify` then compares the declaration against +the running schema and refuses to go further on a mismatch: + +``` +schema mismatch: CITRINE_VARIANT=v1 expects Transactions."stationId", +but the server has ocppConnectionName. Set CITRINE_VARIANT=v2 for this server. +``` + +The trap that makes detection tempting and wrong: `stationId` exists on +`Transactions` in **both** lines — `character varying` holding the OCPP name on +v1.9.1, an `integer` foreign key on v2. Its presence proves nothing; +`ocppConnectionName`'s presence is the discriminator. + +## Environment + +Every default resolves to a name in `compose.yaml`; a stock stack needs none of +them. + +| Variable | Default | Meaning | +|---|---|---| +| `CITRINE_VARIANT` | `v2` | Which CitrineOS line the target runs. `v1` for the v1.9.1 stable. Checked against the running schema by `driver verify`. | +| `CITRINE_API_URL` | `http://localhost:8080` | Message-API base. | +| `CITRINE_WS_URL` | `ws://citrine:8081/` | OCPP endpoint; the charge point id is appended as the last path segment. | +| `CITRINE_TENANT_ID` | `1` | Carried by every API call and every query. | +| `CITRINE_DB_CONTAINER` | `citrine-db` | Postgres container reached by `docker exec`. | +| `CITRINE_DB_USER` | `citrine` | | +| `CITRINE_DB_PASS` | `citrine` | Passed as `-e PGPASSWORD` with no value, so it never reaches docker's argv. | +| `CITRINE_DB_NAME` | `citrine` | | +| `CITRINE_NETWORK` | `citrineos_citrineos-internal` | Docker network the simulator joins. | + +An explicit `SIM_*` value still beats all of these — an operator's override is +the last word. + +## How the contract maps + +Operations go to the message API, which generates its routes from the OCPP +schemas: `POST /ocpp/1.6//?identifier=&tenantId=1`, and +the request body *is* the OCPP payload. The module prefix is not derivable from +the action, which is the only reason a table is needed: + +| Contract operation | Endpoint | +|---|---| +| `Reset` | `configuration/reset` | +| `ChangeAvailability` | `configuration/changeAvailability` | +| `GetConfiguration` | `configuration/getConfiguration` | +| `ChangeConfiguration` | `configuration/changeConfiguration` | +| `TriggerMessage` | `configuration/triggerMessage` | +| `UpdateFirmware` | `configuration/updateFirmware` | +| `UnlockConnector` | `evdriver/unlockConnector` | +| `ClearCache` | `evdriver/clearCache` | +| `RemoteStartTransaction` | `evdriver/remoteStartTransaction` | +| `RemoteStopTransaction` | `evdriver/remoteStopTransaction` | +| `GetLocalListVersion` | `evdriver/getLocalListVersion` | +| `SendLocalList` | `evdriver/sendLocalList` | +| `GetDiagnostics` | `reporting/getDiagnostics` | +| `SetChargingProfile` | `smartcharging/setChargingProfile` | +| `GetCompositeSchedule` | `smartcharging/getCompositeSchedule` | +| `ClearChargingProfile` | `smartcharging/clearChargingProfile` | +| `ReserveNow`, `CancelReservation` | **none** — see the gaps below | + +Observations come from Postgres through `docker exec`, because CitrineOS's REST +data endpoints expose none of what the scenarios assert on. Every +`@AsDataEndpoint` in the repository was read to establish that. + +The bundled Hasura sidecar was the alternative, and [`records.ts`](records.ts) +carries the full argument. The short version: it would **not** decouple the +driver from the schema — Hasura derives field names from column names, so the +v1.9.1 → v2 column rename would have broken the same queries the same way — and +it is part of CitrineOS's *dev compose* rather than its product. What it would +genuinely buy is remote testability, and that is the trigger to revisit it. +Measured cost of the current transport: **~350 ms per query**, almost all of it +`docker exec` spawn; the cheap fix there is a persistent psql session, not a +different API. + +**Consequence: this driver must run on the host that owns the containers.** The +operation half would work against a remote CitrineOS; the record half would +not. + +One thing this driver does *better* than the SteVe one: `SendLocalList` is +lossless here. SteVe's manager UI carries tag names only, so per-entry `status`, +`expiryDate` and `parentIdTag` are silently dropped; CitrineOS's JSON endpoint +carries all three to the wire. + +## Gaps + +Each row names the source fact that causes it, per the rule in `tck/scope.ts`: +a `reason` that cannot name the limitation is `CONDITIONAL`, not +`NOT_APPLICABLE`. + +| Gap | Effect | Source | +|---|---|---| +| **No OCPP 1.6 reservation endpoints.** No `@AsMessageEndpoint` binds `ReserveNow` or `CancelReservation` to `OCPPVersion.OCPP1_6`. The 1.6 schemas exist, the `Reservations` table exists, `evdriver.responses` lists both actions — nothing routes them, and no 1.6 response handler exists either. | 7 scenarios `NOT APPLICABLE`; the driver omits `records.reservations` entirely. | Verified at `v1.9.1`, `v2.0.0-beta1` and `main`. | +| **Local auth list is v2-only.** `EVDriverOcpp16Api` gained `sendLocalList` / `getLocalListVersion` in the v2 line. | 6 scenarios, drivable only on the pinned prerelease. | `packages/core/src/modules/EVDriver/src/module/1.6/MessageApi.ts` | +| **No charging-profile registry.** `ChargingProfiles` has no `description` or `name` column, and nothing to look one up by. | `refByDescription` resolves from this driver's own catalogue instead. Not a scenario cost: OCPP 1.6 carries the profile inline. | `packages/core/src/dal/layers/drizzle/schema/ChargingProfile.ts`, and [`profiles.ts`](profiles.ts) | +| **`Blocked` is unreachable from the 1.6 `Authorize` path.** The handler reaches its status mapper only through the `status === Accepted` branch, so a stored `Blocked` falls through to the default `Invalid`. The only route to a real `Blocked` is an `IAuthorizer`, and the container registers `authorizers: asValue([])` with no setting that changes it. | TC_023.3 — see `scope.ts` for its current status. | `AuthorizeRequestOcpp16Handler.ts`, `apps/ocpp-server/src/container.ts` | +| **No REST for `Authorizations`.** `EVDriverDataApi` exposes exactly one route, a read-only local-list-version GET. | `driver provision` writes fixtures with SQL. | [`provision.ts`](provision.ts) | +| **Four foreign keys reference `Authorizations`, none cascading**: `Transactions.authorizationId`, `LocalListAuthorizations.authorizationId`, `LocalListAuthorizations.groupAuthorizationId`, and the self-reference `Authorizations.groupAuthorizationId`. | `teardown` derives its `NOT EXISTS` guards from `pg_constraint` instead of listing them, so a fifth on a future CitrineOS is picked up rather than aborting the whole delete. Guarding only the first was measured to leave *every* fixture in place, because psql runs the script in one implicit transaction. | Read from the live catalog; see `guards()` in [`provision.ts`](provision.ts). | +| **`Blocked` is unreachable from the 1.6 `Authorize` path** *(see the row above for the mechanism)*. | **TC_023.3 fails**, deterministically: CitrineOS answers `{"idTagInfo":{"status":"Invalid"}}` where the scenario requires `Blocked`. Observed 3 runs out of 3. | Kept red on purpose — see `scope.ts`. | +| **No 1.6 request handler for `FirmwareStatusNotification`.** Every one the charge point sends is answered with `[4,…,"NotSupported","No handler found for action: FirmwareStatusNotification at module configuration"]` — 9 across the three TC_044 logs, and the only CALLERROR the CSMS emits anywhere in the suite. | **A non-conformance, and one this suite does not detect.** OCA `TC_044_{1,2,3}_CSMS` put steps 4 and 6 on the Central System — *"The Central responds with a FirmwareStatusNotification.conf"* — and a CALLERROR is not that conf. Our scenarios pass because they assert only on the statuses the charge point *sent*. See below. | `packages/core/src/handlers/requests/1.6/` — `DiagnosticsStatusNotification` has one, `FirmwareStatusNotification` does not. No ticket upstream. | +| **No 1.6 response handler for `UnlockConnector` or `UpdateFirmware`.** The Calls are routed and sent; the CallResults are answered with the same `NotSupported` CALLERROR. | Harmless — the six affected scenarios all pass. | `packages/core/src/handlers/responses/1.6/` | +| **`GetConfiguration` is batched server-side.** The endpoint splits a request into batches of the station's stored `GetConfigurationMaxKeys`. | *Not* a problem in practice: an unprovisioned station has no such value, so the request stays one `GetConfiguration` on the wire and both TC_019 scenarios pass. Listed because provisioning that key would change it. | `Configuration/src/module/1.6/MessageApi.ts` | +| **`SendLocalList` requires a strictly increasing `listVersion`,** and refuses otherwise *before* anything reaches the wire. Four scenarios send version 1. | `prepareStation` clears the station's stored list version each run, so a refusal cannot masquerade as a charge point ignoring the request. | `LocalAuthListService.ts`, and [`records.ts`](records.ts) | + +### Checked against the OCA reference + +The findings above were re-read against the Open Charge Alliance's OCPP 1.6 +certification material ([certification page][octt]): the *Test Procedure & Test +Plans* (v2.4.1) and the *OCPP Compliancy Testing Tool — Test Case Document*. +The CSMS is the system under test here, so the **`_CSMS`** variant of each test +case is the one that applies. + +[octt]: https://openchargealliance.org/certificationocpp/certification-ocpp-1-6/ + +Three things that changed as a result: + +1. **TC_023.3 is confirmed, and it is mandatory.** `TC_023_3_CSMS` states the + prerequisite as *"The Central System has an idTag in memory with status + 'Blocked'"* — exactly what `provision` writes — and its tool validation as + *"(Message: Authorize.conf) idTagInfo.status is Blocked"*. The test plan + marks TC_023_1/2/3 **M** for the Central System. So this is a failure + against a mandatory case, not a driver setup artifact. + +2. **The seven `NOT_APPLICABLE` reservation rows match the reference's own + gating.** The test plan carries `R-0 — Support for Reservations — Yes / No` + as a declared capability and heads the block *"Optional feature: Reservation + of a Connector"*, with the cases marked *C — "Only applicable if + Reservations are supported"*. Reporting them not-applicable for a CSMS that + routes no 1.6 reservation endpoint is what the reference intends, not a + convenience. + +3. **The firmware rows are green for a reason the reference does not accept.** + `TC_044_{1,2,3}_CSMS` require the Central System to answer each + `FirmwareStatusNotification.req` with a `.conf`; CitrineOS answers a + `NotSupported` CALLERROR. Our scenarios assert only on the statuses the + charge point sent, so they do not see it. **That is a gap in the scenarios, + and closing it would change what they measure** — `ASSERT-INVENTORY.txt` + would move — so it is recorded here rather than fixed in passing. + +**Upstream tickets.** `citrineos-core` has GitHub issues disabled; the tracker +is the umbrella repo [`citrineos/citrineos`][tracker]. +[#169][i169] *"Complete OCPP 1.6J Support — Reservations, LocalList, +SmartCharging, Diagnostics"* is the ticket for the reservation gap. It is +**closed**, answered with *"the intention is to fully implement OCPP 1.6J, but +… it is lower in priority"* — and the rest of its list (local list, smart +charging, diagnostics, clear cache) did ship, while reservations did not: they +are still unrouted at `v2.0.0-beta1`. There is **no** ticket for the `Blocked` +mapping or for the missing `FirmwareStatusNotification` handler. + +[tracker]: https://github.com/citrineos/citrineos/issues +[i169]: https://github.com/citrineos/citrineos/issues/169 + +### Flakes, and what they are not + +The two TC_044 scenarios with a `retrieveDate` of +90 s are the thinnest timing +margins in the suite: the charge point waits for that instant before it starts, +leaving 25 s (TC_044.1, 115 s hold) and 20 s (TC_044.2, 110 s hold) for the +whole firmware status train. + +- **`cert16-tc044-1-firmware-update`** flaked in the parallel pass of both + recorded runs and passed the isolated retry both times. Ordinary lane + contention; `--retry-failed-isolated` is exactly the mechanism for it. +- **`cert16-tc044-2-firmware-download-failed`** passed 1 run in 3, including + failing its isolated retry twice. On the failures the socket dropped + (`code=1006`) shortly after CitrineOS's `NotSupported` CALLERROR, costing a + reconnect and a `BootNotification` that lose the charge point's firmware + state. + +**Which side closes that socket is not established.** The obvious suspicion is +the CALLERROR, and it is wrong: TC_044.1 and TC_044.3 take four of them each +and never disconnect. It is recorded as an open question rather than as a +CitrineOS defect, because the evidence does not support the second reading. + +### Smaller traps, handled + +Neither is listed as a gap, because they cost nothing once known: + +- **More than one `Authorizations` row for an idToken makes the handler answer + `Invalid` outright.** The unique index is on `(idToken, idTokenType, + tenantId)` and Postgres treats NULLs as distinct, so `ON CONFLICT` would not + protect the invariant that matters. `provision` upserts on `(idToken, + tenantId)` and `verify` counts rows per tag. +- **A tag stored as `status = 'Expired'` answers `Invalid`, not `Expired`.** + The expiry is consulted only inside the `Accepted` branch, so `CERT023-EXP` + is provisioned as `Accepted` with a past `cacheExpiryDateTime`. diff --git a/drivers/citrineos/api-client.ts b/drivers/citrineos/api-client.ts new file mode 100644 index 0000000..c3cb795 --- /dev/null +++ b/drivers/citrineos/api-client.ts @@ -0,0 +1,133 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * api-client.ts -- CitrineOS's message API, which is a plain JSON POST. + * + * No authentication is sent, and that is not an omission. CitrineOS's shipped + * `docker` app-env selects `LocalBypassAuthProvider` + * (apps/ocpp-server/src/config/envs/docker.ts, util.authProvider.localByPass), + * whose ApiAuthPlugin hook returns success for every request and synthesises an + * admin principal -- it even logs a warning to that effect on startup. Adding a + * header here would be theatre. A deployment that swapped in the OIDC provider + * would need a real token, and that is a change to this file, not a setting. + * + * WHERE THE THROW LINE IS + * ----------------------- + * The contract forbids throwing for an OCPP-level outcome: a `Rejected` + * CALLRESULT, a CALLERROR, or silence are all normal returns, because every + * scenario asserts on the simulator's captured wire log rather than on this + * call. That is not the same as never throwing. + * + * CitrineOS answers HTTP 200 with `[{"success": false, "payload": "..."}]` for + * several failures where NOTHING REACHED THE WIRE -- an unknown station id, a + * `connectorId <= 0` on TriggerMessage, a schema rejection inside + * sendLocalList's persistence step. Those are request failures wearing a 200, + * and swallowing them would report a scenario as having driven an operation it + * never drove. So `success: false` throws, and the payload travels with it. + */ +import type { CitrineConfig } from "./config"; +import type { CitrineRequest } from "./requests"; + +const DEFAULT_TIMEOUT_MS = 15_000; + +/** CitrineOS's IMessageConfirmation, as it comes back on the wire. */ +interface MessageConfirmation { + success?: boolean; + payload?: unknown; +} + +function describe(value: unknown): string { + return typeof value === "string" ? value : JSON.stringify(value); +} + +export class CitrineMessageApi { + constructor(private readonly cfg: CitrineConfig) {} + + private url(req: CitrineRequest, cpId: string): string { + const query = new URLSearchParams({ + identifier: cpId, + tenantId: String(this.cfg.tenantId), + }); + return `${this.cfg.apiUrl}/ocpp/1.6/${req.module}/${req.action}?${query}`; + } + + /** + * Dispatches one operation and returns a receipt for the run log. + * + * The receipt is the confirmation array, serialised. Specs must not branch on + * it -- it exists so that a human reading results/ can tell a dispatched + * operation from one the CSMS quietly reshaped, which for GetConfiguration it + * genuinely does (see the batching note below). + */ + async send(cpId: string, req: CitrineRequest): Promise { + const url = this.url(req, cpId); + let res: Response; + try { + res = await fetch(url, { + method: "POST", + headers: { "content-type": "application/json" }, + // JSON.stringify preserves insertion order, which requests.ts relies + // on for SendLocalList -- see the key-order note there. + body: JSON.stringify(req.body), + signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS), + }); + } catch (err) { + throw new Error( + `citrineos: POST ${url} failed: ${err instanceof Error ? err.message : String(err)}`, + ); + } + + const text = await res.text(); + if (!res.ok) { + // A 404 here is worth calling out by name, because it is what an + // unrouted action looks like: CitrineOS skips route registration + // entirely when no schema exists for the version, so an operation it + // does not support for 1.6 is indistinguishable from a typo in the path + // unless the message says so. + const hint = + res.status === 404 + ? " -- no OCPP 1.6 route is registered for this action on this CitrineOS version" + : ""; + throw new Error( + `citrineos: POST ${url} returned ${res.status}${hint}: ${text.slice(0, 300)}`, + ); + } + + let parsed: unknown; + try { + parsed = JSON.parse(text); + } catch { + throw new Error( + `citrineos: POST ${url} returned unparseable body: ${text.slice(0, 300)}`, + ); + } + + // One confirmation per identifier -- except GetConfiguration, which + // CitrineOS splits into batches of GetConfigurationMaxKeys and confirms + // once per batch. So "exactly one" is not a property to assert on. + // + // `null` and a bare scalar are both valid JSON and neither is a + // confirmation. Wrapping them without checking made the success test below + // read `.success` off them, so a null body crashed with a TypeError naming + // no URL instead of reporting the response it could not understand. + const confirmations: unknown[] = Array.isArray(parsed) ? parsed : [parsed]; + const isConfirmation = (c: unknown): c is MessageConfirmation => + typeof c === "object" && c !== null; + + if (!confirmations.every(isConfirmation)) { + throw new Error( + `citrineos: POST ${url} returned a body that is not a confirmation array: ${text.slice(0, 300)}`, + ); + } + + const refused = confirmations.filter((c) => c.success !== true); + if (refused.length > 0) { + throw new Error( + `citrineos: ${req.module}/${req.action} for ${cpId} was not dispatched: ` + + refused.map((c) => describe(c.payload)).join("; "), + ); + } + + return text.slice(0, 500); + } +} diff --git a/drivers/citrineos/compose.v1.yaml b/drivers/citrineos/compose.v1.yaml new file mode 100644 index 0000000..e4f3656 --- /dev/null +++ b/drivers/citrineos/compose.v1.yaml @@ -0,0 +1,29 @@ +# Copyright 2026 Julien Herr +# SPDX-License-Identifier: Apache-2.0 +# +# The v1.9.1 variant, as a compose OVERRIDE rather than a second full file: +# +# docker compose -f drivers/citrineos/compose.yaml \ +# -f drivers/citrineos/compose.v1.yaml up -d --wait +# CITRINE_VARIANT=v1 bun bin/ocpp-tck.ts driver provision +# +# An override, so the infrastructure services, the network name, the container +# names and the published port are defined once. Only the bytes under test +# change -- which is the whole point of pinning them. +# +# CITRINE_VARIANT=v1 is NOT optional with this file. The driver declares the +# variant rather than detecting it (drivers/citrineos/variant.ts explains why), +# and v1.9.1 names the OCPP connection column `stationId` where v2 names it +# `ocppConnectionName`. Forgetting it is caught immediately and by name: +# `ocpp-tck driver verify` compares the declaration against the running +# schema before it looks at a single fixture. +# +# What v1.9.1 costs, measured on this image rather than inferred: it advertises +# 16 `/ocpp/1.6/` paths where v2.0.0-beta1 advertises 18. The two missing are +# `evdriver/sendLocalList` and `evdriver/getLocalListVersion`, so six +# local-auth-list scenarios report NOT APPLICABLE. VENDOR.md carries the run. +# +# Re-pin exactly as compose.yaml documents, substituting the v1.9.1 tag. +services: + citrine: + image: ghcr.io/citrineos/citrineos-server:v1.9.1@sha256:4f8791510686af47d5a5cbb55bf69eea7435734836e858d8cc983c0a4edaa884 diff --git a/drivers/citrineos/compose.yaml b/drivers/citrineos/compose.yaml new file mode 100644 index 0000000..0d3e60b --- /dev/null +++ b/drivers/citrineos/compose.yaml @@ -0,0 +1,142 @@ +# Copyright 2026 Julien Herr +# SPDX-License-Identifier: Apache-2.0 +# +# The CitrineOS environment: what `ocpp-tck run-all` needs on the other end of +# the wire when CSMS_DRIVER=./drivers/citrineos/index.ts. Not a production +# deployment -- the message API is unauthenticated here (CitrineOS's shipped +# `docker` app-env selects LocalBypassAuthProvider), and the credentials below +# are the driver's documented defaults, in the clear, on purpose. +# +# Every name in this file is load-bearing, because the driver's defaults +# (drivers/citrineos/config.ts defaultCitrineConfig) resolve to them: +# +# name: citrineos + network citrineos-internal -> CITRINE_NETWORK=citrineos_citrineos-internal +# container_name -> CITRINE_DB_CONTAINER=citrine-db +# service name citrine -> the DNS name in CITRINE_WS_URL=ws://citrine:8081/ +# +# Two service names are load-bearing for CITRINEOS rather than for the driver, +# and cannot be renamed at all: the shipped config hardcodes the database host +# through BOOTSTRAP_CITRINEOS_DATABASE_HOST (set below) and the broker as +# `amqp://guest:guest@amqp-broker:5672` (apps/ocpp-server/src/config/envs/docker.ts, +# util.messageBroker.amqp.url), which no environment variable overrides. +# +# The project name is pinned here rather than inherited from the directory, so +# that `docker compose -f drivers/citrineos/compose.yaml up` produces the same +# network name as `docker compose -p citrineos ...` and as CI. +name: citrineos + +# Derived from citrineos-core's own docker-compose.yml @ v2.0.0-beta1 +# (Apache-2.0). Modified: the operator UI, the OCPI server and the Hasura +# sidecar are dropped (this harness reads Postgres directly); minio is dropped +# because BOOTSTRAP_CITRINEOS_FILE_ACCESS_TYPE=local means nothing reaches S3; +# every volume is dropped; images are pinned by digest; only the HTTP API port +# is published, on loopback. +services: + # Images are pinned by digest, not tag: `latest` is republished on every + # build, and a conformance run that cannot say which bytes it tested is not a + # conformance run. Same discipline as DEFAULT_SIM_IMAGE in tck/sim.ts and as + # drivers/steve/compose.yaml. + # + # v2.0.0-beta1 rather than the v1.9.1 stable, deliberately: the OCPP 1.6 + # GetLocalListVersion and SendLocalList message endpoints exist only from the + # v2 line (packages/core/src/modules/EVDriver/src/module/1.6/MessageApi.ts), + # and six scenarios need them. See drivers/citrineos/README.md for the v1.9.1 + # variant and what it costs. + # + # Re-pin with: + # T=$(curl -sS "https://ghcr.io/token?scope=repository:citrineos/citrineos-server:pull&service=ghcr.io" \ + # | sed -n 's/.*"token":"\([^"]*\)".*/\1/p') + # curl -sSI -H "Authorization: Bearer $T" \ + # -H "Accept: application/vnd.oci.image.index.v1+json" \ + # https://ghcr.io/v2/citrineos/citrineos-server/manifests/v2.0.0-beta1 \ + # | grep -i docker-content-digest + citrine: + image: ghcr.io/citrineos/citrineos-server:v2.0.0-beta1@sha256:58800f45acd82c976e2f55dd9aab85baee61507938bb2cb0d0f81fc70853c6ef + container_name: citrine + restart: unless-stopped + depends_on: + ocpp-db: + condition: service_healthy + amqp-broker: + condition: service_healthy + environment: + APP_NAME: "all" + APP_ENV: "docker" + DB_STRATEGY: "migrate" + BOOTSTRAP_CITRINEOS_DATABASE_HOST: "ocpp-db" + BOOTSTRAP_CITRINEOS_CONFIG_FILENAME: "config.json" + # Local disk, not S3. This is why there is no minio service here: with + # `local` the file-access layer never builds an S3 client, so the two + # upstream containers (minio, minio-init) have nothing to serve. + BOOTSTRAP_CITRINEOS_FILE_ACCESS_TYPE: "local" + BOOTSTRAP_CITRINEOS_FILE_ACCESS_LOCAL_DEFAULT_FILE_PATH: "/data" + CONFIG_CITRINEOS_WIPE_FILE_ON_START: "false" + ports: + # Published because the driver runs on the HOST (it reaches Postgres via + # `docker exec`), so its CITRINE_API_URL is http://localhost:8080 while + # the simulator container, on citrineos-internal, uses ws://citrine:8081/ . + # That asymmetry is why CITRINE_API_URL and CITRINE_WS_URL are separate + # settings. + # + # Loopback only, and 8080 only: the OCPP endpoints (8081 plaintext, 8082 + # basic-auth, 8443/8444 TLS) are reached by the simulator over the + # internal network, and 8080 carries an API that accepts every request + # unauthenticated. + - "127.0.0.1:8080:8080" + networks: + - citrineos-internal + healthcheck: + # `node -e` rather than curl: curl is not in this image. Verbatim from + # upstream's compose, which is the only reason it is this baroque. + test: + [ + "CMD-SHELL", + "node -e \"const net = require('net'); const c = net.createConnection(8080, '127.0.0.1', () => { c.end(); process.exit(0); }); c.on('error', () => process.exit(1)); c.setTimeout(5000, () => { c.destroy(); process.exit(1); });\"", + ] + interval: 5s + timeout: 10s + retries: 40 + # A cold first boot runs the whole migration set before the port opens. + start_period: 120s + + ocpp-db: + image: postgis/postgis:16-3.5@sha256:4e07b425403ba55c20b541884db2e80c686dd6476bf9265046ac9c163895605d + container_name: citrine-db + restart: unless-stopped + # Upstream pins this because postgis publishes no arm64 tag; without it, + # `up` fails outright on an Apple Silicon host rather than falling back. + platform: linux/amd64 + environment: + POSTGRES_DB: citrine + POSTGRES_USER: citrine + POSTGRES_PASSWORD: citrine + networks: + - citrineos-internal + healthcheck: + test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -p 5432 -U citrine -d citrine"] + interval: 5s + timeout: 10s + retries: 10 + start_period: 30s + + amqp-broker: + image: rabbitmq:3-management@sha256:e582c0bc7766f3342496d8485efb5a1df782b5ce3886ad017e2eaae442311f69 + container_name: citrine-amqp + restart: unless-stopped + environment: + RABBITMQ_DEFAULT_USER: "guest" + RABBITMQ_DEFAULT_PASS: "guest" + networks: + - citrineos-internal + healthcheck: + test: rabbitmq-diagnostics -q check_port_connectivity + interval: 10s + timeout: 10s + retries: 6 + start_period: 20s + +# No volume: every run starts from an empty schema and re-provisions. State +# that survives a run is state a scenario can accidentally depend on. +networks: + citrineos-internal: + driver: bridge diff --git a/drivers/citrineos/config.ts b/drivers/citrineos/config.ts new file mode 100644 index 0000000..effd7e8 --- /dev/null +++ b/drivers/citrineos/config.ts @@ -0,0 +1,72 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * config.ts -- every default this driver has, in one place. + * + * The values below resolve to the names in drivers/citrineos/compose.yaml, so + * a stock `docker compose -f drivers/citrineos/compose.yaml up -d --wait` + * needs no environment at all. Renaming anything there means passing the + * matching CITRINE_* variable by hand; index.ts's envHelp is the user-facing + * copy of this table. + * + * Note the asymmetry between `apiUrl` and `wsBaseUrl`, which is not an + * oversight: the driver runs on the HOST (it reaches Postgres through + * `docker exec`) and so talks to `localhost`, while the simulator runs in a + * container on the compose network and talks to `citrine`. One CSMS, two + * addresses, because two different processes are doing the addressing. + */ +import type { CsmsEnv } from "../../tck/driver"; +import { resolveVariant, type CitrineVariant } from "./variant"; + +export interface CitrineConfig { + /** Which CitrineOS line the target runs. Everything version-specific is + * derived from it rather than stored beside it -- see variant.ts. */ + variant: CitrineVariant; + /** Message-API base, no trailing slash, e.g. http://localhost:8080 */ + apiUrl: string; + /** Every message-API call carries it; CitrineOS's DEFAULT_TENANT_ID is 1. */ + tenantId: number; + /** docker container running CitrineOS's Postgres. */ + dbContainer: string; + dbUser: string; + dbPass: string; + dbName: string; + /** OCPP WebSocket endpoint, without the trailing charge-point id. */ + wsBaseUrl: string; + /** Docker network the simulator must join to reach CitrineOS by name. */ + dockerNetwork: string; +} + +/** + * Parses CITRINE_TENANT_ID strictly. + * + * `Number.parseInt("1x")` is 1, and a tenant id silently truncated from a typo + * points every operation at a tenant whose rows this driver then reads as + * absent -- which surfaces as a dozen scenarios failing on empty records + * rather than as the configuration error it is. + */ +function tenantId(raw: string | undefined): number { + if (raw === undefined || raw === "") return 1; + if (!/^\d+$/.test(raw)) { + throw new Error( + `citrineos: CITRINE_TENANT_ID must be a decimal integer, got ${JSON.stringify(raw)}`, + ); + } + return Number(raw); +} + +export function defaultCitrineConfig(env: CsmsEnv): CitrineConfig { + return { + variant: resolveVariant(env), + apiUrl: (env.CITRINE_API_URL ?? "http://localhost:8080").replace(/\/+$/, ""), + tenantId: tenantId(env.CITRINE_TENANT_ID), + dbContainer: env.CITRINE_DB_CONTAINER ?? "citrine-db", + dbUser: env.CITRINE_DB_USER ?? "citrine", + dbPass: env.CITRINE_DB_PASS ?? "citrine", + dbName: env.CITRINE_DB_NAME ?? "citrine", + // Trailing slash on purpose: the simulator appends the charge point id as + // the last path segment, and getClientIdFromUrl takes exactly that. + wsBaseUrl: env.CITRINE_WS_URL ?? "ws://citrine:8081/", + dockerNetwork: env.CITRINE_NETWORK ?? "citrineos_citrineos-internal", + }; +} diff --git a/drivers/citrineos/index.ts b/drivers/citrineos/index.ts new file mode 100644 index 0000000..0e9b770 --- /dev/null +++ b/drivers/citrineos/index.ts @@ -0,0 +1,177 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * The CitrineOS driver. + * + * CitrineOS (LF Energy / S44) is the second CSMS this harness drives, and the + * first one the scenarios were not written against. That is its job here: an + * abstraction with one implementation is neutral by assertion, and this driver + * is how the assertion gets tested. It reports the answer honestly -- seven + * scenarios are NOT_APPLICABLE because CitrineOS's OCPP 1.6 surface is smaller + * than SteVe's, and scope.ts names the missing endpoint for each. + * + * Why the JSON message API + * ------------------------ + * Unlike SteVe, there is no choice to justify: CitrineOS generates its + * outbound surface from the OCPP schemas themselves, so + * `POST /ocpp/1.6//` IS the way to put a Call on the wire, and + * the request body IS the OCPP payload. The interesting part is what the + * surface omits -- see requests.ts. + * + * Where the observations come from, and where this has to run + * ----------------------------------------------------------- + * Postgres, through `docker exec`, because CitrineOS's REST data endpoints + * expose none of what the scenarios assert on: no latest transaction, no idTag + * on a transaction, no stop reason, no count. records.ts documents the full + * search and why the bundled Hasura sidecar was not used instead. The + * consequence is the same as SteVe's: this driver runs on the host that owns + * the containers, so a remote CitrineOS is out of reach for the record half + * even though the operation half would work over HTTP. + * + * Versions + * -------- + * Both CitrineOS lines are supported, selected by CITRINE_VARIANT and + * defaulting to v2 -- drivers/citrineos/compose.yaml pins v2.0.0-beta1 by + * digest, and compose.v1.yaml overrides it with v1.9.1. v1 costs the six + * local-auth-list scenarios, whose 1.6 endpoints exist only from the v2 line, + * and renames the OCPP connection column. See variant.ts. + */ +import { + CSMS_OPERATION_ACTIONS, + type CsmsCapabilities, + type CsmsDriverModule, + type CsmsDriverParts, + type CsmsEnv, + type CsmsOperation, + type CsmsOperationAction, + type CsmsOperations, +} from "../../tck/driver"; +import { CitrineMessageApi } from "./api-client"; +import { defaultCitrineConfig } from "./config"; +import { + provisionCommand, + teardownCommand, + verifyCommand, +} from "./provision"; +import { CitrineRecords } from "./records"; +import { toCitrineRequest } from "./requests"; +import { citrineosScope } from "./scope"; +import { + resolveVariant, + unroutedActions, + type CitrineVariant, +} from "./variant"; + +/** + * What the 1.6 message API does not route, for the declared variant -- + * confirmed against both running images: v2.0.0-beta1's /docs/json advertises + * 18 `/ocpp/1.6/` paths and v1.9.1's advertises 16, with `reserveNow` and + * `cancelReservation` absent from both. + * + * Declared by subtraction from the contract's own list rather than by + * enumerating the supported ones, so that an operation added to the contract + * lands here as supported-and-unimplemented -- which `requests.ts`'s + * `assertNever` turns into a compile error -- instead of being silently + * dropped from the declaration and never noticed. + * + * Read at MODULE load, not in create(): `scope` and `capabilities` are read by + * check-driver and by the pre-flight without ever calling create(), which is + * what lets both run with no credentials and no server. CITRINE_VARIANT is a + * declaration, not a credential, so reading it here keeps that promise. + */ +const VARIANT = resolveVariant(process.env); +const UNROUTED: ReadonlyMap = unroutedActions(VARIANT); + +const CAPABILITIES: CsmsCapabilities = { + operations: new Set( + CSMS_OPERATION_ACTIONS.filter((action) => !UNROUTED.has(action)), + ), + // No reservation capability at all, which is structural rather than a gap in + // this driver: with nothing able to SEND a 1.6 ReserveNow, the Reservations + // table never gets a row for 1.6 to have an opinion about. + reservations: false, + chargingProfiles: true, +}; + +function createOperations( + variant: CitrineVariant, + api: CitrineMessageApi, + records: CitrineRecords, +): CsmsOperations { + return { + async execute(cpId: string, op: CsmsOperation): Promise { + // Refs are resolved here rather than inside the mapper so that the + // mapper stays a pure function of the operation plus one narrow lookup, + // and so the database round-trip only happens for the two operations + // that genuinely need it. + const request = await toCitrineRequest( + op, + { ocppTransactionId: (ref) => records.ocppTransactionId(ref) }, + variant, + ); + return api.send(cpId, request); + }, + }; +} + +export const csmsDriver: CsmsDriverModule = { + id: "citrineos", + displayName: "CitrineOS", + scope: citrineosScope(VARIANT), + capabilities: CAPABILITIES, + create(env: CsmsEnv): CsmsDriverParts { + const cfg = defaultCitrineConfig(env); + // VARIANT above came from process.env at module load, because `scope` and + // `capabilities` are read without ever calling create(). This resolves it + // again from the env the runner passes, and the two are only guaranteed to + // agree because tck/main.ts passes process.env. A caller passing a + // synthetic CsmsEnv would otherwise get a scope table describing one + // server while every request targeted the other -- silently. One + // comparison converts that into a sentence. + if (cfg.variant !== VARIANT) { + throw new Error( + `citrineos: CITRINE_VARIANT is ${cfg.variant} in the environment passed to ` + + `create(), but ${VARIANT} when the module was loaded, so the scope table ` + + "and the requests would describe different servers.", + ); + } + const records = new CitrineRecords(cfg); + return { + operations: createOperations(cfg.variant, new CitrineMessageApi(cfg), records), + records, + prepareStation: (cpId) => records.prepareStation(cpId), + simTransport: async () => ({ + // CitrineOS takes the charge point id as the LAST path segment + // (getClientIdFromUrl in WebsocketNetworkConnection.ts), and port 8081 + // is security profile 0, so no basic auth travels with it. + wsUrl: env.SIM_WS_URL ?? cfg.wsBaseUrl, + appendCpIdToWsPath: true, + network: env.SIM_NETWORK ?? cfg.dockerNetwork, + }), + }; + }, + // Bootstrap lives here rather than in the runner: what a CSMS needs before + // it can be tested is a fact about that CSMS. drivers/citrineos/compose.yaml + // brings the environment up; these put the fixtures in it. + commands: { + provision: provisionCommand, + verify: verifyCommand, + teardown: teardownCommand, + }, + envHelp: [ + "CITRINE_VARIANT v2 (default) or v1. v1 targets the v1.9.1 line: it names", + " the station column stationId and routes no 1.6 local", + " auth list, so 6 scenarios become NOT APPLICABLE.", + "CITRINE_API_URL message API base (default http://localhost:8080).", + " No credentials: the shipped docker app-env selects", + " LocalBypassAuthProvider, which accepts every request.", + "CITRINE_WS_URL OCPP endpoint, id appended (default ws://citrine:8081/)", + "CITRINE_TENANT_ID tenant every call carries (default 1)", + "CITRINE_DB_CONTAINER Postgres container name (default citrine-db)", + "CITRINE_DB_USER Postgres user (default citrine)", + "CITRINE_DB_PASS Postgres password (default citrine)", + "CITRINE_DB_NAME Postgres database (default citrine)", + "CITRINE_NETWORK docker network the simulator joins to reach CitrineOS", + " (default citrineos_citrineos-internal)", + ].join("\n"), +}; diff --git a/drivers/citrineos/profiles.ts b/drivers/citrineos/profiles.ts new file mode 100644 index 0000000..b4777eb --- /dev/null +++ b/drivers/citrineos/profiles.ts @@ -0,0 +1,97 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * profiles.ts -- the pre-provisioned charging profiles, owned by this driver. + * + * THIS IS A FIXTURE CATALOGUE, NOT SCENARIO BRANCHING. It looks like branching + * because the two descriptions below are the ones the SmartCharging scenarios + * name, so it is worth being precise about the difference: a driver may not + * change its BEHAVIOUR based on which scenario is running, but the environment + * every scenario assumes is exactly what `ocpp-tck driver provision` exists to + * create. SteVe's provisioner seeds the same two profiles, under the same two + * descriptions, with the same 11000 W limit -- it just seeds them into SteVe's + * charging_profile table, because SteVe has one. + * + * CitrineOS does not, and does not need one. OCPP 1.6 SetChargingProfile + * carries the whole profile inline (`csChargingProfiles`), so there is nothing + * for a CSMS-side registry to be looked up FROM. Its `ChargingProfiles` table + * is a record of what was sent, written after the fact, and it has no + * `description` or `name` column to look up BY -- verified against + * packages/core/src/dal/layers/drizzle/schema/ChargingProfile.ts. + * + * So `refByDescription` resolves here instead. Two consequences follow, and + * both are load-bearing: + * + * - THE REF IS THE OCPP `chargingProfileId`. It has to be: the scenarios + * assert `Applied charging profile #` against the SIMULATOR's log, + * which prints the id the charge point received on the wire. A ref that + * were a database key, or an index into this array, would make every + * SmartCharging scenario fail on an assertion about the CSMS's bookkeeping + * rather than about the charge point. + * - THE SHAPE MIRRORS SteVe's `chargingProfileForm`: stackLevel 0, kind + * Relative, rate unit W, one period at startPeriod 0. TC_066 asserts + * `"limit":11000` on the returned composite schedule, so the limit is not + * decorative. + */ + +/** OCPP 1.6 ChargingProfile, spelled as the wire spells it. */ +export interface CsChargingProfile { + chargingProfileId: number; + /** Only meaningful for a TxProfile; absent otherwise. */ + transactionId?: number; + stackLevel: number; + chargingProfilePurpose: "ChargePointMaxProfile" | "TxDefaultProfile" | "TxProfile"; + chargingProfileKind: "Absolute" | "Recurring" | "Relative"; + chargingSchedule: { + chargingRateUnit: "A" | "W"; + chargingSchedulePeriod: { startPeriod: number; limit: number }[]; + }; +} + +interface CatalogueEntry { + /** The human-readable name a scenario looks the profile up by. */ + description: string; + profile: CsChargingProfile; +} + +function watts( + chargingProfileId: number, + chargingProfilePurpose: CsChargingProfile["chargingProfilePurpose"], + limit: number, +): CsChargingProfile { + return { + chargingProfileId, + stackLevel: 0, + chargingProfilePurpose, + chargingProfileKind: "Relative", + chargingSchedule: { + chargingRateUnit: "W", + chargingSchedulePeriod: [{ startPeriod: 0, limit }], + }, + }; +} + +/** + * Ids 56 and 57 name the test cases that use them rather than counting from 1. + * A single-digit id would make the scenarios' `#(?!\d)` log assertions + * depend on that negative lookahead to avoid matching `#10`; two digits chosen + * to be memorable cost nothing and remove the question. + */ +export const PROFILE_CATALOGUE: readonly CatalogueEntry[] = [ + { description: "TC056 TxDefaultProfile", profile: watts(56, "TxDefaultProfile", 11000) }, + { description: "TC057 TxProfile", profile: watts(57, "TxProfile", 11000) }, +]; + +/** The ref for a description, or "" when this driver provisions no such + * profile -- which is the contract's "the CSMS has no such record". */ +export function refByDescription(description: string): string { + const entry = PROFILE_CATALOGUE.find((e) => e.description === description); + return entry ? String(entry.profile.chargingProfileId) : ""; +} + +/** The profile behind a ref. `undefined` when the ref names nothing here. */ +export function profileByRef(ref: string): CsChargingProfile | undefined { + return PROFILE_CATALOGUE.find( + (e) => String(e.profile.chargingProfileId) === ref, + )?.profile; +} diff --git a/drivers/citrineos/provision.ts b/drivers/citrineos/provision.ts new file mode 100644 index 0000000..19fe9e8 --- /dev/null +++ b/drivers/citrineos/provision.ts @@ -0,0 +1,447 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * provision.ts -- the environment the scenarios assume, made reproducible. + * + * The scenarios do not create the state they assert on: TC_023 needs three + * idTags that are respectively unknown, expired and blocked, and a dozen + * others must simply authorize. drivers/steve/provision.ts is the sibling of + * this file and explains where the tag list comes from; the list itself is + * duplicated rather than shared because it is a property of the SIMULATOR + * image, and a driver that imported another driver's fixtures would be + * claiming a coupling that does not exist. + * + * ONE CHANNEL, NOT THREE. SteVe's provisioner uses REST, SQL and the manager + * UI because each covers what the others cannot. Here everything is SQL, + * because CitrineOS exposes no Authorization CRUD at all: every + * `@AsDataEndpoint` in the repository was read, and `EVDriverDataApi` offers + * exactly one route, a read-only GET of the local list version. The bundled + * Hasura sidecar would offer insert mutations, at the cost of vendoring its + * metadata -- see records.ts for why that trade was refused. + * + * Charging profiles are not provisioned here either, and that is not an + * omission: OCPP 1.6 SetChargingProfile carries the profile inline, so there + * is no CSMS-side record to create. profiles.ts holds the catalogue. + * + * Everything is idempotent. Re-running provision on a provisioned environment + * must be a no-op that still exits 0, because CI reruns it and an operator + * chasing a failure will run it twice before believing it. + */ +import { defaultCitrineConfig, type CitrineConfig } from "./config"; +import { CitrineRecords, sqlLiteral } from "./records"; +import { stationColumn } from "./variant"; + +/** + * Tags that must exist and authorize normally. + * + * Most of these are hard-coded in the SIMULATOR's scenario templates rather + * than in tck/specs/, so deriving the list from this repository's sources + * yields a set that looks complete and silently fails TC_013/014/017/018. + * Ground truth is the pinned simulator image; drivers/steve/provision.ts + * carries the one-liner that re-extracts it, and tck/sim.ts owns the digest. + */ +const VALID_TAGS = [ + // Sent by the charge point, from the simulator's own templates. + "CERT003", + "CERT004", + "CERT005", + "CERT010", + "CERT011", + "CERT012", + "CERT013", + "CERT014", + "CERT017", + "CERT018", + "CERT028", + "CERT056", + "CERT057", + "CERT059", + "CERT-RES01", + // Supplied BY the CSMS, from tck/specs/ -- RemoteStartTransaction and + // SendLocalList carry these. + "CERT-TAG-1", + "CERT-TAG-2", +] as const; + +/** Absent from Authorizations entirely -- the 1.6 Authorize handler answers + * Invalid when the lookup returns no row. */ +const INVALID_TAG = "CERT023-INV"; +/** Present, Accepted, with cacheExpiryDateTime in the past. */ +const EXPIRED_TAG = "CERT023-EXP"; +/** Present, stored Blocked. See BLOCKED_TAG_CAVEAT. */ +const BLOCKED_TAG = "CERT023-BLK"; + +/** + * The expiry written for EXPIRED_TAG. Fixed rather than "now minus a day" so + * that a provisioned environment is identical between runs, which is what lets + * `verify` tell "expired on purpose" from "expired by accident". + * + * The status stays `Accepted` and only the instant makes it expired, which + * reads backwards until you follow the handler: AuthorizeRequestOcpp16Handler + * compares `cacheExpiryDateTime` against now INSIDE the `status === Accepted` + * branch, and every other stored status falls through to the default. A row + * stored as `status = 'Expired'` therefore answers Invalid, not Expired. + */ +const PAST_EXPIRY = "2020-01-01T00:00:00Z"; + +/** + * Why CERT023-BLK is provisioned anyway, and what it does NOT achieve. + * + * AuthorizeRequestOcpp16Handler reaches its status mapper only through the + * `status === Accepted` branch; a stored `Blocked` matches neither that branch + * nor the null-status one, so the response keeps its default `Invalid`. The + * only route to a real `Blocked` is an IAuthorizer returning it, and the + * shipped container registers `authorizers: asValue([])` + * (apps/ocpp-server/src/container.ts) with no configuration that changes it. + * + * The row is still written, for two reasons: it is the closest honest + * expression of the fixture, and it means the scenario fails on the CSMS's + * mapping rather than on a tag that was never there -- which is the finding + * worth reporting upstream. scope.ts carries the same citation. + */ +const BLOCKED_TAG_CAVEAT = + "stored status Blocked; CitrineOS's 1.6 Authorize handler maps it to Invalid"; + +/** CitrineOS looks tags up by idToken alone, so at most one row may exist per + * tag: the handler answers Invalid outright when the lookup returns more than + * one. `Central` rather than NULL so the value is greppable in the table. */ +const ID_TOKEN_TYPE = "Central"; + +interface TagFixture { + idToken: string; + status: string; + /** ISO instant, or null for "never expires". */ + expiry: string | null; +} + +const FIXTURES: readonly TagFixture[] = [ + ...VALID_TAGS.map((idToken) => ({ idToken, status: "Accepted", expiry: null })), + { idToken: EXPIRED_TAG, status: "Accepted", expiry: PAST_EXPIRY }, + { idToken: BLOCKED_TAG, status: "Blocked", expiry: null }, +]; + +/** Every tag this driver owns. Spelled once so that a fixture added to + * provision but not to teardown cannot leave rows behind that verify still + * demands. */ +const ALL_TAGS = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG]; + +/** A SQL timestamptz literal, or NULL. Free of `this`, so it lives beside + * sqlLiteral rather than on the class. */ +function nullableInstant(value: string | null): string { + return value === null ? "NULL" : `${sqlLiteral(value)}::timestamptz`; +} + +export class CitrineProvisioner { + private readonly db: CitrineRecords; + + constructor( + private readonly cfg: CitrineConfig, + private readonly log: (msg: string) => void = stdout, + ) { + this.db = new CitrineRecords(cfg); + } + + private get tenant(): string { + return String(this.cfg.tenantId); + } + + /** + * Writes every fixture in ONE psql invocation. + * + * Upsert by hand rather than `ON CONFLICT`, because the unique index is on + * (idToken, idTokenType, tenantId) and Postgres treats NULLs as distinct -- + * so a row written with a different idTokenType would not conflict, and the + * table would quietly grow the second row that makes the handler answer + * Invalid. Matching on (idToken, tenantId) enforces the invariant the + * handler actually needs, whatever else is in the table. + */ + async provisionTags(): Promise { + const statements: string[] = []; + + for (const fixture of FIXTURES) { + const idToken = sqlLiteral(fixture.idToken); + const where = `"idToken" = ${idToken} AND "tenantId" = ${this.tenant}`; + statements.push( + `UPDATE "Authorizations" + SET "status" = ${sqlLiteral(fixture.status)}, + "cacheExpiryDateTime" = ${nullableInstant(fixture.expiry)}, + "updatedAt" = NOW() + WHERE ${where};`, + `INSERT INTO "Authorizations" + ("idToken", "idTokenType", "status", "cacheExpiryDateTime", "tenantId", "createdAt", "updatedAt") + SELECT ${idToken}, ${sqlLiteral(ID_TOKEN_TYPE)}, ${sqlLiteral(fixture.status)}, + ${nullableInstant(fixture.expiry)}, ${this.tenant}, NOW(), NOW() + WHERE NOT EXISTS (SELECT 1 FROM "Authorizations" WHERE ${where});`, + ); + } + + // The unknown tag must be ABSENT, and TC_023.1 asserts no transaction was + // ever created for it -- so nothing should reference it. The guard is + // there for the case where something did: a foreign key violation would + // abort the whole script, taking the other fixtures with it. + statements.push( + `DELETE FROM "Authorizations" a + WHERE a."idToken" = ${sqlLiteral(INVALID_TAG)} AND a."tenantId" = ${this.tenant} + AND NOT EXISTS (SELECT 1 FROM "Transactions" t WHERE t."authorizationId" = a.id);`, + ); + + await this.db.scalar(statements.join("\n")); + this.log( + `tags: ${VALID_TAGS.length} valid, ${EXPIRED_TAG} expired at ${PAST_EXPIRY}, ` + + `${BLOCKED_TAG} (${BLOCKED_TAG_CAVEAT}), ${INVALID_TAG} absent`, + ); + } + + /** + * Read-only. Two queries rather than one per fixture: each db call is a + * `docker exec` process spawn, so asking about twenty tags one at a time + * costs seconds of pure process startup -- and verify() runs twice in CI. + */ + /** + * Does the running server's schema match the variant we were told to expect? + * + * variant.ts declares rather than detects, so that the scope table stays + * readable offline -- which leaves exactly one way for the declaration to be + * wrong: pointing a `v2` driver at a `v1.9.1` server, or the reverse. The + * symptom without this check is silent and expensive: every record read + * targets a column that does not exist, `psql` fails, and a dozen scenarios + * report the CSMS as empty. One query converts that into a sentence. + * + * The discriminator is `ocppConnectionName`, never `stationId`: `stationId` + * exists on `Transactions` in BOTH lines -- `character varying` holding the + * OCPP name on v1.9.1, an `integer` foreign key on v2 -- so its presence + * proves nothing. Both facts were read off running containers. + */ + private async verifySchema(): Promise { + const present = + (await this.db.scalar( + `SELECT count(*) FROM information_schema.columns + WHERE table_schema = 'public' AND table_name = 'Transactions' + AND column_name = 'ocppConnectionName';`, + )) !== "0"; + const expected = this.cfg.variant === "v2"; + if (present === expected) return []; + return [ + `schema mismatch: CITRINE_VARIANT=${this.cfg.variant} expects ` + + `Transactions."${stationColumn(this.cfg.variant)}", but the server ` + + `${present ? "has" : "does not have"} ocppConnectionName. ` + + `Set CITRINE_VARIANT=${present ? "v2" : "v1"} for this server.`, + ]; + } + + async verify(): Promise { + // First, and returning early -- not because the checks below depend on it + // (they read `Authorizations`, which has no station column) but because of + // how a mismatch READS. Pointing a v2 driver at a v1.9.1 server makes every + // record query target a column that does not exist, and the sweep that + // follows would report twenty absent fixtures. One sentence about the + // variant is the useful answer; twenty about fixtures is not. + const schema = await this.verifySchema(); + if (schema.length > 0) return schema; + + const problems: string[] = []; + + // "Is the expiry in the past" is asked of Postgres rather than of + // Date.parse: the CSMS compares against its own clock, not this process's, + // and that is the comparison the scenario depends on. + const rows = await this.db.rows( + `SELECT "idToken", COUNT(*), MIN("status"), + COALESCE(MIN("cacheExpiryDateTime")::text, ''), + CASE WHEN MIN("cacheExpiryDateTime") < NOW() THEN 'past' ELSE 'future' END + FROM "Authorizations" + WHERE "tenantId" = ${this.tenant} + AND "idToken" IN (${ALL_TAGS.map(sqlLiteral).join(", ")}) + GROUP BY "idToken";`, + ); + const tags = new Map(rows.map((row) => [row[0], row])); + + // A duplicate is not cosmetic: the 1.6 Authorize handler answers Invalid + // outright when an idToken resolves to more than one row, so this check is + // the difference between a diagnosable environment fault and twelve + // scenarios failing on an unexplained denial. + for (const [idToken, row] of tags) { + if (row[1] !== "1") { + problems.push(`${idToken}: ${row[1]} rows, expected 1 (the handler answers Invalid for more)`); + } + } + + for (const idTag of VALID_TAGS) { + const row = tags.get(idTag); + if (!row) { + problems.push(`${idTag}: missing`); + continue; + } + if (row[2] !== "Accepted") { + problems.push(`${idTag}: status ${row[2] || ""}, expected Accepted`); + } + if (row[3] !== "") { + problems.push(`${idTag}: has cacheExpiryDateTime ${row[3]}, expected none`); + } + } + + if (tags.has(INVALID_TAG)) { + problems.push(`${INVALID_TAG}: present, must be absent for TC_023.1`); + } + + const expired = tags.get(EXPIRED_TAG); + if (!expired || expired[3] === "") { + problems.push(`${EXPIRED_TAG}: missing or has no cacheExpiryDateTime`); + } else if (expired[2] !== "Accepted") { + // The trap PAST_EXPIRY's comment describes, checked rather than merely + // documented: any other status makes the handler answer Invalid and the + // expiry is never consulted. + problems.push( + `${EXPIRED_TAG}: status ${expired[2]}, expected Accepted -- only the ` + + "Accepted branch consults cacheExpiryDateTime", + ); + } else if (expired[4] !== "past") { + problems.push(`${EXPIRED_TAG}: expiry ${expired[3]} is not in the past`); + } + + const blocked = tags.get(BLOCKED_TAG); + if (!blocked) { + problems.push(`${BLOCKED_TAG}: missing`); + } else if (blocked[2] !== "Blocked") { + problems.push(`${BLOCKED_TAG}: status ${blocked[2] || ""}, expected Blocked`); + } + + return problems; + } + + /** + * Every `NOT EXISTS` guard needed to delete an Authorization safely, read + * from the live catalog rather than written out here. + * + * There are four foreign keys onto `Authorizations` on the pinned image -- + * `Transactions.authorizationId`, `LocalListAuthorizations.authorizationId`, + * `LocalListAuthorizations.groupAuthorizationId`, and the self-reference + * `Authorizations.groupAuthorizationId` -- and none of them cascades. An + * earlier version of this method guarded only the first, which is the one a + * transaction-only run exercises; any scenario that had sent a SendLocalList + * then aborted the DELETE on a constraint violation, and because psql runs a + * semicolon-separated script in ONE implicit transaction with ON_ERROR_STOP, + * that abort rolled the whole teardown back. It removed nothing and said + * nothing. + * + * Asking the catalog instead of listing four names is what keeps that fixed: + * a fifth referencing table on a future CitrineOS is picked up rather than + * silently reintroducing the same failure. Table and column names come from + * pg_constraint, so they are the database's own identifiers. + */ + private async guards(): Promise { + const rows = await this.db.rows( + `SELECT c.conrelid::regclass::text, a.attname + FROM pg_constraint c + JOIN unnest(c.conkey) WITH ORDINALITY k(attnum, ord) ON true + JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum + WHERE c.contype = 'f' AND c.confrelid = '"Authorizations"'::regclass + ORDER BY 1, 2;`, + ); + if (rows.length === 0) { + throw new Error( + "citrineos teardown: no foreign keys onto Authorizations found -- " + + "the schema is not what this driver was written against, refusing to delete.", + ); + } + return rows + .map(([table, column]) => + `NOT EXISTS (SELECT 1 FROM ${table} r WHERE r."${column}" = a.id)`, + ) + .join("\n AND "); + } + + /** + * Removes the fixtures, and nothing else. Charge points, their connectors + * and their transactions are runtime residue rather than fixtures, and + * `docker compose -f drivers/citrineos/compose.yaml down -v` is the honest + * way to get a clean slate. + */ + async teardown(): Promise { + const tags = ALL_TAGS.map(sqlLiteral).join(", "); + const mine = `a."idToken" IN (${tags}) AND a."tenantId" = ${this.tenant}`; + const unreferenced = await this.guards(); + + const kept = await this.db.scalar( + `SELECT COUNT(*) FROM "Authorizations" a + WHERE ${mine} AND NOT (${unreferenced});`, + ); + await this.db.scalar( + `DELETE FROM "Authorizations" a WHERE ${mine} AND ${unreferenced};`, + ); + this.log( + kept === "0" + ? "tags: removed" + : `tags: removed, ${kept} kept because scenario records still reference them`, + ); + } +} + +function newProvisioner(): CitrineProvisioner { + return new CitrineProvisioner(defaultCitrineConfig(process.env)); +} + +function stdout(msg: string): void { + process.stdout.write(`${msg}\n`); +} + +/** Turns a thrown error into the exit code a driver verb must return, in one + * place, so no verb can grow a differently-worded failure path. */ +async function runVerb( + label: string, + fn: () => Promise, + onClean: string, + onProblems: string, +): Promise { + let problems: string[]; + try { + problems = await fn(); + } catch (err) { + process.stderr.write( + `${label} failed: ${err instanceof Error ? err.message : String(err)}\n`, + ); + return 1; + } + if (problems.length > 0) { + process.stderr.write(`${onProblems}:\n ${problems.join("\n ")}\n`); + return 1; + } + stdout(onClean); + return 0; +} + +/** `ocpp-tck driver provision` */ +export async function provisionCommand(): Promise { + const provisioner = newProvisioner(); + return runVerb( + "provision", + async () => { + await provisioner.provisionTags(); + return provisioner.verify(); + }, + "provisioned", + "provision ran but the environment is still wrong", + ); +} + +/** `ocpp-tck driver verify` */ +export async function verifyCommand(): Promise { + return runVerb( + "verify", + () => newProvisioner().verify(), + "environment matches what the scenarios assume", + "not provisioned", + ); +} + +/** `ocpp-tck driver teardown` */ +export async function teardownCommand(): Promise { + return runVerb( + "teardown", + async () => { + await newProvisioner().teardown(); + return []; + }, + "torn down", + "teardown left problems", + ); +} diff --git a/drivers/citrineos/records.ts b/drivers/citrineos/records.ts new file mode 100644 index 0000000..4637e5e --- /dev/null +++ b/drivers/citrineos/records.ts @@ -0,0 +1,359 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * records.ts -- what CitrineOS believes happened, read straight from Postgres. + * + * The message API is write-only in practice. CitrineOS's REST data endpoints + * cover boot config, tariffs, certificates, the router's websocket plumbing and + * exactly one transaction lookup -- by explicit `transactionId`, which a + * scenario does not know. There is no "latest transaction for this station", + * no idTag on a transaction, no stop reason, no count, and no Authorization + * CRUD at all. Every `@AsDataEndpoint` in the repository was read to establish + * that, not sampled. + * + * WHY NOT THE BUNDLED HASURA / GraphQL + * ------------------------------------ + * CitrineOS's docker stack ships a Hasura sidecar that does expose all of it. + * Three things decided against it, and the first one is NOT the metadata: yes, + * Hasura tracks no table until metadata is applied and that metadata lives in + * the CitrineOS repository, but its metadata API (`pg_track_table`) would let + * `provision` track the eight tables itself, vendoring nothing. + * + * 1. IT WOULD NOT DECOUPLE US FROM THE SCHEMA. Hasura derives its field names + * from column names, so the v1.9.1 -> v2 rename of the OCPP connection + * column (see variant.ts) would have broken exactly these queries in + * exactly the same way. It is a different syntax for the same coupling, + * not an abstraction over it. + * 2. HASURA IS PART OF THEIR DEV COMPOSE, NOT THEIR PRODUCT. Depending on it + * would mean testing "CitrineOS plus a particular sidecar", and a target + * deployment may well not run one. Postgres is definitionally present. + * 3. It costs another pinned image, another published port, and another + * authentication story. + * + * The one thing it would genuinely buy is remote testability -- GraphQL is + * plain HTTP, whereas the transport below needs `docker exec` and therefore a + * driver running on the host that owns the containers, the same cost + * drivers/steve/records.ts pays and documents. That trade becomes worth making + * the day someone needs to point this driver at a CitrineOS they do not own, + * and when it does, `raw()` below is the only thing that has to change. + * + * MEASURED COST OF THIS TRANSPORT: ~350 ms per query, dominated by the + * `docker exec` process spawn. Worth knowing before optimising the wrong + * thing -- the cheap fix is a persistent psql session fed on stdin, not a + * different database API. + */ +import { + type CsmsChargingProfileRecords, + type CsmsRecords, +} from "../../tck/driver"; +import { waitForCondition } from "../../tck/wait"; +import type { CitrineConfig } from "./config"; +import { stationColumn } from "./variant"; +import { refByDescription } from "./profiles"; + +/** + * Single-quoted SQL literal, for PostgreSQL. + * + * Only the quote is doubled, and unlike the MariaDB sibling in + * drivers/steve/records.ts the backslash is deliberately left alone: + * PostgreSQL has had `standard_conforming_strings = on` by default since 9.1, + * so a backslash inside `'...'` is an ordinary character. Escaping it would + * corrupt any value containing one. `psql -X` below is what keeps that true -- + * it skips ~/.psqlrc, so no local file can turn the setting off underneath us. + */ +export function sqlLiteral(value: string): string { + return `'${value.replace(/'/g, "''")}'`; +} + +/** + * `Omit` rather than `CsmsRecords`, and the Omit + * is the declaration of the gap: `reservations` is a capability this CSMS does + * not have for OCPP 1.6, so the runner substitutes tck/capabilities.ts's + * throwing stub and the scenarios that need it report NOT APPLICABLE. Keeping + * the rest of the interface checked is the point -- an `implements` dropped + * altogether would stop catching a renamed method. + */ +export class CitrineRecords implements Omit { + /** `AND "tenantId" = n`, spelled once. Every table below carries the column, + * and omitting it would read another tenant's rows as this tenant's. */ + private readonly tenant: string; + + /** + * The quoted column holding the OCPP connection name, for the declared + * variant -- `"ocppConnectionName"` on v2, `"stationId"` on v1.9.1. See + * variant.ts for why this is declared rather than detected, and for the trap + * that makes `stationId`'s mere presence useless as a discriminator. + * + * Unqualified. Every call site below is either single-table or joins only + * `Authorizations`, which carries neither name, so it cannot be ambiguous -- + * and if a future schema made it so, Postgres would raise "column reference + * is ambiguous" rather than pick one silently. + */ + private readonly station: string; + + constructor(private readonly cfg: CitrineConfig) { + this.tenant = String(cfg.tenantId); + this.station = `"${stationColumn(cfg.variant)}"`; + } + + /** Runs SQL, returns stdout verbatim. The single path to the database. */ + private async raw(sql: string): Promise { + const proc = Bun.spawn( + [ + "docker", + "exec", + "-i", + // `-e NAME` without a value forwards the variable from OUR environment. + // `-e NAME=VALUE` would put the password in docker's own argv, where + // `ps` shows it to every user on the host. + "-e", + "PGPASSWORD", + this.cfg.dbContainer, + "psql", + // -q quiet, -t tuples only, -A unaligned, -X skip ~/.psqlrc. + // -X is load-bearing twice over: it pins standard_conforming_strings + // for sqlLiteral above, and it pins the NULL rendering to the default + // empty string, which nullSafe's absence below depends on. + "-qtAX", + // Tab, so a multi-column row can be split without smuggling a + // delimiter through a concatenation. Postgres's unaligned default is + // '|', which appears in ordinary text far more often than a tab does. + "-F", + "\t", + "-v", + "ON_ERROR_STOP=1", + "-U", + this.cfg.dbUser, + "-d", + this.cfg.dbName, + "-c", + sql, + ], + { + stdout: "pipe", + stderr: "pipe", + env: { ...process.env, PGPASSWORD: this.cfg.dbPass }, + }, + ); + const [stdout, stderr, exitCode] = await Promise.all([ + new Response(proc.stdout).text(), + new Response(proc.stderr).text(), + proc.exited, + ]); + if (exitCode !== 0) { + throw new Error( + `citrineos db query failed (exit ${exitCode}): ${stderr.trim() || ""}`, + ); + } + return stdout; + } + + /** + * Runs SQL, returns the first column of the first row ("" if no rows). + * + * There is no `nullSafe` counterpart to SteVe's here, and that is a fact + * about psql rather than an omission: `-t -A` renders a SQL NULL as the + * empty string, so an unset stop timestamp already arrives as the "" that + * assertNonEmpty must fail on. MariaDB prints the four characters "NULL", + * which is why the other driver needs the extra step. + */ + async scalar(sql: string): Promise { + return (await this.raw(sql)).split("\n")[0]?.trim() ?? ""; + } + + /** Runs SQL, returns every row as its list of columns ([] if no rows). */ + async rows(sql: string): Promise { + return (await this.raw(sql)) + .split("\n") + .filter((line) => line !== "") + .map((line) => line.split("\t")); + } + + /** + * The transaction joined to the Authorization it was started with. + * + * The join is sound for an OPEN transaction, not only a closed one: + * createTransactionByStartTransaction looks the Authorization up by + * `idToken = request.idTag` and stores its id on the row at creation time + * (packages/core/src/dal/layers/sequelize/repository/TransactionEvent.ts). + * It stores NULL for an unknown tag, which is why every use below is a LEFT + * JOIN or an explicit inner join on a tag the fixtures provide. + */ + private static readonly TX_AUTH_JOIN = + 'FROM "Transactions" t JOIN "Authorizations" a ON a.id = t."authorizationId"'; + + async latestTransaction(cpId: string): Promise { + return this.scalar( + `SELECT t.id FROM "Transactions" t + WHERE ${this.station} = ${sqlLiteral(cpId)} AND t."tenantId" = ${this.tenant} + ORDER BY t.id DESC LIMIT 1;`, + ); + } + + /** + * Binds a scenario's later assertions to the transaction ITS OWN drive() + * created. latestTransaction() takes the newest row regardless of tag or + * state, which on a reused charge point can pick up a stale closed + * transaction from an earlier run instead of the racing in-progress one. + */ + async waitForActiveTransaction( + cpId: string, + idTag: string, + timeoutSecs = 15, + ): Promise { + return waitForCondition( + () => + this.scalar( + `SELECT t.id ${CitrineRecords.TX_AUTH_JOIN} + WHERE ${this.station} = ${sqlLiteral(cpId)} AND t."tenantId" = ${this.tenant} + AND a."idToken" = ${sqlLiteral(idTag)} AND t."isActive" IS TRUE + ORDER BY t.id DESC LIMIT 1;`, + ), + { + timeoutMs: timeoutSecs * 1000, + intervalMs: 1_000, + description: `active transaction on ${cpId} (idToken=${idTag})`, + }, + ); + } + + /** + * The OCPP integer transactionId behind a ref. + * + * Not part of CsmsRecords: it is the translation `requests.ts` needs to turn + * this driver's row key into the number RemoteStopTransaction and a TxProfile + * put on the wire. CitrineOS mints it from a per-station sequence, so it is + * neither the primary key nor globally unique -- assuming the two were the + * same number, as they happen to be in SteVe, would stop a transaction that + * belongs to a different station. + */ + async ocppTransactionId(ref: string): Promise { + if (ref === "") { + throw new Error( + "citrineos: no transaction to reference -- the scenario's own lookup came back empty", + ); + } + const raw = await this.scalar( + `SELECT t."transactionId" FROM "Transactions" t + WHERE t.id = ${sqlLiteral(ref)}::int AND t."tenantId" = ${this.tenant};`, + ); + if (!/^\d+$/.test(raw)) { + throw new Error( + `citrineos: transaction ${ref} has no numeric OCPP transactionId (got ${JSON.stringify(raw)})`, + ); + } + return Number(raw); + } + + /** + * Returns one charge point to the state a scenario may assume, before its + * container starts. Idempotent, and a WRITE -- hence a lifecycle hook rather + * than part of CsmsRecords. One `docker exec`, because psql runs a + * semicolon-separated script in a single implicit transaction. + * + * Two pieces of per-station residue, both of which a previous scenario in + * the same sweep can leave behind on a charge point id the pool then hands + * to the next one: + * + * 1. AN OPEN TRANSACTION. Same job as SteVe's closeStaleTransaction. It + * writes the summary columns on `Transactions` and deliberately does NOT + * fabricate a `StopTransactions` row: that table holds what the charge + * point actually sent, and inventing an entry would put a StopTransaction + * that never happened in front of anyone reading the database afterwards. + * `endTime` is CitrineOS's own bookkeeping, and setting it is true -- + * this driver did end the transaction. + * + * 2. THE LOCAL AUTHORISATION LIST VERSION, which is the non-obvious one. + * LocalAuthListService rejects a SendLocalList whose listVersion is not + * strictly greater than the station's stored versionNumber, throwing + * before anything reaches the wire. Four scenarios send listVersion 1, so + * the second of them to land on a given charge point would be refused by + * the CSMS -- and would look exactly like a charge point that ignored the + * request. Clearing the row restores "this station has no local list", + * which is what every one of those scenarios assumes. + */ + async prepareStation(cpId: string): Promise { + const cp = sqlLiteral(cpId); + const t = this.tenant; + await this.scalar( + [ + `UPDATE "Transactions" SET "isActive" = false, + "endTime" = COALESCE("endTime", NOW()), + "stoppedReason" = COALESCE("stoppedReason", 'Local'), + "updatedAt" = NOW() + WHERE ${this.station} = ${cp} AND "tenantId" = ${t} AND "isActive" IS TRUE;`, + // Join rows before their parents: both carry a foreign key. + `DELETE FROM "LocalListVersionAuthorizations" WHERE "localListVersionId" IN + (SELECT id FROM "LocalListVersions" WHERE ${this.station} = ${cp} AND "tenantId" = ${t});`, + `DELETE FROM "SendLocalListAuthorizations" WHERE "sendLocalListId" IN + (SELECT id FROM "SendLocalLists" WHERE ${this.station} = ${cp} AND "tenantId" = ${t});`, + `DELETE FROM "SendLocalLists" WHERE ${this.station} = ${cp} AND "tenantId" = ${t};`, + `DELETE FROM "LocalListVersions" WHERE ${this.station} = ${cp} AND "tenantId" = ${t};`, + ].join("\n"), + ); + } + + /** + * One column off the transaction row, joined to what the charge point sent. + * + * The three public readers below differ only in that expression, so the + * guard, the joins and the tenant-scoped WHERE live here once -- a fix to any + * of them would otherwise have to land in three places. + */ + private txScalar(tx: string, expr: string): Promise { + if (tx === "") return Promise.resolve(""); + return this.scalar( + `SELECT ${expr} + FROM "Transactions" t + LEFT JOIN "Authorizations" a ON a.id = t."authorizationId" + LEFT JOIN "StopTransactions" st ON st."transactionDatabaseId" = t.id + WHERE t.id = ${sqlLiteral(tx)}::int AND t."tenantId" = ${this.tenant};`, + ); + } + + async transactionIdTag(tx: string): Promise { + return this.txScalar(tx, 'COALESCE(a."idToken", st."idTokenValue")'); + } + + /** + * StopTransactions.timestamp first, Transactions.endTime second. + * + * The order is not arbitrary: the first is the instant the CHARGE POINT + * reported, straight off the wire, and the second is CitrineOS's own summary + * -- which is also what prepareStation above writes. Preferring the wire + * value means a scenario that asserts a transaction closed is answered by the + * charge point wherever the charge point answered. + */ + async transactionStopTimestamp(tx: string): Promise { + return this.txScalar(tx, 'COALESCE(st."timestamp", t."endTime")'); + } + + async transactionStopReason(tx: string): Promise { + return this.txScalar(tx, 'COALESCE(st."reason", t."stoppedReason")'); + } + + async transactionCountForIdTag(cpId: string, idTag: string): Promise { + return this.scalar( + `SELECT COUNT(*) ${CitrineRecords.TX_AUTH_JOIN} + WHERE ${this.station} = ${sqlLiteral(cpId)} AND t."tenantId" = ${this.tenant} + AND a."idToken" = ${sqlLiteral(idTag)};`, + ); + } + + /** + * Deliberately absent: `reservations`. + * + * The runner substitutes tck/capabilities.ts's throwing stub, so the + * scenarios read identically and the absence surfaces as NOT APPLICABLE. It + * is structural rather than an unverifiable() sentinel because CitrineOS + * cannot SEND ReserveNow over OCPP 1.6 at all (see requests.ts), so there is + * never a reservation to have an opinion about -- the `Reservations` table + * exists but nothing for 1.6 ever writes it. + */ + + readonly chargingProfiles: CsmsChargingProfileRecords = { + // Resolved from this driver's own fixture catalogue, not from the database. + // profiles.ts explains why CitrineOS has nothing to look this up in. + refByDescription: async (description: string) => refByDescription(description), + }; +} diff --git a/drivers/citrineos/requests.ts b/drivers/citrineos/requests.ts new file mode 100644 index 0000000..4b164b4 --- /dev/null +++ b/drivers/citrineos/requests.ts @@ -0,0 +1,330 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * requests.ts -- one CsmsOperation, one CitrineOS message-API call. + * + * CitrineOS's outbound surface is generated from the OCPP schemas themselves: + * `AbstractModuleApi._toMessagePath` builds + * `/ocpp/1.6//` and validates the body against + * `OCPP1_6.RequestSchema` before dispatching. So the mapping below is + * almost the identity -- the request bodies ARE the OCPP payloads, which is + * exactly the shape the neutral vocabulary was derived from. + * + * Almost. Three places need real work, and each is a fact about CitrineOS: + * + * - THE MODULE PREFIX IS NOT DERIVABLE FROM THE ACTION. RemoteStart/Stop and + * UnlockConnector live under `evdriver` rather than `transactions`; + * GetDiagnostics lives under `reporting`. There is no rule, only a table + * (apps/ocpp-server/src/config/envs/docker.ts), so it is spelled out here. + * - REFS ARE NOT WIRE VALUES. A TransactionRef is this driver's own row key + * and has to be resolved to the OCPP integer transactionId; a + * ChargingProfileRef expands to the whole inline profile. See + * {@link CitrineRefs}. + * - RESERVATIONS DO NOT EXIST HERE AT ALL. See the two throwing cases. + */ +import { + UnsupportedOperationError, + assertNever, + type ChargingProfileRef, + type CsmsOperation, + type TransactionRef, +} from "../../tck/driver"; +import { profileByRef, type CsChargingProfile } from "./profiles"; +import { + NO_RESERVATIONS, + unroutedActions, + type CitrineVariant, +} from "./variant"; + +/** The endpointPrefix values CitrineOS's shipped `docker` config declares. */ +export type CitrineModule = + | "configuration" + | "evdriver" + | "reporting" + | "smartcharging"; + +export interface CitrineRequest { + module: CitrineModule; + /** The path segment, i.e. the OCPP action with a lowercased first letter. */ + action: string; + body: Record; +} + +/** + * How an opaque ref becomes something CitrineOS will accept. + * + * `ocppTransactionId` is async because it is a database lookup: this driver's + * TransactionRef is `Transactions.id`, the serial primary key, while the wire + * carries `Transactions.transactionId`, the value CitrineOS handed the charge + * point in StartTransaction.conf. The two are different columns and, unlike + * SteVe's, different numbers. + */ +export interface CitrineRefs { + ocppTransactionId(ref: TransactionRef): Promise; +} + + +/** + * An OCPP request body with the `undefined` members dropped. + * + * Replaces seventeen copies of `...(x === undefined ? {} : { k: x })`, and the + * mechanical detail matters: Object.entries/fromEntries preserve insertion + * order for string keys, which SendLocalList depends on -- TC_043.5 asserts the + * raw bytes `"listVersion":2,"localAuthorizationList":[{"idTag":...` against the + * simulator's received line, so reordering these members turns that scenario + * red for a reason unrelated to local lists. + * + * Only `undefined` is dropped. `""` is a defined value and still reaches + * profileFor(), which is what keeps "absent" and "the lookup found nothing" + * distinguishable -- see RemoteStartTransaction below. + */ +function body(fields: Record): Record { + return Object.fromEntries( + Object.entries(fields).filter(([, value]) => value !== undefined), + ); +} + +/** The inline profile a ref names, or a hard failure naming the ref. */ +function profileFor(ref: ChargingProfileRef): CsChargingProfile { + const profile = profileByRef(ref); + if (!profile) { + // Deliberately NOT UnsupportedOperationError: CitrineOS can express this + // operation perfectly well. An unknown ref means `ocpp-tck driver provision` + // did not run, or profiles.ts and the scenario disagree about a name -- + // an environment fault, and reporting it as a capability gap would file it + // against the CSMS. + throw new Error( + `citrineos: no provisioned charging profile for ref ${JSON.stringify(ref)} ` + + "-- did `ocpp-tck driver provision` run?", + ); + } + return profile; +} + +export async function toCitrineRequest( + op: CsmsOperation, + refs: CitrineRefs, + variant: CitrineVariant, +): Promise { + // An action this variant does not route must never be POSTed to a 404, so it + // throws here and the runner turns it into NOT APPLICABLE. The reason comes + // from variant.ts rather than being re-derived from the action, which is what + // keeps this escape and the scope table saying the same thing. + const unrouted = unroutedActions(variant).get(op.action); + if (unrouted !== undefined) { + throw new UnsupportedOperationError(op.action, unrouted); + } + switch (op.action) { + case "Reset": + return { module: "configuration", action: "reset", body: { type: op.type } }; + + case "UnlockConnector": + return { + module: "evdriver", + action: "unlockConnector", + body: { connectorId: op.connectorId }, + }; + + case "ClearCache": + return { module: "evdriver", action: "clearCache", body: {} }; + + case "ChangeAvailability": + return { + module: "configuration", + action: "changeAvailability", + body: { connectorId: op.connectorId, type: op.type }, + }; + + case "GetConfiguration": + // Absent `key` means every key, which is what OCPP 1.6 says an omitted + // list means -- so an absent one is omitted rather than sent as []. + return { + module: "configuration", + action: "getConfiguration", + body: op.keys?.length ? { key: op.keys } : {}, + }; + + case "ChangeConfiguration": + return { + module: "configuration", + action: "changeConfiguration", + body: { key: op.key, value: op.value }, + }; + + case "RemoteStartTransaction": + return { + module: "evdriver", + action: "remoteStartTransaction", + // `undefined` means "start without a profile"; `""` means the + // scenario's lookup found none, and those are not the same request. + // body() drops only `undefined`, so `""` still reaches profileFor(), + // which rejects it loudly -- TC_059, whose whole assertion is that the + // attached profile is NOT applied, would otherwise pass for a reason + // that never happened. + body: body({ + connectorId: op.connectorId, + idTag: op.idTag, + chargingProfile: + op.chargingProfile === undefined + ? undefined + : profileFor(op.chargingProfile), + }), + }; + + case "RemoteStopTransaction": + return { + module: "evdriver", + action: "remoteStopTransaction", + body: { transactionId: await refs.ocppTransactionId(op.transaction) }, + }; + + case "TriggerMessage": + // connectorId is omitted rather than sent as 0 for a station-wide + // trigger: CitrineOS rejects `connectorId <= 0` locally, without putting + // anything on the wire, and the scenario asserts on the wire. + return { + module: "configuration", + action: "triggerMessage", + body: body({ + requestedMessage: op.requestedMessage, + connectorId: op.connectorId, + }), + }; + + case "SetChargingProfile": { + const profile = profileFor(op.chargingProfile); + // A TxProfile is scoped to a running transaction by carrying its OCPP + // transactionId INSIDE the profile, not beside it. An empty ref means + // the scenario's own lookup came back empty; sending the profile + // unscoped is closer to what was asked than refusing to send it, and the + // scenario's assertions are what decide whether that was good enough. + const transactionId = + op.transaction === undefined || op.transaction === "" + ? undefined + : await refs.ocppTransactionId(op.transaction); + return { + module: "smartcharging", + action: "setChargingProfile", + body: { + connectorId: op.connectorId, + csChargingProfiles: + transactionId === undefined ? profile : { ...profile, transactionId }, + }, + }; + } + + case "GetCompositeSchedule": + return { + module: "smartcharging", + action: "getCompositeSchedule", + body: body({ + connectorId: op.connectorId, + duration: op.duration, + chargingRateUnit: op.chargingRateUnit, + }), + }; + + case "ClearChargingProfile": + // Every member is optional in OCPP 1.6, and an omitted one is a wildcard. + // Sending `id: null` for an absent ref would not be the same request. + // + // Same `undefined` vs `""` distinction as RemoteStartTransaction above, + // and the consequence here is worse: an empty ref treated as absent + // becomes a WILDCARD clear, so TC_067 would see its profile removed by a + // request that named nothing and still pass. + return { + module: "smartcharging", + action: "clearChargingProfile", + body: body({ + id: + op.chargingProfile === undefined + ? undefined + : profileFor(op.chargingProfile).chargingProfileId, + connectorId: op.connectorId, + chargingProfilePurpose: op.purpose, + stackLevel: op.stackLevel, + }), + }; + + case "UpdateFirmware": + // toISOString() and not a local rendering: CitrineOS validates this + // against `format: date-time` and forwards the string verbatim, so + // there is no minute-resolution form to round up for here -- the + // rounding rule in tck/driver.ts exists for CSMSs that have one. + return { + module: "configuration", + action: "updateFirmware", + body: body({ + location: op.location, + retrieveDate: op.retrieveDate.toISOString(), + retries: op.retries, + retryInterval: op.retryInterval, + }), + }; + + case "GetDiagnostics": + return { + module: "reporting", + action: "getDiagnostics", + body: body({ + location: op.location, + retries: op.retries, + retryInterval: op.retryInterval, + startTime: op.startTime?.toISOString(), + stopTime: op.stopTime?.toISOString(), + }), + }; + + case "GetLocalListVersion": + return { module: "evdriver", action: "getLocalListVersion", body: {} }; + + case "SendLocalList": + // Unlike SteVe's manager UI, which carries tag NAMES only, this path is + // lossless: status, expiryDate and parentIdTag all reach the wire. + // + // KEY ORDER IS DELIBERATE. CitrineOS forwards the parsed body to + // sendCall, so this object's insertion order is the order the charge + // point receives -- and TC_043.5 asserts + // /"listVersion":2,"localAuthorizationList":\[\{"idTag":"CERT-TAG-2"/ + // against the simulator's raw received line. Reordering these three + // members turns that scenario red for a reason that has nothing to do + // with local lists. + // + // An entry with no status carries no idTagInfo at all, which is not the + // same as carrying an empty one: in a Differential update, OCPP 1.6 + // reads an AuthorizationData without idTagInfo as "remove this tag". + // Inventing a status would silently change what the scenario asked for. + return { + module: "evdriver", + action: "sendLocalList", + body: body({ + listVersion: op.listVersion, + localAuthorizationList: (op.localAuthorizationList ?? []).map((entry) => + body({ + idTag: entry.idTag, + idTagInfo: + entry.status === undefined + ? undefined + : body({ + status: entry.status, + expiryDate: entry.expiryDate?.toISOString(), + parentIdTag: entry.parentIdTag, + }), + }), + ), + updateType: op.updateType, + }), + }; + + case "ReserveNow": + case "CancelReservation": + // Unreachable: the guard above throws for every unrouted action, and + // these two are unrouted on both variants. The arms exist so the switch + // stays exhaustive -- deleting them breaks assertNever's compile-time + // check, not the runtime. + throw new UnsupportedOperationError(op.action, NO_RESERVATIONS); + + default: + return assertNever(op, "citrineos.execute"); + } +} diff --git a/drivers/citrineos/scope.ts b/drivers/citrineos/scope.ts new file mode 100644 index 0000000..eece83a --- /dev/null +++ b/drivers/citrineos/scope.ts @@ -0,0 +1,244 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * scope.ts -- what CitrineOS can drive, and what it demonstrably cannot. + * + * This is the first table in the repository with NOT_APPLICABLE rows, which is + * the point of having a second driver at all: SteVe's table claims every + * scenario because the scenarios were written against SteVe, so until now the + * machinery that reports a scenario as out of scope had never fired. + * + * Every status below was settled by a real sweep against the pinned image, not + * by reading sources -- 44 + 3 scenarios, 2026-08-11; VENDOR.md carries the + * numbers. The seven NOT_APPLICABLE rows were predicted from the sources first + * and then confirmed against a running container, whose /docs/json advertises + * 18 `/ocpp/1.6/` paths with neither `reserveNow` nor `cancelReservation` + * among them. + * + * TWO ROWS ARE DRIVABLE AND CURRENTLY RED, ON PURPOSE. `tck/scope.ts` forbids + * demoting a row to NOT_APPLICABLE to make a red scenario go away, because + * that converts a finding about the CSMS into a silence about the harness. + * Both are findings against CitrineOS rather than gaps in this driver, and + * both are named in drivers/citrineos/README.md's gap table. A TCK whose + * second driver reports 100% green is a TCK that has stopped measuring. + */ +import type { ScopeEntry, ScopeTable } from "../../tck/scope"; +import { + NO_LOCAL_LIST, + NO_RESERVATIONS, + V1_LOCAL_LIST_SCENARIOS, + type CitrineVariant, +} from "./variant"; + +/** The ordinary case: driven and green against the pinned image. */ +const OBSERVED = + "Driven green against the pinned CitrineOS image: the 1.6 message API " + + "expresses the operation and Postgres answers the observation."; + +const d = (reason: string) => ({ status: "DRIVABLE" as const, reason }); +const na = (reason: string) => ({ status: "NOT_APPLICABLE" as const, reason }); + +const V2_SCOPE: ScopeTable = { + // --- Reservation: the whole capability is absent for OCPP 1.6 ----------- + "cert16-reservation-basic": na(NO_RESERVATIONS), + "cert16-tc048-1-reserve-now-faulted": na(NO_RESERVATIONS), + "cert16-tc048-2-reserve-now-occupied": na(NO_RESERVATIONS), + "cert16-tc048-3-reserve-now-unavailable": na(NO_RESERVATIONS), + "cert16-tc048-4-reserve-now-rejected": na(NO_RESERVATIONS), + "cert16-tc051-cancel-reservation": na(NO_RESERVATIONS), + "cert16-tc052-cancel-reservation-rejected": na(NO_RESERVATIONS), + + // --- Core ---------------------------------------------------------------- + "cert16-tc001-cold-boot": d(OBSERVED), + "cert16-tc003-charging-plugin-first": d( + "Driven green. StartTransaction needs a Connectors row matching the OCPP " + + "connectorId -- createTransactionByStartTransaction throws without one " + + "-- and CitrineOS auto-commissions it from the StatusNotification the " + + "charge point sends first.", + ), + "cert16-tc004-charging-id-first": d(OBSERVED), + "cert16-tc005-ev-side-disconnect": d(OBSERVED), + "cert16-tc013-hard-reset": d(OBSERVED), + "cert16-tc014-soft-reset": d(OBSERVED), + "cert16-tc021-change-configuration": d(OBSERVED), + "cert16-tc024-lock-failure": d(OBSERVED), + "cert16-tc061-clear-cache": d(OBSERVED), + "cert16-tc064-data-transfer": d(OBSERVED), + + // --- GetConfiguration ---------------------------------------------------- + // The batching worry did not materialise: CitrineOS splits a request into + // batches of the station's stored GetConfigurationMaxKeys, but an + // unprovisioned station has no such value and the request stays one + // GetConfiguration on the wire, which is what the scenarios assert. + "cert16-tc019-get-configuration-all": d(OBSERVED), + "cert16-tc019-get-configuration-key": d(OBSERVED), + + // --- UnlockConnector ----------------------------------------------------- + // CitrineOS ships no 1.6 response handler for UnlockConnector, so the + // CallResult is answered with a NotSupported CALLERROR. Harmless here, and + // measured rather than assumed: the scenarios assert on the simulator's wire + // log, and the charge point carries on. + "cert16-tc017-unlock-occupied": d(OBSERVED), + "cert16-tc018-unlock-failure": d(OBSERVED), + "cert16-tc031-unlock-unknown-connector": d(OBSERVED), + + // --- Authorize outcomes -------------------------------------------------- + "cert16-tc023-1-authorize-invalid": d(OBSERVED), + "cert16-tc023-2-authorize-expired": d( + "Driven green. The fixture is provisioned as status Accepted with a past " + + "cacheExpiryDateTime, because AuthorizeRequestOcpp16Handler consults the " + + "expiry only inside its Accepted branch -- a row stored as Expired would " + + "answer Invalid.", + ), + "cert16-tc023-3-authorize-blocked": d( + "DRIVABLE AND CURRENTLY RED, deliberately: CitrineOS answers " + + '{"idTagInfo":{"status":"Invalid"}} where the scenario requires Blocked ' + + "(observed 3 runs out of 3). AuthorizeRequestOcpp16Handler reaches its " + + "status mapper only through the `status === Accepted` branch, so a stored " + + "Blocked falls through to the default Invalid; the only route to a real " + + "Blocked is an IAuthorizer, and container.ts registers " + + "`authorizers: asValue([])` with no setting that changes it. This is a " + + "finding against CitrineOS, not a gap in this driver -- demoting it to " + + "NOT_APPLICABLE would hide it. See tck/scope.ts.", + ), + + // --- RemoteTrigger ------------------------------------------------------- + "cert16-tc010-remote-start": d(OBSERVED), + "cert16-tc011-remote-start-stop": d(OBSERVED), + "cert16-tc012-remote-stop": d(OBSERVED), + "cert16-tc026-remote-start-rejected": d(OBSERVED), + "cert16-tc028-remote-stop-rejected": d( + "Driven green, including waitForActiveTransaction: CitrineOS populates " + + "Transactions.authorizationId at creation time, so an OPEN transaction " + + "resolves to its idTag through the Authorizations join.", + ), + "cert16-tc054-trigger-message": d(OBSERVED), + "cert16-tc055-trigger-message-rejected": d(OBSERVED), + + // --- SmartCharging ------------------------------------------------------- + // The charging profiles are this driver's own catalogue rather than CSMS + // records (see profiles.ts), and the sweep confirms the consequence that + // mattered: the simulator logs `Applied charging profile #56`, so the ref + // really is the chargingProfileId that reached the wire. + "cert16-tc056-central-smart-charging-txdefault": d(OBSERVED), + "cert16-tc057-central-smart-charging-txprofile": d( + "Driven green, including the TxProfile's transactionId, which this driver " + + "resolves from Transactions.transactionId rather than from the row key -- " + + "CitrineOS mints the two independently.", + ), + "cert16-tc059-remote-start-with-profile": d(OBSERVED), + "cert16-tc066-get-composite-schedule": d( + 'Driven green, including the "limit":11000 assertion on the returned ' + + "composite schedule -- so profiles.ts's inline schedule reaches the " + + "charge point intact.", + ), + "cert16-tc067-clear-charging-profile": d(OBSERVED), + + // --- LocalAuthListManagement -------------------------------------------- + // Drivable only from the v2 line: the 1.6 GetLocalListVersion and + // SendLocalList endpoints do not exist at v1.9.1. compose.yaml pins + // v2.0.0-beta1 for exactly these six rows; README.md documents what pinning + // v1.9.1 instead would cost. + "cert16-tc042-1-get-local-list-version-not-supported": d(OBSERVED), + "cert16-tc042-2-get-local-list-version-empty": d(OBSERVED), + "cert16-tc043-1-send-local-list-not-supported": d( + "Driven green. LocalAuthListService refuses a listVersion not strictly " + + "greater than the station's stored one, before anything reaches the wire; " + + "prepareStation clears that row per run, which is what lets four " + + "scenarios all send listVersion 1 to the same charge point id.", + ), + "cert16-tc043-3-send-local-list-failed": d(OBSERVED), + "cert16-tc043-4-send-local-list-full": d(OBSERVED), + "cert16-tc043-5-send-local-list-differential": d( + "Driven green, including the wire-byte assertion on " + + '`"listVersion":2,"localAuthorizationList":[{"idTag":...` -- so CitrineOS ' + + "forwards this driver's JSON key order unchanged. See requests.ts.", + ), + + // --- FirmwareManagement -------------------------------------------------- + // CitrineOS registers no 1.6 request handler for FirmwareStatusNotification + // and answers every one with a NotSupported CALLERROR -- 9 of them across the + // three TC_044 logs, and the only CALLERROR the CSMS sends anywhere in the + // captured suite. + // + // TWO OF THESE ROWS ARE GREEN AND MUST NOT BE READ AS "CONFORMANT". OCA + // TC_044_{1,2,3}_CSMS put steps 4 and 6 on the Central System: "The Central + // responds with a FirmwareStatusNotification.conf". A CALLERROR is not that + // conf, so CitrineOS does not do what those test cases require. Our scenarios + // pass anyway because they assert only on the statuses the CHARGE POINT sent, + // never on the CSMS's answer to them. That is a gap in the SCENARIOS, not + // evidence about CitrineOS -- see drivers/citrineos/README.md. + "cert16-tc044-1-firmware-update": d( + "Driven green on isolated retry, but it flaked in the parallel pass of " + + "both recorded runs: retrieveDate is +90s against a 115s hold, leaving " + + "~25s for the status train, which is the second thinnest margin in the " + + "suite. A timing property of the scenario, not a CitrineOS limitation.", + ), + "cert16-tc044-2-firmware-download-failed": d( + "Driven green, but the FLAKIEST scenario here: 1 pass in 3 runs, and it " + + "failed its isolated retry in both recorded sweeps. Thinnest margin of " + + "all -- retrieveDate is +90s against a 110s hold, so only ~20s remain -- " + + "and on the failures the socket dropped (1006) just after CitrineOS's " + + "NotSupported CALLERROR, costing a reconnect and a reboot that lose the " + + "firmware state. Which side closes the socket is NOT established: the " + + "obvious suspect is that CALLERROR, and it is wrong, because TC_044.1 " + + "and TC_044.3 take four of them each without disconnecting. Do not cite " + + "this as a CitrineOS defect until it is established.", + ), + "cert16-tc044-3-firmware-install-failed": d(OBSERVED), + "cert16-tc045-1-get-diagnostics": d( + "Driven green. Unlike UpdateFirmware, GetDiagnostics does have a 1.6 " + + "response handler, and DiagnosticsStatusNotification has a 1.6 request " + + "handler -- so nothing here is answered with a CALLERROR.", + ), +}; + +/** + * The v1.9.1 table, derived from V2_SCOPE rather than written out again. + * + * Two edits, and the second one matters more than it looks. The six + * local-auth-list rows become NOT_APPLICABLE, from the id list in variant.ts so + * the table and `unroutedActions` cannot disagree. And EVERY INHERITED REASON + * IS REPLACED, because V2_SCOPE's reasons say "driven green against the pinned + * image" and that measurement was taken on v2 -- carrying the sentence over + * would make this table assert a run that never happened on this line. + * + * The v1.9.1 line has a defect that most of the suite depends on, so a blanket + * "driven green" would be wrong twice over. See V1_KNOWN. + */ +/** + * Still DRIVABLE, and deliberately not demoted: the driver expresses every one + * of these operations against v1.9.1 exactly as it does against v2. What fails + * is the CSMS, on a defect that is upstream issue citrineos/citrineos#160 -- + * the Connector model requires non-null evseId / evseTypeConnectorId, so a 1.6 + * StatusNotification from an ad-hoc station cannot create a Connectors row, and + * without one every StartTransaction is answered Invalid with transactionId 0. + * Measured: 3 ChargingStations, 0 Connectors, 0 Transactions after a full + * sweep. The issue was closed 2026-05-19, after v1.9.1 shipped on 2026-04-29, + * and the fix is in the v2 line only. + * + * Demoting these to NOT_APPLICABLE would convert a reproducible CSMS defect + * into silence about the harness, which tck/scope.ts forbids. VENDOR.md carries + * the run. + */ +const V1_KNOWN = + "Expressible on v1.9.1 and driven identically to v2. Scenarios that need a " + + "transaction fail on that line through upstream citrineos/citrineos#160: no " + + "Connectors row can be created for an ad-hoc 1.6 station, so StartTransaction " + + "is answered Invalid. Fixed in the v2 line -- use CITRINE_VARIANT=v2."; + +function v1Scope(): ScopeTable { + const table: Record = {}; + for (const [id, entry] of Object.entries(V2_SCOPE)) { + table[id] = entry.status === "DRIVABLE" ? d(V1_KNOWN) : entry; + } + for (const id of V1_LOCAL_LIST_SCENARIOS) { + table[id] = na(NO_LOCAL_LIST); + } + return table; +} + +/** The scope table for a declared variant. See variant.ts. */ +export function citrineosScope(variant: CitrineVariant): ScopeTable { + return variant === "v2" ? V2_SCOPE : v1Scope(); +} diff --git a/drivers/citrineos/variant.ts b/drivers/citrineos/variant.ts new file mode 100644 index 0000000..c460eb1 --- /dev/null +++ b/drivers/citrineos/variant.ts @@ -0,0 +1,129 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * variant.ts -- the two CitrineOS lines this driver speaks, in one place. + * + * CitrineOS restructured between the v1.x stable line and the v2 prerelease, + * and two of those changes reach this driver. Both were read off running + * containers rather than inferred from release notes: + * + * 1. THE OCPP CONNECTION NAME MOVED COLUMN. `Transactions`, + * `LocalListVersions` and `SendLocalLists` carry it as `stationId` on + * v1.9.1 and as `ocppConnectionName` on v2.0.0-beta1. + * 2. THE 1.6 LOCAL AUTH LIST ENDPOINTS DID NOT EXIST YET. v1.9.1 advertises + * 16 `/ocpp/1.6/` paths, v2.0.0-beta1 advertises 18; the two extra are + * `evdriver/sendLocalList` and `evdriver/getLocalListVersion`. + * + * WHY THIS IS DECLARED AND NOT DETECTED + * ------------------------------------- + * Detecting the column from information_schema would be easy and would even be + * unambiguous -- see the trap below. But the scope table and the capability + * set have to be readable with NO running server and NO credentials, because + * that is the promise `ocpp-tck check-driver` and the pre-flight rest on. A + * driver that had to connect to Postgres before it could say which scenarios + * it can drive would break that promise. + * + * So the variant is declared once, drives all three things, and + * `driver verify` then asserts that the running server agrees. Declare, then + * check -- rather than two sources of truth free to disagree in silence. + * + * THE TRAP, recorded because it is the obvious wrong detection: `stationId` + * exists on `Transactions` in BOTH lines. On v1.9.1 it is `character varying` + * and holds the OCPP name; on v2 it is an `integer` foreign key and the name + * lives in `ocppConnectionName`. Testing for the presence of `stationId` is + * therefore always true and always useless. The presence of + * `ocppConnectionName` is the discriminator, and that is what verify() checks. + */ +import type { CsmsEnv, CsmsOperationAction } from "../../tck/driver"; + +export type CitrineVariant = "v1" | "v2"; + +/** v2 by default: it is what `drivers/citrineos/compose.yaml` pins, and the + * only line with a complete OCPP 1.6 surface. */ +export const DEFAULT_VARIANT: CitrineVariant = "v2"; + +export function resolveVariant(env: CsmsEnv): CitrineVariant { + const raw = env.CITRINE_VARIANT; + if (raw === undefined || raw === "") return DEFAULT_VARIANT; + if (raw === "v1" || raw === "v2") return raw; + throw new Error( + `citrineos: CITRINE_VARIANT must be "v1" or "v2", got ${JSON.stringify(raw)}`, + ); +} + +/** + * The column carrying the OCPP connection name -- the string a charge point + * connects as. Unquoted; callers quote it. + */ +export function stationColumn(variant: CitrineVariant): string { + return variant === "v2" ? "ocppConnectionName" : "stationId"; +} + +/** + * Why the reservation actions are unrouted, worded ONCE. + * + * Both the scope table and the runtime escape have to state this, and they are + * the two halves a reader compares: a scope row saying one thing and an + * UnsupportedOperationError saying another is the drift this module exists to + * prevent. Verified in the sources at v1.9.1, v2.0.0-beta1 and main, and + * against both running containers. + */ +export const NO_RESERVATIONS = + "CitrineOS routes no OCPP 1.6 endpoint for ReserveNow or CancelReservation: " + + "the 1.6 schemas and the Reservations table exist, but no @AsMessageEndpoint " + + "binds either action to OCPPVersion.OCPP1_6 and no 1.6 response handler " + + "exists (verified at v1.9.1, v2.0.0-beta1 and main), so the path answers 404."; + +/** Same, for the local auth list pair, which v1.9.1 alone lacks. */ +export const NO_LOCAL_LIST = + "CitrineOS v1.9.1 routes no OCPP 1.6 endpoint for SendLocalList or " + + "GetLocalListVersion: the evdriver 1.6 MessageApi gained both only on the v2 " + + "line. Measured on the running image -- it advertises 16 /ocpp/1.6/ paths " + + "where v2.0.0-beta1 advertises 18. Drivable with CITRINE_VARIANT=v2 against " + + "a v2 server."; + +/** + * Operations the 1.6 message API does not route on this variant, with the + * reason each one is unrouted. + * + * ReserveNow and CancelReservation are absent from both lines. The local auth + * list pair is absent from v1 only -- and absent means the path answers 404, + * so these must throw UnsupportedOperationError rather than be POSTed. + * + * Built once per variant rather than per call: `index.ts` reads it at module + * load for `capabilities` and `requests.ts` reads it per operation, and two + * independent constructions of the same fact is exactly what this module is + * for. + */ +const UNROUTED: Readonly< + Record> +> = { + v2: new Map([ + ["ReserveNow", NO_RESERVATIONS], + ["CancelReservation", NO_RESERVATIONS], + ]), + v1: new Map([ + ["ReserveNow", NO_RESERVATIONS], + ["CancelReservation", NO_RESERVATIONS], + ["SendLocalList", NO_LOCAL_LIST], + ["GetLocalListVersion", NO_LOCAL_LIST], + ]), +}; + +/** The unrouted actions for a variant, mapped to why. */ +export function unroutedActions( + variant: CitrineVariant, +): ReadonlyMap { + return UNROUTED[variant]; +} + +/** Scenarios the local-auth-list gap costs on v1. Named here rather than in + * scope.ts so the two cannot drift from {@link unroutedActions}. */ +export const V1_LOCAL_LIST_SCENARIOS = [ + "cert16-tc042-1-get-local-list-version-not-supported", + "cert16-tc042-2-get-local-list-version-empty", + "cert16-tc043-1-send-local-list-not-supported", + "cert16-tc043-3-send-local-list-failed", + "cert16-tc043-4-send-local-list-full", + "cert16-tc043-5-send-local-list-differential", +] as const; diff --git a/package.json b/package.json index ea02fe8..8e090d1 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ "bin/", "tck/", "drivers/steve/", + "drivers/citrineos/", "types/", "patches/", "tsconfig.base.json", @@ -99,6 +100,10 @@ "types": "./types/drivers/steve/index.d.ts", "default": "./drivers/steve/index.ts" }, + "./drivers/citrineos": { + "types": "./types/drivers/citrineos/index.d.ts", + "default": "./drivers/citrineos/index.ts" + }, "./tsconfig": "./tsconfig.base.json", "./package.json": "./package.json" }, @@ -106,6 +111,7 @@ "typecheck": "tsc --noEmit", "build:types": "tsc -p tsconfig.build.json", "check:reference-driver": "CSMS_DRIVER=./drivers/steve/index.ts bun bin/ocpp-tck.ts check-driver", + "check:citrineos-driver": "CSMS_DRIVER=./drivers/citrineos/index.ts bun bin/ocpp-tck.ts check-driver", "e2e": "bun bin/ocpp-tck.ts run-all --parallel --retry-failed-isolated; all=$?; bun bin/ocpp-tck.ts run-all --group authorize; auth=$?; exit $(( all || auth ))", "e2e:smoke": "bun bin/ocpp-tck.ts run cert16-tc023-1-authorize-invalid && bun bin/ocpp-tck.ts run cert16-tc023-2-authorize-expired && bun bin/ocpp-tck.ts run cert16-tc023-3-authorize-blocked && bun bin/ocpp-tck.ts run cert16-tc066-get-composite-schedule && bun bin/ocpp-tck.ts run cert16-tc003-charging-plugin-first", "check:fixture-tags": "bash tools/extract-fixture-tags.sh --diff", diff --git a/tsconfig.build.json b/tsconfig.build.json index bd4ae48..54e8d33 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -25,6 +25,6 @@ "emitDeclarationOnly": true, "outDir": "types" }, - "include": ["tck/**/*.ts", "drivers/steve/**/*.ts"], + "include": ["tck/**/*.ts", "drivers/**/*.ts"], "exclude": ["types"] } diff --git a/types/drivers/citrineos/api-client.d.ts b/types/drivers/citrineos/api-client.d.ts new file mode 100644 index 0000000..6d73914 --- /dev/null +++ b/types/drivers/citrineos/api-client.d.ts @@ -0,0 +1,41 @@ +/** + * api-client.ts -- CitrineOS's message API, which is a plain JSON POST. + * + * No authentication is sent, and that is not an omission. CitrineOS's shipped + * `docker` app-env selects `LocalBypassAuthProvider` + * (apps/ocpp-server/src/config/envs/docker.ts, util.authProvider.localByPass), + * whose ApiAuthPlugin hook returns success for every request and synthesises an + * admin principal -- it even logs a warning to that effect on startup. Adding a + * header here would be theatre. A deployment that swapped in the OIDC provider + * would need a real token, and that is a change to this file, not a setting. + * + * WHERE THE THROW LINE IS + * ----------------------- + * The contract forbids throwing for an OCPP-level outcome: a `Rejected` + * CALLRESULT, a CALLERROR, or silence are all normal returns, because every + * scenario asserts on the simulator's captured wire log rather than on this + * call. That is not the same as never throwing. + * + * CitrineOS answers HTTP 200 with `[{"success": false, "payload": "..."}]` for + * several failures where NOTHING REACHED THE WIRE -- an unknown station id, a + * `connectorId <= 0` on TriggerMessage, a schema rejection inside + * sendLocalList's persistence step. Those are request failures wearing a 200, + * and swallowing them would report a scenario as having driven an operation it + * never drove. So `success: false` throws, and the payload travels with it. + */ +import type { CitrineConfig } from "./config"; +import type { CitrineRequest } from "./requests"; +export declare class CitrineMessageApi { + private readonly cfg; + constructor(cfg: CitrineConfig); + private url; + /** + * Dispatches one operation and returns a receipt for the run log. + * + * The receipt is the confirmation array, serialised. Specs must not branch on + * it -- it exists so that a human reading results/ can tell a dispatched + * operation from one the CSMS quietly reshaped, which for GetConfiguration it + * genuinely does (see the batching note below). + */ + send(cpId: string, req: CitrineRequest): Promise; +} diff --git a/types/drivers/citrineos/config.d.ts b/types/drivers/citrineos/config.d.ts new file mode 100644 index 0000000..27b77cb --- /dev/null +++ b/types/drivers/citrineos/config.d.ts @@ -0,0 +1,36 @@ +/** + * config.ts -- every default this driver has, in one place. + * + * The values below resolve to the names in drivers/citrineos/compose.yaml, so + * a stock `docker compose -f drivers/citrineos/compose.yaml up -d --wait` + * needs no environment at all. Renaming anything there means passing the + * matching CITRINE_* variable by hand; index.ts's envHelp is the user-facing + * copy of this table. + * + * Note the asymmetry between `apiUrl` and `wsBaseUrl`, which is not an + * oversight: the driver runs on the HOST (it reaches Postgres through + * `docker exec`) and so talks to `localhost`, while the simulator runs in a + * container on the compose network and talks to `citrine`. One CSMS, two + * addresses, because two different processes are doing the addressing. + */ +import type { CsmsEnv } from "../../tck/driver"; +import { type CitrineVariant } from "./variant"; +export interface CitrineConfig { + /** Which CitrineOS line the target runs. Everything version-specific is + * derived from it rather than stored beside it -- see variant.ts. */ + variant: CitrineVariant; + /** Message-API base, no trailing slash, e.g. http://localhost:8080 */ + apiUrl: string; + /** Every message-API call carries it; CitrineOS's DEFAULT_TENANT_ID is 1. */ + tenantId: number; + /** docker container running CitrineOS's Postgres. */ + dbContainer: string; + dbUser: string; + dbPass: string; + dbName: string; + /** OCPP WebSocket endpoint, without the trailing charge-point id. */ + wsBaseUrl: string; + /** Docker network the simulator must join to reach CitrineOS by name. */ + dockerNetwork: string; +} +export declare function defaultCitrineConfig(env: CsmsEnv): CitrineConfig; diff --git a/types/drivers/citrineos/index.d.ts b/types/drivers/citrineos/index.d.ts new file mode 100644 index 0000000..87e6c4a --- /dev/null +++ b/types/drivers/citrineos/index.d.ts @@ -0,0 +1,38 @@ +/** + * The CitrineOS driver. + * + * CitrineOS (LF Energy / S44) is the second CSMS this harness drives, and the + * first one the scenarios were not written against. That is its job here: an + * abstraction with one implementation is neutral by assertion, and this driver + * is how the assertion gets tested. It reports the answer honestly -- seven + * scenarios are NOT_APPLICABLE because CitrineOS's OCPP 1.6 surface is smaller + * than SteVe's, and scope.ts names the missing endpoint for each. + * + * Why the JSON message API + * ------------------------ + * Unlike SteVe, there is no choice to justify: CitrineOS generates its + * outbound surface from the OCPP schemas themselves, so + * `POST /ocpp/1.6//` IS the way to put a Call on the wire, and + * the request body IS the OCPP payload. The interesting part is what the + * surface omits -- see requests.ts. + * + * Where the observations come from, and where this has to run + * ----------------------------------------------------------- + * Postgres, through `docker exec`, because CitrineOS's REST data endpoints + * expose none of what the scenarios assert on: no latest transaction, no idTag + * on a transaction, no stop reason, no count. records.ts documents the full + * search and why the bundled Hasura sidecar was not used instead. The + * consequence is the same as SteVe's: this driver runs on the host that owns + * the containers, so a remote CitrineOS is out of reach for the record half + * even though the operation half would work over HTTP. + * + * Versions + * -------- + * Both CitrineOS lines are supported, selected by CITRINE_VARIANT and + * defaulting to v2 -- drivers/citrineos/compose.yaml pins v2.0.0-beta1 by + * digest, and compose.v1.yaml overrides it with v1.9.1. v1 costs the six + * local-auth-list scenarios, whose 1.6 endpoints exist only from the v2 line, + * and renames the OCPP connection column. See variant.ts. + */ +import { type CsmsDriverModule } from "../../tck/driver"; +export declare const csmsDriver: CsmsDriverModule; diff --git a/types/drivers/citrineos/profiles.d.ts b/types/drivers/citrineos/profiles.d.ts new file mode 100644 index 0000000..1e971de --- /dev/null +++ b/types/drivers/citrineos/profiles.d.ts @@ -0,0 +1,67 @@ +/** + * profiles.ts -- the pre-provisioned charging profiles, owned by this driver. + * + * THIS IS A FIXTURE CATALOGUE, NOT SCENARIO BRANCHING. It looks like branching + * because the two descriptions below are the ones the SmartCharging scenarios + * name, so it is worth being precise about the difference: a driver may not + * change its BEHAVIOUR based on which scenario is running, but the environment + * every scenario assumes is exactly what `ocpp-tck driver provision` exists to + * create. SteVe's provisioner seeds the same two profiles, under the same two + * descriptions, with the same 11000 W limit -- it just seeds them into SteVe's + * charging_profile table, because SteVe has one. + * + * CitrineOS does not, and does not need one. OCPP 1.6 SetChargingProfile + * carries the whole profile inline (`csChargingProfiles`), so there is nothing + * for a CSMS-side registry to be looked up FROM. Its `ChargingProfiles` table + * is a record of what was sent, written after the fact, and it has no + * `description` or `name` column to look up BY -- verified against + * packages/core/src/dal/layers/drizzle/schema/ChargingProfile.ts. + * + * So `refByDescription` resolves here instead. Two consequences follow, and + * both are load-bearing: + * + * - THE REF IS THE OCPP `chargingProfileId`. It has to be: the scenarios + * assert `Applied charging profile #` against the SIMULATOR's log, + * which prints the id the charge point received on the wire. A ref that + * were a database key, or an index into this array, would make every + * SmartCharging scenario fail on an assertion about the CSMS's bookkeeping + * rather than about the charge point. + * - THE SHAPE MIRRORS SteVe's `chargingProfileForm`: stackLevel 0, kind + * Relative, rate unit W, one period at startPeriod 0. TC_066 asserts + * `"limit":11000` on the returned composite schedule, so the limit is not + * decorative. + */ +/** OCPP 1.6 ChargingProfile, spelled as the wire spells it. */ +export interface CsChargingProfile { + chargingProfileId: number; + /** Only meaningful for a TxProfile; absent otherwise. */ + transactionId?: number; + stackLevel: number; + chargingProfilePurpose: "ChargePointMaxProfile" | "TxDefaultProfile" | "TxProfile"; + chargingProfileKind: "Absolute" | "Recurring" | "Relative"; + chargingSchedule: { + chargingRateUnit: "A" | "W"; + chargingSchedulePeriod: { + startPeriod: number; + limit: number; + }[]; + }; +} +interface CatalogueEntry { + /** The human-readable name a scenario looks the profile up by. */ + description: string; + profile: CsChargingProfile; +} +/** + * Ids 56 and 57 name the test cases that use them rather than counting from 1. + * A single-digit id would make the scenarios' `#(?!\d)` log assertions + * depend on that negative lookahead to avoid matching `#10`; two digits chosen + * to be memorable cost nothing and remove the question. + */ +export declare const PROFILE_CATALOGUE: readonly CatalogueEntry[]; +/** The ref for a description, or "" when this driver provisions no such + * profile -- which is the contract's "the CSMS has no such record". */ +export declare function refByDescription(description: string): string; +/** The profile behind a ref. `undefined` when the ref names nothing here. */ +export declare function profileByRef(ref: string): CsChargingProfile | undefined; +export {}; diff --git a/types/drivers/citrineos/provision.d.ts b/types/drivers/citrineos/provision.d.ts new file mode 100644 index 0000000..da84f4e --- /dev/null +++ b/types/drivers/citrineos/provision.d.ts @@ -0,0 +1,102 @@ +/** + * provision.ts -- the environment the scenarios assume, made reproducible. + * + * The scenarios do not create the state they assert on: TC_023 needs three + * idTags that are respectively unknown, expired and blocked, and a dozen + * others must simply authorize. drivers/steve/provision.ts is the sibling of + * this file and explains where the tag list comes from; the list itself is + * duplicated rather than shared because it is a property of the SIMULATOR + * image, and a driver that imported another driver's fixtures would be + * claiming a coupling that does not exist. + * + * ONE CHANNEL, NOT THREE. SteVe's provisioner uses REST, SQL and the manager + * UI because each covers what the others cannot. Here everything is SQL, + * because CitrineOS exposes no Authorization CRUD at all: every + * `@AsDataEndpoint` in the repository was read, and `EVDriverDataApi` offers + * exactly one route, a read-only GET of the local list version. The bundled + * Hasura sidecar would offer insert mutations, at the cost of vendoring its + * metadata -- see records.ts for why that trade was refused. + * + * Charging profiles are not provisioned here either, and that is not an + * omission: OCPP 1.6 SetChargingProfile carries the profile inline, so there + * is no CSMS-side record to create. profiles.ts holds the catalogue. + * + * Everything is idempotent. Re-running provision on a provisioned environment + * must be a no-op that still exits 0, because CI reruns it and an operator + * chasing a failure will run it twice before believing it. + */ +import { type CitrineConfig } from "./config"; +export declare class CitrineProvisioner { + private readonly cfg; + private readonly log; + private readonly db; + constructor(cfg: CitrineConfig, log?: (msg: string) => void); + private get tenant(); + /** + * Writes every fixture in ONE psql invocation. + * + * Upsert by hand rather than `ON CONFLICT`, because the unique index is on + * (idToken, idTokenType, tenantId) and Postgres treats NULLs as distinct -- + * so a row written with a different idTokenType would not conflict, and the + * table would quietly grow the second row that makes the handler answer + * Invalid. Matching on (idToken, tenantId) enforces the invariant the + * handler actually needs, whatever else is in the table. + */ + provisionTags(): Promise; + /** + * Read-only. Two queries rather than one per fixture: each db call is a + * `docker exec` process spawn, so asking about twenty tags one at a time + * costs seconds of pure process startup -- and verify() runs twice in CI. + */ + /** + * Does the running server's schema match the variant we were told to expect? + * + * variant.ts declares rather than detects, so that the scope table stays + * readable offline -- which leaves exactly one way for the declaration to be + * wrong: pointing a `v2` driver at a `v1.9.1` server, or the reverse. The + * symptom without this check is silent and expensive: every record read + * targets a column that does not exist, `psql` fails, and a dozen scenarios + * report the CSMS as empty. One query converts that into a sentence. + * + * The discriminator is `ocppConnectionName`, never `stationId`: `stationId` + * exists on `Transactions` in BOTH lines -- `character varying` holding the + * OCPP name on v1.9.1, an `integer` foreign key on v2 -- so its presence + * proves nothing. Both facts were read off running containers. + */ + private verifySchema; + verify(): Promise; + /** + * Every `NOT EXISTS` guard needed to delete an Authorization safely, read + * from the live catalog rather than written out here. + * + * There are four foreign keys onto `Authorizations` on the pinned image -- + * `Transactions.authorizationId`, `LocalListAuthorizations.authorizationId`, + * `LocalListAuthorizations.groupAuthorizationId`, and the self-reference + * `Authorizations.groupAuthorizationId` -- and none of them cascades. An + * earlier version of this method guarded only the first, which is the one a + * transaction-only run exercises; any scenario that had sent a SendLocalList + * then aborted the DELETE on a constraint violation, and because psql runs a + * semicolon-separated script in ONE implicit transaction with ON_ERROR_STOP, + * that abort rolled the whole teardown back. It removed nothing and said + * nothing. + * + * Asking the catalog instead of listing four names is what keeps that fixed: + * a fifth referencing table on a future CitrineOS is picked up rather than + * silently reintroducing the same failure. Table and column names come from + * pg_constraint, so they are the database's own identifiers. + */ + private guards; + /** + * Removes the fixtures, and nothing else. Charge points, their connectors + * and their transactions are runtime residue rather than fixtures, and + * `docker compose -f drivers/citrineos/compose.yaml down -v` is the honest + * way to get a clean slate. + */ + teardown(): Promise; +} +/** `ocpp-tck driver provision` */ +export declare function provisionCommand(): Promise; +/** `ocpp-tck driver verify` */ +export declare function verifyCommand(): Promise; +/** `ocpp-tck driver teardown` */ +export declare function teardownCommand(): Promise; diff --git a/types/drivers/citrineos/records.d.ts b/types/drivers/citrineos/records.d.ts new file mode 100644 index 0000000..18dc3c9 --- /dev/null +++ b/types/drivers/citrineos/records.d.ts @@ -0,0 +1,186 @@ +/** + * records.ts -- what CitrineOS believes happened, read straight from Postgres. + * + * The message API is write-only in practice. CitrineOS's REST data endpoints + * cover boot config, tariffs, certificates, the router's websocket plumbing and + * exactly one transaction lookup -- by explicit `transactionId`, which a + * scenario does not know. There is no "latest transaction for this station", + * no idTag on a transaction, no stop reason, no count, and no Authorization + * CRUD at all. Every `@AsDataEndpoint` in the repository was read to establish + * that, not sampled. + * + * WHY NOT THE BUNDLED HASURA / GraphQL + * ------------------------------------ + * CitrineOS's docker stack ships a Hasura sidecar that does expose all of it. + * Three things decided against it, and the first one is NOT the metadata: yes, + * Hasura tracks no table until metadata is applied and that metadata lives in + * the CitrineOS repository, but its metadata API (`pg_track_table`) would let + * `provision` track the eight tables itself, vendoring nothing. + * + * 1. IT WOULD NOT DECOUPLE US FROM THE SCHEMA. Hasura derives its field names + * from column names, so the v1.9.1 -> v2 rename of the OCPP connection + * column (see variant.ts) would have broken exactly these queries in + * exactly the same way. It is a different syntax for the same coupling, + * not an abstraction over it. + * 2. HASURA IS PART OF THEIR DEV COMPOSE, NOT THEIR PRODUCT. Depending on it + * would mean testing "CitrineOS plus a particular sidecar", and a target + * deployment may well not run one. Postgres is definitionally present. + * 3. It costs another pinned image, another published port, and another + * authentication story. + * + * The one thing it would genuinely buy is remote testability -- GraphQL is + * plain HTTP, whereas the transport below needs `docker exec` and therefore a + * driver running on the host that owns the containers, the same cost + * drivers/steve/records.ts pays and documents. That trade becomes worth making + * the day someone needs to point this driver at a CitrineOS they do not own, + * and when it does, `raw()` below is the only thing that has to change. + * + * MEASURED COST OF THIS TRANSPORT: ~350 ms per query, dominated by the + * `docker exec` process spawn. Worth knowing before optimising the wrong + * thing -- the cheap fix is a persistent psql session fed on stdin, not a + * different database API. + */ +import { type CsmsChargingProfileRecords, type CsmsRecords } from "../../tck/driver"; +import type { CitrineConfig } from "./config"; +/** + * Single-quoted SQL literal, for PostgreSQL. + * + * Only the quote is doubled, and unlike the MariaDB sibling in + * drivers/steve/records.ts the backslash is deliberately left alone: + * PostgreSQL has had `standard_conforming_strings = on` by default since 9.1, + * so a backslash inside `'...'` is an ordinary character. Escaping it would + * corrupt any value containing one. `psql -X` below is what keeps that true -- + * it skips ~/.psqlrc, so no local file can turn the setting off underneath us. + */ +export declare function sqlLiteral(value: string): string; +/** + * `Omit` rather than `CsmsRecords`, and the Omit + * is the declaration of the gap: `reservations` is a capability this CSMS does + * not have for OCPP 1.6, so the runner substitutes tck/capabilities.ts's + * throwing stub and the scenarios that need it report NOT APPLICABLE. Keeping + * the rest of the interface checked is the point -- an `implements` dropped + * altogether would stop catching a renamed method. + */ +export declare class CitrineRecords implements Omit { + private readonly cfg; + /** `AND "tenantId" = n`, spelled once. Every table below carries the column, + * and omitting it would read another tenant's rows as this tenant's. */ + private readonly tenant; + /** + * The quoted column holding the OCPP connection name, for the declared + * variant -- `"ocppConnectionName"` on v2, `"stationId"` on v1.9.1. See + * variant.ts for why this is declared rather than detected, and for the trap + * that makes `stationId`'s mere presence useless as a discriminator. + * + * Unqualified. Every call site below is either single-table or joins only + * `Authorizations`, which carries neither name, so it cannot be ambiguous -- + * and if a future schema made it so, Postgres would raise "column reference + * is ambiguous" rather than pick one silently. + */ + private readonly station; + constructor(cfg: CitrineConfig); + /** Runs SQL, returns stdout verbatim. The single path to the database. */ + private raw; + /** + * Runs SQL, returns the first column of the first row ("" if no rows). + * + * There is no `nullSafe` counterpart to SteVe's here, and that is a fact + * about psql rather than an omission: `-t -A` renders a SQL NULL as the + * empty string, so an unset stop timestamp already arrives as the "" that + * assertNonEmpty must fail on. MariaDB prints the four characters "NULL", + * which is why the other driver needs the extra step. + */ + scalar(sql: string): Promise; + /** Runs SQL, returns every row as its list of columns ([] if no rows). */ + rows(sql: string): Promise; + /** + * The transaction joined to the Authorization it was started with. + * + * The join is sound for an OPEN transaction, not only a closed one: + * createTransactionByStartTransaction looks the Authorization up by + * `idToken = request.idTag` and stores its id on the row at creation time + * (packages/core/src/dal/layers/sequelize/repository/TransactionEvent.ts). + * It stores NULL for an unknown tag, which is why every use below is a LEFT + * JOIN or an explicit inner join on a tag the fixtures provide. + */ + private static readonly TX_AUTH_JOIN; + latestTransaction(cpId: string): Promise; + /** + * Binds a scenario's later assertions to the transaction ITS OWN drive() + * created. latestTransaction() takes the newest row regardless of tag or + * state, which on a reused charge point can pick up a stale closed + * transaction from an earlier run instead of the racing in-progress one. + */ + waitForActiveTransaction(cpId: string, idTag: string, timeoutSecs?: number): Promise; + /** + * The OCPP integer transactionId behind a ref. + * + * Not part of CsmsRecords: it is the translation `requests.ts` needs to turn + * this driver's row key into the number RemoteStopTransaction and a TxProfile + * put on the wire. CitrineOS mints it from a per-station sequence, so it is + * neither the primary key nor globally unique -- assuming the two were the + * same number, as they happen to be in SteVe, would stop a transaction that + * belongs to a different station. + */ + ocppTransactionId(ref: string): Promise; + /** + * Returns one charge point to the state a scenario may assume, before its + * container starts. Idempotent, and a WRITE -- hence a lifecycle hook rather + * than part of CsmsRecords. One `docker exec`, because psql runs a + * semicolon-separated script in a single implicit transaction. + * + * Two pieces of per-station residue, both of which a previous scenario in + * the same sweep can leave behind on a charge point id the pool then hands + * to the next one: + * + * 1. AN OPEN TRANSACTION. Same job as SteVe's closeStaleTransaction. It + * writes the summary columns on `Transactions` and deliberately does NOT + * fabricate a `StopTransactions` row: that table holds what the charge + * point actually sent, and inventing an entry would put a StopTransaction + * that never happened in front of anyone reading the database afterwards. + * `endTime` is CitrineOS's own bookkeeping, and setting it is true -- + * this driver did end the transaction. + * + * 2. THE LOCAL AUTHORISATION LIST VERSION, which is the non-obvious one. + * LocalAuthListService rejects a SendLocalList whose listVersion is not + * strictly greater than the station's stored versionNumber, throwing + * before anything reaches the wire. Four scenarios send listVersion 1, so + * the second of them to land on a given charge point would be refused by + * the CSMS -- and would look exactly like a charge point that ignored the + * request. Clearing the row restores "this station has no local list", + * which is what every one of those scenarios assumes. + */ + prepareStation(cpId: string): Promise; + /** + * One column off the transaction row, joined to what the charge point sent. + * + * The three public readers below differ only in that expression, so the + * guard, the joins and the tenant-scoped WHERE live here once -- a fix to any + * of them would otherwise have to land in three places. + */ + private txScalar; + transactionIdTag(tx: string): Promise; + /** + * StopTransactions.timestamp first, Transactions.endTime second. + * + * The order is not arbitrary: the first is the instant the CHARGE POINT + * reported, straight off the wire, and the second is CitrineOS's own summary + * -- which is also what prepareStation above writes. Preferring the wire + * value means a scenario that asserts a transaction closed is answered by the + * charge point wherever the charge point answered. + */ + transactionStopTimestamp(tx: string): Promise; + transactionStopReason(tx: string): Promise; + transactionCountForIdTag(cpId: string, idTag: string): Promise; + /** + * Deliberately absent: `reservations`. + * + * The runner substitutes tck/capabilities.ts's throwing stub, so the + * scenarios read identically and the absence surfaces as NOT APPLICABLE. It + * is structural rather than an unverifiable() sentinel because CitrineOS + * cannot SEND ReserveNow over OCPP 1.6 at all (see requests.ts), so there is + * never a reservation to have an opinion about -- the `Reservations` table + * exists but nothing for 1.6 ever writes it. + */ + readonly chargingProfiles: CsmsChargingProfileRecords; +} diff --git a/types/drivers/citrineos/requests.d.ts b/types/drivers/citrineos/requests.d.ts new file mode 100644 index 0000000..7b35af0 --- /dev/null +++ b/types/drivers/citrineos/requests.d.ts @@ -0,0 +1,45 @@ +/** + * requests.ts -- one CsmsOperation, one CitrineOS message-API call. + * + * CitrineOS's outbound surface is generated from the OCPP schemas themselves: + * `AbstractModuleApi._toMessagePath` builds + * `/ocpp/1.6//` and validates the body against + * `OCPP1_6.RequestSchema` before dispatching. So the mapping below is + * almost the identity -- the request bodies ARE the OCPP payloads, which is + * exactly the shape the neutral vocabulary was derived from. + * + * Almost. Three places need real work, and each is a fact about CitrineOS: + * + * - THE MODULE PREFIX IS NOT DERIVABLE FROM THE ACTION. RemoteStart/Stop and + * UnlockConnector live under `evdriver` rather than `transactions`; + * GetDiagnostics lives under `reporting`. There is no rule, only a table + * (apps/ocpp-server/src/config/envs/docker.ts), so it is spelled out here. + * - REFS ARE NOT WIRE VALUES. A TransactionRef is this driver's own row key + * and has to be resolved to the OCPP integer transactionId; a + * ChargingProfileRef expands to the whole inline profile. See + * {@link CitrineRefs}. + * - RESERVATIONS DO NOT EXIST HERE AT ALL. See the two throwing cases. + */ +import { type CsmsOperation, type TransactionRef } from "../../tck/driver"; +import { type CitrineVariant } from "./variant"; +/** The endpointPrefix values CitrineOS's shipped `docker` config declares. */ +export type CitrineModule = "configuration" | "evdriver" | "reporting" | "smartcharging"; +export interface CitrineRequest { + module: CitrineModule; + /** The path segment, i.e. the OCPP action with a lowercased first letter. */ + action: string; + body: Record; +} +/** + * How an opaque ref becomes something CitrineOS will accept. + * + * `ocppTransactionId` is async because it is a database lookup: this driver's + * TransactionRef is `Transactions.id`, the serial primary key, while the wire + * carries `Transactions.transactionId`, the value CitrineOS handed the charge + * point in StartTransaction.conf. The two are different columns and, unlike + * SteVe's, different numbers. + */ +export interface CitrineRefs { + ocppTransactionId(ref: TransactionRef): Promise; +} +export declare function toCitrineRequest(op: CsmsOperation, refs: CitrineRefs, variant: CitrineVariant): Promise; diff --git a/types/drivers/citrineos/scope.d.ts b/types/drivers/citrineos/scope.d.ts new file mode 100644 index 0000000..a8c7bb2 --- /dev/null +++ b/types/drivers/citrineos/scope.d.ts @@ -0,0 +1,26 @@ +/** + * scope.ts -- what CitrineOS can drive, and what it demonstrably cannot. + * + * This is the first table in the repository with NOT_APPLICABLE rows, which is + * the point of having a second driver at all: SteVe's table claims every + * scenario because the scenarios were written against SteVe, so until now the + * machinery that reports a scenario as out of scope had never fired. + * + * Every status below was settled by a real sweep against the pinned image, not + * by reading sources -- 44 + 3 scenarios, 2026-08-11; VENDOR.md carries the + * numbers. The seven NOT_APPLICABLE rows were predicted from the sources first + * and then confirmed against a running container, whose /docs/json advertises + * 18 `/ocpp/1.6/` paths with neither `reserveNow` nor `cancelReservation` + * among them. + * + * TWO ROWS ARE DRIVABLE AND CURRENTLY RED, ON PURPOSE. `tck/scope.ts` forbids + * demoting a row to NOT_APPLICABLE to make a red scenario go away, because + * that converts a finding about the CSMS into a silence about the harness. + * Both are findings against CitrineOS rather than gaps in this driver, and + * both are named in drivers/citrineos/README.md's gap table. A TCK whose + * second driver reports 100% green is a TCK that has stopped measuring. + */ +import type { ScopeTable } from "../../tck/scope"; +import { type CitrineVariant } from "./variant"; +/** The scope table for a declared variant. See variant.ts. */ +export declare function citrineosScope(variant: CitrineVariant): ScopeTable; diff --git a/types/drivers/citrineos/variant.d.ts b/types/drivers/citrineos/variant.d.ts new file mode 100644 index 0000000..f88fc1b --- /dev/null +++ b/types/drivers/citrineos/variant.d.ts @@ -0,0 +1,62 @@ +/** + * variant.ts -- the two CitrineOS lines this driver speaks, in one place. + * + * CitrineOS restructured between the v1.x stable line and the v2 prerelease, + * and two of those changes reach this driver. Both were read off running + * containers rather than inferred from release notes: + * + * 1. THE OCPP CONNECTION NAME MOVED COLUMN. `Transactions`, + * `LocalListVersions` and `SendLocalLists` carry it as `stationId` on + * v1.9.1 and as `ocppConnectionName` on v2.0.0-beta1. + * 2. THE 1.6 LOCAL AUTH LIST ENDPOINTS DID NOT EXIST YET. v1.9.1 advertises + * 16 `/ocpp/1.6/` paths, v2.0.0-beta1 advertises 18; the two extra are + * `evdriver/sendLocalList` and `evdriver/getLocalListVersion`. + * + * WHY THIS IS DECLARED AND NOT DETECTED + * ------------------------------------- + * Detecting the column from information_schema would be easy and would even be + * unambiguous -- see the trap below. But the scope table and the capability + * set have to be readable with NO running server and NO credentials, because + * that is the promise `ocpp-tck check-driver` and the pre-flight rest on. A + * driver that had to connect to Postgres before it could say which scenarios + * it can drive would break that promise. + * + * So the variant is declared once, drives all three things, and + * `driver verify` then asserts that the running server agrees. Declare, then + * check -- rather than two sources of truth free to disagree in silence. + * + * THE TRAP, recorded because it is the obvious wrong detection: `stationId` + * exists on `Transactions` in BOTH lines. On v1.9.1 it is `character varying` + * and holds the OCPP name; on v2 it is an `integer` foreign key and the name + * lives in `ocppConnectionName`. Testing for the presence of `stationId` is + * therefore always true and always useless. The presence of + * `ocppConnectionName` is the discriminator, and that is what verify() checks. + */ +import type { CsmsEnv, CsmsOperationAction } from "../../tck/driver"; +export type CitrineVariant = "v1" | "v2"; +/** v2 by default: it is what `drivers/citrineos/compose.yaml` pins, and the + * only line with a complete OCPP 1.6 surface. */ +export declare const DEFAULT_VARIANT: CitrineVariant; +export declare function resolveVariant(env: CsmsEnv): CitrineVariant; +/** + * The column carrying the OCPP connection name -- the string a charge point + * connects as. Unquoted; callers quote it. + */ +export declare function stationColumn(variant: CitrineVariant): string; +/** + * Why the reservation actions are unrouted, worded ONCE. + * + * Both the scope table and the runtime escape have to state this, and they are + * the two halves a reader compares: a scope row saying one thing and an + * UnsupportedOperationError saying another is the drift this module exists to + * prevent. Verified in the sources at v1.9.1, v2.0.0-beta1 and main, and + * against both running containers. + */ +export declare const NO_RESERVATIONS: string; +/** Same, for the local auth list pair, which v1.9.1 alone lacks. */ +export declare const NO_LOCAL_LIST: string; +/** The unrouted actions for a variant, mapped to why. */ +export declare function unroutedActions(variant: CitrineVariant): ReadonlyMap; +/** Scenarios the local-auth-list gap costs on v1. Named here rather than in + * scope.ts so the two cannot drift from {@link unroutedActions}. */ +export declare const V1_LOCAL_LIST_SCENARIOS: readonly ["cert16-tc042-1-get-local-list-version-not-supported", "cert16-tc042-2-get-local-list-version-empty", "cert16-tc043-1-send-local-list-not-supported", "cert16-tc043-3-send-local-list-failed", "cert16-tc043-4-send-local-list-full", "cert16-tc043-5-send-local-list-differential"]; From 3f938332f29d49adb181c2a26febc6c664078114 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 00:09:06 +0200 Subject: [PATCH 03/13] test(tools): check fixture tags against every bundled driver The idTag list is a property of the pinned simulator image, so each driver carries its own hard-coded copy -- they cannot share a constant when a driver may live in another repository entirely. That makes a second driver reintroduce exactly the drift this script exists to catch: it would report "add it to SteVe", SteVe would go green, and the other driver would keep failing TC_013/014/017/018 with an Authorize:Invalid that reads like a CSMS bug. Discover provisioners with a glob rather than naming them, so a third driver is covered the day it lands, and fail when the glob is empty -- an unchecked run that reports success is the failure mode being removed here, not a convenience. --- tools/extract-fixture-tags.sh | 70 +++++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 24 deletions(-) diff --git a/tools/extract-fixture-tags.sh b/tools/extract-fixture-tags.sh index 27fdd29..8385d31 100755 --- a/tools/extract-fixture-tags.sh +++ b/tools/extract-fixture-tags.sh @@ -16,7 +16,7 @@ # `bun run test`, which stays offline and deterministic. # # bash tools/extract-fixture-tags.sh # print the tags the image uses -# bash tools/extract-fixture-tags.sh --diff # compare with the SteVe driver +# bash tools/extract-fixture-tags.sh --diff # compare with every bundled driver set -euo pipefail repo_root="$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)" @@ -56,34 +56,56 @@ if [ "$mode" = "print" ]; then exit 0 fi -driver_tags="$( - grep -oE '"CERT[A-Za-z0-9-]+"' drivers/steve/provision.ts | - tr -d '"' | sort -u -)" - # Tags the CSMS supplies (RemoteStartTransaction, ReserveNow, SendLocalList) -# come from tck/specs/, so the driver legitimately knows tags the image does not. +# come from tck/specs/, so a driver legitimately knows tags the image does not. spec_tags="$( grep -rhoE '"CERT[A-Za-z0-9-]+"' tck/specs/*.ts | tr -d '"' | sort -u )" -missing="$(comm -23 <(printf '%s\n' "$image_tags") \ - <(printf '%s\n' "$driver_tags"))" -unexplained="$(comm -13 <(sort -u <(printf '%s\n' "$image_tags" "$spec_tags")) \ - <(printf '%s\n' "$driver_tags"))" +# Every bundled provisioner, discovered rather than listed. Each is an +# independent hard-coded copy of the same tag list -- they cannot share a +# constant, because the list is a property of the simulator image and a driver +# may live in another repository entirely. So a second driver reintroduces +# exactly the drift this script exists to catch: a hard-coded list would say +# "add it to SteVe", SteVe would go green, and the other driver would keep +# failing TC_013/014/017/018 with an Authorize:Invalid that looks like a CSMS +# bug. A glob means a third driver is covered the day it lands, and an empty +# glob is itself a failure rather than a silent pass. +shopt -s nullglob +provisioners=(drivers/*/provision.ts) +shopt -u nullglob -status=0 -if [ -n "$missing" ]; then - echo "FAIL: the image uses tags the SteVe driver does not provision:" >&2 - printf '%s\n' "$missing" | sed 's/^/ /' >&2 - echo " → add them to VALID_TAGS in drivers/steve/provision.ts." >&2 - status=1 -fi -if [ -n "$unexplained" ]; then - echo "WARN: the driver provisions tags neither the image nor the specs use:" >&2 - printf '%s\n' "$unexplained" | sed 's/^/ /' >&2 -fi -if [ "$status" -eq 0 ] && [ -z "$unexplained" ]; then - echo "The SteVe driver provisions every tag the pinned simulator image uses." +if [ "${#provisioners[@]}" -eq 0 ]; then + echo "FAIL: no drivers/*/provision.ts found -- nothing was checked." >&2 + exit 1 fi + +# Loop-invariant: what a driver is ALLOWED to know, image plus specs. +explained="$(sort -u <(printf '%s\n' "$image_tags" "$spec_tags"))" + +status=0 +for provisioner in "${provisioners[@]}"; do + name="$(basename "$(dirname "$provisioner")")" + + driver_tags="$(grep -oE '"CERT[A-Za-z0-9-]+"' "$provisioner" | tr -d '"' | sort -u)" + + missing="$(comm -23 <(printf '%s\n' "$image_tags") \ + <(printf '%s\n' "$driver_tags"))" + unexplained="$(comm -13 <(printf '%s\n' "$explained") \ + <(printf '%s\n' "$driver_tags"))" + + if [ -n "$missing" ]; then + echo "FAIL: the image uses tags the $name driver does not provision:" >&2 + printf '%s\n' "$missing" | sed 's/^/ /' >&2 + echo " → add them to VALID_TAGS in $provisioner." >&2 + status=1 + fi + if [ -n "$unexplained" ]; then + echo "WARN: the $name driver provisions tags neither the image nor the specs use:" >&2 + printf '%s\n' "$unexplained" | sed 's/^/ /' >&2 + fi + if [ -z "$missing" ] && [ -z "$unexplained" ]; then + echo "The $name driver provisions every tag the pinned simulator image uses." + fi +done exit "$status" From be9c55afb44589f9b39fd99d2446d05a70154764 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 00:09:06 +0200 Subject: [PATCH 04/13] refactor(drivers): name SteVe and CitrineOS as peer drivers "Reference driver" described a repository with one driver. With two, the label ranks them, and the ranking is wrong: each answers a question the other cannot. SteVe is where a capability the harness LOST shows up, because the scenarios were written against it and its scope table claims all 47. CitrineOS is where the core would be caught assuming something about SteVe, because it had no part in writing them. Renames `check:reference-driver` to `check:steve-driver`, alongside the existing `check:citrineos-driver`, and reframes the README, CONTRIBUTING and the SteVe driver header accordingly. Uses of "reference" that mean the OCA certification documents are deliberately left alone. --- CONTRIBUTING.md | 22 +++++++++++++++- README.md | 46 ++++++++++++++++++++++++++++------ drivers/steve/index.ts | 15 +++++++---- package.json | 2 +- types/drivers/steve/index.d.ts | 15 +++++++---- 5 files changed, 80 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5acfaf2..dd9512a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -151,9 +151,29 @@ Put it on the **module**, not inside `create()`. `check-driver` and the preflight read it without calling `create()`, which is what lets them run with no credentials — including in your CI, which has none. +### Two worked examples + +Two drivers ship here, and they are worth reading together because they solve +the same problem through completely different surfaces — which is the strongest +evidence that the contract is not shaped around either of them. + +`drivers/steve/` drives operations through an HTML manager UI and reads state +from MariaDB. `drivers/citrineos/` posts JSON to a generated REST API and reads +from Postgres, and additionally supports two incompatible releases of its CSMS +behind one `CITRINE_VARIANT` setting. + +For the mechanics of the contract — the operation switch, the record queries, +the bootstrap verbs — either one works as a model. For **what to do when your +CSMS cannot do something**, read `drivers/citrineos/`: it is the one with gaps, +so it is the one that shows a scope table with `NOT_APPLICABLE` rows each citing +the endpoint that does not exist, a `records` object that omits `reservations` +outright rather than faking it, and a +[README](drivers/citrineos/README.md) whose gap table names a source fact per +row. + ## Contributing back -Pull requests welcome for the core, the reference driver, and new scenarios. +Pull requests welcome for the core, either bundled driver, and new scenarios. Two rules the test suite enforces rather than merely documents: - **`tests/generic-core.sh`** — nothing under `tck/` may name a CSMS, and the diff --git a/README.md b/README.md index d5170ae..5852913 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,17 @@ the OCPP-J frames both directions, and asserts on the captured wire log. What it does *not* bring is any knowledge of your CSMS: telling it "reset this charge point" is a **driver**, and a driver is one file you write. +The scenarios trace to the Open Charge Alliance's OCPP 1.6 certification +material — the [OCPP 1.6 certification page][octt], and in particular its +*Test Procedure & Test Plans* and *OCPP Compliancy Testing Tool — Test Case +Document*. Scenario `cert16-tcNNN-…` corresponds to OCA test case `TC_NNN`, +and because the CSMS is the system under test here, the **`_CSMS` variant** is +the one that applies: it is the Central System that must answer. This is not a +certification tool and passing it is not certification — but the reference is +where a disagreement about what a scenario *should* assert gets settled. + [sim]: https://github.com/shiv3/ocpp-cp-simulator +[octt]: https://openchargealliance.org/certificationocpp/certification-ocpp-1-6/ ``` your CSMS <--- REST/UI/SQL --- your driver ---. @@ -31,10 +41,29 @@ green one. Node cannot run it, and `bin/ocpp-tck.ts` says so rather than failing later. - docker — one simulator container per scenario. -## Quick start, against the reference driver +## Bundled drivers + +Two ship here, on equal footing. They reach their CSMS through completely +different surfaces, and each answers a question the other cannot: + +| Driver | Transport | What it answers | Result | +|---|---|---|---| +| [`drivers/steve`](drivers/steve) | HTML manager UI + MariaDB | *Has the harness lost a capability?* SteVe is the CSMS the scenarios were originally written against, so a scope row that had to be demoted would mean the core dropped something. | All 47 `DRIVABLE` | +| [`drivers/citrineos`](drivers/citrineos/README.md) | JSON REST API + Postgres | *Is the contract actually CSMS-neutral?* [CitrineOS](https://github.com/citrineos/citrineos-core) (LF Energy / S44) had no part in writing the scenarios and has a smaller OCPP 1.6 surface. | 38 `PASS`, 7 `NOT APPLICABLE`, 2 `FAIL` | + +An abstraction with one implementation is neutral by assertion, so the second +driver is what turns that into a measurement — and the result is the useful +part: 38 scenarios pass unmodified against a CSMS that had no part in writing +them, 7 report a capability it does not have for OCPP 1.6, and 2 stay red +because they found something. That two drivers this different need no change to +a single scenario is the claim the pair exists to support. + +## Quick start, against SteVe -SteVe is the CSMS these scenarios were originally written against, so its -driver ships here as the reference implementation. +Either bundled driver will do; SteVe is shown here because its environment is a +single container pair. +[`drivers/citrineos/README.md`](drivers/citrineos/README.md) is the equivalent +walkthrough for the other one. ```sh bun add open-ocpp-tck # or: bun add github:juherr/open-ocpp-tck#v0.1.0 @@ -111,10 +140,10 @@ re-sync, and your driver can live in a completely different repository. | `ocpp-tck print-sim-image` | nothing | The pinned simulator image digest | | `ocpp-tck driver ` | driver-defined | A bootstrap verb your driver contributes | -The SteVe driver contributes three: `provision` (seed the fixtures, idempotent), -`verify` (read-only — are they there?), `teardown` (remove them). A driver that -needs no bootstrap contributes none, and the runner never calls them during a -scenario. +Both bundled drivers contribute the same three: `provision` (seed the fixtures, +idempotent), `verify` (read-only — are they there?), `teardown` (remove them). +A driver that needs no bootstrap contributes none, and the runner never calls +them during a scenario. `check-driver` reads the driver **module** and never calls `create()`, so it works with no credentials — which is the same property that lets a scenario @@ -177,7 +206,8 @@ even where the code is new. ```sh bun install bun run typecheck # tsc --noEmit -bun run check:reference-driver # offline +bun run check:steve-driver # offline +bun run check:citrineos-driver # offline bun test # vendor integrity, genericity, spec invariants bash tests/types-current.sh # committed declarations match the sources bash tools/vendor-diff.sh # network: how far upstream has moved diff --git a/drivers/steve/index.ts b/drivers/steve/index.ts index b0bdd10..fc6cb97 100644 --- a/drivers/steve/index.ts +++ b/drivers/steve/index.ts @@ -3,13 +3,18 @@ /** * The SteVe driver. * - * SteVe is the CSMS this harness was originally written against, which makes - * it the reference implementation of the driver contract: if an operation - * cannot be expressed here, the contract has drifted away from OCPP rather - * than towards it. Its scope table claims every scenario, and a guard asserts - * that -- the day it needs a NOT_APPLICABLE row, the generalization lost a + * SteVe is the CSMS this harness was originally written against, which gives + * this driver one job the other bundled one cannot do: if an operation cannot + * be expressed here, the contract has drifted away from OCPP rather than + * towards it. Its scope table claims every scenario, and a guard asserts that + * -- the day it needs a NOT_APPLICABLE row, the generalization lost a * capability it used to have. * + * That is a different question from the one drivers/citrineos/ answers, not a + * lesser or greater one: this driver catches the harness losing something, the + * other catches the core assuming something about SteVe. Neither is "the + * reference". + * * Why the manager UI and not the REST API * --------------------------------------- * Operations go through the manager UI on purpose, not for lack of a REST diff --git a/package.json b/package.json index 8e090d1..f34c0a6 100644 --- a/package.json +++ b/package.json @@ -110,7 +110,7 @@ "scripts": { "typecheck": "tsc --noEmit", "build:types": "tsc -p tsconfig.build.json", - "check:reference-driver": "CSMS_DRIVER=./drivers/steve/index.ts bun bin/ocpp-tck.ts check-driver", + "check:steve-driver": "CSMS_DRIVER=./drivers/steve/index.ts bun bin/ocpp-tck.ts check-driver", "check:citrineos-driver": "CSMS_DRIVER=./drivers/citrineos/index.ts bun bin/ocpp-tck.ts check-driver", "e2e": "bun bin/ocpp-tck.ts run-all --parallel --retry-failed-isolated; all=$?; bun bin/ocpp-tck.ts run-all --group authorize; auth=$?; exit $(( all || auth ))", "e2e:smoke": "bun bin/ocpp-tck.ts run cert16-tc023-1-authorize-invalid && bun bin/ocpp-tck.ts run cert16-tc023-2-authorize-expired && bun bin/ocpp-tck.ts run cert16-tc023-3-authorize-blocked && bun bin/ocpp-tck.ts run cert16-tc066-get-composite-schedule && bun bin/ocpp-tck.ts run cert16-tc003-charging-plugin-first", diff --git a/types/drivers/steve/index.d.ts b/types/drivers/steve/index.d.ts index f93211c..52edb0f 100644 --- a/types/drivers/steve/index.d.ts +++ b/types/drivers/steve/index.d.ts @@ -1,13 +1,18 @@ /** * The SteVe driver. * - * SteVe is the CSMS this harness was originally written against, which makes - * it the reference implementation of the driver contract: if an operation - * cannot be expressed here, the contract has drifted away from OCPP rather - * than towards it. Its scope table claims every scenario, and a guard asserts - * that -- the day it needs a NOT_APPLICABLE row, the generalization lost a + * SteVe is the CSMS this harness was originally written against, which gives + * this driver one job the other bundled one cannot do: if an operation cannot + * be expressed here, the contract has drifted away from OCPP rather than + * towards it. Its scope table claims every scenario, and a guard asserts that + * -- the day it needs a NOT_APPLICABLE row, the generalization lost a * capability it used to have. * + * That is a different question from the one drivers/citrineos/ answers, not a + * lesser or greater one: this driver catches the harness losing something, the + * other catches the core assuming something about SteVe. Neither is "the + * reference". + * * Why the manager UI and not the REST API * --------------------------------------- * Operations go through the manager UI on purpose, not for lack of a REST From 6af5c1aa5a772bb427cfccfc39b80515c6762909 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 00:09:35 +0200 Subject: [PATCH 05/13] ci: run the conformance sweep against CitrineOS Adds `e2e-citrineos` beside the renamed `e2e-steve`, plus the offline `check-driver` step for the second driver -- the one whose scope table has NOT_APPLICABLE rows, so the only place where adding or renaming a scenario silently stops being covered. Both jobs run `bun run e2e`, so they cannot drift from each other or from what a human runs by hand. `continue-on-error` on the CitrineOS job is not a reliability hedge: the job is expected to be red on two named scenarios, both of which are findings kept red deliberately. Its value is the other 45 and the artifact it uploads. It is set per STEP on the sweeps as well as on the job, because a failing step ends a job even under a job-level continue-on-error -- which would skip the authorize sweep, the one containing the known failure. Refs #2 --- .github/workflows/ci.yml | 112 +++++++++++++++++++++++++++++++++++---- 1 file changed, 103 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ba0880b..551cb61 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -43,8 +43,14 @@ jobs: # Offline: reads the driver module and the scenario registry, nothing # else. No CSMS, no container, no credentials. - - name: Reference driver agrees with the core - run: bun run check:reference-driver + - name: SteVe driver agrees with the core + run: bun run check:steve-driver + + # The same check for the second driver, and it earns its place: this is + # the one whose scope table has NOT_APPLICABLE rows, so it is the only + # place where adding or renaming a scenario silently stops being covered. + - name: CitrineOS driver agrees with the core + run: bun run check:citrineos-driver - name: Core names no CSMS run: bash tests/generic-core.sh @@ -60,10 +66,15 @@ jobs: - name: Shell guards lint clean run: shellcheck tests/*.sh tools/*.sh - # Everything above is offline and proves the driver type-checks. This proves - # it works: a real SteVe, real containers, real OCPP-J frames. Without it the - # reference driver can rot green -- nothing else here would notice. - e2e: + # Everything above is offline and proves the drivers type-check. The two e2e + # jobs prove they work: real containers, real OCPP-J frames. They are peers, + # and each answers a question the other cannot -- see e2e-citrineos below. + # + # This one: SteVe is the CSMS the 47 scenarios were originally written + # against, so it is where a capability the harness LOST shows up first. Its + # scope table claims every scenario; a row that had to be demoted would mean + # the core dropped something. Without this job that can rot green unnoticed. + e2e-steve: runs-on: ubuntu-latest needs: check # ~10 min of sweep plus image pull, a cold SteVe boot and the one-off @@ -89,7 +100,7 @@ jobs: # two pinned images and cold-booting SteVe (its healthcheck allows 150s # for Flyway) shares nothing with installing bun, so the two may as well # overlap. The blocking wait below is then usually already satisfied. - - name: Start the reference CSMS + - name: Start SteVe run: docker compose -f drivers/steve/compose.yaml up -d - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 @@ -119,8 +130,8 @@ jobs: # barely moves with runner speed. Across 3 lanes, core is ~3 min and all # 44 are ~10 min. Roughly 7 minutes buys back the 29 scenarios that core # leaves out -- on precisely the branch where a regression is introduced, - # and for a job whose entire reason to exist is that the reference driver - # cannot rot green. Cheap coverage is not worth a stale signal. + # and for a job whose entire reason to exist is that this driver cannot + # rot green. Cheap coverage is not worth a stale signal. # # --retry-failed-isolated is not optional here: the runner warns that # parallel lanes are not fully isolated, so a bare --parallel turns @@ -148,3 +159,86 @@ jobs: - name: Tear down if: always() run: docker compose -f drivers/steve/compose.yaml down -v + + # The peer of the job above, answering the question it cannot: CitrineOS had + # no part in writing the scenarios, so this is where the core would be caught + # quietly re-acquiring a dependency on how SteVe happens to behave. A + # CSMS-neutrality claim that only one CSMS ever exercises is a claim, not a + # check. + # + # continue-on-error, and NOT because the job is unreliable: it is expected to + # be red. Two of the 47 scenarios fail against the pinned CitrineOS, and both + # are kept red deliberately rather than demoted in the scope table -- + # tck/scope.ts forbids demoting a row to make a red scenario go away, and + # these are findings about CitrineOS: + # + # cert16-tc023-3-authorize-blocked deterministic (3 runs of 3): CitrineOS + # answers Invalid where OCPP 1.6 requires + # Blocked. + # cert16-tc044-2-firmware-download-failed + # flaky (1 pass in 3), thinnest timing + # margin of any scenario. + # + # So this job's value is the OTHER 45, and the artifact it uploads. Turn it + # blocking only once both rows are green -- i.e. once upstream fixes the + # Blocked mapping -- and not merely because it has been quiet for a while. + # drivers/citrineos/README.md carries the full gap table. + e2e-citrineos: + runs-on: ubuntu-latest + needs: check + continue-on-error: true + timeout-minutes: 45 + env: + CSMS_DRIVER: ./drivers/citrineos/index.ts + # localhost, not the compose service name -- same asymmetry as the SteVe + # job: the runner reaches the message API through the published port, + # while the simulator containers reach the OCPP endpoint by service name + # from inside the network. + CITRINE_API_URL: http://localhost:8080 + OCPP_CP_IDS: CERTCP1,CERTCP2,CERTCP3 + steps: + - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0 + with: + persist-credentials: false + + # Before the toolchain and without --wait, for the same reason as the + # SteVe job: pulling the images and running the migrations on a cold + # database shares nothing with installing bun. + - name: Start CitrineOS + run: docker compose -f drivers/citrineos/compose.yaml up -d + + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: ${{ env.BUN_VERSION }} + + - run: bun install --frozen-lockfile + + - name: Wait for it to be healthy + run: docker compose -f drivers/citrineos/compose.yaml up -d --wait + + - name: Seed the fixtures the scenarios assume + run: bun bin/ocpp-tck.ts driver provision + + # Same reasoning as the SteVe job: a verb nothing runs is a verb that rots. + - name: Environment matches the scenarios + run: bun bin/ocpp-tck.ts driver verify + + # `bun run e2e`, exactly as the SteVe job runs it -- both sweeps, one + # script, so the two jobs cannot drift apart and neither can drift from + # what a human runs by hand. Seven scenarios are NOT APPLICABLE here and + # never start a container, so this is cheaper than SteVe's rather than + # doubling the bill. + - name: Conformance sweep + run: bun run e2e + + - name: Upload results + if: always() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: ocpp-tck-citrineos-results-${{ github.run_id }} + path: results/ + if-no-files-found: warn + + - name: Tear down + if: always() + run: docker compose -f drivers/citrineos/compose.yaml down -v From eeba388fc024a98e0e3f2b861e6a66543e7aae5c Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 11:28:58 +0200 Subject: [PATCH 06/13] fix(citrineos): keep a failed body read as a contextual API error AbortSignal.timeout covers the response body, not just the headers, so a CSMS that answers its headers and then stalls threw a bare TimeoutError naming no URL. Read the body inside the same try, and give describe() a fallback for the payload-less confirmation, where JSON.stringify returns undefined rather than a string and emptied the failure message. --- drivers/citrineos/api-client.ts | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/drivers/citrineos/api-client.ts b/drivers/citrineos/api-client.ts index c3cb795..76aaab5 100644 --- a/drivers/citrineos/api-client.ts +++ b/drivers/citrineos/api-client.ts @@ -37,7 +37,12 @@ interface MessageConfirmation { } function describe(value: unknown): string { - return typeof value === "string" ? value : JSON.stringify(value); + if (typeof value === "string") return value; + // JSON.stringify returns undefined -- not the string "undefined" -- for + // undefined, a function or a symbol. A confirmation carrying no payload is + // exactly that case, and letting it through emptied the failure message of + // its only detail. String() keeps a name for the thing that was there. + return JSON.stringify(value) ?? String(value); } export class CitrineMessageApi { @@ -62,6 +67,7 @@ export class CitrineMessageApi { async send(cpId: string, req: CitrineRequest): Promise { const url = this.url(req, cpId); let res: Response; + let text: string; try { res = await fetch(url, { method: "POST", @@ -71,13 +77,16 @@ export class CitrineMessageApi { body: JSON.stringify(req.body), signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS), }); + // Inside the try, because the timeout above covers the body stream too: + // a CSMS that answers its headers and then stalls aborts here, not at + // fetch, and that failure deserves the same URL-bearing message. + text = await res.text(); } catch (err) { throw new Error( `citrineos: POST ${url} failed: ${err instanceof Error ? err.message : String(err)}`, ); } - const text = await res.text(); if (!res.ok) { // A 404 here is worth calling out by name, because it is what an // unrouted action looks like: CitrineOS skips route registration From 8e96bb197f1d586e5c57afd046cd172fdb98a85b Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 11:29:09 +0200 Subject: [PATCH 07/13] fix(citrineos): read one stop row deterministically Nothing constrains StopTransactions to one row per transaction -- a charge point that retries StopTransaction gets a second one -- and scalar() then read whichever row the planner emitted first. Order by the stop instant and take the latest, which is the report the station stands by. Verified on the pinned postgis image: two stop rows resolve to the later one, and a transaction with none still falls back to Transactions. --- drivers/citrineos/records.ts | 9 ++++++++- types/drivers/citrineos/records.d.ts | 5 +++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/drivers/citrineos/records.ts b/drivers/citrineos/records.ts index 4637e5e..6dc1be7 100644 --- a/drivers/citrineos/records.ts +++ b/drivers/citrineos/records.ts @@ -299,6 +299,11 @@ export class CitrineRecords implements Omit { * The three public readers below differ only in that expression, so the * guard, the joins and the tenant-scoped WHERE live here once -- a fix to any * of them would otherwise have to land in three places. + * + * ORDER BY + LIMIT because nothing constrains "StopTransactions" to one row + * per transaction: a charge point that retries StopTransaction gets a second + * one, and scalar() would then read whichever row the planner happened to + * emit first. Latest wins, which is the report the station stands by. */ private txScalar(tx: string, expr: string): Promise { if (tx === "") return Promise.resolve(""); @@ -307,7 +312,9 @@ export class CitrineRecords implements Omit { FROM "Transactions" t LEFT JOIN "Authorizations" a ON a.id = t."authorizationId" LEFT JOIN "StopTransactions" st ON st."transactionDatabaseId" = t.id - WHERE t.id = ${sqlLiteral(tx)}::int AND t."tenantId" = ${this.tenant};`, + WHERE t.id = ${sqlLiteral(tx)}::int AND t."tenantId" = ${this.tenant} + ORDER BY st."timestamp" DESC NULLS LAST + LIMIT 1;`, ); } diff --git a/types/drivers/citrineos/records.d.ts b/types/drivers/citrineos/records.d.ts index 18dc3c9..049a4d7 100644 --- a/types/drivers/citrineos/records.d.ts +++ b/types/drivers/citrineos/records.d.ts @@ -157,6 +157,11 @@ export declare class CitrineRecords implements Omit * The three public readers below differ only in that expression, so the * guard, the joins and the tenant-scoped WHERE live here once -- a fix to any * of them would otherwise have to land in three places. + * + * ORDER BY + LIMIT because nothing constrains "StopTransactions" to one row + * per transaction: a charge point that retries StopTransaction gets a second + * one, and scalar() would then read whichever row the planner happened to + * emit first. Latest wins, which is the report the station stands by. */ private txScalar; transactionIdTag(tx: string): Promise; From 37cad412bab112e1ec212d497c9c7c0e5dc920cc Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 11:29:09 +0200 Subject: [PATCH 08/13] refactor(citrineos): type the v1 local-list ids against the v2 table V2_SCOPE now satisfies ScopeTable instead of being annotated with it, so its keys stay literal and the id list variant.ts owns can be declared as keyof typeof V2_SCOPE. A typo there was previously caught only by check-driver under CITRINE_VARIANT=v1, which CI does not run; it is now a build error. --- drivers/citrineos/scope.ts | 44 ++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/drivers/citrineos/scope.ts b/drivers/citrineos/scope.ts index eece83a..3856aa6 100644 --- a/drivers/citrineos/scope.ts +++ b/drivers/citrineos/scope.ts @@ -38,7 +38,9 @@ const OBSERVED = const d = (reason: string) => ({ status: "DRIVABLE" as const, reason }); const na = (reason: string) => ({ status: "NOT_APPLICABLE" as const, reason }); -const V2_SCOPE: ScopeTable = { +// `satisfies` rather than `: ScopeTable`, so the keys stay literal and +// V1_LOCAL_LIST below can be typed against them. +const V2_SCOPE = { // --- Reservation: the whole capability is absent for OCPP 1.6 ----------- "cert16-reservation-basic": na(NO_RESERVATIONS), "cert16-tc048-1-reserve-now-faulted": na(NO_RESERVATIONS), @@ -191,21 +193,8 @@ const V2_SCOPE: ScopeTable = { "response handler, and DiagnosticsStatusNotification has a 1.6 request " + "handler -- so nothing here is answered with a CALLERROR.", ), -}; +} satisfies ScopeTable; -/** - * The v1.9.1 table, derived from V2_SCOPE rather than written out again. - * - * Two edits, and the second one matters more than it looks. The six - * local-auth-list rows become NOT_APPLICABLE, from the id list in variant.ts so - * the table and `unroutedActions` cannot disagree. And EVERY INHERITED REASON - * IS REPLACED, because V2_SCOPE's reasons say "driven green against the pinned - * image" and that measurement was taken on v2 -- carrying the sentence over - * would make this table assert a run that never happened on this line. - * - * The v1.9.1 line has a defect that most of the suite depends on, so a blanket - * "driven green" would be wrong twice over. See V1_KNOWN. - */ /** * Still DRIVABLE, and deliberately not demoted: the driver expresses every one * of these operations against v1.9.1 exactly as it does against v2. What fails @@ -227,12 +216,35 @@ const V1_KNOWN = "Connectors row can be created for an ad-hoc 1.6 station, so StartTransaction " + "is answered Invalid. Fixed in the v2 line -- use CITRINE_VARIANT=v2."; +/** + * The ids variant.ts demotes, restated as keys of V2_SCOPE. + * + * The annotation is the whole point: it makes a typo in that list a build + * error. `check-driver` would also catch it, but only when run with + * CITRINE_VARIANT=v1, and CI runs the v2 table. + */ +const V1_LOCAL_LIST: readonly (keyof typeof V2_SCOPE)[] = + V1_LOCAL_LIST_SCENARIOS; + +/** + * The v1.9.1 table, derived from V2_SCOPE rather than written out again. + * + * Two edits, and the second one matters more than it looks. The six + * local-auth-list rows become NOT_APPLICABLE, from the id list in variant.ts so + * the table and `unroutedActions` cannot disagree. And EVERY INHERITED REASON + * IS REPLACED, because V2_SCOPE's reasons say "driven green against the pinned + * image" and that measurement was taken on v2 -- carrying the sentence over + * would make this table assert a run that never happened on this line. + * + * The v1.9.1 line has a defect that most of the suite depends on, so a blanket + * "driven green" would be wrong twice over. See V1_KNOWN. + */ function v1Scope(): ScopeTable { const table: Record = {}; for (const [id, entry] of Object.entries(V2_SCOPE)) { table[id] = entry.status === "DRIVABLE" ? d(V1_KNOWN) : entry; } - for (const id of V1_LOCAL_LIST_SCENARIOS) { + for (const id of V1_LOCAL_LIST) { table[id] = na(NO_LOCAL_LIST); } return table; From ab7c22ff7aab0b327de3c4b0deae78bfe3d4ea3c Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 11:29:09 +0200 Subject: [PATCH 09/13] docs(citrineos): scope the no-credentials claim to the HTTP API The paragraph is about LocalBypassAuthProvider, but "no credentials anywhere" also reads as a claim about the stack, which does set a Postgres password in compose.yaml and forwards it as PGPASSWORD. --- drivers/citrineos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/citrineos/README.md b/drivers/citrineos/README.md index 76b9e69..fc756a6 100644 --- a/drivers/citrineos/README.md +++ b/drivers/citrineos/README.md @@ -54,7 +54,7 @@ while the simulator container reaches the same CitrineOS as `ws://citrine:8081/` from inside the compose network. That asymmetry is why the two are separate settings — the same one SteVe's driver has, for the same reason. -**No credentials anywhere.** CitrineOS's shipped `docker` app-env selects +**No HTTP API credentials are required.** CitrineOS's shipped `docker` app-env selects `LocalBypassAuthProvider`, which accepts every HTTP request and synthesises an admin principal; it logs a warning saying so on startup. That is a property of this development environment, not of CitrineOS in production, and swapping in From c88aa382681d541aa80fbd1c1d1cced1f3662659 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 11:29:10 +0200 Subject: [PATCH 10/13] fix(tools): keep the tag check running for a tagless provisioner grep exits 1 on no match, and under set -euo pipefail a command substitution that fails aborts the assignment -- so a driver provisioning no CERT tag at all killed the whole check silently, before the FAIL line meant to name it. An empty set is the honest answer, and it falls straight into the missing branch. --- tools/extract-fixture-tags.sh | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tools/extract-fixture-tags.sh b/tools/extract-fixture-tags.sh index 8385d31..bb10110 100755 --- a/tools/extract-fixture-tags.sh +++ b/tools/extract-fixture-tags.sh @@ -87,7 +87,11 @@ status=0 for provisioner in "${provisioners[@]}"; do name="$(basename "$(dirname "$provisioner")")" - driver_tags="$(grep -oE '"CERT[A-Za-z0-9-]+"' "$provisioner" | tr -d '"' | sort -u)" + # `|| true`: grep exits 1 on no match, which under `set -euo pipefail` would + # abort the whole run at the first driver that provisions no tag at all -- + # silently, and before the FAIL line below could name it. An empty set is the + # honest answer there, and it falls straight into the missing branch. + driver_tags="$(grep -oE '"CERT[A-Za-z0-9-]+"' "$provisioner" | tr -d '"' | sort -u || true)" missing="$(comm -23 <(printf '%s\n' "$image_tags") \ <(printf '%s\n' "$driver_tags"))" From f1c2d3e6e14af5acc195e1ced724b8892749bb98 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 14:20:32 +0200 Subject: [PATCH 11/13] fix(drivers): expire the CERT023-EXP fixture as of the run Both provisioners wrote a hardcoded 2020 instant into the expired-tag fixture, so the row claimed to have expired years before any activity recorded against it. Date it from the CSMS's own clock at provisioning time instead, one minute back so the strictly-ordered "is this expired" comparison is unambiguous whatever the clock granularity on either side. It is a backdate, not a wait: nothing sleeps. That is what steve-community/steve#2100 settled on for the endpoint it proposes -- expire with now() rather than accept an arbitrary past date, because a fabricated date is bad data hygiene. Adopting that endpoint later becomes a call swap rather than a change of meaning. The offset and the reasoning live in tck/time.ts as a number of minutes, never an instant: each driver subtracts it server-side, so no timestamp this process computed reaches a fixture. The fixed date was never load-bearing -- both verifiers compare the relation, not the literal, and nothing else in the repository mentions it. --- VENDOR.md | 7 +++-- drivers/citrineos/provision.ts | 53 ++++++++++++++++++++-------------- drivers/steve/provision.ts | 40 ++++++++++++++++++++----- tck/time.ts | 30 +++++++++++++++++++ types/tck/time.d.ts | 29 +++++++++++++++++++ 5 files changed, 128 insertions(+), 31 deletions(-) diff --git a/VENDOR.md b/VENDOR.md index 14f58c9..d6a4bb4 100644 --- a/VENDOR.md +++ b/VENDOR.md @@ -221,8 +221,11 @@ container before the pin moved. All of them still hold, and held identically on - `POST /api/v1/ocppTags` with a past `expiryDate` is rejected **400**: `OcppTagForm.expiryDate` carries `@Future`. The manager UI binds the same form object, so it refuses it too — hence the one SQL write in - `provision.ts`. Raised upstream as [steve-community/steve#2100][sc2100]; - if it is relaxed, that SQL write goes away. + `provision.ts`. That write dates `CERT023-EXP` from MariaDB's own clock at + provisioning time, not from a fabricated historical date, which is what + [steve-community/steve#2100][sc2100] settled on: a `PATCH + /ocppTags/{pk}/expire` endpoint expiring with `now()`. If it lands, the SQL + write folds into REST and the fixture keeps the same meaning. - API access is off until `web_user.api_password` (bcrypt, distinct from the UI password) is set, and SteVe reads that column once at startup. There is still no environment variable for it, so `provision` writes it and restarts diff --git a/drivers/citrineos/provision.ts b/drivers/citrineos/provision.ts index 19fe9e8..502ef23 100644 --- a/drivers/citrineos/provision.ts +++ b/drivers/citrineos/provision.ts @@ -28,6 +28,9 @@ * chasing a failure will run it twice before believing it. */ import { defaultCitrineConfig, type CitrineConfig } from "./config"; +// After ./config, not before: tsc elides this import from the generated .d.ts, +// and the header above travels with whichever import survives. +import { EXPIRED_FIXTURE_BACKDATE_MINUTES } from "../../tck/time"; import { CitrineRecords, sqlLiteral } from "./records"; import { stationColumn } from "./variant"; @@ -72,9 +75,11 @@ const EXPIRED_TAG = "CERT023-EXP"; const BLOCKED_TAG = "CERT023-BLK"; /** - * The expiry written for EXPIRED_TAG. Fixed rather than "now minus a day" so - * that a provisioned environment is identical between runs, which is what lets - * `verify` tell "expired on purpose" from "expired by accident". + * The expiry written for EXPIRED_TAG: an EXPRESSION, not a literal, so Postgres + * dates the row from its own clock at provisioning time -- the run's start, + * never a fabricated historical instant. tck/time.ts owns the offset and the + * policy; `verify` reads it back through the same server's `NOW()`, so no + * instant this process computed ever reaches the fixture. * * The status stays `Accepted` and only the instant makes it expired, which * reads backwards until you follow the handler: AuthorizeRequestOcpp16Handler @@ -82,7 +87,15 @@ const BLOCKED_TAG = "CERT023-BLK"; * branch, and every other stored status falls through to the default. A row * stored as `status = 'Expired'` therefore answers Invalid, not Expired. */ -const PAST_EXPIRY = "2020-01-01T00:00:00Z"; +const EXPIRED_AT_RUN_START = `NOW() - INTERVAL '${EXPIRED_FIXTURE_BACKDATE_MINUTES} minutes'`; + +/** How a fixture expires. A domain value, not a SQL fragment: the table below + * declares WHAT each tag is, and `expiryOf` decides how to say it. */ +type FixtureExpiry = "never" | "at-run-start"; + +function expiryOf(expiry: FixtureExpiry): string { + return expiry === "never" ? "NULL" : EXPIRED_AT_RUN_START; +} /** * Why CERT023-BLK is provisioned anyway, and what it does NOT achieve. @@ -110,14 +123,17 @@ const ID_TOKEN_TYPE = "Central"; interface TagFixture { idToken: string; status: string; - /** ISO instant, or null for "never expires". */ - expiry: string | null; + expiry: FixtureExpiry; } const FIXTURES: readonly TagFixture[] = [ - ...VALID_TAGS.map((idToken) => ({ idToken, status: "Accepted", expiry: null })), - { idToken: EXPIRED_TAG, status: "Accepted", expiry: PAST_EXPIRY }, - { idToken: BLOCKED_TAG, status: "Blocked", expiry: null }, + ...VALID_TAGS.map((idToken) => ({ + idToken, + status: "Accepted", + expiry: "never" as const, + })), + { idToken: EXPIRED_TAG, status: "Accepted", expiry: "at-run-start" }, + { idToken: BLOCKED_TAG, status: "Blocked", expiry: "never" }, ]; /** Every tag this driver owns. Spelled once so that a fixture added to @@ -125,12 +141,6 @@ const FIXTURES: readonly TagFixture[] = [ * demands. */ const ALL_TAGS = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG]; -/** A SQL timestamptz literal, or NULL. Free of `this`, so it lives beside - * sqlLiteral rather than on the class. */ -function nullableInstant(value: string | null): string { - return value === null ? "NULL" : `${sqlLiteral(value)}::timestamptz`; -} - export class CitrineProvisioner { private readonly db: CitrineRecords; @@ -164,13 +174,13 @@ export class CitrineProvisioner { statements.push( `UPDATE "Authorizations" SET "status" = ${sqlLiteral(fixture.status)}, - "cacheExpiryDateTime" = ${nullableInstant(fixture.expiry)}, + "cacheExpiryDateTime" = ${expiryOf(fixture.expiry)}, "updatedAt" = NOW() WHERE ${where};`, `INSERT INTO "Authorizations" ("idToken", "idTokenType", "status", "cacheExpiryDateTime", "tenantId", "createdAt", "updatedAt") SELECT ${idToken}, ${sqlLiteral(ID_TOKEN_TYPE)}, ${sqlLiteral(fixture.status)}, - ${nullableInstant(fixture.expiry)}, ${this.tenant}, NOW(), NOW() + ${expiryOf(fixture.expiry)}, ${this.tenant}, NOW(), NOW() WHERE NOT EXISTS (SELECT 1 FROM "Authorizations" WHERE ${where});`, ); } @@ -187,7 +197,8 @@ export class CitrineProvisioner { await this.db.scalar(statements.join("\n")); this.log( - `tags: ${VALID_TAGS.length} valid, ${EXPIRED_TAG} expired at ${PAST_EXPIRY}, ` + + `tags: ${VALID_TAGS.length} valid, ${EXPIRED_TAG} expired ` + + `${EXPIRED_FIXTURE_BACKDATE_MINUTES} min before this run's provisioning, ` + `${BLOCKED_TAG} (${BLOCKED_TAG_CAVEAT}), ${INVALID_TAG} absent`, ); } @@ -287,9 +298,9 @@ export class CitrineProvisioner { if (!expired || expired[3] === "") { problems.push(`${EXPIRED_TAG}: missing or has no cacheExpiryDateTime`); } else if (expired[2] !== "Accepted") { - // The trap PAST_EXPIRY's comment describes, checked rather than merely - // documented: any other status makes the handler answer Invalid and the - // expiry is never consulted. + // The trap EXPIRED_AT_RUN_START's comment describes, checked rather than + // merely documented: any other status makes the handler answer Invalid + // and the expiry is never consulted. problems.push( `${EXPIRED_TAG}: status ${expired[2]}, expected Accepted -- only the ` + "Accepted branch consults cacheExpiryDateTime", diff --git a/drivers/steve/provision.ts b/drivers/steve/provision.ts index f22cd82..38235b7 100644 --- a/drivers/steve/provision.ts +++ b/drivers/steve/provision.ts @@ -29,8 +29,14 @@ * asserts. The write path forbids the state the read path exists to * report, so the SQL below is working around an input rule, not * around the protocol. Raised upstream as - * steve-community/steve#2100; if it is relaxed, this channel goes - * away and tags become REST-only. + * steve-community/steve#2100. + * + * What that SQL writes is deliberately the same thing the endpoint + * proposed there would: the tag is expired AS OF THIS RUN, from the + * database's own clock, never a fabricated historical date -- see + * EXPIRED_FIXTURE_BACKDATE_MINUTES in tck/time.ts. So if + * `PATCH /ocppTags/{pk}/expire` lands, this channel goes away and tags + * become REST-only without any fixture changing meaning. * UI for the two charging profiles. SteVe's WebAPI exposes exactly * ocppTags, operations and transactions (confirmed against its own * /v3/api-docs); there is no chargingProfile endpoint at all. @@ -46,6 +52,7 @@ * must be a no-op that still exits 0, because CI reruns it and an operator * chasing a failure will run it twice before believing it. */ +import { EXPIRED_FIXTURE_BACKDATE_MINUTES } from "../../tck/time"; import { waitForCondition } from "../../tck/wait"; import { chargingProfileForm, type ChargingProfileFields } from "./forms"; import { SteveRecords, sqlLiteral } from "./records"; @@ -104,11 +111,20 @@ const EXPIRED_TAG = "CERT023-EXP"; const BLOCKED_TAG = "CERT023-BLK"; /** - * The expiry written for EXPIRED_TAG. Fixed rather than "now minus a day" so - * that a provisioned environment is byte-identical between runs, which is what - * makes `verify` able to tell "expired on purpose" from "expired by accident". + * The expiry written for EXPIRED_TAG: an EXPRESSION, not a literal, so MariaDB + * dates the row from its own clock at provisioning time. `verify` asks the same + * server the same way (`expiry_date < NOW()`), so neither this process's clock + * nor its timezone enters the fixture at any point. + * + * The backdate is what makes both readers agree, and each is strict in its own + * way: SteVe's `isExpired` is `now.isAfter(expiry)`, and `verify`'s `NOW()` is + * second-granular while `ocpp_tag.expiry_date` is `timestamp(6)` -- so an + * expiry written at exactly "now" reads as not-yet-expired for the rest of that + * second, which `provision` would hit on the spot since it verifies itself. + * `NOW(6)` rather than `NOW()` for the same reason: truncating the written + * value would narrow the margin for nothing. */ -const PAST_EXPIRY = "2020-01-01 00:00:00"; +const EXPIRED_AT_RUN_START = `NOW(6) - INTERVAL ${EXPIRED_FIXTURE_BACKDATE_MINUTES} MINUTE`; /** `limitW` on the first: TC_066 asserts that exact number on the composite * schedule. The field names it turns into live in forms.ts. */ @@ -361,6 +377,12 @@ export class SteveProvisioner { // Created through the API for the row, then aged through SQL: @Future makes // the API refuse to write a past date, but says nothing about reading one. + // + // The UPDATE is unconditional, and that is the idempotency wanted here + // rather than a departure from it: every provision re-expires the tag as of + // that run, which is exactly what an `expire` endpoint called with now() + // would do. Skipping it when the row is already expired would keep an older + // run's instant alive for no gain. if (!existing.has(EXPIRED_TAG)) { await this.createTag({ idTag: EXPIRED_TAG, @@ -368,9 +390,11 @@ export class SteveProvisioner { }); } await this.db.scalar( - `UPDATE ocpp_tag SET expiry_date = ${sqlLiteral(PAST_EXPIRY)} WHERE id_tag = ${sqlLiteral(EXPIRED_TAG)};`, + `UPDATE ocpp_tag SET expiry_date = ${EXPIRED_AT_RUN_START} WHERE id_tag = ${sqlLiteral(EXPIRED_TAG)};`, + ); + this.log( + `tag: ${EXPIRED_TAG} expired ${EXPIRED_FIXTURE_BACKDATE_MINUTES} min before this run's provisioning`, ); - this.log(`tag: ${EXPIRED_TAG} expired ${PAST_EXPIRY}`); const invalid = existing.get(INVALID_TAG); if (invalid) { diff --git a/tck/time.ts b/tck/time.ts index 617c44e..fd78749 100644 --- a/tck/time.ts +++ b/tck/time.ts @@ -15,6 +15,12 @@ * minute could land in the already-past current minute. That made one CSMS's * form resolution a property of the OCPP scenario, which is exactly the kind * of leak this file exists to remove. + * + * WHICH CLOCK RESOLVES AN INSTANT IS A DRIVER CONCERN TOO, which is why the + * provisioning policy below is an OFFSET IN MINUTES rather than a `Date`: an + * instant computed here would carry this process's clock into a system that + * has its own. Handed the offset, a driver applies it however its CSMS is + * addressed. */ export function inMinutes(minutes: number, now: Date = new Date()): Date { return new Date(now.getTime() + minutes * 60_000); @@ -23,3 +29,27 @@ export function inMinutes(minutes: number, now: Date = new Date()): Date { export function inSeconds(seconds: number, now: Date = new Date()): Date { return new Date(now.getTime() + seconds * 1_000); } + +/** + * How far before the provisioning instant a fixture that must ALREADY BE + * EXPIRED is dated -- CERT023-EXP, the tag TC_023.2 needs the CSMS to answer + * `Expired` for. + * + * The policy, which is the part worth sharing: such a fixture is dated from the + * run itself, never from a fabricated historical date. A row that claims to + * have expired years before the activity recorded against it is a lie the + * scenarios do not need, and one that no CSMS should have to accept in order to + * be measured. + * + * Why an offset rather than the instant itself: "expired" is read back through + * a strictly-ordered comparison, and the clock that answers it may be coarser + * than whatever stores it -- so a fixture stamped at exactly "now" can read as + * not-yet-expired for the rest of that second, which a provisioner that + * verifies itself hits immediately. A minute clears that, along with any skew + * between the clocks involved. + * + * It costs nothing: this is a BACKDATE, not a wait. Nothing sleeps. How a given + * CSMS is told about it, and which of its clocks decides, each driver's + * provisioner says for itself. + */ +export const EXPIRED_FIXTURE_BACKDATE_MINUTES = 1; diff --git a/types/tck/time.d.ts b/types/tck/time.d.ts index 4c18685..75fd541 100644 --- a/types/tck/time.d.ts +++ b/types/tck/time.d.ts @@ -13,6 +13,35 @@ * minute could land in the already-past current minute. That made one CSMS's * form resolution a property of the OCPP scenario, which is exactly the kind * of leak this file exists to remove. + * + * WHICH CLOCK RESOLVES AN INSTANT IS A DRIVER CONCERN TOO, which is why the + * provisioning policy below is an OFFSET IN MINUTES rather than a `Date`: an + * instant computed here would carry this process's clock into a system that + * has its own. Handed the offset, a driver applies it however its CSMS is + * addressed. */ export declare function inMinutes(minutes: number, now?: Date): Date; export declare function inSeconds(seconds: number, now?: Date): Date; +/** + * How far before the provisioning instant a fixture that must ALREADY BE + * EXPIRED is dated -- CERT023-EXP, the tag TC_023.2 needs the CSMS to answer + * `Expired` for. + * + * The policy, which is the part worth sharing: such a fixture is dated from the + * run itself, never from a fabricated historical date. A row that claims to + * have expired years before the activity recorded against it is a lie the + * scenarios do not need, and one that no CSMS should have to accept in order to + * be measured. + * + * Why an offset rather than the instant itself: "expired" is read back through + * a strictly-ordered comparison, and the clock that answers it may be coarser + * than whatever stores it -- so a fixture stamped at exactly "now" can read as + * not-yet-expired for the rest of that second, which a provisioner that + * verifies itself hits immediately. A minute clears that, along with any skew + * between the clocks involved. + * + * It costs nothing: this is a BACKDATE, not a wait. Nothing sleeps. How a given + * CSMS is told about it, and which of its clocks decides, each driver's + * provisioner says for itself. + */ +export declare const EXPIRED_FIXTURE_BACKDATE_MINUTES = 1; From bb962cbc631da330f57b3462d6c9765756949393 Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 14:20:55 +0200 Subject: [PATCH 12/13] refactor(steve): read the CSMS through its WebAPI, not its database The driver answered every observation out of MariaDB through docker exec, on the stated grounds that SteVe's WebAPI "does not expose stop_reason". Measured against the pinned image, that was wrong: GET /api/v1/transactions serves stopReason, stopTimestamp and ocppIdTag on the Transaction DTO, filters by chargeBoxId, ocppIdTag, transactionPk and type=ACTIVE with no default date window, and PATCH /transactions/{pk}/stop closes a transaction without putting anything on the wire -- which is exactly what the stale-transaction hook needs. So transactions, fixture verification and tag teardown now go through the API, and the database is left with precisely what SteVe has no endpoint for, each naming its ticket: expiry write steve-community/steve#2100 WebAPI credential bootstrap steve-community/steve#2075, #2059 reservations steve-community/steve#2074 charging profiles steve-community/steve#2069 That is the property to preserve: every remaining database access in this driver is one of those four, and nothing else. Asserting through the API is also the stronger claim -- an integrator can reproduce it, where a claim about SteVe's private tables cannot be. A shared client (api-client.ts) now serves both the provisioner and the records reader; appContainer moves to SteveConfig, beside dbContainer, since a container name is deployment rather than transport. verify() trades two properties for this, deliberately: it no longer works on an environment where API access was never enabled, and it compares the expiry against this process's clock -- which the fixture's one-minute backdate covers. Refs #8: 44 of the 51 record calls a sweep makes no longer spawn a process. The issue stays open -- the SQL transport is unchanged, and the CitrineOS driver has no API to move to. --- VENDOR.md | 46 +++- drivers/citrineos/provision.ts | 29 ++- drivers/steve/api-client.ts | 143 +++++++++++ drivers/steve/index.ts | 32 ++- drivers/steve/provision.ts | 324 ++++++++++++------------- drivers/steve/records.ts | 177 +++++++++++--- drivers/steve/ui-client.ts | 7 + types/drivers/citrineos/provision.d.ts | 18 +- types/drivers/steve/api-client.d.ts | 69 ++++++ types/drivers/steve/index.d.ts | 20 +- types/drivers/steve/provision.d.ts | 40 +-- types/drivers/steve/records.d.ts | 90 ++++++- types/drivers/steve/ui-client.d.ts | 6 + 13 files changed, 735 insertions(+), 266 deletions(-) create mode 100644 drivers/steve/api-client.ts create mode 100644 types/drivers/steve/api-client.d.ts diff --git a/VENDOR.md b/VENDOR.md index d6a4bb4..32ca204 100644 --- a/VENDOR.md +++ b/VENDOR.md @@ -72,6 +72,7 @@ strongest available demonstration that the core names no CSMS. | `drivers/steve/index.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/forms.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/records.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | +| `drivers/steve/api-client.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/ui-client.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/scope.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | | `drivers/steve/provision.ts` | `local-upstreamable` | `—` | `—` | `—` | `—` | @@ -213,11 +214,25 @@ container before the pin moved. All of them still hold, and held identically on 3.13.0: - SteVe's WebAPI exposes `ocppTags`, `operations` and `transactions` — and - nothing else. There is no chargeBox and no chargingProfile endpoint, per its - own `/steve/manager/v3/api-docs`. That is why provisioning uses three - channels and not one. This is the bullet most likely to change: - [steve-community/steve#2069][sc2069] proposes charging-profile CRUD, and - would let the UI channel fold into REST. + nothing else. Probed on this digest: `chargePoints`, `reservations` and + `chargingProfiles` all answer **403**, because no such controller exists. + That is why provisioning uses three channels and not one, and why the SQL + channel is exactly the list of endpoints SteVe does not have. This is the + bullet most likely to change: [steve-community/steve#2069][sc2069] proposes + charging-profile CRUD, and would let the UI channel fold into REST. +- `GET /api/v1/transactions` serves the observations the scenarios assert on: + the `Transaction` DTO carries `id`, `ocppIdTag`, `startTimestamp`, + `stopTimestamp`, `stopReason` and `stopEventActor`, and + `TransactionQueryFormForApi` filters by `chargeBoxId`, `ocppIdTag`, + `transactionPk` and `type=ACTIVE` with **no** default date window (its + constructor sets `periodType = ALL`). All four filters were exercised against + a real transaction on this digest. `PATCH /transactions/{pk}/stop` closes a + transaction **without touching the wire** — `TransactionService#stop` writes + the stop row with `eventActor = manual` and returns early if it is already + stopped — which is what the stale-transaction hook needs, since the charge + point that opened it is gone. An earlier revision of `records.ts` claimed the + API exposed no `stop_reason` and read everything from MariaDB; that claim was + wrong on 3.13.0 and 3.14.0 alike. - `POST /api/v1/ocppTags` with a past `expiryDate` is rejected **400**: `OcppTagForm.expiryDate` carries `@Future`. The manager UI binds the same form object, so it refuses it too — hence the one SQL write in @@ -230,6 +245,23 @@ container before the pin moved. All of them still hold, and held identically on UI password) is set, and SteVe reads that column once at startup. There is still no environment variable for it, so `provision` writes it and restarts the container — once; it probes first and skips when already on. + [steve-community/steve#2075][sc2075] (manager and API account CRUD) and + [#2059][sc2059] (a Web UI for those accounts) are what would end it. + +Every remaining database access in `drivers/steve/` is one of these four gaps, +and nothing else — which is the property to preserve when editing that driver: + +| what needs the database | upstream ticket | +|---|---| +| write a past `expiry_date` | [#2100][sc2100] | +| turn the WebAPI on (`web_user.api_password`) | [#2075][sc2075], [#2059][sc2059] | +| read reservation status; teardown's reservation guard | [#2074][sc2074] | +| create, verify and remove charging profiles | [#2069][sc2069] | + +All four sit under the [#1000 "Meta - API Endpoint"][sc1000] umbrella. The +CitrineOS driver has no such table because it has no such tickets: issues are +disabled on `citrineos/citrineos-core`, and its missing Authorization CRUD is +unreported rather than pending. - The `chargingProfiles/add` form binds the same field names, including the indexed `schedulePeriods[N].powerLimit`. - Unknown idTags are **not** auto-inserted on Authorize, which is what makes @@ -251,7 +283,11 @@ a scenario rather than by a version number: TC_052 is the reason it exists, and TC_052 passes on this digest. If TC_052 ever regresses, read that header first. [sc2069]: https://github.com/steve-community/steve/issues/2069 +[sc2074]: https://github.com/steve-community/steve/issues/2074 +[sc2075]: https://github.com/steve-community/steve/issues/2075 [sc2100]: https://github.com/steve-community/steve/issues/2100 +[sc1000]: https://github.com/steve-community/steve/issues/1000 +[sc2059]: https://github.com/steve-community/steve/issues/2059 ### CitrineOS diff --git a/drivers/citrineos/provision.ts b/drivers/citrineos/provision.ts index 502ef23..13bd130 100644 --- a/drivers/citrineos/provision.ts +++ b/drivers/citrineos/provision.ts @@ -19,6 +19,14 @@ * Hasura sidecar would offer insert mutations, at the cost of vendoring its * metadata -- see records.ts for why that trade was refused. * + * Unlike the SteVe driver, whose every database write names the upstream + * ticket that would replace it, THIS FILE HAS NO TICKET TO NAME: issues are + * disabled on citrineos/citrineos-core, and the two filed against + * citrineos/citrineos from this repository (#215, #216) are protocol defects + * rather than the missing data API. Nothing here is waiting on a number -- + * the gap is unreported, which is a state worth writing down rather than + * leaving as an apparent omission. + * * Charging profiles are not provisioned here either, and that is not an * omission: OCPP 1.6 SetChargingProfile carries the profile inline, so there * is no CSMS-side record to create. profiles.ts holds the catalogue. @@ -28,8 +36,8 @@ * chasing a failure will run it twice before believing it. */ import { defaultCitrineConfig, type CitrineConfig } from "./config"; -// After ./config, not before: tsc elides this import from the generated .d.ts, -// and the header above travels with whichever import survives. +// Second on purpose: tsc elides this import from the .d.ts, and the header +// above travels with whichever import survives. import { EXPIRED_FIXTURE_BACKDATE_MINUTES } from "../../tck/time"; import { CitrineRecords, sqlLiteral } from "./records"; import { stationColumn } from "./variant"; @@ -171,16 +179,19 @@ export class CitrineProvisioner { for (const fixture of FIXTURES) { const idToken = sqlLiteral(fixture.idToken); const where = `"idToken" = ${idToken} AND "tenantId" = ${this.tenant}`; + // Bound once, like `where`: how "never expires" renders is one decision, + // and the UPDATE and the INSERT below must never disagree about it. + const expiry = expiryOf(fixture.expiry); statements.push( `UPDATE "Authorizations" SET "status" = ${sqlLiteral(fixture.status)}, - "cacheExpiryDateTime" = ${expiryOf(fixture.expiry)}, + "cacheExpiryDateTime" = ${expiry}, "updatedAt" = NOW() WHERE ${where};`, `INSERT INTO "Authorizations" ("idToken", "idTokenType", "status", "cacheExpiryDateTime", "tenantId", "createdAt", "updatedAt") SELECT ${idToken}, ${sqlLiteral(ID_TOKEN_TYPE)}, ${sqlLiteral(fixture.status)}, - ${expiryOf(fixture.expiry)}, ${this.tenant}, NOW(), NOW() + ${expiry}, ${this.tenant}, NOW(), NOW() WHERE NOT EXISTS (SELECT 1 FROM "Authorizations" WHERE ${where});`, ); } @@ -203,11 +214,6 @@ export class CitrineProvisioner { ); } - /** - * Read-only. Two queries rather than one per fixture: each db call is a - * `docker exec` process spawn, so asking about twenty tags one at a time - * costs seconds of pure process startup -- and verify() runs twice in CI. - */ /** * Does the running server's schema match the variant we were told to expect? * @@ -240,6 +246,11 @@ export class CitrineProvisioner { ]; } + /** + * Read-only. Two queries rather than one per fixture: each db call is a + * `docker exec` process spawn, so asking about twenty tags one at a time + * costs seconds of pure process startup -- and verify() runs twice in CI. + */ async verify(): Promise { // First, and returning early -- not because the checks below depend on it // (they read `Authorizations`, which has no station column) but because of diff --git a/drivers/steve/api-client.ts b/drivers/steve/api-client.ts new file mode 100644 index 0000000..e9a8772 --- /dev/null +++ b/drivers/steve/api-client.ts @@ -0,0 +1,143 @@ +// Copyright 2026 Julien Herr +// SPDX-License-Identifier: Apache-2.0 +/** + * api-client.ts -- SteVe's WebAPI, the one channel that is neither a form post + * nor a database connection. + * + * It exists as its own module because two callers need it for opposite + * reasons: `provision.ts` WRITES fixtures through it, and `records.ts` READS + * what the CSMS believes happened. Before this file, the client lived inside + * the provisioner and observations had no choice but to shell out to MariaDB. + * + * WHAT IT CAN REACH. Exactly `ocppTags`, `transactions` and `operations` -- + * confirmed by probing the pinned image, where `chargePoints`, `reservations` + * and `chargingProfiles` all answer 403 because no such controller exists. + * That is why the SQL channel does not go away: it is now, precisely, the list + * of endpoints SteVe does not have. See VENDOR.md. + * + * AUTHENTICATION is HTTP Basic against `web_user.api_password`, a bcrypt + * column distinct from the UI password and NULL until something writes it -- + * which is `provision.ts`'s job, not this file's. A caller that gets 401 here + * has not provisioned; the message says so. + */ +import type { SteveConfig } from "./ui-client"; + +const HTTP_TIMEOUT_MS = 15_000; + +export interface SteveApiConfig { + /** e.g. http://localhost:8180/steve/api/v1 */ + baseUrl: string; + username: string; + password: string; +} + +export function defaultApiConfig( + cfg: SteveConfig, + env: NodeJS.ProcessEnv = process.env, +): SteveApiConfig { + return { + baseUrl: + env.STEVE_API_URL ?? cfg.baseUrl.replace(/\/manager\/?$/, "/api/v1"), + username: env.STEVE_API_USER ?? cfg.username, + password: env.STEVE_API_PASS ?? "ocpp-tck", + }; +} + +/** + * Query parameters as a LIST OF PAIRS, not a record: SteVe's query forms take + * repeated keys for their list filters (`chargeBoxId` and `ocppIdTag` are + * `List` on QueryForm), and a record would silently cap each filter at + * one value. + */ +export type QueryParams = readonly (readonly [string, string])[]; + +export class SteveWebApi { + /** Encoded once. Rebuilding it per request would put a base64 of the + * credentials inside the one-second poll loop in records.ts. */ + private readonly authorization: string; + + constructor(private readonly cfg: SteveApiConfig) { + this.authorization = `Basic ${btoa(`${cfg.username}:${cfg.password}`)}`; + } + + /** GET, decoded. The shape is the caller's to declare: this module knows the + * transport, `records.ts` and `provision.ts` know the payloads. */ + async getJson(path: string, params: QueryParams = []): Promise { + const res = await this.request("GET", path, { params, allowed: [200] }); + return (await res.json()) as T; + } + + /** + * A write. `allowed` defaults to the pair SteVe actually answers with -- 200 + * from a controller returning a value, 204 from a `void` one -- and 201 + * because POST /ocppTags may answer either. + * + * The failure description is derived from the request rather than passed in, + * which is the point of having this at all: three call sites used to spell + * out "DELETE /ocppTags/${pk}" beside the very call that said it, and a + * hand-written label is one refactor away from describing a different route. + */ + async send( + method: string, + path: string, + opts: { body?: unknown; allowed?: readonly number[] } = {}, + ): Promise { + return this.request(method, path, { + allowed: opts.allowed ?? [200, 201, 204], + init: { + method, + ...(opts.body === undefined + ? {} + : { body: JSON.stringify(opts.body) }), + }, + }); + } + + /** Whether the WebAPI answers with the configured credentials. A probe, so a + * rejection is an answer ("no") rather than a failure. */ + async reachable(): Promise { + try { + return (await this.raw("/ocppTags", {})).status === 200; + } catch { + return false; + } + } + + /** + * One request, checked. The single place that decides what an unacceptable + * status looks like, so the body-truncation and the message shape cannot + * drift per call site. + */ + private async request( + method: string, + path: string, + opts: { params?: QueryParams; allowed: readonly number[]; init?: RequestInit }, + ): Promise { + const res = await this.raw(path, opts.init ?? {}, opts.params); + if (opts.allowed.includes(res.status)) return res; + const what = `${method} ${path}`; + throw new Error( + res.status === 401 || res.status === 403 + ? `steve api: ${what} returned ${res.status}. WebAPI access is off until ` + + `web_user.api_password is set -- run \`ocpp-tck driver provision\` first.` + : `steve api: ${what} returned ${res.status}: ${(await res.text()).slice(0, 300)}`, + ); + } + + private async raw( + path: string, + init: RequestInit, + params: QueryParams = [], + ): Promise { + const query = new URLSearchParams(params as [string, string][]).toString(); + return fetch(`${this.cfg.baseUrl}${path}${query ? `?${query}` : ""}`, { + ...init, + headers: { + authorization: this.authorization, + "content-type": "application/json", + ...(init.headers ?? {}), + }, + signal: AbortSignal.timeout(HTTP_TIMEOUT_MS), + }); + } +} diff --git a/drivers/steve/index.ts b/drivers/steve/index.ts index fc6cb97..c665727 100644 --- a/drivers/steve/index.ts +++ b/drivers/steve/index.ts @@ -35,12 +35,20 @@ * * Where it has to run * ------------------- - * Observations come from MariaDB through `docker exec`, because SteVe's REST - * API exposes neither stop_reason, nor reservation status, nor the - * charging-profile registry. So this driver runs on the host that owns the - * SteVe containers, and reaches the manager UI on the container network -- - * a deployment behind a forward-auth proxy is unreachable from outside it, - * and its OCPP port may not be published to the internet at all. + * Transactions are observed over the WebAPI, which serves `stopReason`, + * `stopTimestamp` and `ocppIdTag` and filters by charge point, idTag and + * active-ness -- measured on the pinned image, and worth stating because an + * earlier version of this file claimed the opposite and read all of it from + * MariaDB. What REST genuinely cannot serve is reservation status and the + * charging-profile registry: no such controller exists. Those two still come + * from MariaDB through `docker exec` -- steve-community/steve#2074 and #2069 + * respectively, both under the #1000 "Meta - API Endpoint" umbrella. + * + * So this driver runs on the host that owns the SteVe containers, and reaches + * the manager UI on the container network -- a deployment behind a + * forward-auth proxy is unreachable from outside it, and its OCPP port may not + * be published to the internet at all. The day those two tickets land, that + * constraint goes with them. */ import { CSMS_OPERATION_ACTIONS, @@ -51,6 +59,7 @@ import { type CsmsOperation, type CsmsOperations, } from "../../tck/driver"; +import { defaultApiConfig } from "./api-client"; import { cpSelect, toSteveForm } from "./forms"; import { provisionCommand, @@ -86,7 +95,9 @@ export const csmsDriver: CsmsDriverModule = { capabilities: CAPABILITIES, create(env: CsmsEnv): CsmsDriverParts { const cfg = defaultSteveConfig(env); - const records = new SteveRecords(cfg); + // `env`, not process.env: the runner owns what a driver may read, and the + // WebAPI credentials are now on the scenario path, not just provisioning's. + const records = new SteveRecords(cfg, defaultApiConfig(cfg, env)); return { operations: createOperations(cfg), records, @@ -117,14 +128,15 @@ export const csmsDriver: CsmsDriverModule = { "STEVE_DB_USER MariaDB user (default steve)", "STEVE_DB_PASS MariaDB password", "STEVE_DB_NAME MariaDB schema (default stevedb)", + "STEVE_APP_CONTAINER SteVe container (default steve). Restarted once by", + " provision, to enable the WebAPI.", "STEVE_NETWORK docker network the simulator joins to reach SteVe", "", - "provisioning only (ocpp-tck driver provision):", + "WebAPI -- fixtures AND transaction observations, so scenarios need it too:", "STEVE_API_URL WebAPI base (default: STEVE_URL with /manager -> /api/v1)", "STEVE_API_USER WebAPI user (default: STEVE_USER)", "STEVE_API_PASS WebAPI password (default ocpp-tck). Stored bcrypt-hashed in", " web_user.api_password, which is NOT the manager UI password.", - "STEVE_APP_CONTAINER SteVe container, restarted once to enable the WebAPI", - " (default steve)", + " Set the same value here as when you provisioned.", ].join("\n"), }; diff --git a/drivers/steve/provision.ts b/drivers/steve/provision.ts index 38235b7..a749f4f 100644 --- a/drivers/steve/provision.ts +++ b/drivers/steve/provision.ts @@ -11,10 +11,15 @@ * unrunnable. This is its replacement, reachable as `ocpp-tck driver provision`. * * Three channels, because no single one can do the job -- each claim below was - * verified against the pinned image (see VENDOR.md), not inferred: + * verified against the pinned image (see VENDOR.md), not inferred. The REST + * channel is used wherever REST can answer, on purpose: a fixture asserted + * through the API is a fixture an integrator could reproduce, while one + * asserted through the tables is a claim about SteVe's private state. So the + * two other channels are not a style choice -- each is a missing endpoint with + * a ticket number, and the day it lands the channel goes with it. * - * REST `POST /api/v1/ocppTags` for tags. The cleanest channel, and the only - * one with real create/update semantics. + * REST tags, end to end: `POST /ocppTags` to create, `GET /ocppTags` for + * everything `verify` checks, `DELETE /ocppTags/{pk}` for teardown. * SQL for `CERT023-EXP` alone. OcppTagForm.expiryDate carries @Future, so * REST answers 400 to a past date -- and the manager UI binds the very * same form, so it refuses it too. A row that must look stale can only @@ -38,15 +43,30 @@ * `PATCH /ocppTags/{pk}/expire` lands, this channel goes away and tags * become REST-only without any fixture changing meaning. * UI for the two charging profiles. SteVe's WebAPI exposes exactly - * ocppTags, operations and transactions (confirmed against its own - * /v3/api-docs); there is no chargingProfile endpoint at all. - * steve-community/steve#2069 proposes adding that CRUD, noting that - * "a fully automated client must therefore use the manager UI or - * direct database access". If it lands, this channel folds into REST. + * ocppTags, operations and transactions; there is no chargingProfile + * endpoint at all. steve-community/steve#2069 proposes adding that + * CRUD, noting that "a fully automated client must therefore use the + * manager UI or direct database access". If it lands, this channel + * folds into REST, and so does verify's second half and teardown's. + * + * Two more places reach past the API for the same reason, each with its own + * ticket: + * + * web_user.api_password written in SQL to turn the WebAPI on at all -- no + * endpoint, no environment variable, and the /webusers page is not + * reachable. steve-community/steve#2075 (manager and API account CRUD) + * and #2059 (a Web UI for web-user accounts) are the two that would + * end it. Until then, enabling the API costs a database write. + * reservation.id_tag read in SQL by teardown, to avoid deleting a tag a + * reservation still references. steve-community/steve#2074. + * + * All of these sit under the #1000 "Meta - API Endpoint" umbrella, which is + * the one link to follow when wondering why a TCK needs database access. * * Charge points are not provisioned here on purpose: there is no REST endpoint - * for them either, and compose.yaml sets AUTO_REGISTER_UNKNOWN_STATIONS=true so - * the roster registers itself on first BootNotification. + * for them either (steve-community/steve#2068), and compose.yaml sets + * AUTO_REGISTER_UNKNOWN_STATIONS=true so the roster registers itself on first + * BootNotification. * * Everything is idempotent. Re-running provision on a provisioned environment * must be a no-op that still exits 0, because CI reruns it and an operator @@ -54,11 +74,18 @@ */ import { EXPIRED_FIXTURE_BACKDATE_MINUTES } from "../../tck/time"; import { waitForCondition } from "../../tck/wait"; +import { + defaultApiConfig, + SteveWebApi, + type SteveApiConfig, +} from "./api-client"; import { chargingProfileForm, type ChargingProfileFields } from "./forms"; import { SteveRecords, sqlLiteral } from "./records"; import { defaultSteveConfig, SteveUiOps, type SteveConfig } from "./ui-client"; -const HTTP_TIMEOUT_MS = 15_000; +/** Per-request budget for the signin probe below; the WebAPI client owns its + * own, and the manager UI client owns a third. */ +const SIGNIN_PROBE_TIMEOUT_MS = 15_000; const RESTART_TIMEOUT_MS = 300_000; const RESTART_POLL_MS = 3_000; @@ -112,17 +139,17 @@ const BLOCKED_TAG = "CERT023-BLK"; /** * The expiry written for EXPIRED_TAG: an EXPRESSION, not a literal, so MariaDB - * dates the row from its own clock at provisioning time. `verify` asks the same - * server the same way (`expiry_date < NOW()`), so neither this process's clock - * nor its timezone enters the fixture at any point. + * dates the row from its own clock at provisioning time rather than from this + * process's -- the write is the one place where using the CSMS's own clock + * costs nothing. * - * The backdate is what makes both readers agree, and each is strict in its own - * way: SteVe's `isExpired` is `now.isAfter(expiry)`, and `verify`'s `NOW()` is - * second-granular while `ocpp_tag.expiry_date` is `timestamp(6)` -- so an - * expiry written at exactly "now" reads as not-yet-expired for the rest of that - * second, which `provision` would hit on the spot since it verifies itself. - * `NOW(6)` rather than `NOW()` for the same reason: truncating the written - * value would narrow the margin for nothing. + * The backdate is what makes every reader agree, and each is strict in its own + * way: SteVe's `isExpired` is `now.isAfter(expiry)`, and `verify` compares the + * instant the API reports against THIS process's clock. A minute covers the + * gap between the two clocks and the second-granularity of `NOW()`, which + * `provision` would otherwise trip over immediately since it verifies itself. + * `NOW(6)` rather than `NOW()` so the written value does not lose precision + * the margin is there to protect. */ const EXPIRED_AT_RUN_START = `NOW(6) - INTERVAL ${EXPIRED_FIXTURE_BACKDATE_MINUTES} MINUTE`; @@ -133,76 +160,51 @@ const PROFILES: readonly ChargingProfileFields[] = [ { description: "TC057 TxProfile", purpose: "TX_PROFILE", limitW: 11000 }, ]; -export interface SteveApiConfig { - /** e.g. http://localhost:8180/steve/api/v1 */ - baseUrl: string; - username: string; - password: string; - /** Container running the SteVe application, restarted to pick up API access. */ - appContainer: string; -} - -export function defaultApiConfig( - cfg: SteveConfig, - env: NodeJS.ProcessEnv = process.env, -): SteveApiConfig { - return { - baseUrl: - env.STEVE_API_URL ?? cfg.baseUrl.replace(/\/manager\/?$/, "/api/v1"), - username: env.STEVE_API_USER ?? cfg.username, - password: env.STEVE_API_PASS ?? "ocpp-tck", - appContainer: env.STEVE_APP_CONTAINER ?? "steve", - }; -} - +/** + * SteVe's `OcppTagOverview`, narrowed to what provisioning and verification + * read. `blocked` is SteVe's own reading of the fixture rather than ours: it is + * derived from maxActiveTransactionCount server-side, so asserting on it checks + * the state the Authorize path will actually see. + */ interface OcppTagOverview { ocppTagPk: number; idTag: string; expiryDate: string | null; + blocked: boolean; maxActiveTransactionCount: number; } +/** + * What "this fixture is still what we seeded" means, spelled once. + * + * provision and verify have to agree on it or the environment oscillates: + * provision rebuilding a tag every run because its rule says "drifted" while + * verify's says "clean", or verify blessing a tag provision would rebuild. + * They used to answer the same two questions off different fields -- + * maxActiveTransactionCount here, SteVe's derived `blocked` there. + */ +function isUsable(row: OcppTagOverview): boolean { + return !row.blocked && row.expiryDate === null; +} + +function isBlocked(row: OcppTagOverview): boolean { + return row.blocked; +} + export class SteveProvisioner { private readonly ui: SteveUiOps; private readonly db: SteveRecords; + private readonly api: SteveWebApi; + constructor( private readonly cfg: SteveConfig, - private readonly api: SteveApiConfig, + private readonly apiCfg: SteveApiConfig, private readonly log: (msg: string) => void = stdout, ) { + this.api = new SteveWebApi(apiCfg); this.ui = new SteveUiOps(cfg); - this.db = new SteveRecords(cfg); - } - - private async apiFetch( - path: string, - init: RequestInit = {}, - ): Promise { - return fetch(`${this.api.baseUrl}${path}`, { - ...init, - headers: { - authorization: `Basic ${btoa(`${this.api.username}:${this.api.password}`)}`, - "content-type": "application/json", - ...(init.headers ?? {}), - }, - signal: AbortSignal.timeout(HTTP_TIMEOUT_MS), - }); - } - - /** One place that decides what an unacceptable WebAPI status looks like, so - * the body-truncation and the message shape cannot drift per call site. */ - private async expectStatus( - res: Response, - allowed: readonly number[], - what: string, - ): Promise { - if (!allowed.includes(res.status)) { - throw new Error( - `steve provision: ${what} returned ${res.status}: ${(await res.text()).slice(0, 300)}`, - ); - } - return res; + this.db = new SteveRecords(cfg, apiCfg); } /** @@ -230,7 +232,7 @@ export class SteveProvisioner { * overwritten -- the operator knows their password and this does not. */ async ensureApiAccess(): Promise { - if (await this.apiReachable()) { + if (await this.api.reachable()) { this.log("api: already enabled"); return; } @@ -240,34 +242,34 @@ export class SteveProvisioner { // "no such user" and for "already had this value" -- two situations that // need opposite responses. const existing = await this.db.scalar( - `SELECT CONCAT('row|', IFNULL(api_password, '')) FROM web_user WHERE username = ${sqlLiteral(this.api.username)};`, + `SELECT CONCAT('row|', IFNULL(api_password, '')) FROM web_user WHERE username = ${sqlLiteral(this.apiCfg.username)};`, ); if (existing === "") { throw new Error( - `steve provision: no web_user row for '${this.api.username}'. ` + + `steve provision: no web_user row for '${this.apiCfg.username}'. ` + `SteVe seeds it on first boot from AUTH_USER -- is the container up, and is STEVE_API_USER the same as AUTH_USER?`, ); } if (existing !== "row|") { throw new Error( - `steve provision: '${this.api.username}' already has a WebAPI password set, and it is not the one configured. ` + + `steve provision: '${this.apiCfg.username}' already has a WebAPI password set, and it is not the one configured. ` + `Refusing to overwrite a credential in use. Set STEVE_API_PASS to the existing password, or clear ` + `web_user.api_password for that user if this environment is disposable.`, ); } this.log("api: enabling WebAPI access (requires one SteVe restart)"); - const hash = await Bun.password.hash(this.api.password, { + const hash = await Bun.password.hash(this.apiCfg.password, { algorithm: "bcrypt", cost: 10, }); await this.db.scalar( - `UPDATE web_user SET api_password = ${sqlLiteral(hash)} WHERE username = ${sqlLiteral(this.api.username)};`, + `UPDATE web_user SET api_password = ${sqlLiteral(hash)} WHERE username = ${sqlLiteral(this.apiCfg.username)};`, ); await this.restartApp(); - if (!(await this.apiReachable())) { + if (!(await this.api.reachable())) { throw new Error( "steve provision: WebAPI still refuses the credentials after a restart. " + "Check STEVE_API_USER/STEVE_API_PASS and STEVE_APP_CONTAINER.", @@ -276,17 +278,8 @@ export class SteveProvisioner { this.log("api: enabled"); } - private async apiReachable(): Promise { - try { - const res = await this.apiFetch("/ocppTags"); - return res.status === 200; - } catch { - return false; - } - } - private async restartApp(): Promise { - const proc = Bun.spawn(["docker", "restart", this.api.appContainer], { + const proc = Bun.spawn(["docker", "restart", this.cfg.appContainer], { stdout: "pipe", stderr: "pipe", }); @@ -296,56 +289,40 @@ export class SteveProvisioner { ]); if (exitCode !== 0) { throw new Error( - `steve provision: docker restart ${this.api.appContainer} failed: ${stderr.trim() || ""}`, + `steve provision: docker restart ${this.cfg.appContainer} failed: ${stderr.trim() || ""}`, ); } - this.log(`api: waiting for ${this.api.appContainer} to come back`); + this.log(`api: waiting for ${this.cfg.appContainer} to come back`); await waitForCondition( () => // A rejection here is "not listening yet" -- SteVe replays its // migrations before it binds -- so it folds into the falsy retry. fetch(`${this.cfg.baseUrl}/signin`, { redirect: "manual", - signal: AbortSignal.timeout(HTTP_TIMEOUT_MS), + signal: AbortSignal.timeout(SIGNIN_PROBE_TIMEOUT_MS), }) .then((res) => res.status === 200) .catch(() => false), { timeoutMs: RESTART_TIMEOUT_MS, intervalMs: RESTART_POLL_MS, - description: `${this.api.appContainer} to answer ${this.cfg.baseUrl}/signin`, + description: `${this.cfg.appContainer} to answer ${this.cfg.baseUrl}/signin`, }, ); } private async listTags(): Promise> { - const res = await this.expectStatus( - await this.apiFetch("/ocppTags"), - [200], - "GET /ocppTags", - ); - const rows = (await res.json()) as OcppTagOverview[]; + const rows = await this.api.getJson("/ocppTags"); return new Map(rows.map((r) => [r.idTag, r])); } private async createTag(body: Record): Promise { - await this.expectStatus( - await this.apiFetch("/ocppTags", { - method: "POST", - body: JSON.stringify(body), - }), - [200, 201], - `POST /ocppTags ${JSON.stringify(body)}`, - ); + await this.api.send("POST", "/ocppTags", { body }); } private async deleteTag(pk: number): Promise { - await this.expectStatus( - await this.apiFetch(`/ocppTags/${pk}`, { method: "DELETE" }), - [200, 204], - `DELETE /ocppTags/${pk}`, - ); + await this.api.send("DELETE", `/ocppTags/${pk}`); } async provisionTags(): Promise { @@ -353,9 +330,7 @@ export class SteveProvisioner { for (const idTag of VALID_TAGS) { const row = existing.get(idTag); - if (row && row.maxActiveTransactionCount > 0 && row.expiryDate === null) { - continue; - } + if (row && isUsable(row)) continue; // A tag that exists but drifted (blocked, or carrying an expiry from an // earlier run) is deleted rather than patched: PUT would hit the same // @Future validation that forbids writing the expiry in the first place. @@ -365,7 +340,7 @@ export class SteveProvisioner { } const blocked = existing.get(BLOCKED_TAG); - if (!blocked || blocked.maxActiveTransactionCount !== 0) { + if (!blocked || !isBlocked(blocked)) { if (blocked) await this.deleteTag(blocked.ocppTagPk); await this.createTag({ idTag: BLOCKED_TAG, @@ -377,18 +352,16 @@ export class SteveProvisioner { // Created through the API for the row, then aged through SQL: @Future makes // the API refuse to write a past date, but says nothing about reading one. - // - // The UPDATE is unconditional, and that is the idempotency wanted here - // rather than a departure from it: every provision re-expires the tag as of - // that run, which is exactly what an `expire` endpoint called with now() - // would do. Skipping it when the row is already expired would keep an older - // run's instant alive for no gain. if (!existing.has(EXPIRED_TAG)) { await this.createTag({ idTag: EXPIRED_TAG, note: "open-ocpp-tck fixture: expired", }); } + // Unconditional, and that is the idempotency wanted here rather than a + // departure from it: every provision re-expires the tag as of that run. + // Skipping the write when the row is already expired would keep an older + // run's instant alive for no gain. await this.db.scalar( `UPDATE ocpp_tag SET expiry_date = ${EXPIRED_AT_RUN_START} WHERE id_tag = ${sqlLiteral(EXPIRED_TAG)};`, ); @@ -429,27 +402,27 @@ export class SteveProvisioner { } /** - * Read-only. Deliberately answers from the database rather than the WebAPI: - * verify must work on an environment where API access was never enabled, - * and must not be the thing that enables it. + * Read-only, and answered from the WebAPI wherever the WebAPI can answer. + * + * The tag half asks `GET /ocppTags`, which is what the Authorize path will + * itself consult -- a fixture that looks right in the table but wrong through + * the API is a fixture that will behave wrong. The profile half stays on SQL + * because there is no charging-profile endpoint to ask + * ([steve-community/steve#2069]); when that lands, this method becomes + * single-channel. + * + * TWO PROPERTIES WERE TRADED AWAY, deliberately, and they are worth naming: + * verify no longer works on an environment where API access was never + * enabled -- it reports that as the first problem to fix, which is honest but + * is not what it did before -- and "is the expiry in the past" is now decided + * by THIS process's clock via Date.parse rather than by the database's. + * EXPIRED_FIXTURE_BACKDATE_MINUTES is what makes the second safe: a minute of + * backdate absorbs any skew between the two clocks, which on a local compose + * environment is zero anyway. */ async verify(): Promise { const problems: string[] = []; - const wanted = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG]; - - // Two queries, not one per fixture. Each db call is a `docker exec` process - // spawn, so asking about twenty tags one at a time costs seconds of pure - // process startup -- and verify() runs twice in the CI job. "Is the expiry - // in the past" is asked of the database rather than of Date.parse: MariaDB - // renders that column with six fractional digits, more precision than the - // ECMAScript date grammar promises to accept, and the CSMS compares against - // its own clock anyway, not this process's. - const tagRows = await this.db.rows( - `SELECT id_tag, IFNULL(max_active_transaction_count, 1), IFNULL(expiry_date, ''), - IF(expiry_date < NOW(), 'past', 'future') - FROM ocpp_tag WHERE id_tag IN (${wanted.map(sqlLiteral).join(", ")});`, - ); - const tags = new Map(tagRows.map((row) => [row[0], row])); + const tags = await this.listTags(); for (const idTag of VALID_TAGS) { const row = tags.get(idTag); @@ -457,8 +430,11 @@ export class SteveProvisioner { problems.push(`${idTag}: missing`); continue; } - if (row[1] === "0") problems.push(`${idTag}: blocked, expected usable`); - if (row[2] !== "") problems.push(`${idTag}: has expiry ${row[2]}`); + if (isUsable(row)) continue; + if (row.blocked) problems.push(`${idTag}: blocked, expected usable`); + if (row.expiryDate !== null) { + problems.push(`${idTag}: has expiry ${row.expiryDate}`); + } } if (tags.has(INVALID_TAG)) { @@ -466,22 +442,25 @@ export class SteveProvisioner { } const expired = tags.get(EXPIRED_TAG); - if (!expired || expired[2] === "") { + if (!expired?.expiryDate) { problems.push(`${EXPIRED_TAG}: missing or has no expiry`); - } else if (expired[3] !== "past") { - problems.push(`${EXPIRED_TAG}: expiry ${expired[2]} is not in the past`); + } else if (!(Date.parse(expired.expiryDate) < Date.now())) { + problems.push( + `${EXPIRED_TAG}: expiry ${expired.expiryDate} is not in the past`, + ); } const blocked = tags.get(BLOCKED_TAG); if (!blocked) { problems.push(`${BLOCKED_TAG}: missing`); - } else if (blocked[1] !== "0") { + } else if (!isBlocked(blocked)) { problems.push( - `${BLOCKED_TAG}: maxActiveTransactionCount ${blocked[1]}, expected 0`, + `${BLOCKED_TAG}: maxActiveTransactionCount ${blocked.maxActiveTransactionCount}, expected 0`, ); } - // The limit is checked, not just the name. A profile carrying the wrong + // From here down, SQL -- there is no charging-profile endpoint to ask + // (steve-community/steve#2069). The limit is checked, not just the name. A profile carrying the wrong // limit is exactly the case verify() exists to catch: TC_066 asserts // "limit":11000 on the composite schedule, so a profile that is present but // wrong turns into a scenario FAIL that reads like a CSMS defect, while @@ -527,30 +506,31 @@ export class SteveProvisioner { * the volume, which is the only case where it matters. */ async teardown(): Promise { - const tags = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG] - .map(sqlLiteral) - .join(", "); + const wanted = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG]; // Only tags nothing refers to. `transaction_start.id_tag` and - // `reservation.id_tag` are ON DELETE CASCADE onto ocpp_tag, so a plain - // DELETE here does not fail on a used tag -- it silently takes the run's - // transaction history with it. Measured: one scenario, then teardown, and - // transaction_start went from 1 row to 0. - // - // The NOT NULL guards are not decoration: `x NOT IN (SELECT ...)` is NULL, - // hence false, the moment the subquery yields a single NULL, which would - // turn this into a no-op that deletes nothing at all. - const deletable = `id_tag IN (${tags}) - AND id_tag NOT IN (SELECT id_tag FROM transaction_start WHERE id_tag IS NOT NULL) - AND id_tag NOT IN (SELECT id_tag FROM reservation WHERE id_tag IS NOT NULL)`; - - const kept = await this.db.scalar( - `SELECT COUNT(*) FROM ocpp_tag WHERE id_tag IN (${tags}) - AND NOT (${deletable});`, - ); - await this.db.scalar(`DELETE FROM ocpp_tag WHERE ${deletable};`); + // `reservation.id_tag` are ON DELETE CASCADE onto ocpp_tag, so deleting a + // used tag -- through SQL or through the API, they hit the same + // constraint -- does not fail. It silently takes the run's transaction + // history with it. Measured: one scenario, then teardown, and + // transaction_start went from 1 row to 0. So the guard runs BEFORE the + // delete, and records.ts owns which channel answers it. + const [used, tags] = await Promise.all([ + this.db.idTagsReferenced(wanted), + this.listTags(), + ]); + let kept = 0; + for (const idTag of wanted) { + const row = tags.get(idTag); + if (!row) continue; + if (used.has(idTag)) { + kept += 1; + continue; + } + await this.deleteTag(row.ocppTagPk); + } this.log( - kept === "0" + kept === 0 ? "tags: removed" : `tags: removed, ${kept} kept because transactions or reservations still reference them`, ); diff --git a/drivers/steve/records.ts b/drivers/steve/records.ts index ab33a48..e967a26 100644 --- a/drivers/steve/records.ts +++ b/drivers/steve/records.ts @@ -5,12 +5,35 @@ // implements the CSMS-neutral CsmsRecords contract, with reservations and charging // profiles moved onto the optional capability sub-interfaces. /** - * records.ts -- what SteVe believes happened, read straight from its MariaDB. + * records.ts -- what SteVe believes happened. * - * SteVe's REST API does not expose stop_reason, reservation status or the - * charging-profile registry, so the scenarios that assert on those can only be - * answered from the database. The queries shell out through `docker exec`, - * which means this driver has to run where that container is. + * TWO CHANNELS, AND THE SPLIT IS NOT ARBITRARY: transactions come from the + * WebAPI, reservations and the charging-profile registry from MariaDB through + * `docker exec`, because SteVe has no controller for either (probed on the + * pinned image: `/api/v1/reservations` and `/api/v1/chargingProfiles` answer + * 403 -- no such route). So the SQL half of this file is exactly the list of + * endpoints SteVe does not have, and each one that lands upstream deletes code + * here rather than changing it. Both are open upstream, and each fallback + * below names its own: + * + * reservations steve-community/steve#2074 + * charging profiles steve-community/steve#2069 + * + * Both sit under the #1000 "Meta - API Endpoint" umbrella. + * + * An earlier version read everything from the database on the grounds that the + * WebAPI "does not expose stop_reason". Measured against the pinned image, that + * was wrong: `GET /api/v1/transactions` returns `stopReason`, `stopTimestamp`, + * `ocppIdTag` and `id` on the `Transaction` DTO, filterable by `chargeBoxId`, + * `ocppIdTag` and `type=ACTIVE`. Forty-four of the fifty-one record calls the + * scenarios make were paying a process spawn each for state the CSMS was + * willing to hand over on a socket. + * + * WHY THIS IS THE BETTER SOURCE, not merely the cheaper one: the database is + * SteVe's private state, while the WebAPI is what an integrator can see. A + * conformance claim that only holds when you can read the CSMS's own tables is + * a weaker claim than one an integrator could reproduce. The database is kept + * only where nothing else can answer. */ import { type CsmsChargingProfileRecords, @@ -18,8 +41,25 @@ import { type CsmsReservationRecords, } from "../../tck/driver"; import { waitForCondition } from "../../tck/wait"; +import { SteveWebApi, type SteveApiConfig } from "./api-client"; import type { SteveConfig } from "./ui-client"; +/** + * SteVe's `Transaction` DTO, narrowed to the fields the contract needs. + * + * Every one is optional-by-absence rather than trusted: a still-open + * transaction carries `stopTimestamp: null`, and a StopTransaction that named + * no reason carries `stopReason: null`. Both must reach the assertions as `""` + * -- the contract's "not set" -- and never as the string "null", which is + * exactly the trap `nullSafe` guards on the SQL side. + */ +interface SteveTransaction { + id: number; + ocppIdTag: string | null; + stopTimestamp: string | null; + stopReason: string | null; +} + /** * Single-quoted SQL literal. * @@ -37,7 +77,14 @@ export function sqlLiteral(value: string): string { } export class SteveRecords implements CsmsRecords { - constructor(private readonly cfg: SteveConfig) {} + private readonly api: SteveWebApi; + + constructor( + private readonly cfg: SteveConfig, + apiCfg: SteveApiConfig, + ) { + this.api = new SteveWebApi(apiCfg); + } /** Runs SQL, returns stdout verbatim. The single path to the database. */ private async raw(sql: string): Promise { @@ -115,17 +162,38 @@ export class SteveRecords implements CsmsRecords { return raw === "NULL" ? "" : raw; } + /** + * The transactions matching a filter. The single path to the WebAPI's + * transaction registry, so no call site has to know the route or the + * repeated-key convention its list filters use. + */ + private async transactions( + ...filters: readonly (readonly [string, string])[] + ): Promise { + return this.api.getJson("/transactions", filters); + } + + /** + * The newest of a filtered set, as the contract's `""`-when-absent string. + * + * The maximum is taken here rather than trusted from the response order: + * SteVe's query form takes no sort parameter, so the order is the + * repository's business and not a promise. The SQL this replaced said + * `ORDER BY transaction_pk DESC LIMIT 1` out loud. + */ + private static newest(rows: readonly SteveTransaction[]): string { + return rows.length === 0 ? "" : String(Math.max(...rows.map((r) => r.id))); + } + async latestTransaction(cpId: string): Promise { - return this.scalar( - `SELECT t.transaction_pk FROM transaction t JOIN evse e ON e.evse_pk = t.evse_pk WHERE e.charge_box_id = ${sqlLiteral(cpId)} ORDER BY t.transaction_pk DESC LIMIT 1;`, - ); + return SteveRecords.newest(await this.transactions(["chargeBoxId", cpId])); } /** Most recent still-open transaction. Not part of the contract: it exists * for the stale-transaction cleanup below. */ async latestOpenTransaction(cpId: string): Promise { - return this.scalar( - `SELECT t.transaction_pk FROM transaction t JOIN evse e ON e.evse_pk = t.evse_pk WHERE e.charge_box_id = ${sqlLiteral(cpId)} AND t.stop_timestamp IS NULL ORDER BY t.transaction_pk DESC LIMIT 1;`, + return SteveRecords.newest( + await this.transactions(["chargeBoxId", cpId], ["type", "ACTIVE"]), ); } @@ -141,9 +209,13 @@ export class SteveRecords implements CsmsRecords { timeoutSecs = 15, ): Promise { return waitForCondition( - () => - this.scalar( - `SELECT t.transaction_pk FROM transaction t JOIN evse e ON e.evse_pk = t.evse_pk WHERE e.charge_box_id = ${sqlLiteral(cpId)} AND t.id_tag = ${sqlLiteral(idTag)} AND t.stop_timestamp IS NULL ORDER BY t.transaction_pk DESC LIMIT 1;`, + async () => + SteveRecords.newest( + await this.transactions( + ["chargeBoxId", cpId], + ["ocppIdTag", idTag], + ["type", "ACTIVE"], + ), ), { timeoutMs: timeoutSecs * 1000, @@ -153,41 +225,83 @@ export class SteveRecords implements CsmsRecords { ); } - /** Closes any transaction left open by an interrupted run, so that - * max_active_transaction_count does not block the next scenario. - * Idempotent. A WRITE, hence a lifecycle hook and not part of CsmsRecords. */ + /** + * Closes any transaction left open by an interrupted run, so that + * max_active_transaction_count does not block the next scenario. Idempotent. + * A WRITE, hence a lifecycle hook and not part of CsmsRecords. + * + * `PATCH /transactions/{pk}/stop` is the endpoint for exactly this, and it + * puts nothing on the wire: TransactionService#stop writes the stop row + * itself with `eventActor = manual`, and returns early when the transaction + * already carries a stop value (source-verified). Both matter here -- the + * charge point that opened the stale transaction is, by definition, gone, + * and this hook runs before every scenario. + */ async closeStaleTransaction(cpId: string): Promise { const pk = await this.latestOpenTransaction(cpId); if (!pk) return; - await this.scalar( - `INSERT INTO transaction_stop (transaction_pk, event_timestamp, event_actor, stop_timestamp, stop_value, stop_reason) VALUES (${pk}, NOW(), 'manual', NOW(), '0', 'Local');`, - ); + await this.api.send("PATCH", `/transactions/${pk}/stop`); + } + + /** One transaction by primary key, or undefined. The three accessors below + * each read one field off it. */ + private async transaction(tx: string): Promise { + return (await this.transactions(["transactionPk", tx]))[0]; } async transactionIdTag(tx: string): Promise { - return this.nullSafe( - `SELECT id_tag FROM transaction WHERE transaction_pk=${tx};`, - ); + return (await this.transaction(tx))?.ocppIdTag ?? ""; } async transactionStopTimestamp(tx: string): Promise { - return this.nullSafe( - `SELECT stop_timestamp FROM transaction WHERE transaction_pk=${tx};`, - ); + return (await this.transaction(tx))?.stopTimestamp ?? ""; } async transactionStopReason(tx: string): Promise { - return this.nullSafe( - `SELECT stop_reason FROM transaction WHERE transaction_pk=${tx};`, - ); + return (await this.transaction(tx))?.stopReason ?? ""; } async transactionCountForIdTag(cpId: string, idTag: string): Promise { - return this.scalar( - `SELECT COUNT(*) FROM transaction t JOIN evse e ON e.evse_pk = t.evse_pk WHERE e.charge_box_id = ${sqlLiteral(cpId)} AND t.id_tag = ${sqlLiteral(idTag)};`, + const rows = await this.transactions( + ["chargeBoxId", cpId], + ["ocppIdTag", idTag], ); + return String(rows.length); + } + + /** + * Which of these idTags anything still refers to. Not part of the contract: + * teardown needs it to avoid deleting a tag out from under a transaction or + * a reservation, either of which cascades and takes the row's history with + * it. + * + * ONE question, answered here rather than half here and half in the caller, + * because the two halves travel by different channels for a reason that is + * this module's to know and not teardown's: transactions come from the API, + * reservations from SQL, since there is no reservation endpoint + * ([steve-community/steve#2074]). When it lands, this method stops touching + * the database and nothing above it changes. + * + * Both halves ask once for the whole set -- `ocppIdTag` is a list filter, so + * the repeated key does the work a loop would have done -- and they ask + * concurrently, since the SQL half pays a `docker exec` process spawn. + */ + async idTagsReferenced(idTags: readonly string[]): Promise> { + if (idTags.length === 0) return new Set(); + const [transactions, reservations] = await Promise.all([ + this.transactions(...idTags.map((t) => ["ocppIdTag", t] as const)), + this.rows( + `SELECT DISTINCT id_tag FROM reservation + WHERE id_tag IN (${idTags.map(sqlLiteral).join(", ")});`, + ), + ]); + return new Set([ + ...transactions.map((row) => row.ocppIdTag), + ...reservations.map(([idTag]) => idTag), + ].filter((tag): tag is string => !!tag)); } + /** SQL until [steve-community/steve#2074] exposes reservation resources. */ readonly reservations: CsmsReservationRecords = { latest: (cpId: string) => this.scalar( @@ -199,6 +313,7 @@ export class SteveRecords implements CsmsRecords { ), }; + /** SQL until [steve-community/steve#2069] exposes charging-profile CRUD. */ readonly chargingProfiles: CsmsChargingProfileRecords = { refByDescription: (description: string) => this.scalar( diff --git a/drivers/steve/ui-client.ts b/drivers/steve/ui-client.ts index 5edc4ef..7935d0a 100644 --- a/drivers/steve/ui-client.ts +++ b/drivers/steve/ui-client.ts @@ -26,6 +26,12 @@ export interface SteveConfig { dbUser: string; dbPass: string; dbName: string; + /** docker container running the SteVe application. Deployment, not + * transport: only `provision` uses it, to restart the process once so it + * picks up the WebAPI credential it just wrote. It sits beside dbContainer + * because that is what it is -- a container name -- and not on the API + * config, which would make every scenario resolve a variable it never uses. */ + appContainer: string; /** OCPP WebSocket endpoint, without the trailing charge-point id. */ wsBaseUrl: string; /** Docker network the simulator must join to reach SteVe by container name. */ @@ -44,6 +50,7 @@ export function defaultSteveConfig( dbUser: env.STEVE_DB_USER ?? "steve", dbPass: env.STEVE_DB_PASS ?? "changeme", dbName: env.STEVE_DB_NAME ?? "stevedb", + appContainer: env.STEVE_APP_CONTAINER ?? "steve", wsBaseUrl: env.STEVE_WS_URL ?? "ws://steve:8180/steve/websocket/CentralSystemService", dockerNetwork: env.STEVE_NETWORK ?? "steve_steve-internal", diff --git a/types/drivers/citrineos/provision.d.ts b/types/drivers/citrineos/provision.d.ts index da84f4e..5644a33 100644 --- a/types/drivers/citrineos/provision.d.ts +++ b/types/drivers/citrineos/provision.d.ts @@ -17,6 +17,14 @@ * Hasura sidecar would offer insert mutations, at the cost of vendoring its * metadata -- see records.ts for why that trade was refused. * + * Unlike the SteVe driver, whose every database write names the upstream + * ticket that would replace it, THIS FILE HAS NO TICKET TO NAME: issues are + * disabled on citrineos/citrineos-core, and the two filed against + * citrineos/citrineos from this repository (#215, #216) are protocol defects + * rather than the missing data API. Nothing here is waiting on a number -- + * the gap is unreported, which is a state worth writing down rather than + * leaving as an apparent omission. + * * Charging profiles are not provisioned here either, and that is not an * omission: OCPP 1.6 SetChargingProfile carries the profile inline, so there * is no CSMS-side record to create. profiles.ts holds the catalogue. @@ -43,11 +51,6 @@ export declare class CitrineProvisioner { * handler actually needs, whatever else is in the table. */ provisionTags(): Promise; - /** - * Read-only. Two queries rather than one per fixture: each db call is a - * `docker exec` process spawn, so asking about twenty tags one at a time - * costs seconds of pure process startup -- and verify() runs twice in CI. - */ /** * Does the running server's schema match the variant we were told to expect? * @@ -64,6 +67,11 @@ export declare class CitrineProvisioner { * proves nothing. Both facts were read off running containers. */ private verifySchema; + /** + * Read-only. Two queries rather than one per fixture: each db call is a + * `docker exec` process spawn, so asking about twenty tags one at a time + * costs seconds of pure process startup -- and verify() runs twice in CI. + */ verify(): Promise; /** * Every `NOT EXISTS` guard needed to delete an Authorization safely, read diff --git a/types/drivers/steve/api-client.d.ts b/types/drivers/steve/api-client.d.ts new file mode 100644 index 0000000..99abd16 --- /dev/null +++ b/types/drivers/steve/api-client.d.ts @@ -0,0 +1,69 @@ +/** + * api-client.ts -- SteVe's WebAPI, the one channel that is neither a form post + * nor a database connection. + * + * It exists as its own module because two callers need it for opposite + * reasons: `provision.ts` WRITES fixtures through it, and `records.ts` READS + * what the CSMS believes happened. Before this file, the client lived inside + * the provisioner and observations had no choice but to shell out to MariaDB. + * + * WHAT IT CAN REACH. Exactly `ocppTags`, `transactions` and `operations` -- + * confirmed by probing the pinned image, where `chargePoints`, `reservations` + * and `chargingProfiles` all answer 403 because no such controller exists. + * That is why the SQL channel does not go away: it is now, precisely, the list + * of endpoints SteVe does not have. See VENDOR.md. + * + * AUTHENTICATION is HTTP Basic against `web_user.api_password`, a bcrypt + * column distinct from the UI password and NULL until something writes it -- + * which is `provision.ts`'s job, not this file's. A caller that gets 401 here + * has not provisioned; the message says so. + */ +import type { SteveConfig } from "./ui-client"; +export interface SteveApiConfig { + /** e.g. http://localhost:8180/steve/api/v1 */ + baseUrl: string; + username: string; + password: string; +} +export declare function defaultApiConfig(cfg: SteveConfig, env?: NodeJS.ProcessEnv): SteveApiConfig; +/** + * Query parameters as a LIST OF PAIRS, not a record: SteVe's query forms take + * repeated keys for their list filters (`chargeBoxId` and `ocppIdTag` are + * `List` on QueryForm), and a record would silently cap each filter at + * one value. + */ +export type QueryParams = readonly (readonly [string, string])[]; +export declare class SteveWebApi { + private readonly cfg; + /** Encoded once. Rebuilding it per request would put a base64 of the + * credentials inside the one-second poll loop in records.ts. */ + private readonly authorization; + constructor(cfg: SteveApiConfig); + /** GET, decoded. The shape is the caller's to declare: this module knows the + * transport, `records.ts` and `provision.ts` know the payloads. */ + getJson(path: string, params?: QueryParams): Promise; + /** + * A write. `allowed` defaults to the pair SteVe actually answers with -- 200 + * from a controller returning a value, 204 from a `void` one -- and 201 + * because POST /ocppTags may answer either. + * + * The failure description is derived from the request rather than passed in, + * which is the point of having this at all: three call sites used to spell + * out "DELETE /ocppTags/${pk}" beside the very call that said it, and a + * hand-written label is one refactor away from describing a different route. + */ + send(method: string, path: string, opts?: { + body?: unknown; + allowed?: readonly number[]; + }): Promise; + /** Whether the WebAPI answers with the configured credentials. A probe, so a + * rejection is an answer ("no") rather than a failure. */ + reachable(): Promise; + /** + * One request, checked. The single place that decides what an unacceptable + * status looks like, so the body-truncation and the message shape cannot + * drift per call site. + */ + private request; + private raw; +} diff --git a/types/drivers/steve/index.d.ts b/types/drivers/steve/index.d.ts index 52edb0f..221a71d 100644 --- a/types/drivers/steve/index.d.ts +++ b/types/drivers/steve/index.d.ts @@ -33,12 +33,20 @@ * * Where it has to run * ------------------- - * Observations come from MariaDB through `docker exec`, because SteVe's REST - * API exposes neither stop_reason, nor reservation status, nor the - * charging-profile registry. So this driver runs on the host that owns the - * SteVe containers, and reaches the manager UI on the container network -- - * a deployment behind a forward-auth proxy is unreachable from outside it, - * and its OCPP port may not be published to the internet at all. + * Transactions are observed over the WebAPI, which serves `stopReason`, + * `stopTimestamp` and `ocppIdTag` and filters by charge point, idTag and + * active-ness -- measured on the pinned image, and worth stating because an + * earlier version of this file claimed the opposite and read all of it from + * MariaDB. What REST genuinely cannot serve is reservation status and the + * charging-profile registry: no such controller exists. Those two still come + * from MariaDB through `docker exec` -- steve-community/steve#2074 and #2069 + * respectively, both under the #1000 "Meta - API Endpoint" umbrella. + * + * So this driver runs on the host that owns the SteVe containers, and reaches + * the manager UI on the container network -- a deployment behind a + * forward-auth proxy is unreachable from outside it, and its OCPP port may not + * be published to the internet at all. The day those two tickets land, that + * constraint goes with them. */ import { type CsmsDriverModule } from "../../tck/driver"; export declare const csmsDriver: CsmsDriverModule; diff --git a/types/drivers/steve/provision.d.ts b/types/drivers/steve/provision.d.ts index f3f2e77..bf66d1f 100644 --- a/types/drivers/steve/provision.d.ts +++ b/types/drivers/steve/provision.d.ts @@ -1,24 +1,13 @@ +import { type SteveApiConfig } from "./api-client"; import { type SteveConfig } from "./ui-client"; -export interface SteveApiConfig { - /** e.g. http://localhost:8180/steve/api/v1 */ - baseUrl: string; - username: string; - password: string; - /** Container running the SteVe application, restarted to pick up API access. */ - appContainer: string; -} -export declare function defaultApiConfig(cfg: SteveConfig, env?: NodeJS.ProcessEnv): SteveApiConfig; export declare class SteveProvisioner { private readonly cfg; - private readonly api; + private readonly apiCfg; private readonly log; private readonly ui; private readonly db; - constructor(cfg: SteveConfig, api: SteveApiConfig, log?: (msg: string) => void); - private apiFetch; - /** One place that decides what an unacceptable WebAPI status looks like, so - * the body-truncation and the message shape cannot drift per call site. */ - private expectStatus; + private readonly api; + constructor(cfg: SteveConfig, apiCfg: SteveApiConfig, log?: (msg: string) => void); /** * Makes the WebAPI answer, restarting SteVe only if it does not already. * @@ -44,7 +33,6 @@ export declare class SteveProvisioner { * overwritten -- the operator knows their password and this does not. */ ensureApiAccess(): Promise; - private apiReachable; private restartApp; private listTags; private createTag; @@ -52,9 +40,23 @@ export declare class SteveProvisioner { provisionTags(): Promise; provisionProfiles(): Promise; /** - * Read-only. Deliberately answers from the database rather than the WebAPI: - * verify must work on an environment where API access was never enabled, - * and must not be the thing that enables it. + * Read-only, and answered from the WebAPI wherever the WebAPI can answer. + * + * The tag half asks `GET /ocppTags`, which is what the Authorize path will + * itself consult -- a fixture that looks right in the table but wrong through + * the API is a fixture that will behave wrong. The profile half stays on SQL + * because there is no charging-profile endpoint to ask + * ([steve-community/steve#2069]); when that lands, this method becomes + * single-channel. + * + * TWO PROPERTIES WERE TRADED AWAY, deliberately, and they are worth naming: + * verify no longer works on an environment where API access was never + * enabled -- it reports that as the first problem to fix, which is honest but + * is not what it did before -- and "is the expiry in the past" is now decided + * by THIS process's clock via Date.parse rather than by the database's. + * EXPIRED_FIXTURE_BACKDATE_MINUTES is what makes the second safe: a minute of + * backdate absorbs any skew between the two clocks, which on a local compose + * environment is zero anyway. */ verify(): Promise; /** diff --git a/types/drivers/steve/records.d.ts b/types/drivers/steve/records.d.ts index 2c82c7d..006f194 100644 --- a/types/drivers/steve/records.d.ts +++ b/types/drivers/steve/records.d.ts @@ -1,12 +1,36 @@ /** - * records.ts -- what SteVe believes happened, read straight from its MariaDB. + * records.ts -- what SteVe believes happened. * - * SteVe's REST API does not expose stop_reason, reservation status or the - * charging-profile registry, so the scenarios that assert on those can only be - * answered from the database. The queries shell out through `docker exec`, - * which means this driver has to run where that container is. + * TWO CHANNELS, AND THE SPLIT IS NOT ARBITRARY: transactions come from the + * WebAPI, reservations and the charging-profile registry from MariaDB through + * `docker exec`, because SteVe has no controller for either (probed on the + * pinned image: `/api/v1/reservations` and `/api/v1/chargingProfiles` answer + * 403 -- no such route). So the SQL half of this file is exactly the list of + * endpoints SteVe does not have, and each one that lands upstream deletes code + * here rather than changing it. Both are open upstream, and each fallback + * below names its own: + * + * reservations steve-community/steve#2074 + * charging profiles steve-community/steve#2069 + * + * Both sit under the #1000 "Meta - API Endpoint" umbrella. + * + * An earlier version read everything from the database on the grounds that the + * WebAPI "does not expose stop_reason". Measured against the pinned image, that + * was wrong: `GET /api/v1/transactions` returns `stopReason`, `stopTimestamp`, + * `ocppIdTag` and `id` on the `Transaction` DTO, filterable by `chargeBoxId`, + * `ocppIdTag` and `type=ACTIVE`. Forty-four of the fifty-one record calls the + * scenarios make were paying a process spawn each for state the CSMS was + * willing to hand over on a socket. + * + * WHY THIS IS THE BETTER SOURCE, not merely the cheaper one: the database is + * SteVe's private state, while the WebAPI is what an integrator can see. A + * conformance claim that only holds when you can read the CSMS's own tables is + * a weaker claim than one an integrator could reproduce. The database is kept + * only where nothing else can answer. */ import { type CsmsChargingProfileRecords, type CsmsRecords, type CsmsReservationRecords } from "../../tck/driver"; +import { type SteveApiConfig } from "./api-client"; import type { SteveConfig } from "./ui-client"; /** * Single-quoted SQL literal. @@ -23,7 +47,8 @@ import type { SteveConfig } from "./ui-client"; export declare function sqlLiteral(value: string): string; export declare class SteveRecords implements CsmsRecords { private readonly cfg; - constructor(cfg: SteveConfig); + private readonly api; + constructor(cfg: SteveConfig, apiCfg: SteveApiConfig); /** Runs SQL, returns stdout verbatim. The single path to the database. */ private raw; /** Runs SQL, returns the first column of the first row ("" if no rows). */ @@ -48,6 +73,21 @@ export declare class SteveRecords implements CsmsRecords { * zero-row result already comes back as "" because MariaDB prints nothing. */ private nullSafe; + /** + * The transactions matching a filter. The single path to the WebAPI's + * transaction registry, so no call site has to know the route or the + * repeated-key convention its list filters use. + */ + private transactions; + /** + * The newest of a filtered set, as the contract's `""`-when-absent string. + * + * The maximum is taken here rather than trusted from the response order: + * SteVe's query form takes no sort parameter, so the order is the + * repository's business and not a promise. The SQL this replaced said + * `ORDER BY transaction_pk DESC LIMIT 1` out loud. + */ + private static newest; latestTransaction(cpId: string): Promise; /** Most recent still-open transaction. Not part of the contract: it exists * for the stale-transaction cleanup below. */ @@ -59,14 +99,46 @@ export declare class SteveRecords implements CsmsRecords { * transaction from an earlier run instead of the racing in-progress one. */ waitForActiveTransaction(cpId: string, idTag: string, timeoutSecs?: number): Promise; - /** Closes any transaction left open by an interrupted run, so that - * max_active_transaction_count does not block the next scenario. - * Idempotent. A WRITE, hence a lifecycle hook and not part of CsmsRecords. */ + /** + * Closes any transaction left open by an interrupted run, so that + * max_active_transaction_count does not block the next scenario. Idempotent. + * A WRITE, hence a lifecycle hook and not part of CsmsRecords. + * + * `PATCH /transactions/{pk}/stop` is the endpoint for exactly this, and it + * puts nothing on the wire: TransactionService#stop writes the stop row + * itself with `eventActor = manual`, and returns early when the transaction + * already carries a stop value (source-verified). Both matter here -- the + * charge point that opened the stale transaction is, by definition, gone, + * and this hook runs before every scenario. + */ closeStaleTransaction(cpId: string): Promise; + /** One transaction by primary key, or undefined. The three accessors below + * each read one field off it. */ + private transaction; transactionIdTag(tx: string): Promise; transactionStopTimestamp(tx: string): Promise; transactionStopReason(tx: string): Promise; transactionCountForIdTag(cpId: string, idTag: string): Promise; + /** + * Which of these idTags anything still refers to. Not part of the contract: + * teardown needs it to avoid deleting a tag out from under a transaction or + * a reservation, either of which cascades and takes the row's history with + * it. + * + * ONE question, answered here rather than half here and half in the caller, + * because the two halves travel by different channels for a reason that is + * this module's to know and not teardown's: transactions come from the API, + * reservations from SQL, since there is no reservation endpoint + * ([steve-community/steve#2074]). When it lands, this method stops touching + * the database and nothing above it changes. + * + * Both halves ask once for the whole set -- `ocppIdTag` is a list filter, so + * the repeated key does the work a loop would have done -- and they ask + * concurrently, since the SQL half pays a `docker exec` process spawn. + */ + idTagsReferenced(idTags: readonly string[]): Promise>; + /** SQL until [steve-community/steve#2074] exposes reservation resources. */ readonly reservations: CsmsReservationRecords; + /** SQL until [steve-community/steve#2069] exposes charging-profile CRUD. */ readonly chargingProfiles: CsmsChargingProfileRecords; } diff --git a/types/drivers/steve/ui-client.d.ts b/types/drivers/steve/ui-client.d.ts index 7b4f0c4..14c56c0 100644 --- a/types/drivers/steve/ui-client.d.ts +++ b/types/drivers/steve/ui-client.d.ts @@ -9,6 +9,12 @@ export interface SteveConfig { dbUser: string; dbPass: string; dbName: string; + /** docker container running the SteVe application. Deployment, not + * transport: only `provision` uses it, to restart the process once so it + * picks up the WebAPI credential it just wrote. It sits beside dbContainer + * because that is what it is -- a container name -- and not on the API + * config, which would make every scenario resolve a variable it never uses. */ + appContainer: string; /** OCPP WebSocket endpoint, without the trailing charge-point id. */ wsBaseUrl: string; /** Docker network the simulator must join to reach SteVe by container name. */ From 2bfba44c658743dd5e01d9ad0fcfea74f21381ea Mon Sep 17 00:00:00 2001 From: Julien Herr Date: Wed, 12 Aug 2026 23:04:21 +0200 Subject: [PATCH 13/13] fix(specs): keep the firmware retrieveDate inside the observation window TC_044 asked for `retrieveDate: inSeconds(90)`, and a driver may only round that value UP -- the contract says so, because a CSMS whose form has no seconds field must still receive a strictly future instant. SteVe's UpdateFirmware form is minute-resolution, so the charge point waited 90-150s against a 115s window: the scenario passed or failed on where the wall clock happened to sit within the minute, and since the three run back to back at a ~120s period they drew the same phase together -- one unlucky sweep failed all three. Asking for 15s instead puts the worst case at 75s, leaving the status train and a tail buffer inside the same window. The offset was 90s for a reason that no longer holds: it dated from when the rounding truncated DOWN and a small offset could land in the already-past minute. Reproduced and fixed under measurement rather than inferred: starting the scenario at a wall-clock second that makes the rounding worst-case, tc044-1 failed on the old offset and passed on the new one at the very same phase. The whole firmware group then passed on both drivers. Fixes #4 --- VENDOR.md | 2 +- patches/tck/specs/firmware.ts.patch | 39 +++++++++++++++++++++++------ tck/specs/firmware.ts | 21 +++++++++++++--- 3 files changed, 49 insertions(+), 13 deletions(-) diff --git a/VENDOR.md b/VENDOR.md index 32ca204..f995c1c 100644 --- a/VENDOR.md +++ b/VENDOR.md @@ -53,7 +53,7 @@ strongest available demonstration that the core names no CSMS. | `tck/specs/authorize.ts` | `upstream-patched` | `scripts/steve-verify/runner/specs/authorize.ts` | `aaf1c5f2b4888df41cd1f0b8637b47eedc376ff2d61d29841d3668d26b66e7da` | `a627d704d62ccc5e47c60974859a12975827a4727da57cd3fd01a1bc96b57062` | `patches/tck/specs/authorize.ts.patch` | | `tck/specs/authlist-reservation.ts` | `upstream-patched` | `scripts/steve-verify/runner/specs/authlist-reservation.ts` | `3ee302032025a889053d108d0813cc644819e58879b6cd554d56f85b804d0cd6` | `1c6726e0522ccce2cea16fb490e4351852d28986b778f5940258bf4337c2f7d8` | `patches/tck/specs/authlist-reservation.ts.patch` | | `tck/specs/remotetrigger-smartcharging.ts` | `upstream-patched` | `scripts/steve-verify/runner/specs/remotetrigger-smartcharging.ts` | `f0d2b720c8b6343d08e2506f4d6e4fcbf68069bb586e5bfea841ca9e37fdbca2` | `26ccd319a566955f384d0d93e423033a6538ba471ff0ff0219542a8904b30bad` | `patches/tck/specs/remotetrigger-smartcharging.ts.patch` | -| `tck/specs/firmware.ts` | `upstream-patched` | `scripts/steve-verify/runner/specs/firmware.ts` | `e1bc6c288fe5c56e2cceae6f4ea650e901d852637ecdec914fc7ccdbdd5d1fe8` | `c3bb42861902f0b7f70ca6e2dcd02d5d96af29238f2e2081f018e64fe10a2927` | `patches/tck/specs/firmware.ts.patch` | +| `tck/specs/firmware.ts` | `upstream-patched` | `scripts/steve-verify/runner/specs/firmware.ts` | `e1bc6c288fe5c56e2cceae6f4ea650e901d852637ecdec914fc7ccdbdd5d1fe8` | `e80494f65f4b2cf958742f297607af0612ce34193ca8fde3fa2ada99d55958f7` | `patches/tck/specs/firmware.ts.patch` | | `tck/specs/index.ts` | `upstream-verbatim` | `scripts/steve-verify/runner/specs/index.ts` | `be8595765f4d66965bfd58498622c26a696962fabae8a2700f080ae5cd55d832` | `be8595765f4d66965bfd58498622c26a696962fabae8a2700f080ae5cd55d832` | `—` | | `tck/assert.ts` | `upstream-patched` | `src/cp/application/verification/assert.ts` | `2431f5f6c0df997d4d821d9af55689c1f0f2df199de1e9e4ed6f3fbaad4fc89e` | `76d0f293db4f6ecc5768affea0ca76d2841c147fa3687dbea1f9e950bfbd9298` | `patches/tck/assert.ts.patch` | | `tck/sim.ts` | `upstream-patched` | `scripts/steve-verify/runner/sim.ts` | `2bf2f78afe3434e7139cd62c3ff6d70f02defd39dd700611e7c5f7614260cd35` | `45f897f273ea73227bb9b30766127eb9ecae0a319ab9048cbc30428fafff7f32` | `patches/tck/sim.ts.patch` | diff --git a/patches/tck/specs/firmware.ts.patch b/patches/tck/specs/firmware.ts.patch index 181fada..c3830ab 100644 --- a/patches/tck/specs/firmware.ts.patch +++ b/patches/tck/specs/firmware.ts.patch @@ -15,9 +15,32 @@ ); } -@@ -37,13 +37,13 @@ +@@ -27,6 +27,19 @@ + // before starting the FirmwareStatusNotification train (confirmed live in + // the bash suite: this is correct OCPP 1.6 semantics, not a bug), then + // progresses Downloading -> Downloaded -> Installing -> Installed. ++// ++// THE OFFSET IS SMALL ON PURPOSE, and the three TC_044 scenarios below share ++// the reason. A driver may only round a retrieveDate UP -- the contract says ++// so, because a CSMS whose form has no seconds field must still receive a ++// strictly future instant -- so the CP can wait up to a whole resolution step ++// LONGER than asked. SteVe's UpdateFirmware form is minute-resolution, which ++// makes the real wait `offset + up to 60s`. At the +90s this used to ask for, ++// that is up to 150s against a 115s window: the scenario passed or failed on ++// where the wall clock happened to sit within the minute, and the three ran ++// back to back at a ~120s period, so they drew the same unlucky phase together. ++// ++// Budget, which any edit here has to keep: offset + 60s of driver rounding + ++// ~10s of status train + tail buffer <= holdSecs. + // --------------------------------------------------------------------------- + + export const tc0441FirmwareUpdateSpec: ScenarioSpec = { +@@ -35,15 +48,15 @@ + "TC_044.1 Firmware Update: full Downloading -> Downloaded -> Installing -> Installed train.", + connector: 1, bootWaitSecs: 4, - // retrieveDateTime wait (~90s) + ~10s status train + tail buffer. +- // retrieveDateTime wait (~90s) + ~10s status train + tail buffer. ++ // 15s + up to 60s of rounding + ~10s train, inside a 115s window. holdSecs: 115, - async drive({ cpId, steve }) { + async drive({ cpId, csms }) { @@ -29,11 +52,11 @@ + action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDateTime: retrieveDatetimeSoon(), -+ retrieveDate: inSeconds(90), ++ retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err); -@@ -119,13 +119,13 @@ +@@ -119,13 +132,13 @@ connector: 1, bootWaitSecs: 4, holdSecs: 110, @@ -47,11 +70,11 @@ + action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDateTime: retrieveDatetimeSoon(), -+ retrieveDate: inSeconds(90), ++ retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err); -@@ -184,13 +184,13 @@ +@@ -184,13 +197,13 @@ connector: 1, bootWaitSecs: 4, holdSecs: 115, @@ -65,11 +88,11 @@ + action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDateTime: retrieveDatetimeSoon(), -+ retrieveDate: inSeconds(90), ++ retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err); -@@ -277,13 +277,10 @@ +@@ -277,13 +290,10 @@ connector: 1, bootWaitSecs: 4, holdSecs: 25, diff --git a/tck/specs/firmware.ts b/tck/specs/firmware.ts index c81c496..f827b8b 100644 --- a/tck/specs/firmware.ts +++ b/tck/specs/firmware.ts @@ -27,6 +27,19 @@ function warnOpFailed(op: string, err: unknown): void { // before starting the FirmwareStatusNotification train (confirmed live in // the bash suite: this is correct OCPP 1.6 semantics, not a bug), then // progresses Downloading -> Downloaded -> Installing -> Installed. +// +// THE OFFSET IS SMALL ON PURPOSE, and the three TC_044 scenarios below share +// the reason. A driver may only round a retrieveDate UP -- the contract says +// so, because a CSMS whose form has no seconds field must still receive a +// strictly future instant -- so the CP can wait up to a whole resolution step +// LONGER than asked. SteVe's UpdateFirmware form is minute-resolution, which +// makes the real wait `offset + up to 60s`. At the +90s this used to ask for, +// that is up to 150s against a 115s window: the scenario passed or failed on +// where the wall clock happened to sit within the minute, and the three ran +// back to back at a ~120s period, so they drew the same unlucky phase together. +// +// Budget, which any edit here has to keep: offset + 60s of driver rounding + +// ~10s of status train + tail buffer <= holdSecs. // --------------------------------------------------------------------------- export const tc0441FirmwareUpdateSpec: ScenarioSpec = { @@ -35,7 +48,7 @@ export const tc0441FirmwareUpdateSpec: ScenarioSpec = { "TC_044.1 Firmware Update: full Downloading -> Downloaded -> Installing -> Installed train.", connector: 1, bootWaitSecs: 4, - // retrieveDateTime wait (~90s) + ~10s status train + tail buffer. + // 15s + up to 60s of rounding + ~10s train, inside a 115s window. holdSecs: 115, async drive({ cpId, csms }) { await sleep(2000); @@ -43,7 +56,7 @@ export const tc0441FirmwareUpdateSpec: ScenarioSpec = { await csms.execute(cpId, { action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDate: inSeconds(90), + retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err); @@ -125,7 +138,7 @@ export const tc0442FirmwareDownloadFailedSpec: ScenarioSpec = { await csms.execute(cpId, { action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDate: inSeconds(90), + retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err); @@ -190,7 +203,7 @@ export const tc0443FirmwareInstallFailedSpec: ScenarioSpec = { await csms.execute(cpId, { action: "UpdateFirmware", location: "http://example.com/fw.bin", - retrieveDate: inSeconds(90), + retrieveDate: inSeconds(15), }); } catch (err) { warnOpFailed("UpdateFirmware", err);