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 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/VENDOR.md b/VENDOR.md index 8fd0a96..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` | @@ -72,9 +72,19 @@ 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` | `—` | `—` | `—` | `—` | +| `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 +161,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 +181,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. @@ -204,20 +214,54 @@ 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 - `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 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 @@ -239,4 +283,144 @@ 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 + +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..fc756a6 --- /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 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 +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..76aaab5 --- /dev/null +++ b/drivers/citrineos/api-client.ts @@ -0,0 +1,142 @@ +// 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 { + 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 { + 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; + let text: string; + 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), + }); + // 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)}`, + ); + } + + 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..13bd130 --- /dev/null +++ b/drivers/citrineos/provision.ts @@ -0,0 +1,469 @@ +// 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. + * + * 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. + * + * 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"; +// 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"; + +/** + * 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: 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 + * 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 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. + * + * 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; + expiry: FixtureExpiry; +} + +const FIXTURES: readonly TagFixture[] = [ + ...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 + * provision but not to teardown cannot leave rows behind that verify still + * demands. */ +const ALL_TAGS = [...VALID_TAGS, BLOCKED_TAG, EXPIRED_TAG, INVALID_TAG]; + +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}`; + // 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" = ${expiry}, + "updatedAt" = NOW() + WHERE ${where};`, + `INSERT INTO "Authorizations" + ("idToken", "idTokenType", "status", "cacheExpiryDateTime", "tenantId", "createdAt", "updatedAt") + SELECT ${idToken}, ${sqlLiteral(ID_TOKEN_TYPE)}, ${sqlLiteral(fixture.status)}, + ${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 ` + + `${EXPIRED_FIXTURE_BACKDATE_MINUTES} min before this run's provisioning, ` + + `${BLOCKED_TAG} (${BLOCKED_TAG_CAVEAT}), ${INVALID_TAG} absent`, + ); + } + + /** + * 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.`, + ]; + } + + /** + * 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 + // 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 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", + ); + } 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..6dc1be7 --- /dev/null +++ b/drivers/citrineos/records.ts @@ -0,0 +1,366 @@ +// 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. + * + * 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(""); + 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} + ORDER BY st."timestamp" DESC NULLS LAST + LIMIT 1;`, + ); + } + + 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..3856aa6 --- /dev/null +++ b/drivers/citrineos/scope.ts @@ -0,0 +1,256 @@ +// 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 }); + +// `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), + "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.", + ), +} satisfies ScopeTable; + +/** + * 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."; + +/** + * 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) { + 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/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 b0bdd10..c665727 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 @@ -30,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, @@ -46,6 +59,7 @@ import { type CsmsOperation, type CsmsOperations, } from "../../tck/driver"; +import { defaultApiConfig } from "./api-client"; import { cpSelect, toSteveForm } from "./forms"; import { provisionCommand, @@ -81,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, @@ -112,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 f22cd82..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 @@ -29,29 +34,58 @@ * 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. - * 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 * chasing a failure will run it twice before believing it. */ +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; @@ -104,11 +138,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 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 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 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. */ @@ -117,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); } /** @@ -214,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; } @@ -224,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.", @@ -260,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", }); @@ -280,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 { @@ -337,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. @@ -349,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, @@ -367,10 +358,16 @@ export class SteveProvisioner { 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 = ${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) { @@ -405,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); @@ -433,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)) { @@ -442,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 @@ -503,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/package.json b/package.json index b2cebe3..f34c0a6 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ "bin/", "tck/", "drivers/steve/", + "drivers/citrineos/", "types/", "patches/", "tsconfig.base.json", @@ -99,14 +100,19 @@ "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" }, "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", - "e2e": "bun bin/ocpp-tck.ts run-all --parallel --retry-failed-isolated && bun bin/ocpp-tck.ts run-all --group authorize", + "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", "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" 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); 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/tools/extract-fixture-tags.sh b/tools/extract-fixture-tags.sh index 27fdd29..bb10110 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,60 @@ 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")")" + + # `|| 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"))" + 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" 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..5644a33 --- /dev/null +++ b/types/drivers/citrineos/provision.d.ts @@ -0,0 +1,110 @@ +/** + * 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. + * + * 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. + * + * 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; + /** + * 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; + /** + * 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 + * 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..049a4d7 --- /dev/null +++ b/types/drivers/citrineos/records.d.ts @@ -0,0 +1,191 @@ +/** + * 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. + * + * 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; + /** + * 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"]; 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 f93211c..221a71d 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 @@ -28,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. */ 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;