Mercurial > hg > orthanc-book
changeset 822:0f4f11636193
transfers atomicity
| author | Alain Mazy <am@osimis.io> |
|---|---|
| date | Mon, 21 Mar 2022 12:54:40 +0100 |
| parents | d7c8c8f6cffb |
| children | 9e953bba1b21 |
| files | Sphinx/source/faq.rst Sphinx/source/faq/transfer-atomicity.rst Sphinx/source/plugins/dicomweb.rst |
| diffstat | 3 files changed, 149 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/faq.rst Mon Mar 07 10:58:09 2022 +0100 +++ b/Sphinx/source/faq.rst Mon Mar 21 12:54:40 2022 +0100 @@ -69,3 +69,4 @@ faq/series-completion.rst faq/dcmtk-tricks.rst faq/debugging-encodings.rst + faq/transfer-atomicity.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/faq/transfer-atomicity.rst Mon Mar 21 12:54:40 2022 +0100 @@ -0,0 +1,145 @@ +.. _dcmtk-tricks: + +How to guarantee study transfer atomicity ? +========================================= + +.. contents:: + :depth: 3 + +Introduction +------------ + +There are multiple ways to transfer studies to an Orthanc instance. +Only a few of them provide a guarantee that the study has been +transferred completely. + +**Notes**: + +* By ``transfer atomicity``, we mean the capability to transfer + only full studies and make sure that if a transfer fails before + it is complete, no partial data is saved in Orthanc. The study is either + fully stored or not stored at all. + +* DICOM, in general, does not provide any way to detect that a study + is ``complete``. Actually, a study is never ``complete`` since, e.g, + a viewing workstation or an AI algorithm can still add a new enhanced + series even years after the study has been acquired. + However, it is still important, in many applications, to make sure + that a study, in its current state, is fully transmitted to another + destination. + +* Both the **client/source** and the **server/destination** might be interrested + in the transfer status. Usually, the **client** will have a guarantee that the + study was fully transmitted if it receives a successful answer from the server. + On the **server** side, it is usually more complex to make sure that the + full study has been received. + + +Summary +------- + ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ +| Transfer method | What can the Client/source trust to make sure | Can Server/destination trust ``StableStudy`` | +| | the full study has been stored in the server ? | event to consider the study as complete ? | ++==================================================+==================================================+===============================================+ +| **C-Store** | * If every C-Store receives a success status. | No | +| | * If ``/modalities/sample/store`` receives a | | +| | 200 or if job is successfull | | ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ +| **C-Store with storage commitment** | * same as above | No | +| | * use storage commitment to check which | | +| | instances are stored on destination | | ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ +| **DicomWeb** | * If client receives a 200 | No | +| | * If ``/dicom-web/servers/sample/stow`` returns | | +| | a 200 or if job is successfull | | ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ +| **Orthanc Rest API** | * If every call to ``/instances`` receives a | No | +| | 200 | | +| | * If ``/peers/sample/store`` receives a | | +| | 200 or if job is successfull | | ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ +| **Transfers accelerator plugin** | * If ``/transfers/send`` receives a | Yes (provided that the client sends full | +| | 200 or if job is successfull | study) | ++--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ + + +C-Store +------- + +If you are sending a study to Orthanc via C-Store, the study will be +considered as ``stable`` after a given period of time (defined by +the configuration ``StableAge``). This gives no guarantee at all that +the study has been fully transferred. The sending modality may have +paused transfer for a while and might resume in a few minutes. + +Although inaccurate by design, the ``IsStable`` status in Orthanc is the +best way to assume that a study has been fully transferred via DICOM. +The default value of ``60 seconds`` is appropriate for most setups. + +**Note**: + +* When Orthanc, acting as C-Store SCP, responds with a success status to a C-Store command, + it means that the instance has already been saved in the DB and + on the storage. + + + +C-Store with storage commitment +------------------------------- + +Since release 1.6.0, Orthanc supports :ref:`Storage Commitment <storage-commitment>`. +Storage commitment is not a guarantee of atomicity but simply provides a +way to check that a set of instances have really been saved by Orthanc. + +Given that Orthanc only responsds to C-Store with a success status once the +instance has really been saved in DB and on disk, storage commitment +actually do not provide any additional guarantee during transfer. + + +DicomWeb STOW-RS +---------------- + +:ref:`STOW-RS <dicomweb-stow-rs>` can be used to transfer studies to an Orthanc. +The STOW-RS request contains a list of DICOM instances to store in the destination +Orthanc (likely a complete study). + +Files are stored as they are received which means that, if the transfer is interrupted, +only a partial study may be stored on the destination. Therefore, on the destination, +a ``StableStudy`` event might be triggered even if the study was not fully received. + + +**Note**: + +* In earlier Orthanc versions, ``ChunkedTransfers`` was disabled, and the whole study +was transmitted in a single HTTP request and parsed only once the full HTTP request +had been received. Therefore, the whole study was stored at once on the destination. +However, note that ``ChunkedTransfers`` is enabled by default on every Orthanc server +but it can be disabled in the client configuration. Also note that studies bigger than +2 GB can not be transferred with ``ChunkedTransfers`` disabled which means it is not +recommended to perform transfers with disabled ``ChunkedTransfers``. + + + +Orthanc Rest API +---------------- + +When transferring a study through the Orthanc Rest API, each instance is transferred individually. +Therefore, on server side, if the transfer is interrupted, the destination has no way to know that the study +has been fully transmitted or not. + +The server will respond with a 200 HTTP status only once the instance is stored in DB and on storage. + + + +Transfers Accelerator plugin +---------------------------- + +:ref:`Transfers Accelerator plugin <transfers>` has been design to: + +* speed up transfers over HTTP/HTTPS. +* guarantee the transfer atomicity + +Provided that the client is sending a full study, the server receiving it +will store it completely. Therefore, on server side, the ``StableStudy`` event will trigger only +on full studies. \ No newline at end of file
--- a/Sphinx/source/plugins/dicomweb.rst Mon Mar 07 10:58:09 2022 +0100 +++ b/Sphinx/source/plugins/dicomweb.rst Mon Mar 21 12:54:40 2022 +0100 @@ -591,6 +591,9 @@ Sending DICOM resources to a STOW-RS server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _dicomweb-stow-rs: + + .. highlight:: bash STOW-RS allows to send local DICOM resources to a remote DICOMweb