hl7v2-server

HTTP/gRPC runtime service for HL7 v2 validation and evidence workflows.

hl7v2-server is the deployable sidecar/edge-guard crate in the hl7v2-rs workspace. It is separate from the hl7v2 library crate because it carries runtime concerns: HTTP/gRPC serving, metrics, authentication, rate limits, config loading, and filesystem output roots.

Sidecar workflows

Useful release-candidate workflows include:

• hl7v2-server --print-config for sanitized effective configuration output.
• GET /ready for startup readiness checks.
• POST /hl7/validate for typed validation reports.
• POST /hl7/validate-redacted for validate-and-redact workflows.
• POST /hl7/bundle for server-created redacted evidence bundles under a configured bundle output root.
• POST /hl7/ack-policy for policy-driven ACK/NAK decisions.
• /metrics for Prometheus metrics.

The gRPC service implements Parse, ParseStream, Validate, ProfileLint, ProfileExplain, ProfileTest, ValidateRedacted, CreateEvidenceBundle, ReplayEvidenceBundle, CorpusSummarize, CorpusFingerprint, CorpusDiff, GenerateAck, Normalize, and HealthCheck. Validate and ValidateRedacted return the shared validation report fields; ProfileLint, ProfileExplain, and ProfileTest return the shared profile report fields; ValidateRedacted also returns a redaction receipt, keeps the redacted HL7 payload opt-in, and can write configured quarantine output when redacted validation fails. CreateEvidenceBundle writes a redacted bundle under the configured server bundle root and returns a shared bundle summary with a hashed public output ID. ReplayEvidenceBundle verifies configured-root bundles and returns the shared replay report shape with opt-in v2 replay provenance. CorpusSummarize, CorpusFingerprint, and CorpusDiff accept inline messages only and can return v2 corpus provenance shapes with summary_schema_version = 2, fingerprint_schema_version = 2, or diff_schema_version = 2. See GRPC_IMPLEMENTATION.md for the current protobuf and test contract notes.

The stable Prometheus contract includes HTTP request metrics plus evidence-loop counters for parse failures, validation failures, redaction failures, bundles created, replay attempts/failures, and inline corpus diffs. Labels are bounded operation/status values only; raw HL7 payloads, profile YAML, redaction policies, local paths, raw bundle IDs, raw message control IDs, and patient identifiers are not metric labels.

The server reuses the same evidence contracts as the CLI and hl7v2 library instead of defining a server-only report language.

Structured logs are emitted for parse, validation, redacted validation, bundle, replay, ACK, and ACK-policy workflows. They include message type, validation status, issue counts, redaction status, and hashed correlation identifiers. Raw HL7 payloads, raw message control IDs, profile YAML, redaction policies, and local filesystem roots are not logged by default.

Set RUST_LOG_FORMAT=json to emit these fields as JSON records. The default is human-readable text logs.

Usage

Inspect effective configuration without leaking secrets:

hl7v2-server --print-config

Run readiness after startup:

curl http://127.0.0.1:8080/ready

Create a redacted validation report:

curl -X POST http://127.0.0.1:8080/hl7/validate-redacted \
  -H "Content-Type: application/json" \
  -d '{
    "message": "MSH|^~\\&|App||Fac||20250128||ADT^A01|123|P|2.5.1\rPID|1||MRN123||Doe^John\r",
    "profile": "name: ADT_A01\nmessage_type: ADT^A01\nsegments: []\n",
    "redaction_policy": "[[rules]]\npath = \"PID.3\"\naction = \"hash\"\nreason = \"patient identifier\"\n[[rules]]\npath = \"PID.5\"\naction = \"drop\"\nreason = \"patient name\"\n"
  }'

For a full operator walkthrough, see the Deploy Validation Sidecar guide. For source examples, see the examples/ directory in the root of the repository.