Armando Montanez | 28698d0 | 2021-08-11 12:19:40 -0700 | [diff] [blame] | 1 | // Copyright 2021 The Pigweed Authors |
| 2 | // |
| 3 | // Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| 4 | // use this file except in compliance with the License. You may obtain a copy of |
| 5 | // the License at |
| 6 | // |
| 7 | // https://www.apache.org/licenses/LICENSE-2.0 |
| 8 | // |
| 9 | // Unless required by applicable law or agreed to in writing, software |
| 10 | // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| 11 | // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| 12 | // License for the specific language governing permissions and limitations under |
| 13 | // the License. |
| 14 | |
| 15 | syntax = "proto3"; |
| 16 | |
| 17 | package pw.file; |
| 18 | |
| 19 | import "pw_protobuf_protos/common.proto"; |
| 20 | |
| 21 | option java_outer_classname = "File"; |
| 22 | |
| 23 | // The FileSystem RPC service is used to enumerate and manage files present on a |
| 24 | // server. |
| 25 | service FileSystem { |
| 26 | // Returns a series of file paths with associated metadata for all immediate |
| 27 | // children of the provided path. |
| 28 | rpc List(ListRequest) returns (stream ListResponse) {} |
| 29 | |
| 30 | // Deletes the file at the requested path. |
| 31 | rpc Delete(DeleteRequest) returns (pw.protobuf.Empty) {} |
| 32 | } |
| 33 | |
| 34 | // A ListRequest has the following properties: |
| 35 | // |
| 36 | // - A request with an empty `path` string is valid and will list the contents |
| 37 | // at the "root" directory. |
| 38 | // - Only exact path matches will be resolved (i.e. no prefix matching). |
| 39 | // - Paths should be treated as case-sensitive. |
| 40 | // - The provided path must be absolute. If no matching path is found, a |
| 41 | // NOT_FOUND error is raised. |
| 42 | message ListRequest { |
| 43 | string path = 1; |
| 44 | } |
| 45 | |
| 46 | // A DeleteRequest has the following properties: |
| 47 | // |
| 48 | // - Only exact path matches will be resolved (i.e. no prefix matching). |
| 49 | // - Paths should be treated as case-sensitive. |
| 50 | // - Deletion of directories is implementation-defined, and may be |
| 51 | // disallowed and return an UNIMPLEMENTED error. |
| 52 | // - The provided path must be absolute. If no matching path is found, a |
| 53 | // NOT_FOUND error is raised. |
| 54 | message DeleteRequest { |
| 55 | string path = 1; |
| 56 | } |
| 57 | |
| 58 | message Path { |
| 59 | // This enum is a bitmask of permissions: |
| 60 | // Bit 0: readable. |
| 61 | // Bit 1: writable. |
| 62 | enum Permissions { |
| 63 | NONE = 0; |
| 64 | READ = 1; |
| 65 | WRITE = 2; |
| 66 | READ_AND_WRITE = 3; |
| 67 | } |
| 68 | |
| 69 | // A path to a file/directory. This path is relative to the requested path |
| 70 | // to reduce transmission of redundant information. |
| 71 | string path = 1; |
| 72 | |
| 73 | // Permitted operations on this path. |
| 74 | optional Permissions permissions = 2; |
| 75 | |
| 76 | // The size of the file at this path. |
| 77 | optional uint32 size_bytes = 3; |
| 78 | |
| 79 | // A globally-unique transfer ID for this file path (e.g. for use with |
| 80 | // pw_transfer's RPC service). It is implementation defined whether a file's |
| 81 | // file ID is stable or ephemeral. |
| 82 | optional uint32 file_id = 4; |
| 83 | } |
| 84 | |
| 85 | message ListResponse { |
| 86 | // Each returned Path's path name is always relative to the requested path to |
| 87 | // reduce transmission of redundant information. |
| 88 | repeated Path paths = 1; |
| 89 | } |