fs

Documentation

Overview

Package fs implements a Gridwell plugin that projects a host directory tree. Each plugin instance has its own SQLite DB that maps directory paths to stable integer grid IDs and file/dir names to stable integer tile IDs. Positions (x,y,w,h) and well view framing are stored in the plugin DB so they survive restarts.

Index

• Constants
• func NewFactory(cfg map[string]string) (gridwellv1.GridwellServer, error)
• type Host
• type Plugin
  • func Open(dbPath string, host Host) (*Plugin, error)
  • func (p *Plugin) Close() error
  • func (p *Plugin) ContentBody(tileIDStr string) (data []byte, mediaType string, err error)
  • func (p *Plugin) CreateTile(_ context.Context, req *gridwellv1.CreateTileRequest) (*gridwellv1.TileResponse, error)
  • func (p *Plugin) DeleteTile(_ context.Context, req *gridwellv1.DeleteTileRequest) (*gridwellv1.DeleteTileResponse, error)
  • func (p *Plugin) GetGrid(_ context.Context, req *gridwellv1.GetGridRequest) (*gridwellv1.GetGridResponse, error)
  • func (p *Plugin) GetTile(_ context.Context, req *gridwellv1.GetTileRequest) (*gridwellv1.TileResponse, error)
  • func (p *Plugin) GetTilePreview(_ context.Context, req *gridwellv1.GetTilePreviewRequest) (*gridwellv1.GetTilePreviewResponse, error)
  • func (p *Plugin) Info(_ context.Context, _ *gridwellv1.InfoRequest) (*gridwellv1.InfoResponse, error)
  • func (p *Plugin) PlaceTile(_ context.Context, req *gridwellv1.PlaceTileRequest) (*gridwellv1.TileResponse, error)
  • func (p *Plugin) Probe(_ context.Context, req *gridwellv1.ProbeRequest) (*gridwellv1.ProbeResponse, error)
  • func (p *Plugin) ReadContent(req *gridwellv1.ReadContentRequest, ...) error
  • func (p *Plugin) ServeContent(req *gridwellv1.ServeContentRequest, ...) error
  • func (p *Plugin) SetReadDir(f func(dir string) ([]fssource.Entry, error))
  • func (p *Plugin) SetRoot(root string)
  • func (p *Plugin) SetRootView(_ context.Context, req *gridwellv1.SetRootViewRequest) (*gridwellv1.SetRootViewResponse, error)
  • func (p *Plugin) SetTile(_ context.Context, req *gridwellv1.SetTileRequest) (*gridwellv1.TileResponse, error)
  • func (p *Plugin) WriteContent(...) error

Constants

const MenuEntrySearch = "search"

MenuEntrySearch is the entry id fs declares (Tile.menu_entry carries it).

const SearchParamSchema = `` /* 128-byte string literal not displayed */

searchParamSchema is the #198-subset form the client prompts with on first descent. SearchParamSchema is exported for the v2 fs provider, which declares the same tool (one schema, two declarers until the legacy plugin dies).

Functions

func NewFactory

func NewFactory(cfg map[string]string) (gridwellv1.GridwellServer, error)

NewFactory is the compose.Factory for the "fs" kind: cfg is the ONE config vocabulary both process shapes share (the same map a subprocess reads from the spawn env). cfg["db_file"] is the plugin's SQLite DB; cfg["root"] the projected directory.

Types

type Host

type Host interface {
	Remove(path string) error
	RemoveAll(path string) error
}

Host is the destructive side-effect surface. Injected so tests never rm anything on disk. Production wires osHost; tests wire recordHost.

type Plugin

type Plugin struct {
	gridwellv1.UnimplementedGridwellServer
	// contains filtered or unexported fields
}

Plugin implements gridwellv1.GridwellServer for a filesystem source.

func Open

func Open(dbPath string, host Host) (*Plugin, error)

Open opens (or creates) the plugin SQLite DB at dbPath. A nil host uses plain os.Remove/os.RemoveAll.

func (*Plugin) Close

func (p *Plugin) Close() error

Close closes the underlying database.

func (*Plugin) ContentBody

func (p *Plugin) ContentBody(tileIDStr string) (data []byte, mediaType string, err error)

ContentBody returns the descent body for a file tile: real bytes for a renderable/plain file, the metadata summary otherwise (fsfile.Body owns the rule, shared with the v2 provider). Directories, unreadable paths, and unknown ids return empty content rather than an error.

func (*Plugin) CreateTile

func (p *Plugin) CreateTile(_ context.Context, req *gridwellv1.CreateTileRequest) (*gridwellv1.TileResponse, error)

CreateTile accepts exactly the tiles fs itself offers: a search well (menu_entry = "search"). Everything else stays refused — fs is a read-only projection; the entry declaration IS the permission.

func (*Plugin) DeleteTile

func (p *Plugin) DeleteTile(_ context.Context, req *gridwellv1.DeleteTileRequest) (*gridwellv1.DeleteTileResponse, error)

DeleteTile removes the file or directory from disk (via Host), then drops the tile row from the plugin DB.

func (*Plugin) GetGrid

func (p *Plugin) GetGrid(_ context.Context, req *gridwellv1.GetGridRequest) (*gridwellv1.GetGridResponse, error)

GetGrid reads the directory for the given grid_id, reconciles tile rows against the current directory contents, and returns the resulting tiles. A missing (definitively gone) directory returns an empty grid without error; a directory that exists but cannot be read this pass returns the stored rows untouched — see the sweep-policy split in the body.

func (*Plugin) GetTile

func (p *Plugin) GetTile(_ context.Context, req *gridwellv1.GetTileRequest) (*gridwellv1.TileResponse, error)

GetTile returns one tile row by id — cloneAcrossPlugins' first call against the source plugin when a tile is right-dragged into another plugin's grid (issue #171). The row was materialized by the GetGrid that rendered it.

func (*Plugin) GetTilePreview

func (p *Plugin) GetTilePreview(_ context.Context, req *gridwellv1.GetTilePreviewRequest) (*gridwellv1.GetTilePreviewResponse, error)

GetTilePreview serves a JPEG thumbnail for image file tiles. Non-image tiles (and undecodable files) return an empty preview, never an error — the client falls back to the label exactly as it does for a url tile with no capture yet.

func (*Plugin) Info

func (p *Plugin) Info(_ context.Context, _ *gridwellv1.InfoRequest) (*gridwellv1.InfoResponse, error)

Info is the whole handshake: identity plus the default root grid (the plugin's configured root directory, resolved to a grid id). No Attach/Detach.

func (*Plugin) PlaceTile

func (p *Plugin) PlaceTile(_ context.Context, req *gridwellv1.PlaceTileRequest) (*gridwellv1.TileResponse, error)

PlaceTile is the single placement writeback: in-grid only (a cross-grid placement would be an on-disk move, which fs does not perform).

func (*Plugin) Probe

func (p *Plugin) Probe(_ context.Context, req *gridwellv1.ProbeRequest) (*gridwellv1.ProbeResponse, error)

Probe checks whether the tile at tile_id still has its backing path on disk.

func (*Plugin) ReadContent

func (p *Plugin) ReadContent(req *gridwellv1.ReadContentRequest, stream grpc.ServerStreamingServer[gridwellv1.ContentChunk]) error

ReadContent streams a file tile's descent body (one chunk; fs bodies are small metadata summaries, version 0 — not version-edited). The one content read.

func (*Plugin) ServeContent

func (p *Plugin) ServeContent(req *gridwellv1.ServeContentRequest, stream grpc.ServerStreamingServer[gridwellv1.ServeContentChunk]) error

ServeContent streams a file's raw bytes as web content. subpath "" is the tile's own file; a non-empty subpath is a page-relative resource resolved against the file's directory (fsfile.ServeFile owns the confinement).

func (*Plugin) SetReadDir

func (p *Plugin) SetReadDir(f func(dir string) ([]fssource.Entry, error))

SetReadDir overrides the directory reader (a test seam, like the Host deletion surface). nil restores the default fssource.Read.

func (*Plugin) SetRoot

func (p *Plugin) SetRoot(root string)

SetRoot sets the configured default directory Info reports as the root when no path is supplied. Wired by NewFactory from config["root"].

func (*Plugin) SetRootView

func (p *Plugin) SetRootView(_ context.Context, req *gridwellv1.SetRootViewRequest) (*gridwellv1.SetRootViewResponse, error)

SetRootView persists the root grid's viewport (framing audit 2026-08-13: this was silently swallowed before — pan an fs root, gone on re-entry). Framing-class; the server routes here by root_grid_id.

func (*Plugin) SetTile

func (p *Plugin) SetTile(_ context.Context, req *gridwellv1.SetTileRequest) (*gridwellv1.TileResponse, error)

SetTile persists a directory well's preview framing so descent and ascent restore the same view. fs supports framing only on its directory wells; other kinds/writebacks are not applicable.

func (*Plugin) WriteContent

func (p *Plugin) WriteContent(stream grpc.ClientStreamingServer[gridwellv1.WriteContentRequest, gridwellv1.TileResponse]) error

WriteContent is fs's one write door — and it opens ONLY for the tiles fs itself minted: a search well's params commit (#258), which runs the snapshot and fills the child grid. Everything else stays refused (the projection is read-only; editing files is not fs's business).