• Home
/
• Modules /
• pw_file

pw_file

Attention

pw_file is under construction, and may see significant breaking API changes.

The pw_file module defines a service for file system-like interactions between a client and server. FileSystem services may be backed by true file systems, or by virtual file systems that provide a file-system like interface with no true underlying file system.

pw_file does not define a protocol for file transfers. pw_transfer provides a generalized mechanism for performing file transfers, and is recommended to be used in tandem with pw_file.

RPC service

The FileSystem RPC service is oriented to allow direct interaction, and has no sequenced protocol. Unlike FTP, all interactions are stateless. This service also does not yet define any authentication mechanism, meaning that all clients that can access a FileSystem service are granted equal permissions.

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;
}

Flat FileSystem implementation

This module provides the FlatFileSystemService, an optional implementation of the FileSystem RPC service with a virtual interface that allows different data storage implementations to expose logical files. As the name implies, the file system is treated as a flat file system; it does not support any directory-like interactions.

The FlatFileSystemService implementation requires a static, fixed list of Entry pointers. Each Entry represents a potential file, and acts as an interface boundary that is backed by some kind of storage mechanism (e.g. BlobStore, PersistentBuffer).

All Entry objects that should be enumerated by a FlatFileSystemService MUST be named, and names must be globally unique to prevent ambiguity. Unnamed file entries will NOT be enumerated by a FlatFileSystemService, and are considered empty/deleted files. It is valid to have empty files that are enumerated with a name.

FlatFileSystemService requires two buffers at construction: one buffer for reading file names and another for encoding protobuf responses. The recommended encoding buffer size for a particular maximum file name length can be calculated with EncodingBufferSizeBytes. For convenience, the FlatFileSystemServiceWithBuffer<kMaxFileNameLength> class is provided. That class creates a FlatFileSystemService with a buffer automatically sized based on the maximum file name length.