# gRPC Server Implementation
This crate implements the `HL7Service` gRPC API for HL7 v2 parsing,
validation, normalization, ACK generation, streaming parse, redacted
validation, evidence bundle creation, evidence bundle replay, and inline corpus
evidence workflows.
## Contract Source
The canonical protobuf contract is:
```text
api/proto/hl7v2/v1/hl7v2.proto
```
The packaged crate copy is:
```text
crates/hl7v2-server/proto/hl7v2/v1/hl7v2.proto
```
`build.rs` uses the workspace contract when it is available and falls back to
the packaged copy for crate packaging. The packaging drift test verifies both
copies stay synchronized.
## Implemented RPCs
| `Parse` | Implemented | Parses raw or MLLP-framed HL7 bytes into protobuf message fields and metadata. |
| `ParseStream` | Implemented | Parses one request message into one response message; per-message parse or MLLP failures return error payloads without failing the whole stream. Malformed gRPC frames still return a tonic `Status`. |
| `Validate` | Implemented | Validates raw or MLLP-framed HL7 against an inline profile. Preserves legacy `valid`, `errors`, `warnings`, and `summary` fields while also returning `validation_report`; `report_schema_version = 2` adds `validation_report_v2`. |
| `ProfileLint` | Implemented | Lints caller-supplied inline profile YAML without applying it to a message. Always returns v1 `profile_lint_report`; `report_schema_version = 2` adds `profile_lint_report_v2`. |
| `ProfileExplain` | Implemented | Explains caller-supplied inline profile YAML without applying it to a message. Always returns v1 `profile_explain_report`; `report_schema_version = 2` adds `profile_explain_report_v2`. |
| `ProfileTest` | Implemented | Tests caller-supplied inline HL7 fixtures against an inline profile without reading request filesystem paths. Always returns v1 `profile_test_report`; `report_schema_version = 2` adds `profile_test_report_v2`. |
| `ValidateRedacted` | Implemented | Applies an inline safe-analysis redaction policy before validation. Always returns v1 `validation_report` and `redaction_receipt`, can include v2 validation, redaction receipt, and quarantine summary artifacts, includes `redacted_hl7` only when requested, and writes configured quarantine output only when validation fails. |
| `CreateEvidenceBundle` | Implemented | Writes a redacted evidence bundle under the configured server bundle output root. The request supplies inline message, profile, policy, and a bundle ID; the response returns the shared summary shape with a hashed public output ID and never exposes the configured root or raw bundle ID. `bundle_artifact_schema_version = 2` writes v2 bundle artifacts. |
| `ReplayEvidenceBundle` | Implemented | Replays and verifies a redacted evidence bundle under the configured server bundle output root. The request supplies a bundle ID; the response returns the shared replay report shape and never exposes the configured root or raw bundle ID. `replay_report_schema_version = 2` adds `replay_report_v2`. |
| `CorpusSummarize` | Implemented | Summarizes caller-supplied inline messages only. The RPC does not read filesystem paths from requests; `summary_schema_version = 2` adds the v2 corpus summary provenance shape. |
| `CorpusFingerprint` | Implemented | Fingerprints caller-supplied inline messages only. The RPC does not read filesystem paths from requests; optional inline profiles add validation issue-code counts; `fingerprint_schema_version = 2` adds the v2 corpus fingerprint provenance shape. |
| `CorpusDiff` | Implemented | Diffs caller-supplied inline before/after corpora only. The RPC does not read filesystem paths from requests; optional inline profiles add validation issue-code deltas; `diff_schema_version = 2` adds the v2 corpus diff provenance shape. |
| `GenerateAck` | Implemented | Generates ACK messages using the canonical `hl7v2` ACK facade. |
| `Normalize` | Implemented | Normalizes delimiter output and can optionally MLLP-frame the response. |
| `HealthCheck` | Implemented | Reports serving status and crate version. |
## Evidence Semantics
The gRPC service keeps v1-compatible response fields by default. Provenance
fields are additive and opt in:
```text
ValidateRequest.report_schema_version = 2
ProfileLintRequest.report_schema_version = 2
ProfileExplainRequest.report_schema_version = 2
ProfileTestRequest.report_schema_version = 2
ValidateRedactedRequest.report_schema_version = 2
ValidateRedactedRequest.redaction_receipt_schema_version = 2
ValidateRedactedRequest.quarantine_schema_version = 2
CreateEvidenceBundleRequest.bundle_artifact_schema_version = 2
ReplayEvidenceBundleRequest.replay_report_schema_version = 2
CorpusSummarizeRequest.summary_schema_version = 2
CorpusFingerprintRequest.fingerprint_schema_version = 2
CorpusDiffRequest.diff_schema_version = 2
```
For `Validate`, `ProfileLint`, `ProfileExplain`, `ProfileTest`, `ValidateRedacted`,
`CreateEvidenceBundle`, `ReplayEvidenceBundle`, `CorpusSummarize`,
`CorpusFingerprint`, and `CorpusDiff`, schema versions `0` and `1` use the
default v1 shape, `2` returns or writes the requested v2 artifact, and other
values return
`InvalidArgument`.
`ValidateRedacted` fails closed when the redaction policy is invalid or misses a
present built-in sensitive path. The redacted HL7 body is omitted unless
`include_redacted_hl7` is set. When quarantine is configured, failed redacted
validation writes quarantine output under the configured quarantine root and
returns a root-relative `quarantine` summary. `quarantine_schema_version = 2`
adds `quarantine_v2`. Valid reports or disabled quarantine config do not write
output, and enabled quarantine without a configured root fails closed with
`FailedPrecondition`.
`CreateEvidenceBundle` and `ReplayEvidenceBundle` operate only beneath
`bundle_output_root` from server configuration. Request bundle IDs are
validated for safe relative output, bundle creation responses expose a hashed
public output ID, and diagnostics must not echo raw HL7, raw bundle IDs,
configured filesystem roots, profile YAML, or redaction policy text.
## Validation
Useful checks for gRPC contract changes:
```powershell
npx -y @bufbuild/buf lint api/proto
npx -y @bufbuild/buf breaking api/proto --against "https://github.com/EffortlessMetrics/hl7v2-rs.git#branch=main,subdir=api/proto"
cargo +1.95.0 test -p hl7v2-server --test proto_packaging_test
cargo +1.95.0 test -p hl7v2-server --test grpc_contract_tests
cargo +1.95.0 check -p hl7v2-server --all-features --all-targets
cargo +1.95.0 clippy -p hl7v2-server --all-targets -- -D warnings
```