wehub-resource-sync
313 lines
9.0 KiB
YAML
313 lines
9.0 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: envd
|
|
version: 0.1.3
|
|
description: API for managing files' content and controlling envd
|
|
|
|
tags:
|
|
- name: files
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
summary: Check the health of the service
|
|
responses:
|
|
'204':
|
|
description: The service is healthy
|
|
|
|
/metrics:
|
|
get:
|
|
summary: Get the stats of the service
|
|
security:
|
|
- AccessTokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
description: The resource usage metrics of the service
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Metrics'
|
|
|
|
/init:
|
|
post:
|
|
summary: Set initial vars, ensure the time and metadata is synced with the host
|
|
security:
|
|
- AccessTokenAuth: []
|
|
- {}
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
hyperloopIP:
|
|
type: string
|
|
description: IP address of the hyperloop server to connect to
|
|
envVars:
|
|
$ref: '#/components/schemas/EnvVars'
|
|
accessToken:
|
|
type: string
|
|
description: Access token for secure access to envd service
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
description: The current timestamp in RFC3339 format
|
|
defaultUser:
|
|
type: string
|
|
description: The default user to use for operations
|
|
defaultWorkdir:
|
|
type: string
|
|
description: The default working directory to use for operations
|
|
responses:
|
|
'204':
|
|
description: Env vars set, the time and metadata is synced with the host
|
|
|
|
/envs:
|
|
get:
|
|
summary: Get the environment variables
|
|
security:
|
|
- AccessTokenAuth: []
|
|
- {}
|
|
responses:
|
|
'200':
|
|
description: Environment variables
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EnvVars'
|
|
|
|
/files:
|
|
get:
|
|
summary: Download a file
|
|
tags: [files]
|
|
security:
|
|
- AccessTokenAuth: []
|
|
- {}
|
|
parameters:
|
|
- $ref: '#/components/parameters/FilePath'
|
|
- $ref: '#/components/parameters/User'
|
|
- $ref: '#/components/parameters/Signature'
|
|
- $ref: '#/components/parameters/SignatureExpiration'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/DownloadSuccess'
|
|
'401':
|
|
$ref: '#/components/responses/InvalidUser'
|
|
'400':
|
|
$ref: '#/components/responses/InvalidPath'
|
|
'404':
|
|
$ref: '#/components/responses/FileNotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
post:
|
|
summary: Upload a file and ensure the parent directories exist. If the file exists, it will be overwritten.
|
|
description: |
|
|
Any request header of the form `X-Metadata-<key>: <value>` is persisted
|
|
as a user-defined extended attribute on the uploaded file. The
|
|
`X-Metadata-` prefix is stripped and the remaining header name is
|
|
lowercased to form the metadata key; the resulting map is returned on
|
|
`EntryInfo` lookups (e.g. `Stat`, `ListDir`).
|
|
|
|
Each upload replaces the file's metadata with the keys provided in
|
|
that request: keys previously stored but absent from the new request
|
|
are removed, and an upload that sends no `X-Metadata-*` header clears
|
|
all existing metadata.
|
|
|
|
Both keys and values must be printable US-ASCII (bytes `0x20`-`0x7E`)
|
|
and are rejected with HTTP 400 otherwise. Each key is capped at 246
|
|
bytes (the Linux VFS xattr-name limit minus the namespace prefix), and
|
|
the combined size of all metadata on a file (keys plus values, with the
|
|
namespace prefix counted per key) is capped at 4096 bytes to stay within
|
|
the filesystem's per-inode xattr budget. Multiple files in a single
|
|
multipart upload receive the same metadata. If the same
|
|
`X-Metadata-<key>` header is sent more than once, only the first
|
|
value is used.
|
|
tags: [files]
|
|
security:
|
|
- AccessTokenAuth: []
|
|
- {}
|
|
parameters:
|
|
- $ref: '#/components/parameters/FilePath'
|
|
- $ref: '#/components/parameters/User'
|
|
- $ref: '#/components/parameters/Signature'
|
|
- $ref: '#/components/parameters/SignatureExpiration'
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/File'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/UploadSuccess'
|
|
'400':
|
|
$ref: '#/components/responses/InvalidPath'
|
|
'401':
|
|
$ref: '#/components/responses/InvalidUser'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
'507':
|
|
$ref: '#/components/responses/NotEnoughDiskSpace'
|
|
|
|
components:
|
|
securitySchemes:
|
|
AccessTokenAuth:
|
|
type: apiKey
|
|
scheme: header
|
|
name: X-Access-Token
|
|
|
|
parameters:
|
|
FilePath:
|
|
name: path
|
|
in: query
|
|
required: false
|
|
description: Path to the file, URL encoded. Can be relative to user's home directory.
|
|
schema:
|
|
type: string
|
|
User:
|
|
name: username
|
|
in: query
|
|
required: false
|
|
description: User used for setting the owner, or resolving relative paths.
|
|
schema:
|
|
type: string
|
|
Signature:
|
|
name: signature
|
|
in: query
|
|
required: false
|
|
description: Signature used for file access permission verification.
|
|
schema:
|
|
type: string
|
|
SignatureExpiration:
|
|
name: signature_expiration
|
|
in: query
|
|
required: false
|
|
description: Signature expiration used for defining the expiration time of the signature.
|
|
schema:
|
|
type: integer
|
|
|
|
requestBodies:
|
|
File:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
|
|
responses:
|
|
UploadSuccess:
|
|
description: The file was uploaded successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/EntryInfo'
|
|
|
|
DownloadSuccess:
|
|
description: Entire file downloaded successfully.
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
description: The file content
|
|
InvalidPath:
|
|
description: Invalid path
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
InternalServerError:
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
FileNotFound:
|
|
description: File not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
InvalidUser:
|
|
description: Invalid user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
NotEnoughDiskSpace:
|
|
description: Not enough disk space
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
schemas:
|
|
Error:
|
|
required:
|
|
- message
|
|
- code
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Error message
|
|
code:
|
|
type: integer
|
|
description: Error code
|
|
EntryInfo:
|
|
required:
|
|
- path
|
|
- name
|
|
- type
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: Path to the file
|
|
name:
|
|
type: string
|
|
description: Name of the file
|
|
type:
|
|
type: string
|
|
description: Type of the file
|
|
enum:
|
|
- file
|
|
metadata:
|
|
type: object
|
|
description: User-defined metadata stored as extended attributes on the file.
|
|
additionalProperties:
|
|
type: string
|
|
EnvVars:
|
|
type: object
|
|
description: Environment variables to set
|
|
additionalProperties:
|
|
type: string
|
|
Metrics:
|
|
type: object
|
|
description: Resource usage metrics
|
|
properties:
|
|
ts:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp in UTC for current sandbox time
|
|
cpu_count:
|
|
type: integer
|
|
description: Number of CPU cores
|
|
cpu_used_pct:
|
|
type: number
|
|
format: float
|
|
description: CPU usage percentage
|
|
mem_total:
|
|
type: integer
|
|
description: Total virtual memory in bytes
|
|
mem_used:
|
|
type: integer
|
|
description: Used virtual memory in bytes
|
|
disk_used:
|
|
type: integer
|
|
description: Used disk space in bytes
|
|
disk_total:
|
|
type: integer
|
|
description: Total disk space in bytes
|