// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.

syntax = "proto3";

package pw.file;

import "pw_protobuf_protos/common.proto";

option java_outer_classname = "File";

// The FileSystem RPC service is used to enumerate and manage files present on a
// server.
service FileSystem {
  // Returns a series of file paths with associated metadata for all immediate
  // children of the provided path.
  rpc List(ListRequest) returns (stream ListResponse) {}

  // Deletes the file at the requested path.
  rpc Delete(DeleteRequest) returns (pw.protobuf.Empty) {}
}

// A ListRequest has the following properties:
//
//  - A request with an empty `path` string is valid and will list the contents
//    at the "root" directory.
//  - Only exact path matches will be resolved (i.e. no prefix matching).
//  - Paths should be treated as case-sensitive.
//  - The provided path must be absolute. If no matching path is found, a
//    NOT_FOUND error is raised.
message ListRequest {
  string path = 1;
}

// A DeleteRequest has the following properties:
//
//  - Only exact path matches will be resolved (i.e. no prefix matching).
//  - Paths should be treated as case-sensitive.
//  - Deletion of directories is implementation-defined, and may be
//    disallowed and return an UNIMPLEMENTED error.
//  - The provided path must be absolute. If no matching path is found, a
//    NOT_FOUND error is raised.
message DeleteRequest {
  string path = 1;
}

message Path {
  // This enum is a bitmask of permissions:
  // Bit 0: readable.
  // Bit 1: writable.
  enum Permissions {
    NONE = 0;
    READ = 1;
    WRITE = 2;
    READ_AND_WRITE = 3;
  }

  // A path to a file/directory. This path is relative to the requested path
  // to reduce transmission of redundant information.
  string path = 1;

  // Permitted operations on this path.
  optional Permissions permissions = 2;

  // The size of the file at this path.
  optional uint32 size_bytes = 3;

  // A globally-unique transfer ID for this file path (e.g. for use with
  // pw_transfer's RPC service). It is implementation defined whether a file's
  // file ID is stable or ephemeral.
  optional uint32 file_id = 4;
}

message ListResponse {
  // Each returned Path's path name is always relative to the requested path to
  // reduce transmission of redundant information.
  repeated Path paths = 1;
}