From fed44f8cb83767385b4f1293043cbaccdbfc577e Mon Sep 17 00:00:00 2001 From: Jennings Zhang Date: Sun, 8 Sep 2024 00:03:22 -0400 Subject: [PATCH] Add NATS message protocol --- docs/oxidicom.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/oxidicom.md b/docs/oxidicom.md index 195f698..7992172 100644 --- a/docs/oxidicom.md +++ b/docs/oxidicom.md @@ -2,6 +2,12 @@ title: Oxidicom --- +:::tip + +This page is for an upcoming release of _ChRIS_. See https://github.com/FNNDSC/oxidicom/pull/3 + +::: + _oxidicom_ is a high-performance DICOM receiver for the [_ChRIS_ backend](https://github.com/FNNDSC/ChRIS_ultron_backEnd) (CUBE). @@ -125,3 +131,46 @@ received DICOMs. When we receive DICOMs from `MGH`, the PACS address is unknown, `oxidicom` exports traces to OpenTelemetry collector. There is a span for the association (TCP connection from PACS server to send us DICOM objects). +## NATS Messages Protocol + +_oxidicom_ sends to _CUBE_ via NATS messages about the progress of DICOM storage. + +### NATS Subject Convention + +There is a subject for each series. The subject name is + +``` +oxidicom.{pacs_name}.{SeriesInstanceUID}.ndicom +``` + +Where `{pacs_name}` is the AE title of the PACS which associated with _oxidicom_, and +`{SeriesInstanceUID}` is the `SeriesInstanceUID` **but with `.` replaced by `_`**. + +### NATS Message Encoding + +The messages take the form of a magic byte followed by data. Messages are one of: + +| Type | Magic Byte | Description | +|----------|------------|-------------------------------------------------------------------------------------------------------------------------------------| +| Done | `0x00` | `0x00` indicating no more messages will be sent for the DICOM series (for the current association). | +| Progress | `0x01` | `0x01` followed by a little-endian unsigned 32-bit integer, representing the number of DICOM files received for that series so far. | +| Error | `0x02` | `0x02` followed by a UTF-8 string, which is an error message. | + +#### Encoded Message Examples + +##### Example: Typical Messages + +``` +0x01 0x01 0x00 0x00 0x00 | Received 1 DICOM file so far +0x01 0x02 0x00 0x00 0x00 | Received 2 DICOM files so far +0x01 0xc0 0x00 0x00 0x00 | Received 192 DICOM file so far +0x00 | Done receiving DICOM files +``` + +#### Example: Error Message + +``` +0x01 0x01 0x00 0x00 0x00 | Received 1 DICOM file so far +0x02 0x73 0x74 0x75 0x63 0x6b 0x20 0x69 0x6e 0x20 0x63 0x68 0x69 0x6d 0x6e 0x65 0x79 | error: "stuck in chimney" +0x00 | Done receiving DICOM files +```