Skip to content

DIG-Network/dig-propagation-server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

9348301 · Oct 6, 2024
Oct 1, 2024
Sep 10, 2024
Oct 6, 2024
Sep 21, 2024
Sep 8, 2024
Sep 8, 2024
Oct 6, 2024
Oct 1, 2024
Sep 8, 2024
Sep 22, 2024
Sep 8, 2024
Sep 8, 2024
Oct 6, 2024
Oct 6, 2024
Sep 8, 2024
Sep 8, 2024

Repository files navigation

Upload Protocol - README

Overview

This upload protocol manages file uploads securely and efficiently in a distributed storage network. Each upload session is tied to a unique session ID and is managed via a temporary folder with a customizable Time-to-Live (TTL). The protocol validates key ownership using signatures and supports flexible session handling, including file uploads, session commits, and aborts.

Key Features

  • Session-Based File Uploads: Each upload occurs within a session that has a unique session ID. Files are uploaded to a temporary directory that has a defined TTL.
  • Key Ownership Validation: File uploads require nonce-based validation with a key ownership signature to ensure the uploader has write permissions.
  • Session TTL Management: Sessions are cleaned up automatically after inactivity, or the session TTL can be reset during active file uploads.
  • Commit and Abort Support: Once files are uploaded, they can either be committed to the store's permanent directory or aborted, deleting all files associated with the session.

API Endpoints

1. HEAD /stores/{storeId}

Description: Check if a store exists and optionally verify if a specific root hash exists in that store.

  • Query Param: hasRootHash (optional) — Use this query parameter to check if the root hash exists in the store.
  • Headers Returned:
    • x-store-exists: Indicates whether the store exists (true or false).
    • x-has-root-hash: If the hasRootHash query is provided, this header will indicate whether the specific root hash exists (true or false).

Example:

HEAD /stores/myStoreId?hasRootHash=12345abcdef

The server will return the following headers:

  • x-store-exists: true
  • x-has-root-hash: true (if the root hash exists)

2. POST /upload/{storeId}

Description: Starts an upload session for a store. If the store does not exist, the user will be required to authenticate.

  • Response:
    • sessionId: A unique identifier for the upload session.

Example:

POST /upload/myStoreId

Response:

{
  "message": "Upload session started for DataStore myStoreId.",
  "sessionId": "12345-abcdef-67890"
}

3. PUT /upload/{storeId}/{sessionId}/{filename}

Description: Uploads a file to the store within an active session. Each file must be validated with a nonce, key ownership signature, and the uploader's public key.

  • Headers Required:
    • x-key-ownership-sig: A signature proving key ownership.
    • x-public-key: The uploader's public key.
    • x-nonce: A unique nonce used to generate the signature.

Example:

PUT /upload/myStoreId/12345-abcdef-67890/myfile.txt

Headers:

  • x-key-ownership-sig: <signature>
  • x-public-key: <public-key>
  • x-nonce: <nonce>

4. POST /commit/{storeId}/{sessionId}

Description: Finalizes the upload by moving files from the session's temporary folder to the store's permanent directory.

Example:

POST /commit/myStoreId/12345-abcdef-67890

Response:

{
  "message": "Upload for DataStore myStoreId under session 12345-abcdef-67890 committed successfully."
}

5. POST /abort/{storeId}/{sessionId}

Description: Aborts the upload session, deletes the temporary session folder, and removes the session from the cache.

Example:

POST /abort/myStoreId/12345-abcdef-67890

Response:

{
  "message": "Upload session 12345-abcdef-67890 for DataStore myStoreId aborted and cleaned up."
}

Example Workflow

  1. Start an Upload Session:

    • Call the POST /upload/{storeId} endpoint to start an upload session.
    • The server responds with a sessionId to track the session.
  2. Upload a File:

    • For each file, send a PUT /upload/{storeId}/{sessionId}/{filename} request.
    • Include the required headers (x-key-ownership-sig, x-public-key, and x-nonce).
  3. Commit the Session:

    • After all files are uploaded, call the POST /commit/{storeId}/{sessionId} endpoint to commit the session.
  4. Abort the Session (Optional):

    • If you need to abort the session and discard the uploaded files, use the POST /abort/{storeId}/{sessionId} endpoint.