Mercurial > hg > orthanc-book
annotate Sphinx/source/faq/transfer-atomicity.rst @ 1113:a588960a72e5 default tip
spelling
| author | Alain Mazy <am@orthanc.team> |
|---|---|
| date | Mon, 28 Oct 2024 09:23:08 +0100 |
| parents | d37e987c312a |
| children |
| rev | line source |
|---|---|
|
823
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
1 .. _transfer_atomicity: |
| 822 | 2 |
|
823
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
3 How to guarantee study transfer atomicity? |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
4 ========================================== |
| 822 | 5 |
| 6 .. contents:: | |
| 7 :depth: 3 | |
| 8 | |
| 9 Introduction | |
| 10 ------------ | |
| 11 | |
| 12 There are multiple ways to transfer studies to an Orthanc instance. | |
| 13 Only a few of them provide a guarantee that the study has been | |
| 14 transferred completely. | |
| 15 | |
| 16 **Notes**: | |
| 17 | |
| 18 * By ``transfer atomicity``, we mean the capability to transfer | |
| 19 only full studies and make sure that if a transfer fails before | |
| 20 it is complete, no partial data is saved in Orthanc. The study is either | |
| 21 fully stored or not stored at all. | |
| 22 | |
| 23 * DICOM, in general, does not provide any way to detect that a study | |
| 24 is ``complete``. Actually, a study is never ``complete`` since, e.g, | |
| 25 a viewing workstation or an AI algorithm can still add a new enhanced | |
| 26 series even years after the study has been acquired. | |
| 27 However, it is still important, in many applications, to make sure | |
| 28 that a study, in its current state, is fully transmitted to another | |
| 29 destination. | |
| 30 | |
| 31 * Both the **client/source** and the **server/destination** might be interrested | |
| 32 in the transfer status. Usually, the **client** will have a guarantee that the | |
| 33 study was fully transmitted if it receives a successful answer from the server. | |
| 34 On the **server** side, it is usually more complex to make sure that the | |
| 35 full study has been received. | |
| 36 | |
| 37 | |
| 38 Summary | |
| 39 ------- | |
| 40 | |
| 41 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 42 | Transfer method | What can the Client/source trust to make sure | Can Server/destination trust ``StableStudy`` | | |
| 43 | | the full study has been stored in the server ? | event to consider the study as complete ? | | |
| 44 +==================================================+==================================================+===============================================+ | |
| 45 | **C-Store** | * If every C-Store receives a success status. | No | | |
| 46 | | * If ``/modalities/sample/store`` receives a | | | |
| 47 | | 200 or if job is successfull | | | |
| 48 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 49 | **C-Store with storage commitment** | * same as above | No | | |
| 50 | | * use storage commitment to check which | | | |
| 51 | | instances are stored on destination | | | |
| 52 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 898 | 53 | **DicomWeb** | * If client receives a 200 | Yes (provided that the client sends a full | |
| 54 | | * If ``/dicom-web/servers/sample/stow`` returns | study in a single STOW-RS request | | |
| 822 | 55 | | a 200 or if job is successfull | | |
| 56 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 57 | **Orthanc Rest API** | * If every call to ``/instances`` receives a | No | | |
| 58 | | 200 | | | |
| 59 | | * If ``/peers/sample/store`` receives a | | | |
| 60 | | 200 or if job is successfull | | | |
| 61 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 898 | 62 | **Transfers accelerator plugin** | * If ``/transfers/send`` receives a | Yes (provided that the client sends a full | |
| 822 | 63 | | 200 or if job is successfull | study) | |
| 64 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+ | |
| 65 | |
| 66 | |
| 67 C-Store | |
| 68 ------- | |
| 69 | |
| 70 If you are sending a study to Orthanc via C-Store, the study will be | |
| 71 considered as ``stable`` after a given period of time (defined by | |
| 72 the configuration ``StableAge``). This gives no guarantee at all that | |
| 73 the study has been fully transferred. The sending modality may have | |
| 74 paused transfer for a while and might resume in a few minutes. | |
| 75 | |
| 76 Although inaccurate by design, the ``IsStable`` status in Orthanc is the | |
| 77 best way to assume that a study has been fully transferred via DICOM. | |
| 78 The default value of ``60 seconds`` is appropriate for most setups. | |
| 79 | |
| 80 **Note**: | |
| 81 | |
| 82 * When Orthanc, acting as C-Store SCP, responds with a success status to a C-Store command, | |
| 83 it means that the instance has already been saved in the DB and | |
| 84 on the storage. | |
| 85 | |
| 86 | |
| 87 | |
| 88 C-Store with storage commitment | |
| 89 ------------------------------- | |
| 90 | |
| 91 Since release 1.6.0, Orthanc supports :ref:`Storage Commitment <storage-commitment>`. | |
| 92 Storage commitment is not a guarantee of atomicity but simply provides a | |
| 93 way to check that a set of instances have really been saved by Orthanc. | |
| 94 | |
| 95 Given that Orthanc only responsds to C-Store with a success status once the | |
| 96 instance has really been saved in DB and on disk, storage commitment | |
| 97 actually do not provide any additional guarantee during transfer. | |
| 98 | |
| 99 | |
| 100 DicomWeb STOW-RS | |
| 101 ---------------- | |
| 102 | |
| 103 :ref:`STOW-RS <dicomweb-stow-rs>` can be used to transfer studies to an Orthanc. | |
| 104 The STOW-RS request contains a list of DICOM instances to store in the destination | |
| 105 Orthanc (likely a complete study). | |
| 106 | |
| 107 Files are stored as they are received which means that, if the transfer is interrupted, | |
| 108 only a partial study may be stored on the destination. Therefore, on the destination, | |
| 109 a ``StableStudy`` event might be triggered even if the study was not fully received. | |
| 110 | |
| 111 | |
| 112 **Note**: | |
| 113 | |
|
823
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
114 * In earlier Orthanc versions, ``ChunkedTransfers`` was disabled, and |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
115 the whole study was transmitted in a single HTTP request and parsed |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
116 only once the full HTTP request had been received. Therefore, the |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
117 whole study was stored at once on the destination. However, note |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
118 that ``ChunkedTransfers`` is enabled by default on every Orthanc |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
119 server but it can be disabled in the client configuration. Also |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
120 note that studies bigger than 2 GB can not be transferred with |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
121 ``ChunkedTransfers`` disabled which means it is not recommended to |
|
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
122 perform transfers with disabled ``ChunkedTransfers``. |
| 822 | 123 |
| 124 | |
| 125 | |
| 126 Orthanc Rest API | |
| 127 ---------------- | |
| 128 | |
| 129 When transferring a study through the Orthanc Rest API, each instance is transferred individually. | |
| 130 Therefore, on server side, if the transfer is interrupted, the destination has no way to know that the study | |
| 131 has been fully transmitted or not. | |
| 132 | |
| 133 The server will respond with a 200 HTTP status only once the instance is stored in DB and on storage. | |
| 134 | |
| 135 | |
| 136 | |
| 137 Transfers Accelerator plugin | |
| 138 ---------------------------- | |
| 139 | |
| 140 :ref:`Transfers Accelerator plugin <transfers>` has been design to: | |
| 141 | |
| 142 * speed up transfers over HTTP/HTTPS. | |
| 143 * guarantee the transfer atomicity | |
| 144 | |
| 145 Provided that the client is sending a full study, the server receiving it | |
| 146 will store it completely. Therefore, on server side, the ``StableStudy`` event will trigger only | |
|
823
9e953bba1b21
added stone_webviewer_troubleshooting
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
822
diff
changeset
|
147 on full studies. |