From 882fc598d4259fc1888ae28866297d36bf3e2c5a Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Tue, 4 Aug 2026 12:02:32 +0200 Subject: [PATCH] Extract EDSL to fsedsl/ library - Create fsedsl/ as embedded library with generic types: - FsNodeDecl[Ctx], Binding[Ctx], NodeOption[Ctx] - BuildTree[Ctx], GenerateHelp[Ctx] - Tree, File, FileConfig, SyntheticFileInfo - Update ollie/fs to use fsedsl via type aliases: - type FsNodeDecl = fsedsl.FsNodeDecl[HandlerCtx] - Wrapper functions for constructors and options - Migrate binding functions to Applier pattern: - Binding.Applier replaces direct field assignment - Cleanly separates EDSL mechanics from domain types - Add replace directive in go.mod for local module The library can be extracted to a separate repo later by changing the module path and removing the replace directive. --- fs/edsl.go | 253 +++++++------- fs/handlers.go | 101 ++---- fsedsl/LICENSE.md | 675 ++++++++++++++++++++++++++++++++++++++ fsedsl/README.md | 127 +++++++ {fs => fsedsl}/builder.go | 93 ++---- fsedsl/decl.go | 224 +++++++++++++ fsedsl/decl_test.go | 295 +++++++++++++++++ {fs => fsedsl}/file.go | 21 +- fsedsl/go.mod | 3 + fsedsl/help.go | 71 ++++ {fs => fsedsl}/tree.go | 28 +- go.mod | 3 + 12 files changed, 1592 insertions(+), 302 deletions(-) create mode 100644 fsedsl/LICENSE.md create mode 100644 fsedsl/README.md rename {fs => fsedsl}/builder.go (82%) create mode 100644 fsedsl/decl.go create mode 100644 fsedsl/decl_test.go rename {fs => fsedsl}/file.go (92%) create mode 100644 fsedsl/go.mod create mode 100644 fsedsl/help.go rename {fs => fsedsl}/tree.go (94%) diff --git a/fs/edsl.go b/fs/edsl.go index 1d20ac9..60d5bbc 100644 --- a/fs/edsl.go +++ b/fs/edsl.go @@ -1,11 +1,16 @@ package fs +// This file provides type aliases and wrappers that instantiate the generic +// fsedsl types with ollie's HandlerCtx. This allows the fs package to use +// the generic EDSL library while maintaining backward compatibility. + import ( "context" "os" "ollie/agent" "ollie/elevate" + "ollie/fsedsl" olog "ollie/log" "ollie/skills" "ollie/toolsrv" @@ -42,188 +47,180 @@ type HandlerCtx struct { // BlockFn is the signature for blocking/streaming reads. type BlockFn func(ctx context.Context, base string) ([]byte, string, error) -// Structural permissions — used by Tree for mounted children and synthetic files. -const ( - PermChildDir os.FileMode = 0555 - PermIdx os.FileMode = 0444 - PermMkdir os.FileMode = 0755 - PermMkdirPrivate os.FileMode = 0700 -) - -// BindingFn returns the bindings for Each to iterate over. -type BindingFn func(ctx HandlerCtx) ([]Binding, error) - -// Binding provides identity and data for one iteration of Each. -// The structure is cloned for each binding, and handlers receive -// the bound data via ctx.Session, ctx.Agent, or ctx.AgentLog. -type Binding struct { - Name string // directory name (e.g. session name, agent name) - Aliases []string // alternate lookup names (e.g. immutable ID) - UID string // owner (empty = inherit) - GID string // group (empty = inherit) - - // Bound data — handlers access via ctx.Session/Agent/AgentLog/Data. - Session *Session - Agent *agent.Agent - AgentLog *AgentLog - Data any // generic binding for domain-specific data - - // Lifecycle callbacks. - Remove func() - Rename func(string) error -} - -// BindTarget declares what data an Each block binds to handlers. -type BindTarget int - -const ( - BindSession BindTarget = iota - BindAgent - BindAgentLog - BindData - BindRemove - BindRename -) +// ── Type aliases from fsedsl ───────────────────────────────────── // FsNodeDecl describes one node in the 9P namespace. -// The entire filesystem is a single recursive tree of these. -type FsNodeDecl struct { - // Identity. - Name string - Aliases []string // alternate names that resolve to this node (e.g. immutable ID) - UID string // "" = inherit from parent - GID string // "" = inherit from parent - Mode os.FileMode // 0 = inherit parent default - Desc string // human-readable description - - // Tstat — metadata override (non-nil bypasses Name/UID/GID/Mode/size defaulting). - Stat func() os.FileInfo - - // Twalk — children (implies directory; at most one set). - Children []FsNodeDecl // static, known at compile time - Bindings func(HandlerCtx) ([]Binding, error) // Each bindings - BindTargets []BindTarget // declares what Bindings provides - - // Tread (non-blocking) + Twrite. - Read func(ctx HandlerCtx) ([]byte, error) - Write func(ctx HandlerCtx, data []byte) error - - // Tread — blocking variants (at most one set). - BlockOnce func(ctx HandlerCtx, cctx context.Context, base string) ([]byte, string, error) - Stream func(ctx HandlerCtx, cctx context.Context, base string) ([]byte, string, error) - - // Request — rdwr: write triggers result, read returns it once. - Request func(ctx HandlerCtx, data []byte) ([]byte, error) - - // Tcreate + Tremove + Trename (directory ops). - Create func(ctx HandlerCtx, name string) error - Remove func(ctx HandlerCtx) error - Rename func(newName string) error -} +type FsNodeDecl = fsedsl.FsNodeDecl[HandlerCtx] // NodeOption configures a FsNodeDecl at construction time. -type NodeOption func(*FsNodeDecl) +type NodeOption = fsedsl.NodeOption[HandlerCtx] -// ── EDSL constructors ──────────────────────────────────────────── +// Binding provides identity and data for one iteration of Each. +type Binding = fsedsl.Binding[HandlerCtx] -// DirNode declares a static directory node, optionally with NodeOptions (GID, UID). +// Tree is the filesystem tree implementation. +type Tree = fsedsl.Tree + +// File is an open handle to a single named blob. +type File = fsedsl.File + +// FileTree is a named collection of entries. +type FileTree = fsedsl.FileTree + +// FileConfig implements File via function pointers. +type FileConfig = fsedsl.FileConfig + +// SyntheticFileInfo implements os.FileInfo for entries with no backing file. +type SyntheticFileInfo = fsedsl.SyntheticFileInfo + +// SyntheticEntry implements os.DirEntry for entries with no backing file. +type SyntheticEntry = fsedsl.SyntheticEntry + +// TreeOption configures a Tree. +type TreeOption = fsedsl.TreeOption + +// ── Re-exported constants ──────────────────────────────────────── + +// Structural permissions — used by Tree for mounted children and synthetic files. +const ( + PermChildDir = fsedsl.PermChildDir + PermIdx = fsedsl.PermIdx + PermMkdir = fsedsl.PermMkdir + PermMkdirPrivate = fsedsl.PermMkdirPrivate +) + +// BindTarget declares what data an Each block binds to handlers. +// These are advisory — the actual binding is done by Binding.Applier. +type BindTarget = fsedsl.BindTarget + +const ( + BindData = fsedsl.BindData +) + +// Legacy bind targets for backward compatibility. +// These are no longer meaningful since we use Applier, but keep them +// to avoid breaking existing code that references them. +const ( + BindSession BindTarget = 100 + iota // deprecated: use Applier + BindAgent // deprecated: use Applier + BindAgentLog // deprecated: use Applier + BindRemove // deprecated: use Applier + BindRename // deprecated: use Applier +) + +// ── EDSL constructors (wrappers) ───────────────────────────────── + +// DirNode declares a static directory node. func DirNode(name string, args ...any) FsNodeDecl { - d := FsNodeDecl{Name: name} - for _, a := range args { - switch v := a.(type) { - case FsNodeDecl: - d.Children = append(d.Children, v) - case NodeOption: - v(&d) - } - } - return d + return fsedsl.DirNode[HandlerCtx](name, args...) } // Each declares a directory that is instantiated for each binding in a collection. -// Use Bind() to declare what data handlers receive; the bindings function provides it. -// -// Example: -// -// Each("{sname}", sessionBindings, -// Bind(BindSession), -// FileNode("name", 0666, Read(readSessionName)), -// ) -func Each(name string, bindings BindingFn, args ...any) FsNodeDecl { - d := FsNodeDecl{Name: name, Bindings: bindings} - for _, a := range args { - switch v := a.(type) { - case FsNodeDecl: - d.Children = append(d.Children, v) - case NodeOption: - v(&d) - } - } - return d +func Each(name string, bindings func(HandlerCtx) ([]Binding, error), args ...any) FsNodeDecl { + return fsedsl.Each(name, bindings, args...) } // FileNode declares a file node (non-directory). func FileNode(name string, mode os.FileMode, opts ...NodeOption) FsNodeDecl { - d := FsNodeDecl{Name: name, Mode: mode} - for _, o := range opts { - o(&d) - } - return d + return fsedsl.FileNode[HandlerCtx](name, mode, opts...) } -// ── Options ────────────────────────────────────────────────────── +// ── Options (wrappers) ─────────────────────────────────────────── func Read(fn func(HandlerCtx) ([]byte, error)) NodeOption { - return func(d *FsNodeDecl) { d.Read = fn } + return fsedsl.Read(fn) } func Write(fn func(HandlerCtx, []byte) error) NodeOption { - return func(d *FsNodeDecl) { d.Write = fn } + return fsedsl.Write(fn) } func Stream(fn func(HandlerCtx, context.Context, string) ([]byte, string, error)) NodeOption { - return func(d *FsNodeDecl) { d.Stream = fn } + return fsedsl.Stream(fn) } func BlockOnce(fn func(HandlerCtx, context.Context, string) ([]byte, string, error)) NodeOption { - return func(d *FsNodeDecl) { d.BlockOnce = fn } + return fsedsl.BlockOnce(fn) } func Request(fn func(HandlerCtx, []byte) ([]byte, error)) NodeOption { - return func(d *FsNodeDecl) { d.Request = fn } + return fsedsl.Request(fn) } func CreateFile(fn func(HandlerCtx, string) error) NodeOption { - return func(d *FsNodeDecl) { d.Create = fn } + return fsedsl.CreateFile(fn) } func Remove(fn func(HandlerCtx) error) NodeOption { - return func(d *FsNodeDecl) { d.Remove = fn } + return fsedsl.RemoveNode(fn) } func Stat(fn func() os.FileInfo) NodeOption { - return func(d *FsNodeDecl) { d.Stat = fn } + return fsedsl.StatOverride[HandlerCtx](fn) } func UID(uid string) NodeOption { - return func(d *FsNodeDecl) { d.UID = uid } + return fsedsl.UID[HandlerCtx](uid) } func GID(gid string) NodeOption { - return func(d *FsNodeDecl) { d.GID = gid } + return fsedsl.GID[HandlerCtx](gid) } func Alias(names ...string) NodeOption { - return func(d *FsNodeDecl) { d.Aliases = append(d.Aliases, names...) } + return fsedsl.Alias[HandlerCtx](names...) } // Bind declares how Each bindings populate HandlerCtx. -// The BindTarget specifies which field(s) the binding provides. +// This is advisory metadata — the actual binding is done by Binding.Applier. func Bind(targets ...BindTarget) NodeOption { - return func(d *FsNodeDecl) { d.BindTargets = append(d.BindTargets, targets...) } + return fsedsl.Bind[HandlerCtx](targets...) } // Doc sets a human-readable description for the node. func Doc(desc string) NodeOption { - return func(d *FsNodeDecl) { d.Desc = desc } + return fsedsl.Doc[HandlerCtx](desc) +} + +// ── Tree construction (wrappers) ───────────────────────────────── + +// BuildTree walks an FsNodeDecl spec and produces a *Tree. +func BuildTree(spec FsNodeDecl, rootCtx HandlerCtx) *Tree { + return fsedsl.BuildTree(spec, rootCtx) +} + +// NewTree creates a Tree backed by one or more directories. +func NewTree(dirs []string, perm os.FileMode, opts ...TreeOption) *Tree { + return fsedsl.NewTree(dirs, perm, opts...) +} + +// Tree options +var ( + WithReadOnly = fsedsl.WithReadOnly + WithIndex = fsedsl.WithIndex + WithResolver = fsedsl.WithResolver + WithLister = fsedsl.WithLister + WithCreator = fsedsl.WithCreator + WithDeleter = fsedsl.WithDeleter + WithRenamer = fsedsl.WithRenamer + WithOpener = fsedsl.WithOpener + WithStat = fsedsl.WithStat + WithReaddir = fsedsl.WithReaddir +) + +// ── Helpers (wrappers) ─────────────────────────────────────────── + +// FileEntry returns a synthetic file DirEntry. +func FileEntry(name string, mode os.FileMode) os.DirEntry { + return fsedsl.FileEntry(name, mode) +} + +// DirEntry returns a synthetic directory DirEntry. +func DirEntry(name string, mode os.FileMode) os.DirEntry { + return fsedsl.DirEntry(name, mode) +} + +// GenerateHelp produces help text from a filesystem spec tree. +func GenerateHelp(root FsNodeDecl) string { + return fsedsl.GenerateHelp(root) } diff --git a/fs/handlers.go b/fs/handlers.go index 699284b..84877ae 100644 --- a/fs/handlers.go +++ b/fs/handlers.go @@ -42,69 +42,6 @@ var ( helpText string ) -// GenerateHelp produces help text from a filesystem spec tree. -func GenerateHelp(root FsNodeDecl) string { - return generateHelp(root, "") -} - -func generateHelp(node FsNodeDecl, prefix string) string { - var sb strings.Builder - - path := node.Name - if prefix != "" { - path = prefix + "/" + node.Name - } - if node.Name == "/" { - path = "" - } - - // Write this node's doc if it has one - if node.Desc != "" { - displayPath := path - if displayPath == "" { - displayPath = "/" - } - mode := node.Mode - if len(node.Children) > 0 || node.Bindings != nil { - mode = 0755 | os.ModeDir - } - fmt.Fprintf(&sb, "%-40s %s %s\n", displayPath, fmtMode(mode), node.Desc) - } - - // Recurse into children - for _, child := range node.Children { - sb.WriteString(generateHelp(child, path)) - } - - return sb.String() -} - -func fmtMode(m os.FileMode) string { - if m == 0 { - return "----" - } - var buf [4]byte - buf[0] = '-' - if m.IsDir() { - buf[0] = 'd' - } - buf[1] = 'r' - if m&0200 != 0 { - buf[1] = 'w' - } - if m&0400 != 0 { - buf[2] = 'r' - } else { - buf[2] = '-' - } - if m&0100 != 0 { - buf[3] = 'x' - } else { - buf[3] = '-' - } - return string(buf[:]) -} - func readModels(ctx HandlerCtx) ([]byte, error) { if ctx.Models != nil { return ctx.Models.Get(), nil @@ -262,9 +199,13 @@ func elevateBindings(ctx HandlerCtx) ([]Binding, error) { pending := ctx.Elevate.Pending() out := make([]Binding, len(pending)) for i, r := range pending { + req := r // capture out[i] = Binding{ Name: r.ID, - Data: r, + Applier: func(c HandlerCtx) HandlerCtx { + c.Data = req + return c + }, } } return out, nil @@ -323,9 +264,14 @@ func sessionBindings(_ HandlerCtx) ([]Binding, error) { Aliases: []string{s.RunnableID()}, UID: s.Uname(), GID: "agent", - Session: s, - Remove: func() { Kill(rs, s.Name()) }, - Rename: func(newName string) error { return Rename(rs, s.Name(), newName) }, + Applier: func(c HandlerCtx) HandlerCtx { + c.Session = s + c.Remove = func() { Kill(rs, s.Name()) } + c.Rename = func(newName string) error { return Rename(rs, s.Name(), newName) } + return c + }, + Remove: func() { Kill(rs, s.Name()) }, + Rename: func(newName string) error { return Rename(rs, s.Name(), newName) }, }) } return out, nil @@ -450,12 +396,15 @@ func agentBindings(ctx HandlerCtx) ([]Binding, error) { continue } out = append(out, Binding{ - Name: a.Name(), - Aliases: []string{a.ID()}, - UID: a.ID(), - GID: "agent", - Agent: a, - AgentLog: al, + Name: a.Name(), + Aliases: []string{a.ID()}, + UID: a.ID(), + GID: "agent", + Applier: func(c HandlerCtx) HandlerCtx { + c.Agent = a + c.AgentLog = al + return c + }, Rename: func(newName string) error { a.SetName(newName) persistSession(globalRootState, sess.Name()) @@ -808,9 +757,13 @@ func processBindings(ctx HandlerCtx) ([]Binding, error) { procs := ctx.Agent.ListDetached() out := make([]Binding, len(procs)) for i, p := range procs { + pid := p.PID // capture out[i] = Binding{ Name: strconv.Itoa(p.PID), - Data: p.PID, + Applier: func(c HandlerCtx) HandlerCtx { + c.Data = pid + return c + }, } } return out, nil diff --git a/fsedsl/LICENSE.md b/fsedsl/LICENSE.md new file mode 100644 index 0000000..496acdb --- /dev/null +++ b/fsedsl/LICENSE.md @@ -0,0 +1,675 @@ +# GNU GENERAL PUBLIC LICENSE + +Version 3, 29 June 2007 + +Copyright (C) 2007 Free Software Foundation, Inc. + + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +## Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program--to make sure it remains +free software for all its users. We, the Free Software Foundation, use +the GNU General Public License for most of our software; it applies +also to any other work released this way by its authors. You can apply +it to your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +## TERMS AND CONDITIONS + +### 0. Definitions. + +"This License" refers to version 3 of the GNU General Public License. + +"Copyright" also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +"The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + +To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a "modified version" of +the earlier work or a work "based on" the earlier work. + +A "covered work" means either the unmodified Program or a work based +on the Program. + +To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays "Appropriate Legal Notices" to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +### 1. Source Code. + +The "source code" for a work means the preferred form of the work for +making modifications to it. "Object code" means any non-source form of +a work. + +A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +### 2. Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 makes +it unnecessary. + +### 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +### 4. Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +### 5. Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +- a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. +- b) The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in section 4 + to "keep intact all notices". +- c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. +- d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +### 6. Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +- a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. +- b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the Corresponding + Source from a network server at no charge. +- c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. +- d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. +- e) Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the general + public at no charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +"normally used" refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +"Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +### 7. Additional Terms. + +"Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +- a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or +- b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or +- c) Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or +- d) Limiting the use for publicity purposes of names of licensors + or authors of the material; or +- e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or +- f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions + of it) with contractual assumptions of liability to the recipient, + for any liability that these contractual assumptions directly + impose on those licensors and authors. + +All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +### 8. Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +### 9. Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +### 10. Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +### 11. Patents. + +A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + +A contributor's "essential patent claims" are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is "discriminatory" if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +### 12. No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree to +terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +### 13. Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +### 14. Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If the +Program does not specify a version number of the GNU General Public +License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +### 15. Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +### 16. Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +### 17. Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS + +## How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest to +attach them to the start of each source file to most effectively state +the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper +mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands \`show w' and \`show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + +You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see . + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read . diff --git a/fsedsl/README.md b/fsedsl/README.md new file mode 100644 index 0000000..60de9aa --- /dev/null +++ b/fsedsl/README.md @@ -0,0 +1,127 @@ +# fsedsl + +A Go library providing an embedded domain-specific language (EDSL) for declaring synthetic filesystems. Designed for building 9P namespaces where the entire structure is declared statically but populated dynamically at runtime. + +## Features + +- **Declarative filesystem specification**: Define your namespace structure with `DirNode`, `FileNode`, and `Each` constructors +- **Generic context propagation**: Type-safe context passing through the tree via `Binding.Applier` +- **Dynamic bindings**: `Each` nodes iterate over runtime-determined collections +- **Auto-generated help**: `GenerateHelp` produces documentation from `Doc()` annotations +- **Standard filesystem semantics**: Implements read, write, stat, list, create, delete, rename + +## Installation + +```bash +go get git.lneely.de/lkn/fsedsl +``` + +## Quick Example + +```go +package main + +import ( + "fmt" + "git.lneely.de/lkn/fsedsl" +) + +type Ctx struct { + User *User +} + +type User struct { + ID string + Name string +} + +var users = []*User{ + {ID: "1", Name: "alice"}, + {ID: "2", Name: "bob"}, +} + +func main() { + spec := fsedsl.DirNode[Ctx]("/", + fsedsl.FileNode[Ctx]("version", 0444, + fsedsl.Doc[Ctx]("API version"), + fsedsl.Read(func(ctx Ctx) ([]byte, error) { + return []byte("1.0\n"), nil + }), + ), + fsedsl.Each("{user}", func(ctx Ctx) ([]fsedsl.Binding[Ctx], error) { + var out []fsedsl.Binding[Ctx] + for _, u := range users { + user := u // capture + out = append(out, fsedsl.Binding[Ctx]{ + Name: user.Name, + Aliases: []string{user.ID}, + Applier: func(c Ctx) Ctx { + c.User = user + return c + }, + }) + } + return out, nil + }, + fsedsl.FileNode[Ctx]("id", 0444, + fsedsl.Read(func(ctx Ctx) ([]byte, error) { + return []byte(ctx.User.ID + "\n"), nil + }), + ), + fsedsl.FileNode[Ctx]("name", 0666, + fsedsl.Read(func(ctx Ctx) ([]byte, error) { + return []byte(ctx.User.Name + "\n"), nil + }), + ), + ), + ) + + tree := fsedsl.BuildTree(spec, Ctx{}) + + // List root + entries, _ := tree.List() + for _, e := range entries { + fmt.Println(e.Name()) + } + + // Read a file + f, _ := tree.Open("alice/name") + data, _ := f.Read() + fmt.Printf("alice/name: %s", data) +} +``` + +## API Overview + +### Constructors + +- `DirNode[Ctx](name, children/options...)` — static directory +- `FileNode[Ctx](name, mode, options...)` — file with handlers +- `Each[Ctx](pattern, bindingsFn, children/options...)` — dynamic directory template + +### Options + +- `Read(fn)` — read handler +- `Write(fn)` — write handler +- `Stream(fn)` — streaming read (blocks indefinitely) +- `BlockOnce(fn)` — blocking read (returns once) +- `Request(fn)` — request/response pattern (rdwr) +- `Doc(desc)` — human-readable description +- `UID(uid)`, `GID(gid)` — ownership +- `Alias(names...)` — alternate lookup names + +### Building + +```go +tree := fsedsl.BuildTree(spec, rootCtx) +``` + +### Help Generation + +```go +help := fsedsl.GenerateHelp(spec) +``` + +## License + +GPLv3 diff --git a/fs/builder.go b/fsedsl/builder.go similarity index 82% rename from fs/builder.go rename to fsedsl/builder.go index 42c9acb..451217d 100644 --- a/fs/builder.go +++ b/fsedsl/builder.go @@ -1,4 +1,4 @@ -package fs +package fsedsl import ( "context" @@ -9,7 +9,7 @@ import ( // BuildTree walks an FsNodeDecl spec and produces a *Tree. // It validates the spec, resolves inheritance, and wires handlers. -func BuildTree(spec FsNodeDecl, rootCtx HandlerCtx) *Tree { +func BuildTree[Ctx any](spec FsNodeDecl[Ctx], rootCtx Ctx) *Tree { validate(&spec, "") tree := build(&spec, "", "", rootCtx) return tree @@ -17,7 +17,7 @@ func BuildTree(spec FsNodeDecl, rootCtx HandlerCtx) *Tree { // ── validation ─────────────────────────────────────────────────── -func validate(d *FsNodeDecl, path string) { +func validate[Ctx any](d *FsNodeDecl[Ctx], path string) { hasChildren := len(d.Children) > 0 hasBindings := d.Bindings != nil hasFileHandlers := d.Read != nil || d.Write != nil || d.BlockOnce != nil || d.Stream != nil || d.Request != nil @@ -78,7 +78,7 @@ func validate(d *FsNodeDecl, path string) { // build ──────────────────────────────────────────────────────── -func build(d *FsNodeDecl, parentUid, parentGid string, parentCtx HandlerCtx) *Tree { +func build[Ctx any](d *FsNodeDecl[Ctx], parentUid, parentGid string, parentCtx Ctx) *Tree { // Resolve inheritance. uid := d.UID if uid == "" { @@ -144,7 +144,7 @@ func build(d *FsNodeDecl, parentUid, parentGid string, parentCtx HandlerCtx) *Tr // ── directory ops ──────────────────────────────────────────────── -func listDir(d *FsNodeDecl, uid, gid string, ctx HandlerCtx) ([]os.DirEntry, error) { +func listDir[Ctx any](d *FsNodeDecl[Ctx], uid, gid string, ctx Ctx) ([]os.DirEntry, error) { // Static directories: return static children and also resolve // template/blueprint children for dynamic entries. var entries []os.DirEntry @@ -189,7 +189,7 @@ func listDir(d *FsNodeDecl, uid, gid string, ctx HandlerCtx) ([]os.DirEntry, err return entries, nil } -func readdirDir(d *FsNodeDecl, uid, gid, name string, ctx HandlerCtx) ([]os.DirEntry, error) { +func readdirDir[Ctx any](d *FsNodeDecl[Ctx], uid, gid, name string, ctx Ctx) ([]os.DirEntry, error) { child, childCtx := findChild(d, name, ctx) if child == nil { return nil, fmt.Errorf("%s: not found", name) @@ -197,7 +197,7 @@ func readdirDir(d *FsNodeDecl, uid, gid, name string, ctx HandlerCtx) ([]os.DirE return listDir(child, resolveUID(child, uid), resolveGID(child, gid), childCtx) } -func statDir(d *FsNodeDecl, uid, gid, name string, ctx HandlerCtx) (os.FileInfo, error) { +func statDir[Ctx any](d *FsNodeDecl[Ctx], uid, gid, name string, ctx Ctx) (os.FileInfo, error) { // Stat of the dir itself. if name == "" || name == "." { m := d.Mode @@ -228,7 +228,7 @@ func statDir(d *FsNodeDecl, uid, gid, name string, ctx HandlerCtx) (os.FileInfo, return &SyntheticFileInfo{Name_: name, Mode_: cm, UID_: cu, GID_: cg}, nil } -func openDir(d *FsNodeDecl, uid, gid string, name string, ctx HandlerCtx) (File, error) { +func openDir[Ctx any](d *FsNodeDecl[Ctx], uid, gid string, name string, ctx Ctx) (File, error) { child, childCtx := findChild(d, name, ctx) if child == nil { return nil, fmt.Errorf("%s: not found", name) @@ -237,7 +237,7 @@ func openDir(d *FsNodeDecl, uid, gid string, name string, ctx HandlerCtx) (File, return sub.Open("") } -func deleteDir(d *FsNodeDecl, name string, ctx HandlerCtx) error { +func deleteDir[Ctx any](d *FsNodeDecl[Ctx], name string, ctx Ctx) error { child, childCtx := findChild(d, name, ctx) if child == nil { return fmt.Errorf("%s: not found", name) @@ -248,7 +248,7 @@ func deleteDir(d *FsNodeDecl, name string, ctx HandlerCtx) error { return fmt.Errorf("%s: not removable", name) } -func renameDir(d *FsNodeDecl, old, new string, ctx HandlerCtx) error { +func renameDir[Ctx any](d *FsNodeDecl[Ctx], old, new string, ctx Ctx) error { child, _ := findChild(d, old, ctx) if child == nil { return fmt.Errorf("%s: not found", old) @@ -261,7 +261,7 @@ func renameDir(d *FsNodeDecl, old, new string, ctx HandlerCtx) error { // ── leaf ops ───────────────────────────────────────────────────── -func openLeaf(d *FsNodeDecl, uid, gid string, mode os.FileMode, ctx HandlerCtx, name string) (File, error) { +func openLeaf[Ctx any](d *FsNodeDecl[Ctx], uid, gid string, mode os.FileMode, ctx Ctx, name string) (File, error) { notBlocking := func(context.Context, string) ([]byte, string, error) { return nil, "", fmt.Errorf("blocking read not supported") } @@ -342,7 +342,7 @@ func openLeaf(d *FsNodeDecl, uid, gid string, mode os.FileMode, ctx HandlerCtx, // ── helpers ────────────────────────────────────────────────────── -func findChild(d *FsNodeDecl, name string, ctx HandlerCtx) (*FsNodeDecl, HandlerCtx) { +func findChild[Ctx any](d *FsNodeDecl[Ctx], name string, ctx Ctx) (*FsNodeDecl[Ctx], Ctx) { // Handle nested paths recursively. if i := strings.IndexByte(name, '/'); i >= 0 { prefix := name[:i] @@ -372,7 +372,10 @@ func findChild(d *FsNodeDecl, name string, ctx HandlerCtx) (*FsNodeDecl, Handler if b.Name == name || matchAlias(b.Aliases, name) { // Clone the blueprint with binding identity and apply context. clone := cloneBlueprint(&d.Children[i], b) - boundCtx := applyBinding(ctx, b, d.Children[i].BindTargets) + boundCtx := ctx + if b.Applier != nil { + boundCtx = b.Applier(ctx) + } return clone, boundCtx } } @@ -383,7 +386,7 @@ func findChild(d *FsNodeDecl, name string, ctx HandlerCtx) (*FsNodeDecl, Handler } // cloneBlueprint creates a copy of the blueprint with binding identity applied. -func cloneBlueprint(bp *FsNodeDecl, b Binding) *FsNodeDecl { +func cloneBlueprint[Ctx any](bp *FsNodeDecl[Ctx], b Binding[Ctx]) *FsNodeDecl[Ctx] { clone := *bp clone.Name = b.Name clone.Aliases = b.Aliases @@ -399,64 +402,6 @@ func cloneBlueprint(bp *FsNodeDecl, b Binding) *FsNodeDecl { return &clone } -// applyBinding populates the HandlerCtx with binding data based on BindTargets. -// If no targets are specified, all non-nil fields are applied (legacy behavior). -func applyBinding(ctx HandlerCtx, b Binding, targets []BindTarget) HandlerCtx { - if len(targets) == 0 { - // Legacy: apply all non-nil fields. - if b.Session != nil { - ctx.Session = b.Session - } - if b.Agent != nil { - ctx.Agent = b.Agent - } - if b.AgentLog != nil { - ctx.AgentLog = b.AgentLog - } - if b.Data != nil { - ctx.Data = b.Data - } - if b.Remove != nil { - ctx.Remove = b.Remove - } - if b.Rename != nil { - ctx.Rename = b.Rename - } - return ctx - } - - // Apply only specified targets. - for _, t := range targets { - switch t { - case BindSession: - if b.Session != nil { - ctx.Session = b.Session - } - case BindAgent: - if b.Agent != nil { - ctx.Agent = b.Agent - } - case BindAgentLog: - if b.AgentLog != nil { - ctx.AgentLog = b.AgentLog - } - case BindData: - if b.Data != nil { - ctx.Data = b.Data - } - case BindRemove: - if b.Remove != nil { - ctx.Remove = b.Remove - } - case BindRename: - if b.Rename != nil { - ctx.Rename = b.Rename - } - } - } - return ctx -} - func matchAlias(aliases []string, name string) bool { for _, a := range aliases { if a == name { @@ -466,14 +411,14 @@ func matchAlias(aliases []string, name string) bool { return false } -func resolveUID(d *FsNodeDecl, parent string) string { +func resolveUID[Ctx any](d *FsNodeDecl[Ctx], parent string) string { if d.UID != "" { return d.UID } return parent } -func resolveGID(d *FsNodeDecl, parent string) string { +func resolveGID[Ctx any](d *FsNodeDecl[Ctx], parent string) string { if d.GID != "" { return d.GID } diff --git a/fsedsl/decl.go b/fsedsl/decl.go new file mode 100644 index 0000000..31525c9 --- /dev/null +++ b/fsedsl/decl.go @@ -0,0 +1,224 @@ +// Package fsedsl provides an embedded domain-specific language for declaring +// synthetic filesystems. It is designed for building 9P namespaces where the +// entire filesystem structure is declared statically but populated dynamically. +// +// The core type is FsNodeDecl[Ctx], a recursive structure that describes +// directories, files, and template nodes (Each). Handlers receive a context +// of type Ctx, allowing domain-specific data to flow through the tree. +// +// Example usage: +// +// type MyCtx struct { +// User *User +// Data any +// } +// +// spec := DirNode[MyCtx]("/", +// FileNode[MyCtx]("version", 0444, +// Doc("API version"), +// Read(func(ctx MyCtx) ([]byte, error) { +// return []byte("1.0\n"), nil +// }), +// ), +// Each[MyCtx]("{user}", userBindings, +// FileNode[MyCtx]("name", 0444, +// Read(func(ctx MyCtx) ([]byte, error) { +// return []byte(ctx.User.Name + "\n"), nil +// }), +// ), +// ), +// ) +// +// tree := BuildTree(spec, MyCtx{}) +package fsedsl + +import ( + "context" + "os" +) + +// FsNodeDecl describes one node in a filesystem namespace. +// The entire filesystem is a single recursive tree of these declarations. +// Ctx is the context type passed to all handler functions. +type FsNodeDecl[Ctx any] struct { + // Identity. + Name string + Aliases []string // alternate names that resolve to this node (e.g. immutable ID) + UID string // "" = inherit from parent + GID string // "" = inherit from parent + Mode os.FileMode // 0 = inherit parent default + Desc string // human-readable description + + // Tstat — metadata override (non-nil bypasses Name/UID/GID/Mode/size defaulting). + Stat func() os.FileInfo + + // Twalk — children (implies directory; at most one set). + Children []FsNodeDecl[Ctx] // static, known at compile time + Bindings func(Ctx) ([]Binding[Ctx], error) // Each bindings + BindTargets []BindTarget // declares what Bindings provides + + // Tread (non-blocking) + Twrite. + Read func(ctx Ctx) ([]byte, error) + Write func(ctx Ctx, data []byte) error + + // Tread — blocking variants (at most one set). + BlockOnce func(ctx Ctx, cctx context.Context, base string) ([]byte, string, error) + Stream func(ctx Ctx, cctx context.Context, base string) ([]byte, string, error) + + // Request — rdwr: write triggers result, read returns it once. + Request func(ctx Ctx, data []byte) ([]byte, error) + + // Tcreate + Tremove + Trename (directory ops). + Create func(ctx Ctx, name string) error + Remove func(ctx Ctx) error + Rename func(newName string) error +} + +// NodeOption configures a FsNodeDecl at construction time. +type NodeOption[Ctx any] func(*FsNodeDecl[Ctx]) + +// Binding provides identity and data for one iteration of Each. +// The structure is cloned for each binding, and handlers receive +// the bound data via the Ctx fields specified by BindTargets. +type Binding[Ctx any] struct { + Name string // directory/file name (e.g. session name, agent name) + Aliases []string // alternate lookup names (e.g. immutable ID) + UID string // owner (empty = inherit) + GID string // group (empty = inherit) + + // Applier updates the context with bound data. + // Called when traversing into this binding's node. + Applier func(ctx Ctx) Ctx + + // Lifecycle callbacks. + Remove func() + Rename func(string) error +} + +// BindTarget declares what data an Each block binds to handlers. +// This is advisory — the actual binding is done by Binding.Applier. +type BindTarget int + +const ( + BindData BindTarget = iota // generic data binding +) + +// ── EDSL constructors ──────────────────────────────────────────── + +// DirNode declares a static directory node. +// Arguments can be FsNodeDecl[Ctx] children or NodeOption[Ctx] modifiers. +func DirNode[Ctx any](name string, args ...any) FsNodeDecl[Ctx] { + d := FsNodeDecl[Ctx]{Name: name} + for _, a := range args { + switch v := a.(type) { + case FsNodeDecl[Ctx]: + d.Children = append(d.Children, v) + case NodeOption[Ctx]: + v(&d) + } + } + return d +} + +// Each declares a directory that is instantiated for each binding in a collection. +// The bindings function is called at list/traverse time to determine instances. +// +// Example: +// +// Each[MyCtx]("{id}", func(ctx MyCtx) ([]Binding[MyCtx], error) { +// return []Binding[MyCtx]{ +// {Name: "foo", Applier: func(c MyCtx) MyCtx { c.Data = "foo"; return c }}, +// }, nil +// }, +// FileNode[MyCtx]("name", 0444, Read(readName)), +// ) +func Each[Ctx any](name string, bindings func(Ctx) ([]Binding[Ctx], error), args ...any) FsNodeDecl[Ctx] { + d := FsNodeDecl[Ctx]{Name: name, Bindings: bindings} + for _, a := range args { + switch v := a.(type) { + case FsNodeDecl[Ctx]: + d.Children = append(d.Children, v) + case NodeOption[Ctx]: + v(&d) + } + } + return d +} + +// FileNode declares a file node (non-directory). +func FileNode[Ctx any](name string, mode os.FileMode, opts ...NodeOption[Ctx]) FsNodeDecl[Ctx] { + d := FsNodeDecl[Ctx]{Name: name, Mode: mode} + for _, o := range opts { + o(&d) + } + return d +} + +// ── Options ────────────────────────────────────────────────────── + +// Read sets the read handler for a file node. +func Read[Ctx any](fn func(Ctx) ([]byte, error)) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Read = fn } +} + +// Write sets the write handler for a file node. +func Write[Ctx any](fn func(Ctx, []byte) error) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Write = fn } +} + +// Stream sets a streaming read handler that blocks indefinitely. +func Stream[Ctx any](fn func(Ctx, context.Context, string) ([]byte, string, error)) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Stream = fn } +} + +// BlockOnce sets a blocking read handler that returns once. +func BlockOnce[Ctx any](fn func(Ctx, context.Context, string) ([]byte, string, error)) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.BlockOnce = fn } +} + +// Request sets a request-response handler (rdwr pattern). +func Request[Ctx any](fn func(Ctx, []byte) ([]byte, error)) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Request = fn } +} + +// CreateFile sets the file creation handler for a directory node. +func CreateFile[Ctx any](fn func(Ctx, string) error) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Create = fn } +} + +// RemoveNode sets the removal handler for a node. +func RemoveNode[Ctx any](fn func(Ctx) error) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Remove = fn } +} + +// StatOverride sets a custom stat handler that bypasses default metadata. +func StatOverride[Ctx any](fn func() os.FileInfo) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Stat = fn } +} + +// UID sets the owner for a node. +func UID[Ctx any](uid string) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.UID = uid } +} + +// GID sets the group for a node. +func GID[Ctx any](gid string) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.GID = gid } +} + +// Alias adds alternate names for resolving this node. +func Alias[Ctx any](names ...string) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Aliases = append(d.Aliases, names...) } +} + +// Bind declares how Each bindings populate the context. +// This is advisory metadata; the actual binding is done by Binding.Applier. +func Bind[Ctx any](targets ...BindTarget) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.BindTargets = append(d.BindTargets, targets...) } +} + +// Doc sets a human-readable description for the node. +// Used by GenerateHelp to produce documentation. +func Doc[Ctx any](desc string) NodeOption[Ctx] { + return func(d *FsNodeDecl[Ctx]) { d.Desc = desc } +} diff --git a/fsedsl/decl_test.go b/fsedsl/decl_test.go new file mode 100644 index 0000000..3eb9a98 --- /dev/null +++ b/fsedsl/decl_test.go @@ -0,0 +1,295 @@ +package fsedsl + +import ( + "os" + "testing" +) + +// TestCtx is a simple test context. +type TestCtx struct { + Data any +} + +// TestEachBasic tests the basic Blueprint pattern: +// - Declares structure statically +// - Bindings function provides identity (name, aliases, UID/GID) +// - Handlers receive context with bound data +func TestEachBasic(t *testing.T) { + type testData struct { + ID string + Name string + } + + instances := []testData{ + {ID: "aaa-111", Name: "first"}, + {ID: "bbb-222", Name: "second"}, + } + + spec := DirNode[TestCtx]("/", + Each("{id}", func(ctx TestCtx) ([]Binding[TestCtx], error) { + var out []Binding[TestCtx] + for _, d := range instances { + data := d // capture + out = append(out, Binding[TestCtx]{ + Name: data.Name, + Aliases: []string{data.ID}, + UID: data.ID, + GID: "testgroup", + }) + } + return out, nil + }, + FileNode[TestCtx]("id", 0444, Read(func(ctx TestCtx) ([]byte, error) { + return []byte("test-id\n"), nil + })), + FileNode[TestCtx]("name", 0666, + Read(func(ctx TestCtx) ([]byte, error) { + return []byte("test-name\n"), nil + }), + Write(func(ctx TestCtx, data []byte) error { + return nil // no-op for test + }), + ), + ), + ) + + tree := BuildTree(spec, TestCtx{}) + + // Test: List root should show the two instances by name + entries, err := tree.List() + if err != nil { + t.Fatalf("List root: %v", err) + } + if len(entries) != 2 { + t.Errorf("List root: got %d entries, want 2", len(entries)) + } + + names := make(map[string]bool) + for _, e := range entries { + names[e.Name()] = true + } + if !names["first"] { + t.Error("List root: missing 'first'") + } + if !names["second"] { + t.Error("List root: missing 'second'") + } + + // Test: Access by name + sub, err := tree.Readdir("first") + if err != nil { + t.Fatalf("Readdir(first): %v", err) + } + foundID := false + foundName := false + for _, e := range sub { + switch e.Name() { + case "id": + foundID = true + case "name": + foundName = true + } + } + if !foundID { + t.Error("Readdir(first): missing 'id' leaf") + } + if !foundName { + t.Error("Readdir(first): missing 'name' leaf") + } + + // Test: Access by alias + subByAlias, err := tree.Readdir("aaa-111") + if err != nil { + t.Fatalf("Readdir(aaa-111): %v", err) + } + if len(subByAlias) != len(sub) { + t.Errorf("Readdir by alias: got %d entries, want %d", len(subByAlias), len(sub)) + } + + // Test: Read leaf file + f, err := tree.Open("first/id") + if err != nil { + t.Fatalf("Open(first/id): %v", err) + } + data, err := f.Read() + if err != nil { + t.Fatalf("Read(first/id): %v", err) + } + if string(data) != "test-id\n" { + t.Errorf("Read(first/id) = %q, want %q", data, "test-id\n") + } + + // Test: Stat instance directory + fi, err := tree.Stat("first") + if err != nil { + t.Fatalf("Stat(first): %v", err) + } + if !fi.IsDir() { + t.Error("Stat(first): expected directory") + } + if fi.Name() != "first" { + t.Errorf("Stat(first).Name() = %q, want 'first'", fi.Name()) + } + + // Test: Stat via alias + fiAlias, err := tree.Stat("aaa-111") + if err != nil { + t.Fatalf("Stat(aaa-111): %v", err) + } + if fiAlias.Name() != "aaa-111" { + t.Errorf("Stat(aaa-111).Name() = %q, want 'aaa-111'", fiAlias.Name()) + } +} + +// TestContextApplier tests that Binding.Applier correctly propagates context +func TestContextApplier(t *testing.T) { + type Ctx struct { + UserID string + } + + spec := DirNode[Ctx]("/", + Each("{user}", func(ctx Ctx) ([]Binding[Ctx], error) { + return []Binding[Ctx]{ + { + Name: "alice", + Applier: func(c Ctx) Ctx { + c.UserID = "alice-123" + return c + }, + }, + { + Name: "bob", + Applier: func(c Ctx) Ctx { + c.UserID = "bob-456" + return c + }, + }, + }, nil + }, + FileNode[Ctx]("whoami", 0444, Read(func(ctx Ctx) ([]byte, error) { + return []byte(ctx.UserID + "\n"), nil + })), + ), + ) + + tree := BuildTree(spec, Ctx{}) + + // Test: Read alice's whoami + f, err := tree.Open("alice/whoami") + if err != nil { + t.Fatalf("Open(alice/whoami): %v", err) + } + data, err := f.Read() + if err != nil { + t.Fatalf("Read: %v", err) + } + if string(data) != "alice-123\n" { + t.Errorf("alice/whoami = %q, want 'alice-123\\n'", data) + } + + // Test: Read bob's whoami + f2, err := tree.Open("bob/whoami") + if err != nil { + t.Fatalf("Open(bob/whoami): %v", err) + } + data2, err := f2.Read() + if err != nil { + t.Fatalf("Read: %v", err) + } + if string(data2) != "bob-456\n" { + t.Errorf("bob/whoami = %q, want 'bob-456\\n'", data2) + } +} + +// TestGenerateHelp tests help generation +func TestGenerateHelp(t *testing.T) { + spec := DirNode[TestCtx]("/", + FileNode[TestCtx]("version", 0444, + Doc[TestCtx]("API version"), + Read(func(ctx TestCtx) ([]byte, error) { + return []byte("1.0\n"), nil + }), + ), + DirNode[TestCtx]("data", + Doc[TestCtx]("Data directory"), + FileNode[TestCtx]("config", 0666, + Doc[TestCtx]("Configuration file"), + ), + ), + ) + + help := GenerateHelp(spec) + + if help == "" { + t.Error("GenerateHelp returned empty string") + } + if !contains(help, "version") { + t.Error("help missing 'version'") + } + if !contains(help, "API version") { + t.Error("help missing 'API version' description") + } + if !contains(help, "data") { + t.Error("help missing 'data'") + } +} + +func contains(s, substr string) bool { + return len(s) >= len(substr) && (s == substr || len(s) > 0 && containsAt(s, substr)) +} + +func containsAt(s, substr string) bool { + for i := 0; i <= len(s)-len(substr); i++ { + if s[i:i+len(substr)] == substr { + return true + } + } + return false +} + +// TestStatMode tests file modes are preserved +func TestStatMode(t *testing.T) { + spec := DirNode[TestCtx]("/", + Each("{id}", func(ctx TestCtx) ([]Binding[TestCtx], error) { + return []Binding[TestCtx]{{Name: "instance"}}, nil + }, + FileNode[TestCtx]("readable", 0444, Read(func(ctx TestCtx) ([]byte, error) { + return []byte("r\n"), nil + })), + FileNode[TestCtx]("writable", 0666, + Read(func(ctx TestCtx) ([]byte, error) { + return []byte("rw\n"), nil + }), + Write(func(ctx TestCtx, data []byte) error { + return nil + }), + ), + FileNode[TestCtx]("executable", 0555, Read(func(ctx TestCtx) ([]byte, error) { + return []byte("#!/bin/sh\n"), nil + })), + ), + ) + + tree := BuildTree(spec, TestCtx{}) + + tests := []struct { + path string + mode os.FileMode + }{ + {"instance", os.ModeDir | 0755}, + {"instance/readable", 0444}, + {"instance/writable", 0666}, + {"instance/executable", 0555}, + } + + for _, tc := range tests { + fi, err := tree.Stat(tc.path) + if err != nil { + t.Errorf("Stat(%q): %v", tc.path, err) + continue + } + if fi.Mode() != tc.mode { + t.Errorf("Stat(%q).Mode() = %o, want %o", tc.path, fi.Mode(), tc.mode) + } + } +} diff --git a/fs/file.go b/fsedsl/file.go similarity index 92% rename from fs/file.go rename to fsedsl/file.go index 27e74e8..4a8ac11 100644 --- a/fs/file.go +++ b/fsedsl/file.go @@ -1,6 +1,4 @@ -// Package fs defines the file tree interfaces and implementation. -// implementation used by the 9P server. -package fs +package fsedsl import ( "context" @@ -34,15 +32,6 @@ type FileTree interface { Rename(oldName, newName string) error } -// Runnable is a running agent that can be observed and controlled. -type Runnable interface { - RunnableID() string - Cancel() - Interrupt() - AppendLog([]byte) - LogInfo() (length int, vers uint32) -} - // FileConfig implements File via function pointers. type FileConfig struct { StatFn func() (os.FileInfo, error) @@ -127,3 +116,11 @@ func FileEntry(name string, mode os.FileMode) os.DirEntry { func DirEntry(name string, mode os.FileMode) os.DirEntry { return &SyntheticEntry{Name_: name, Mode_: mode, IsDir_: true} } + +// Structural permissions — used by Tree for mounted children and synthetic files. +const ( + PermChildDir os.FileMode = 0555 + PermIdx os.FileMode = 0444 + PermMkdir os.FileMode = 0755 + PermMkdirPrivate os.FileMode = 0700 +) diff --git a/fsedsl/go.mod b/fsedsl/go.mod new file mode 100644 index 0000000..9889f7e --- /dev/null +++ b/fsedsl/go.mod @@ -0,0 +1,3 @@ +module ollie/fsedsl + +go 1.25.6 diff --git a/fsedsl/help.go b/fsedsl/help.go new file mode 100644 index 0000000..7ed9665 --- /dev/null +++ b/fsedsl/help.go @@ -0,0 +1,71 @@ +package fsedsl + +import ( + "fmt" + "os" + "strings" +) + +// GenerateHelp produces documentation from a filesystem spec tree. +// It walks the tree recursively and emits a line for each node with a Doc description. +func GenerateHelp[Ctx any](root FsNodeDecl[Ctx]) string { + return generateHelp(root, "") +} + +func generateHelp[Ctx any](node FsNodeDecl[Ctx], prefix string) string { + var sb strings.Builder + + path := node.Name + if prefix != "" { + path = prefix + "/" + node.Name + } + if node.Name == "/" { + path = "" + } + + // Write this node's doc if it has one + if node.Desc != "" { + displayPath := path + if displayPath == "" { + displayPath = "/" + } + mode := node.Mode + if len(node.Children) > 0 || node.Bindings != nil { + mode = 0755 | os.ModeDir + } + fmt.Fprintf(&sb, "%-40s %s %s\n", displayPath, fmtMode(mode), node.Desc) + } + + // Recurse into children + for _, child := range node.Children { + sb.WriteString(generateHelp(child, path)) + } + + return sb.String() +} + +func fmtMode(m os.FileMode) string { + if m == 0 { + return "----" + } + var buf [4]byte + buf[0] = '-' + if m.IsDir() { + buf[0] = 'd' + } + buf[1] = 'r' + if m&0200 != 0 { + buf[1] = 'w' + } + if m&0400 != 0 { + buf[2] = 'r' + } else { + buf[2] = '-' + } + if m&0100 != 0 { + buf[3] = 'x' + } else { + buf[3] = '-' + } + return string(buf[:]) +} diff --git a/fs/tree.go b/fsedsl/tree.go similarity index 94% rename from fs/tree.go rename to fsedsl/tree.go index 4021723..569c6e9 100644 --- a/fs/tree.go +++ b/fsedsl/tree.go @@ -1,4 +1,4 @@ -package fs +package fsedsl import ( "context" @@ -28,61 +28,61 @@ type Tree struct { Data any // user-attached state } -// Option configures a Tree. -type Option func(*Tree) +// TreeOption configures a Tree. +type TreeOption func(*Tree) // WithReadOnly makes the tree reject writes, creates, deletes, and renames. -func WithReadOnly() Option { return func(d *Tree) { d.readOnly = true } } +func WithReadOnly() TreeOption { return func(d *Tree) { d.readOnly = true } } // WithIndex adds a synthetic read-only "idx" entry whose content is // generated by calling fn with the tree itself. -func WithIndex(fn func(FileTree) ([]byte, error)) Option { +func WithIndex(fn func(FileTree) ([]byte, error)) TreeOption { return func(d *Tree) { d.indexFn = fn } } // WithResolver overrides how virtual names map to filesystem paths. -func WithResolver(fn func(dirs []string, name string) (string, error)) Option { +func WithResolver(fn func(dirs []string, name string) (string, error)) TreeOption { return func(d *Tree) { d.resolveFn = fn } } // WithLister overrides how the tree lists its entries. -func WithLister(fn func(dirs []string) ([]os.DirEntry, error)) Option { +func WithLister(fn func(dirs []string) ([]os.DirEntry, error)) TreeOption { return func(d *Tree) { d.listFn = fn } } // WithCreator overrides file creation logic. -func WithCreator(fn func(dirs []string, name string, perm os.FileMode) error) Option { +func WithCreator(fn func(dirs []string, name string, perm os.FileMode) error) TreeOption { return func(d *Tree) { d.createFn = fn } } // WithDeleter overrides file deletion logic. -func WithDeleter(fn func(dirs []string, name string) error) Option { +func WithDeleter(fn func(dirs []string, name string) error) TreeOption { return func(d *Tree) { d.deleteFn = fn } } // WithRenamer overrides rename logic. -func WithRenamer(fn func(dirs []string, old, new string) error) Option { +func WithRenamer(fn func(dirs []string, old, new string) error) TreeOption { return func(d *Tree) { d.renameFn = fn } } // WithOpener overrides how entries are opened (bypasses filesystem read). -func WithOpener(fn func(dirs []string, name string) (File, error)) Option { +func WithOpener(fn func(dirs []string, name string) (File, error)) TreeOption { return func(d *Tree) { d.openFn = fn } } // WithStat overrides how entries are stat'd. -func WithStat(fn func(dirs []string, name string) (os.FileInfo, error)) Option { +func WithStat(fn func(dirs []string, name string) (os.FileInfo, error)) TreeOption { return func(d *Tree) { d.statFn = fn } } // WithReaddir overrides subdirectory listing. -func WithReaddir(fn func(dirs []string, name string) ([]os.DirEntry, error)) Option { +func WithReaddir(fn func(dirs []string, name string) ([]os.DirEntry, error)) TreeOption { return func(d *Tree) { d.readdirFn = fn } } // NewTree creates a Tree backed by one or more directories. // The first directory is the write target for unions. -func NewTree(dirs []string, perm os.FileMode, opts ...Option) *Tree { +func NewTree(dirs []string, perm os.FileMode, opts ...TreeOption) *Tree { d := &Tree{Tree: dirs, perm: perm} for _, o := range opts { o(d) diff --git a/go.mod b/go.mod index 0c4e430..293ab9f 100644 --- a/go.mod +++ b/go.mod @@ -9,6 +9,9 @@ require ( github.com/simonfxr/pubsub v0.0.5 golang.org/x/time v0.15.0 gopkg.in/yaml.v3 v3.0.1 + ollie/fsedsl v0.0.0 ) require golang.org/x/sys v0.47.0 // indirect + +replace ollie/fsedsl => ./fsedsl