/v1/files
This page describes /v1/files on the node data plane. Its parameter names and limits are generated from the constants the Kibotos code implements it with.
Reads and writes the content of one file in the guest. Directories and metadata go through FilesystemService, and paths follow its rules: absolute, or relative to the home directory of the identity user selects.
Credential
Authorization: Bearer <credential>, with the credential of a data-plane session that has the scope the method needs.
Methods
| Method | Scope | Description |
|---|---|---|
GET | DATA_PLANE_SCOPE_FILE_READ | Reads the file. A single Range: bytes=… range, including one that counts from the end such as bytes=-500, answers 206 with Content-Range; several ranges answer 400 and a range beyond the file answers 416. If-Range is forwarded to the guest unchanged. The response carries Content-Type, Content-Length, Content-Range, Accept-Ranges, ETag and Last-Modified; ETag is an opaque string. |
PUT | DATA_PLANE_SCOPE_FILE_WRITE | Writes the file from the request body. 200 means the file is on storage; the body reports what was written. A read-only directory answers 403 and an exhausted file system or quota answers 413, also for root; neither is retryable, and a file already at the path stays unchanged. |
Query parameters
| Parameter | Methods | Required | Description |
|---|---|---|---|
path | GET, PUT | Yes | The file: an absolute path in the guest, or a path relative to the home directory of user. |
user | GET, PUT | The guest identity the request runs as: empty for the account the Template declares, that account's name, or root. | |
mode | PUT | The permissions of a new file, in octal with permission bits only, such as 0644. Defaults to 0600. | |
create_only | PUT | true or 1 fails the request when the file exists; false, 0 or no value overwrites it. |
Any other parameter, a parameter given twice, an invalid value, and mode or create_only on GET answer 400 (invalid_argument) before the request reaches the guest.
Bodies
PUT result
The body of a successful PUT. Compare the size and digest with what you sent.
| Field | Type | Description |
|---|---|---|
path | string | The cleaned absolute path written. |
size_bytes | number | The number of bytes written. |
sha256 | string | The SHA-256 digest of the bytes written, in lowercase hexadecimal. |
Error body
The body of every error response, with Content-Type: application/json.
| Field | Type | Description |
|---|---|---|
code | string | The name of the Connect error code, such as not_found. |
detail | object | The ErrorDetail of the error in protobuf JSON, with the field names of the proto file. |
Status codes
| HTTP status | Connect error codes |
|---|---|
| 400 | invalid_argument |
| 401 | unauthenticated |
| 403 | permission_denied |
| 404 | not_found |
| 405 | unimplemented |
| 409 | already_exists, failed_precondition, aborted |
| 413 | resource_exhausted |
| 499 | canceled |
| 500 | unknown, out_of_range, internal, data_loss |
| 503 | unavailable |
| 504 | deadline_exceeded |
An unsatisfiable range answers 416 with Content-Range: bytes */<size>.
A request whose body stalls for longer than the progress timeout answers 408.
Methods other than GET and PUT answer 405.
Limits
| Limit | Value | Description |
|---|---|---|
| Bytes per request | 1 GiB | The bytes of one GET response or PUT body. Read a larger file with several Range requests. |
| Rate | 64 MiB/s | The transfer rate of one request. |
| Burst | 1 MiB | The bytes one request may transfer above the rate at once. |
| Progress timeout | 5 s | How long the caller may send no request body, or read no response, before the node ends the request. Time the node spends waiting for the guest does not count. |
See also
EnrollmentService
This page lists the methods of EnrollmentService in kibotos.enrollment.v1 with the messages and enums each one uses, generated from enrollment.proto and its comments.
/v1/service
This page describes /v1/service on the node data plane. Its parameter names and limits are generated from the constants the Kibotos code implements it with.