Skip to main content

Crate hl7_2_redact

Crate hl7_2_redact 

Source
Expand description

Redaction for HL7 v2 messages in ER7 (pipe-hat) encoding, in either direction: reject by default and name what survives, or accept by default and name what does not.

An HL7 v2 message is almost entirely patient detail. A process that logs one — to find a failure, to trace a flow, to answer “what happened to the message the ward is asking about?” — is putting clinical data into a store that is queried far more widely, and retained far longer, than the message store it came from. This crate is what goes between.

§Two dispositions, and which one to pick

Every field is either accepted — it survives into the output — or rejected — it is replaced by a mask. A Policy decides which, starting from a default disposition and applying whatever exceptions you name.

Starts fromYou nameUse when
Policy::reject_allreject everythingwhat to acceptthe payload is clinical and you are publishing a little of it
Policy::accept_allaccept everythingwhat to rejectthe payload is already known-safe and you are removing a few known fields

Reject by default is the safer of the two, and it is the default. The difference is what happens when a sender adds a field nobody anticipated: rejecting by default masks it, accepting by default publishes it. Reach for Policy::accept_all when you genuinely know the whole shape of what you are handling — a synthetic corpus, a message that has already been through a redactor, a feed with no patient content — and not merely because it is fewer lines to write.

Policy::routing_metadata is the built-in reject-by-default answer: ten MSH fields — the routing and metadata a support engineer needs to find one message among millions — and nothing else, from any segment.

§Shape survives, content does not

Field positions are preserved: an empty field stays empty and a populated one becomes the mask. Segment identifiers are structural and are always emitted.

use hl7_2_redact::redact;

// PID-2 is empty and PID-3 is not; both stay where they are.
assert_eq!(redact("MSH|^~\\&|A\rPID|1||X"), "MSH|^~\\&|A\rPID|***||***");

That keeps visible which segments arrived, how many fields each carried, and where the gaps are — which is most of what a structural problem looks like, without any of the content.

§What this is not

Not a de-identification tool. It is a positional editor. It cannot find an identifier written into a free-text NTE segment that a policy accepts, and it has no opinion about whether what survives is anonymous enough for a given purpose — that is a judgement about a whole data set, made by a person.

Not a parser. It never allocates proportional to a declared length, and never panics on arbitrary bytes. Anything it cannot recognise as ER7 is handled whole rather than inspected, because the content of an unrecognised payload is by definition unknown. Those properties matter because the caller is usually an ingress process logging whatever arrived on a socket.

§An invalid payload: mask it, pass it, or refuse it

Unrecognised decides what happens to a payload that is not readable as ER7 at all:

What comes outUse when
Unrecognised::Rejectthe mask, in place of the whole payloadthe default: safe, and always produces a log line
Unrecognised::Acceptthe payload, unchangedyou already know it is not clinical
Unrecognised::Refusenothing — Policy::try_redact returns Refuseda placeholder is not good enough and the caller must decide

Refusal is the one that needs the fallible API. *** in a log line cannot distinguish “this was masked” from “this could not be read”, and for a caller that must fail the operation, raise an alert, or route the payload somewhere it can be inspected safely, that distinction is the whole point.

use hl7_2_redact::{Policy, Refusal, Unrecognised};

let policy = Policy::routing_metadata().on_unrecognised(Unrecognised::Refuse);

// A real message is redacted as usual.
let redacted = policy.try_redact("MSH|^~\\&|A\rPID|1||SECRET")?;
assert_eq!(redacted, "MSH|^~\\&|A\rPID|***||***");

// A payload that is invalid is refused.
let error = policy.try_redact(r#"{"nhsNumber": "4444444444"}"#).unwrap_err();
assert_eq!(error.reason(), Refusal::NotAMessageHeader);

// The error names no content — only why, and how many bytes.
assert!(!error.to_string().contains("4444444444"));

An empty payload is returned unchanged under every setting, refusal included: there is nothing to hide, and refusing it would turn “the payload was empty” — itself the diagnosis — into an error a caller has to unpick.

§Examples

The default policy, which is what most callers want:

use hl7_2_redact::redact;

let message = "MSH|^~\\&|252|252|100|100|20260729095037|SEC|ADT^A28^ADT_A05|MSG1|P|2.5\r\
               PID|1||B0000010612^^^328^PI||SURNAME^FORENAME||20010909|M";

let redacted = redact(message);

// Routing metadata is accepted, so the message is still findable.
assert!(redacted.contains("|252|252|100|100|20260729095037|"));
assert!(redacted.contains("ADT^A28^ADT_A05"));
// The patient is not.
assert!(!redacted.contains("SURNAME"));
assert!(!redacted.contains("B0000010612"));
// MSH-8, the security field, is not accepted.
assert!(!redacted.contains("SEC"));

Reject by default, additionally accepting the event type in EVN-1:

use hl7_2_redact::Policy;

let policy = Policy::routing_metadata().accept("EVN", [1]);
let redacted = policy.redact("MSH|^~\\&|A\rEVN|A28|20260729095037");

assert!(redacted.contains("EVN|A28|***"));

Accept by default, rejecting two segments outright and one field elsewhere:

use hl7_2_redact::Policy;

let policy = Policy::accept_all()
    .reject_segment("PID")
    .reject_segment("NK1")
    .reject("PV1", [7]);

let redacted = policy.redact("MSH|^~\\&|A\rPID|1||SECRET\rPV1|1|I|||||DOCTOR");

assert!(redacted.contains("MSH|^~\\&|A"), "{redacted}");
assert!(!redacted.contains("SECRET"), "{redacted}");
assert!(!redacted.contains("DOCTOR"), "{redacted}");
assert!(redacted.contains("PV1|1|I"), "{redacted}");

Structs§

Policy
Which fields of which segments this policy names, and what happens to everything it does not.
Refused
A payload that Unrecognised::Refuse declined to redact.

Enums§

Disposition
What happens to a field that no exception names.
Refusal
Why a payload was refused.
Unrecognised
What to do with a payload that is not recognisable as ER7.

Constants§

DEFAULT_MASK
What a rejected value is replaced with, unless a policy says otherwise.
ROUTING_METADATA_MSH_FIELDS
The MSH field numbers Policy::routing_metadata accepts, in HL7’s own 1-based numbering.
SEPARATOR_IS_FIELD_ONE
The segments whose field 1 is the field separator.

Functions§

redact
Redact a payload under Policy::routing_metadata.
separator_of
The field separator a message declares, if it declares one readably.