syntax = "proto3";
package virtualfs;

message PathRequest {
  string path = 1;
}

message AttrResponse {
  uint64 size = 1;
  uint32 mode = 2; // Permissions and file type
  uint64 mtime = 3; // Modification time
  // ... other standard stat attributes
}

message DirEntry {
  string name = 1;
  uint32 type = 2; // File or Directory, mapping roughly to libc::DT_REG, libc::DT_DIR, etc.
}

message ReadRequest {
  string path = 1;
  uint64 offset = 2;
  uint32 size = 3;
  // Optional requested chunk size. If 0, the server uses its default chunk size.
  uint32 chunk_size = 4;
}

message FileChunk {
  bytes data = 1;
}

// ── Snapshot & watch ──────────────────────────────────────────────

// Request a pre-built snapshot of the directory tree up to `depth` levels.
// depth = 0 means only the requested path itself; depth = 1 includes immediate children, etc.
message SnapshotRequest {
  string path = 1;
  uint32 depth = 2;
}

// One directory's contents within a snapshot response.
message SnapshotEntry {
  string path = 1;
  repeated DirEntry children = 2;
}

// Subscribe to live filesystem change notifications (no parameters needed).
message WatchRequest {}

enum ChangeKind {
  CREATED = 0;
  DELETED = 1;
  MODIFIED = 2;
}

// Notifies the client that the contents of `path` have changed.
message ChangeEvent {
  string path = 1;
  ChangeKind kind = 2;
}

service RemoteFileSystem {
  // Get file or directory attributes (size, permissions, timestamps). Maps to stat/getattr.
  rpc GetAttr (PathRequest) returns (AttrResponse);

  // List directory contents. Uses Server Streaming to handle massively large directories efficiently.
  rpc ReadDir (PathRequest) returns (stream DirEntry);

  // Read chunks of a file. Uses Server Streaming for efficient chunk delivery based on offset/size.
  rpc ReadFile (ReadRequest) returns (stream FileChunk);

  // Return a pre-built in-memory snapshot of the directory tree rooted at `path`.
  // The server walks `depth` levels deep on its side — one round-trip fills the client cache.
  rpc GetSnapshot (SnapshotRequest) returns (stream SnapshotEntry);

  // Subscribe to live filesystem change events. The server pushes a ChangeEvent whenever
  // a directory's contents change, allowing the client to invalidate its cache immediately.
  rpc WatchChanges (WatchRequest) returns (stream ChangeEvent);
}