Mercurial > hg > orthanc-book

comparison Sphinx/source/faq/transfer-atomicity.rst @ 822:0f4f11636193

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
transfers atomicity
author Alain Mazy <am@osimis.io>
date Mon, 21 Mar 2022 12:54:40 +0100
parents
children 9e953bba1b21
comparison
equal deleted inserted replaced
821:d7c8c8f6cffb 822:0f4f11636193
1 .. _dcmtk-tricks:
2
3 How to guarantee study transfer atomicity ?
4 =========================================
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 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
53 | **DicomWeb** | * If client receives a 200 | No |
54 | | * If ``/dicom-web/servers/sample/stow`` returns | |
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 +--------------------------------------------------+--------------------------------------------------+-----------------------------------------------+
62 | **Transfers accelerator plugin** | * If ``/transfers/send`` receives a | Yes (provided that the client sends full |
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
114 * In earlier Orthanc versions, ``ChunkedTransfers`` was disabled, and the whole study
115 was transmitted in a single HTTP request and parsed only once the full HTTP request
116 had been received. Therefore, the whole study was stored at once on the destination.
117 However, note that ``ChunkedTransfers`` is enabled by default on every Orthanc server
118 but it can be disabled in the client configuration. Also note that studies bigger than
119 2 GB can not be transferred with ``ChunkedTransfers`` disabled which means it is not
120 recommended to perform transfers with disabled ``ChunkedTransfers``.
121
122
123
124 Orthanc Rest API
125 ----------------
126
127 When transferring a study through the Orthanc Rest API, each instance is transferred individually.
128 Therefore, on server side, if the transfer is interrupted, the destination has no way to know that the study
129 has been fully transmitted or not.
130
131 The server will respond with a 200 HTTP status only once the instance is stored in DB and on storage.
132
133
134
135 Transfers Accelerator plugin
136 ----------------------------
137
138 :ref:`Transfers Accelerator plugin <transfers>` has been design to:
139
140 * speed up transfers over HTTP/HTTPS.
141 * guarantee the transfer atomicity
142
143 Provided that the client is sending a full study, the server receiving it
144 will store it completely. Therefore, on server side, the ``StableStudy`` event will trigger only
145 on full studies.