Pre-release. HostCraft is in testing and not yet for sale. These docs describe the current build and may change. Join the waitlist to hear when it launches.

Files API

Source: daemon/proto/hostcraft/v1/files.proto

FilesService

FilesService is the file manager. Every path is relative to the account's home directory and confined to it. account_id defaults to the caller's own account. REST: /api/v1/files.

Method	REST route	Permission	Streaming
`ListEntries`	`GET /api/v1/files/list`	`FilesList`	unary
`GetEntry`	`GET /api/v1/files/entry`	`FilesRead`	unary
`ReadFile`	`GET /api/v1/files/read`	`FilesRead`	unary
`WriteFile`	`POST /api/v1/files/write`	`FilesWrite`	unary
`MakeDirectory`	`POST /api/v1/files/mkdir`	`FilesWrite`	unary
`DeleteEntries`	`POST /api/v1/files/delete`	`FilesDelete`	unary
`MoveEntry`	`POST /api/v1/files/move`	`FilesMove`	unary
`CopyEntry`	`POST /api/v1/files/copy`	`FilesCopy`	unary
`Chmod`	`POST /api/v1/files/chmod`	`FilesChmod`	unary
`Chown`	`POST /api/v1/files/chown`	`FilesChown`	unary
`CreateArchive`	`POST /api/v1/files/archive/create`	`FilesArchive`	unary
`ExtractArchive`	`POST /api/v1/files/archive/extract`	`FilesArchive`	unary
`BeginUpload`	`POST /api/v1/files/upload/begin`	`FilesUpload`	unary
`AppendUpload`	`POST /api/v1/files/upload/{upload_id}/append`	`FilesUpload`	unary
`CompleteUpload`	`POST /api/v1/files/upload/{upload_id}/complete`	`FilesUpload`	unary
`DownloadFile`	`GET /api/v1/files/download`	`FilesDownload`	unary

ListEntries

/hostcraft.v1.FilesService/ListEntries

Request: ListEntriesRequest
Response: ListEntriesResponse

GetEntry

/hostcraft.v1.FilesService/GetEntry

Request: GetEntryRequest
Response: FileEntry

ReadFile

ReadFile returns a UTF-8 text range; binary files must use DownloadFile.

/hostcraft.v1.FilesService/ReadFile

Request: ReadFileRequest
Response: ReadFileResponse

WriteFile

/hostcraft.v1.FilesService/WriteFile

Request: WriteFileRequest
Response: FileEntryResponse

MakeDirectory

/hostcraft.v1.FilesService/MakeDirectory

Request: MakeDirectoryRequest
Response: FileEntryResponse

DeleteEntries

/hostcraft.v1.FilesService/DeleteEntries

Request: DeleteEntriesRequest
Response: DeleteEntriesResponse

MoveEntry

/hostcraft.v1.FilesService/MoveEntry

Request: MoveEntryRequest
Response: FileEntryResponse

CopyEntry

/hostcraft.v1.FilesService/CopyEntry

Request: CopyEntryRequest
Response: FileEntryResponse

Chmod

/hostcraft.v1.FilesService/Chmod

Request: ChmodRequest
Response: FileEntryResponse

Chown

/hostcraft.v1.FilesService/Chown

Request: ChownRequest
Response: FileEntryResponse

CreateArchive

/hostcraft.v1.FilesService/CreateArchive

Request: CreateArchiveRequest
Response: CreateArchiveResponse

ExtractArchive

/hostcraft.v1.FilesService/ExtractArchive

Request: ExtractArchiveRequest
Response: ExtractArchiveResponse

BeginUpload

BeginUpload, AppendUpload and CompleteUpload are the chunked upload protocol: begin returns an upload id, append sends chunks at increasing offsets, complete verifies the optional SHA-256 and moves the file into place.

/hostcraft.v1.FilesService/BeginUpload

Request: BeginUploadRequest
Response: BeginUploadResponse

AppendUpload

/hostcraft.v1.FilesService/AppendUpload

Request: AppendUploadRequest
Response: AppendUploadResponse

CompleteUpload

/hostcraft.v1.FilesService/CompleteUpload

Request: CompleteUploadRequest
Response: FileEntryResponse

DownloadFile

DownloadFile returns the whole file in one message (up to 256 MiB; raise the client's max receive size for files over 4 MiB).

/hostcraft.v1.FilesService/DownloadFile

Request: DownloadFileRequest
Response: DownloadFileResponse

Messages

AppendUploadRequest

Field	Type	Number	Description
`upload_id`	`string`	1	-
`offset`	`int64`	2	-
`chunk`	`bytes`	3	-

AppendUploadResponse

Field	Type	Number	Description
`bytes_received`	`int64`	1	-

BeginUploadRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`target_path`	`string`	2	-
`total_size`	`int64`	3	-
`mode`	`uint32`	4	-
`overwrite`	`bool`	5	-

BeginUploadResponse

Field	Type	Number	Description
`upload_id`	`string`	1	-
`chunk_size_hint`	`int64`	2	-

ChmodRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`mode`	`uint32`	3	-
`recursive`	`bool`	4	-

ChownRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`user`	`string`	3	-
`group`	`string`	4	-
`recursive`	`bool`	5	-

CompleteUploadRequest

Field	Type	Number	Description
`upload_id`	`string`	1	-
`sha256_hex`	`string`	2	-

CopyEntryRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`from`	`string`	2	-
`to`	`string`	3	-
`overwrite`	`bool`	4	-
`recursive`	`bool`	5	-

CreateArchiveRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`paths`	`repeated string`	2	-
`format`	`string`	3	zip \| tar \| tar_gz
`output_path`	`string`	4	-
`overwrite`	`bool`	5	-

CreateArchiveResponse

Field	Type	Number	Description
`entry`	`FileEntry`	1	-
`size_bytes`	`int64`	2	-

DeleteEntriesRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`paths`	`repeated string`	2	-
`recursive`	`bool`	3	-

DeleteEntriesResponse

Field	Type	Number	Description
`deleted_count`	`int64`	1	-

DownloadFileRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-

DownloadFileResponse

Field	Type	Number	Description
`content`	`bytes`	1	-

ExtractArchiveRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`target_dir`	`string`	3	-
`overwrite`	`bool`	4	-

ExtractArchiveResponse

Field	Type	Number	Description
`extracted_count`	`int64`	1	-
`target_dir`	`string`	2	-

FileEntry

Field	Type	Number	Description
`path`	`string`	1	-
`name`	`string`	2	-
`kind`	`string`	3	file \| directory \| symlink
`size_bytes`	`int64`	4	-
`mode`	`uint32`	5	-
`owner`	`string`	6	-
`group`	`string`	7	-
`modified_at`	`google.protobuf.Timestamp`	8	-
`symlink_target`	`string`	9	-
`is_hidden`	`bool`	10	-

FileEntryResponse

Field	Type	Number	Description
`entry`	`FileEntry`	1	-

GetEntryRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-

ListEntriesRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	default /
`recursive`	`bool`	3	-
`glob`	`string`	4	-

ListEntriesResponse

Field	Type	Number	Description
`entries`	`repeated FileEntry`	1	-

MakeDirectoryRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`mode`	`uint32`	3	-
`parents`	`bool`	4	-

MoveEntryRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`from`	`string`	2	-
`to`	`string`	3	-
`overwrite`	`bool`	4	-

ReadFileRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`offset`	`int64`	3	-
`length`	`int64`	4	-

ReadFileResponse

Field	Type	Number	Description
`content`	`string`	1	-
`total_size_bytes`	`int64`	2	-
`eof`	`bool`	3	-

WriteFileRequest

Field	Type	Number	Description
`account_id`	`string`	1	-
`path`	`string`	2	-
`content`	`string`	3	-
`mode`	`uint32`	4	-
`create_only`	`bool`	5	-