pw_file

Pigweed AI summary: The pw_file module is currently under construction and may undergo significant API changes. It defines a service for file system-like interactions between a client and server, which can be backed by true or virtual file systems. However, it does not define a protocol for file transfers, and it is recommended to use the pw_transfer module in tandem with pw_file. The FileSystem RPC service allows direct interaction and has no sequenced protocol, but it does not yet define any authentication mechanism. The FlatFileSystemService is an optional

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

Pigweed AI summary: The FileSystem RPC service allows for direct interaction with no sequenced protocol and no authentication mechanism, granting equal permissions to all clients. It is used to enumerate and manage files on a server, with List and Delete requests available. The ListRequest and DeleteRequest messages have specific properties, and the Path message includes information on permissions, size, and file ID. The ListResponse message returns a list of paths with associated metadata.

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

Pigweed AI summary: The Flat FileSystem implementation module provides the FlatFileSystemService, which is an optional implementation of the FileSystem RPC service. It has a virtual interface that allows different data storage implementations to expose logical files. However, it treats the file system as a flat file system and does not support any directory-like interactions. The implementation requires a static, fixed list of Entry pointers, where each Entry represents a potential file and acts as an interface boundary backed by some storage mechanism. All Entry objects that should be enumerated by the Flat

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.