sal/rfs-client/openapi.json

{"openapi":"3.0.3","info":{"title":"rfs","description":"","license":{"name":""},"version":"0.2.0"},"paths":{"/api/v1":{"get":{"tags":["System"],"operationId":"health_check_handler","responses":{"200":{"description":"flist server is working","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/v1/block":{"post":{"tags":["Block Management"],"summary":"Upload a block to the server.","description":"If the block already exists, the server will return a 200 OK response.\nIf the block is new, the server will return a 201 Created response.","operationId":"upload_block_handler","parameters":[{"name":"file_hash","in":"query","description":"File hash associated with the block","required":true,"schema":{"type":"string"}},{"name":"idx","in":"query","description":"Block index within the file","required":true,"schema":{"type":"integer","format":"int64","minimum":0}}],"requestBody":{"description":"Block data to upload","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"200":{"description":"Block already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockUploadedResponse"}}}},"201":{"description":"Block created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockUploadedResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/block/verify":{"post":{"tags":["Block Management"],"summary":"Verify if multiple blocks exist on the server.","description":"Returns a list of missing blocks.","operationId":"verify_blocks_handler","requestBody":{"description":"List of block hashes to verify","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyBlocksRequest"}}},"required":true},"responses":{"200":{"description":"Verification completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyBlocksResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/block/{hash}":{"get":{"tags":["Block Management"],"summary":"Retrieve a block by its hash.","operationId":"get_block_handler","parameters":[{"name":"hash","in":"path","description":"Block hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Block found","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Block not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}},"head":{"tags":["Block Management"],"summary":"Checks a block by its hash.","operationId":"check_block_handler","parameters":[{"name":"hash","in":"path","description":"Block hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Block found"},"404":{"description":"Block not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/block/{hash}/downloads":{"get":{"tags":["Block Management"],"summary":"Retrieve the number of times a block has been downloaded.","operationId":"get_block_downloads_handler","parameters":[{"name":"hash","in":"path","description":"Block hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Download count retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockDownloadsResponse"}}}},"404":{"description":"Block not found"},"500":{"description":"Internal server error"}}}},"/api/v1/blocks":{"get":{"tags":["Block Management"],"summary":"List all block hashes in the server with pagination","operationId":"list_blocks_handler","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"schema":{"type":"integer","format":"int32","nullable":true,"minimum":0}},{"name":"per_page","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","format":"int32","nullable":true,"minimum":0}}],"responses":{"200":{"description":"List of block hashes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListBlocksResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}}}},"/api/v1/blocks/{hash}":{"get":{"tags":["Block Management"],"summary":"Retrieve blocks by hash (file hash or block hash).","description":"If the hash is a file hash, returns all blocks with their block index related to that file.\nIf the hash is a block hash, returns the block itself.","operationId":"get_blocks_by_hash_handler","parameters":[{"name":"hash","in":"path","description":"File hash or block hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Blocks found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocksResponse"}}}},"404":{"description":"Hash not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/file":{"post":{"tags":["File Management"],"summary":"Upload a file to the server.","description":"The file will be split into blocks and stored in the database.","operationId":"upload_file_handler","requestBody":{"description":"File data to upload","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"201":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/file/{hash}":{"get":{"tags":["File Management"],"summary":"Retrieve a file by its hash from path, with optional custom filename in request body.","description":"The file will be reconstructed from its blocks.","operationId":"get_file_handler","parameters":[{"name":"hash","in":"path","description":"File hash","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Optional custom filename for download","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDownloadRequest"}}},"required":true},"responses":{"200":{"description":"File found","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/fl":{"get":{"tags":["Flist Management"],"operationId":"list_flists_handler","responses":{"200":{"description":"Listing flists","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/FileInfo"}}}}}},"401":{"description":"Unauthorized user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}},"post":{"tags":["Flist Management"],"operationId":"create_flist_handler","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlistBody"}}},"required":true},"responses":{"201":{"description":"Flist conversion started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Unauthorized user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/fl/preview/{flist_path}":{"get":{"tags":["Flist Management"],"operationId":"preview_flist_handler","parameters":[{"name":"flist_path","in":"path","description":"flist file path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Flist preview result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"401":{"description":"Unauthorized user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/fl/{job_id}":{"get":{"tags":["Flist Management"],"operationId":"get_flist_state_handler","parameters":[{"name":"job_id","in":"path","description":"flist job id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Flist state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlistStateResponse"}}}},"401":{"description":"Unauthorized user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"404":{"description":"Flist not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}},"security":[{"bearerAuth":[]}]}},"/api/v1/signin":{"post":{"tags":["Authentication"],"operationId":"sign_in_handler","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInBody"}}},"required":true},"responses":{"201":{"description":"User signed in successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignInResponse"}}}},"401":{"description":"Unauthorized user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/api/v1/user/blocks":{"get":{"tags":["Block Management"],"summary":"Retrieve all blocks uploaded by a specific user.","operationId":"get_user_blocks_handler","parameters":[{"name":"page","in":"query","description":"Page number (1-indexed)","required":false,"schema":{"type":"integer","format":"int32","nullable":true,"minimum":0}},{"name":"per_page","in":"query","description":"Number of items per page","required":false,"schema":{"type":"integer","format":"int32","nullable":true,"minimum":0}}],"responses":{"200":{"description":"Blocks found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserBlocksResponse"}}}},"401":{"description":"Unauthorized"},"500":{"description":"Internal server error"}},"security":[{"bearerAuth":[]}]}},"/api/v1/website/{website_hash}/{path}":{"get":{"tags":["Website Serving"],"operationId":"serve_website_handler","parameters":[{"name":"website_hash","in":"path","description":"flist hash of the website directory","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","description":"Path to the file within the website directory, defaults to index.html if empty","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Website file served successfully","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}},"/{path}":{"get":{"tags":["Flist Management"],"summary":"Serve flist files from the server's filesystem","operationId":"serve_flists","parameters":[{"name":"path","in":"path","description":"Path to the flist file or directory to serve","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully served the flist or directory listing","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Flist not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseError"}}}}}}}},"components":{"schemas":{"BlockDownloadsResponse":{"type":"object","description":"Response for block downloads endpoint","required":["block_hash","downloads_count","block_size"],"properties":{"block_hash":{"type":"string","description":"Block hash"},"block_size":{"type":"integer","format":"int64","description":"Size of the block in bytes","minimum":0},"downloads_count":{"type":"integer","format":"int64","description":"Number of times the block has been downloaded","minimum":0}}},"BlockInfo":{"type":"object","description":"Block information with hash and index","required":["hash","index"],"properties":{"hash":{"type":"string","description":"Block hash"},"index":{"type":"integer","format":"int64","description":"Block index within the file","minimum":0}}},"BlockUploadedResponse":{"type":"object","required":["hash","message"],"properties":{"hash":{"type":"string"},"message":{"type":"string"}}},"BlocksResponse":{"type":"object","description":"Response for blocks by hash endpoint","required":["blocks"],"properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/BlockInfo"},"description":"List of blocks with their indices"}}},"DirListTemplate":{"type":"object","required":["lister","cur_path"],"properties":{"cur_path":{"type":"string"},"lister":{"$ref":"#/components/schemas/DirLister"}}},"DirLister":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/FileInfo"}}}},"ErrorTemplate":{"type":"object","required":["err","cur_path","message"],"properties":{"cur_path":{"type":"string"},"err":{"$ref":"#/components/schemas/TemplateErr"},"message":{"type":"string"}}},"FileDownloadRequest":{"type":"object","description":"Request for file download with custom filename","required":["file_name"],"properties":{"file_name":{"type":"string","description":"The custom filename to use for download"}}},"FileInfo":{"type":"object","required":["name","path_uri","is_file","size","last_modified","progress"],"properties":{"is_file":{"type":"boolean"},"last_modified":{"type":"integer","format":"int64"},"name":{"type":"string"},"path_uri":{"type":"string"},"progress":{"type":"number","format":"float"},"size":{"type":"integer","format":"int64","minimum":0}}},"FileUploadResponse":{"type":"object","description":"Response for file upload","required":["file_hash","message"],"properties":{"file_hash":{"type":"string","description":"The file hash"},"message":{"type":"string","description":"Message indicating success"}}},"FlistBody":{"type":"object","required":["image_name"],"properties":{"auth":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"identity_token":{"type":"string","nullable":true},"image_name":{"type":"string","example":"redis"},"password":{"type":"string","nullable":true},"registry_token":{"type":"string","nullable":true},"server_address":{"type":"string","nullable":true},"username":{"type":"string","nullable":true}}},"FlistState":{"oneOf":[{"type":"object","title":"FlistStateAccepted","required":["Accepted"],"properties":{"Accepted":{"type":"string"}}},{"type":"object","title":"FlistStateStarted","required":["Started"],"properties":{"Started":{"type":"string"}}},{"type":"object","title":"FlistStateInProgress","required":["InProgress"],"properties":{"InProgress":{"$ref":"#/components/schemas/FlistStateInfo"}}},{"type":"object","title":"FlistStateCreated","required":["Created"],"properties":{"Created":{"type":"string"}}},{"type":"string","title":"FlistStateFailed","enum":["Failed"]}]},"FlistStateInfo":{"type":"object","required":["msg","progress"],"properties":{"msg":{"type":"string"},"progress":{"type":"number","format":"float"}}},"FlistStateResponse":{"type":"object","required":["flist_state"],"properties":{"flist_state":{"$ref":"#/components/schemas/FlistState"}}},"HealthResponse":{"type":"object","required":["msg"],"properties":{"msg":{"type":"string"}}},"Job":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}},"ListBlocksParams":{"type":"object","description":"Query parameters for listing blocks","properties":{"page":{"type":"integer","format":"int32","description":"Page number (1-indexed)","default":1,"nullable":true,"minimum":1},"per_page":{"type":"integer","format":"int32","description":"Number of items per page","default":50,"nullable":true,"maximum":100,"minimum":1}}},"ListBlocksResponse":{"type":"object","description":"Response for listing blocks","required":["blocks","total","page","per_page"],"properties":{"blocks":{"type":"array","items":{"type":"string"},"description":"List of block hashes"},"page":{"type":"integer","format":"int32","description":"Current page number","minimum":0},"per_page":{"type":"integer","format":"int32","description":"Number of items per page","minimum":0},"total":{"type":"integer","format":"int64","description":"Total number of blocks","minimum":0}}},"PreviewResponse":{"type":"object","required":["content","metadata","checksum"],"properties":{"checksum":{"type":"string"},"content":{"type":"array","items":{"type":"string"}},"metadata":{"type":"string"}}},"ResponseError":{"oneOf":[{"type":"string","title":"ResponseErrorInternalServerError","enum":["InternalServerError"]},{"type":"object","title":"ResponseErrorConflict","required":["Conflict"],"properties":{"Conflict":{"type":"string"}}},{"type":"object","title":"ResponseErrorNotFound","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","title":"ResponseErrorUnauthorized","required":["Unauthorized"],"properties":{"Unauthorized":{"type":"string"}}},{"type":"object","title":"ResponseErrorBadRequest","required":["BadRequest"],"properties":{"BadRequest":{"type":"string"}}},{"type":"object","title":"ResponseErrorForbidden","required":["Forbidden"],"properties":{"Forbidden":{"type":"string"}}},{"type":"object","title":"ResponseErrorTemplateError","required":["TemplateError"],"properties":{"TemplateError":{"$ref":"#/components/schemas/ErrorTemplate"}}}]},"ResponseResult":{"oneOf":[{"type":"string","title":"ResponseResultHealth","enum":["Health"]},{"type":"object","title":"ResponseResultFlistCreated","required":["FlistCreated"],"properties":{"FlistCreated":{"$ref":"#/components/schemas/Job"}}},{"type":"object","title":"ResponseResultFlistState","required":["FlistState"],"properties":{"FlistState":{"$ref":"#/components/schemas/FlistState"}}},{"type":"object","title":"ResponseResultFlists","required":["Flists"],"properties":{"Flists":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/FileInfo"}}}}},{"type":"object","title":"ResponseResultPreviewFlist","required":["PreviewFlist"],"properties":{"PreviewFlist":{"$ref":"#/components/schemas/PreviewResponse"}}},{"type":"object","title":"ResponseResultSignedIn","required":["SignedIn"],"properties":{"SignedIn":{"$ref":"#/components/schemas/SignInResponse"}}},{"type":"object","title":"ResponseResultDirTemplate","required":["DirTemplate"],"properties":{"DirTemplate":{"$ref":"#/components/schemas/DirListTemplate"}}},{"type":"object","title":"ResponseResultBlockUploaded","required":["BlockUploaded"],"properties":{"BlockUploaded":{"type":"string"}}},{"type":"object","title":"ResponseResultFileUploaded","required":["FileUploaded"],"properties":{"FileUploaded":{"$ref":"#/components/schemas/FileUploadResponse"}}},{"type":"object","title":"ResponseResultRes","required":["Res"],"properties":{"Res":{"type":"string","format":"binary"}}}]},"SignInBody":{"type":"object","required":["username","password"],"properties":{"password":{"type":"string"},"username":{"type":"string"}}},"SignInResponse":{"type":"object","required":["access_token"],"properties":{"access_token":{"type":"string"}}},"TemplateErr":{"oneOf":[{"type":"object","title":"TemplateErrBadRequest","required":["BadRequest"],"properties":{"BadRequest":{"type":"string"}}},{"type":"object","title":"TemplateErrNotFound","required":["NotFound"],"properties":{"NotFound":{"type":"string"}}},{"type":"object","title":"TemplateErrInternalServerError","required":["InternalServerError"],"properties":{"InternalServerError":{"type":"string"}}}]},"UploadBlockParams":{"type":"object","description":"Query parameters for uploading a block","required":["file_hash","idx"],"properties":{"file_hash":{"type":"string","description":"File hash associated with the block"},"idx":{"type":"integer","format":"int64","description":"Block index within the file","minimum":0}}},"UserBlocksResponse":{"type":"object","description":"Response for user blocks endpoint","required":["blocks","total","all_blocks"],"properties":{"all_blocks":{"type":"integer","format":"int64","description":"Total number of all blocks","minimum":0},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/BlockInfo"},"description":"List of blocks with their indices"},"total":{"type":"integer","format":"int64","description":"Total number of blocks","minimum":0}}},"VerifyBlock":{"type":"object","description":"Request to verify if multiple blocks exist on the server","required":["block_hash","file_hash","block_index"],"properties":{"block_hash":{"type":"string","description":"Block hash to verify"},"block_index":{"type":"integer","format":"int64","description":"Block index within the file","minimum":0},"file_hash":{"type":"string","description":"File hash associated with the block"}}},"VerifyBlocksRequest":{"type":"object","required":["blocks"],"properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/VerifyBlock"},"description":"List of blocks to verify"}}},"VerifyBlocksResponse":{"type":"object","description":"Response with list of missing blocks","required":["missing"],"properties":{"missing":{"type":"array","items":{"type":"string"},"description":"List of block hashes that are missing on the server"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"System","description":"System health and status"},{"name":"Authentication","description":"Authentication endpoints"},{"name":"Flist Management","description":"Flist creation and management"},{"name":"Block Management","description":"Block storage and retrieval"},{"name":"File Management","description":"File upload and download"},{"name":"Website Serving","description":"Website content serving"}]}