Idea: LIST/GLOB — enumerate guest files without shelling out

Abierto
  • ¿Algo no está bien?
#74 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
go
Área
api, backend

Línea de trabajo

Start by reading the existing message set and follow-up issue #72 before deciding whether this belongs in a new RPC or an optional surface. The work would include the proto, guest implementation, and an e2e test; done means single-directory listing supports optional globbing, deterministic name ordering, pagination, and the specified file metadata.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement
Problem

There is no primitive for directory enumeration on the guest filesystem. Clients that need to discover files must either exec a shell (ls/find), which couples clients to guest shell semantics and bypasses structured errors and accounting, or maintain client-side ledgers that drift from actual filesystem state.

Follow-up from #72: append makes segmented, append-only logs viable inside guests; enumeration is the complementary half of that workload. Our concrete case: agents write rotating segment files (seg.0.jsonl, seg.1.jsonl, …), and a host-side poller needs to enumerate segments it hasn't read. This generalizes to checkpoint discovery, temp-file cleanup passes, and any "what exists in this directory" query.

Proposal

Additive RPC (or an optional surface on the existing message set), single-directory scope for v1:

message ListFilesRequest {
  string path = 1;      // directory to list
  string pattern = 2;   // optional glob, e.g. "seg.*.jsonl"
  int32 limit = 3;      // page size
  string page_token = 4;
}
message ListFilesResponse {
  repeated FileEntry entries = 1;
  string next_page_token = 2;
}
message FileEntry {
  string name = 1;
  int64 size = 2;
  google.protobuf.Timestamp modified = 3;
  uint32 mode = 4;
}
  • Deterministic ordering: entries sorted by name.
  • Pagination (limit/page_token) keeps large directories bounded.
  • Out of scope for v1: recursive walks; streaming/watch semantics — the fuller long-term answer for tailing workloads, but a substantially larger surface, worth discussing separately.
Alternatives considered
  • Exec find/ls in the guest — rejected: shell coupling, unstructured output and errors, no accounting.
  • Client-side segment ledgers — rejected: duplicate directory state, drifts from the filesystem, and must be reimplemented in every client.
  • ReadFile on directories — not meaningful under current read semantics; would overload the read path.

If this fits the project's direction, I'm glad to draft the PR — proto + guest implementation + e2e test, same shape as #72.

Lenguaje dominante
Go
Estrellas
71
Forks
17
Merge medio
21 h 36 min
PR fusionados (30 d)
19

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de agent-substrate/env

Todos los issues de agent-substrate/env

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.