dkim2ctl

command module
v0.0.0-...-89e479d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

README

dkim2ctl

dkim2ctl is the local OpenAPI-based test and conformance client for dkim2d. It deliberately has no operator mutation commands or generic HTTP sender.

The client accepts only canonical loopback HTTP authorities, disables proxies, redirects, cookies, compression, retries, and connection reuse, and emits stable content-free JSON Lines with bounded duration buckets rather than exact timings. Health, readiness, process, sign, revise, and delivery-status sign calls use the generated OpenAPI client and DTOs. Negative cases are restricted to a closed contract-test mutation vocabulary. The authoritative HTTP contract remains docs/specs/openapi/dkim2d.yaml, and the production path starts in docs/operator/postfix-compose.md.

Commands:

dkim2ctl smoke [--expect-ready=true|false]
dkim2ctl fixture validate PATH...
dkim2ctl fixture run PATH...

Global options:

--server-url http://127.0.0.1:8080
--timeout 10s
--capability-file /absolute/protected/path
--sign-capability-file /absolute/protected/sign-path
--revise-capability-file /absolute/protected/revise-path
--dsn-sign-capability-file /absolute/protected/dsn-sign-path
--dsn-propagate-capability-file /absolute/protected/dsn-propagate-path
--output jsonl

fixture validate is offline and never reads the capability or opens a network connection. fixture run validates every path and case before doing either. Authenticated process and negative cases require a regular, effective-user-owned, single-link 32-byte route capability file with mode 0400 or 0600. Sign, revise, and sign_dsn fixtures require their corresponding distinct capability options. A sign_dsn fixture contains the byte-preserving outer DSN message, exact null outer envelope, and tenant; it has no caller- selected fidelity. The Postfix-exclusive route and its dedicated capability attest the representation. Its expected response operation is delivery_status. The daemon chooses the domain only among local profile domains that relaxed-match a verified embedded rt= address (Draft-09 Section 16.2); a report without such a domain is the 204 response, which must carry exactly one closed X-DKIM2-Unsigned-Reason. The two propagation fixture kinds require the fifth, distinct propagation capability option. A propagate_dsn fixture contains the byte-preserving received delivery-status notification, its selected fidelity, the observed outer envelope of the transaction that delivered it (null reverse path, one recipient, SMTPUTF8 flag), the tenant, and the adapter's Reporting-MTA; its expected projection carries the closed six-member delivery_status projection, the propagation disposition, and only a digest of the rebuilt notification, never its bytes. A commit_dsn_propagation fixture contains one opaque commit token from a previous propagation response and expects the closed commit outcome. Neither kind is accepted by the process, sign, revise, or DSN-sign capability. Credentials, raw messages, envelope values, paths, URLs, headers, response bodies, and raw errors never enter output.

Checked draft-versioned examples live under cmd/dkim2ctl/testdata/fixtures/draft-ietf-dkim-dkim2-spec-09/. Validate the complete offline set without protected-file or network access:

dkim2ctl fixture validate cmd/dkim2ctl/testdata/fixtures/draft-ietf-dkim-dkim2-spec-09/*.json

Their expectations are allowlisted typed projections rather than response snapshots. dkim2ctl smoke is the non-mutating live health/readiness check; authenticated fixture execution is appropriate only after selecting the exact route capability files for the test deployment.

Stable exits are 0 for a complete match and 2 through 8 for usage, fixture, capability, transport, response-contract, expectation-mismatch, and internal-invariant failures respectively.

Build and verify through the repository targets:

go build ./cmd/dkim2ctl
go test ./cmd/dkim2ctl/...
make check-openapi
make guardrails

Documentation

Overview

Command dkim2ctl provides the bounded DKIM2 daemon conformance client.

Directories

Path Synopsis
internal
command
Package command owns the dkim2ctl Cobra surface and its single exit boundary.
Package command owns the dkim2ctl Cobra surface and its single exit boundary.
testclient
Package testclient will contain OpenAPI-backed test-client workflows for exercising dkim2d through its public HTTP contract.
Package testclient will contain OpenAPI-backed test-client workflows for exercising dkim2d through its public HTTP contract.
testclient/generated
Package generated provides primitives to interact with the openapi HTTP API.
Package generated provides primitives to interact with the openapi HTTP API.
testsupport
Package testsupport owns shared test-only infrastructure.
Package testsupport owns shared test-only infrastructure.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL