diff --git a/docs/images/.gitignore b/docs/images/.gitignore new file mode 100644 --- /dev/null +++ b/docs/images/.gitignore @@ -0,0 +1 @@ +*.svg diff --git a/docs/images/Makefile b/docs/images/Makefile new file mode 100644 --- /dev/null +++ b/docs/images/Makefile @@ -0,0 +1,10 @@ +UML_DIAGS_SRC = $(wildcard *.uml) +UML_DIAGS = $(patsubst %.uml,%.svg,$(UML_DIAGS_SRC)) + +all: $(UML_DIAGS) + +%.svg: %.uml + DISPLAY="" plantuml -tsvg $< + +clean: + -rm -f $(UML_DIAGS) diff --git a/docs/images/deposit-create-chart.uml b/docs/images/deposit-create-chart.uml new file mode 100644 --- /dev/null +++ b/docs/images/deposit-create-chart.uml @@ -0,0 +1,26 @@ +@startuml + participant CLIENT as "SWORD client\n(eg. HAL)" + participant DEPOSIT as "swh-deposit" + participant DEPOSIT_STORAGE as "deposit storage" + + activate CLIENT + activate DEPOSIT + activate DEPOSIT_STORAGE + + CLIENT ->> DEPOSIT: GET /1// + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok (if client exists and credentials ok) + + DEPOSIT -->> CLIENT: return 200, + + CLIENT ->> DEPOSIT: POST /1// + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok (if client exists and credentials ok) + + DEPOSIT ->> DEPOSIT_STORAGE: create new deposit + DEPOSIT_STORAGE -->> DEPOSIT: return deposit_id + + DEPOSIT -->> CLIENT: return 201, +@enduml diff --git a/docs/images/deposit-delete-chart.uml b/docs/images/deposit-delete-chart.uml new file mode 100644 --- /dev/null +++ b/docs/images/deposit-delete-chart.uml @@ -0,0 +1,37 @@ +@startuml + participant CLIENT as "SWORD client\n(eg. HAL)" + participant DEPOSIT as "swh-deposit" + participant DEPOSIT_STORAGE as "deposit storage" + + activate CLIENT + activate DEPOSIT + activate DEPOSIT_STORAGE + + CLIENT ->> DEPOSIT: POST /1//\nHEADER In-Progress: true + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok (if client exists and credentials ok) + + DEPOSIT -->> CLIENT: return 201, + + loop while status is 'partial' + + CLIENT -> DEPOSIT: DELETE /1///media/\nDELETE /1///metadata/ + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok + + DEPOSIT ->> DEPOSIT_STORAGE: check inputs() + + alt status is not 'partial' + DEPOSIT_STORAGE -->> DEPOSIT: return ko + DEPOSIT -->> CLIENT: return 403 + else status is 'partial' + DEPOSIT ->> DEPOSIT_STORAGE: delete-deposit-or-deposit-archives() + DEPOSIT_STORAGE -->> DEPOSIT: return ko + DEPOSIT -->> CLIENT: return 204 + end + + end +@enduml + diff --git a/docs/images/deposit-update-chart.uml b/docs/images/deposit-update-chart.uml new file mode 100644 --- /dev/null +++ b/docs/images/deposit-update-chart.uml @@ -0,0 +1,37 @@ +@startuml + participant CLIENT as "SWORD client\n(eg. HAL)" + participant DEPOSIT as "swh-deposit" + participant DEPOSIT_STORAGE as "deposit storage" + + activate CLIENT + activate DEPOSIT + activate DEPOSIT_STORAGE + + CLIENT ->> DEPOSIT: POST /1//\nHEADER In-Progress: true + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok (if client exists and credentials ok) + + DEPOSIT -->> CLIENT: return 201, + + loop while status is 'partial' + + CLIENT -> DEPOSIT: POST/PUT /1///media/\nPOST/PUT /1///metadata/ + + DEPOSIT ->> DEPOSIT_STORAGE: check authentication + DEPOSIT_STORAGE -->> DEPOSIT: return ok + + DEPOSIT ->> DEPOSIT_STORAGE: check inputs() + DEPOSIT_STORAGE -->> DEPOSIT: return ok + + alt HEADER: In-Progress = true + DEPOSIT ->> DEPOSIT_STORAGE: add-or-replace-data-and-update-status('partial') + else HEADER: In-Progress = false + DEPOSIT ->> DEPOSIT_STORAGE: add-or-replace-data-and-update-status('ready') + end + DEPOSIT_STORAGE -->> DEPOSIT: return ok + + end + + DEPOSIT -->> CLIENT: return 201, \nreturn 204 +@enduml diff --git a/docs/specs/blueprint.rst b/docs/specs/blueprint.rst --- a/docs/specs/blueprint.rst +++ b/docs/specs/blueprint.rst @@ -36,14 +36,36 @@ Schema representation ^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html +Scenario: pushing a deposit via SWORD protocol (nominal scenario) - - -.. figure:: ../images/deposit-create-chart.png +.. figure:: ../images/deposit-create-chart.svg :alt: +Deposit statuses: + +'partial' + The deposit is new or partially received, since it can be done in + multiple requests + +'expired' + Deposit was there too long and is new deemed ready to be + garbage-collected + +'ready' + Deposit is fully received and ready for injection + +'injecting' + Injection is ongoing on SWH's side + +'success' + Injection successful + +'failure' + Injection failure + + + Updating an existing deposit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -71,13 +93,34 @@ Schema representation ^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html - - +Scenario: updating a deposit via SWORD protocol -.. figure:: ../images/deposit-update-chart.png +.. figure:: ../images/deposit-update-chart.svg :alt: + +Deposit statuses: + +'partial' + The deposit is new or partially received, since it can be done in + multiple requests + +'expired' + Deposit was there too long and is new deemed ready to be + garbage-collected + +'ready' + Deposit is fully received and ready for injection + +'injecting' + Injection is ongoing on SWH's side + +'success' + Injection successful + +'failure' + Injection failure + Deleting deposit (or associated archive, or associated metadata) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,13 +133,34 @@ Schema representation ^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html - - +Scenario: deleting a deposit via SWORD protocol -.. figure:: ../images/deposit-delete-chart.png +.. figure:: ../images/deposit-delete-chart.svg :alt: + +Deposit statuses: + +'partial' + The deposit is new or partially received, since it can be done in + multiple requests + +'expired' + Deposit was there too long and is new deemed ready to be + garbage-collected + +'ready' + Deposit is fully received and ready for injection + +'injecting' + Injection is ongoing on SWH's side + +'success' + Injection successful + +'failure' + Injection failure + Client asks for operation status ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~