From 72cf1553e87bef43a4d988896d98034ddfbc018c Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Mon, 6 Jul 2026 09:57:54 +0300 Subject: move more into API --- api/api.go | 39 +++++++++ api/option/option.go | 140 ++++++++++++++++++++++++++++++++ examples/examples.go | 36 ++++----- internal/resource/dir/dir.go | 2 +- internal/resource/dir/dir_test.go | 2 +- internal/resource/dir/source.go | 2 +- internal/resource/file/file.go | 2 +- internal/resource/file/file_test.go | 2 +- internal/resource/link/link.go | 2 +- internal/resource/link/link_test.go | 2 +- internal/resource/opt/opt.go | 156 ------------------------------------ 11 files changed, 203 insertions(+), 182 deletions(-) create mode 100644 api/api.go create mode 100644 api/option/option.go delete mode 100644 internal/resource/opt/opt.go diff --git a/api/api.go b/api/api.go new file mode 100644 index 0000000..d82c2c8 --- /dev/null +++ b/api/api.go @@ -0,0 +1,39 @@ +package api + +import ( + "codeberg.org/snonux/gonf/api/option" + "codeberg.org/snonux/gonf/internal/resource" + "codeberg.org/snonux/gonf/internal/resource/dir" + "codeberg.org/snonux/gonf/internal/resource/file" + "codeberg.org/snonux/gonf/internal/resource/link" +) + +// File creates a file resource. +func File(path string, opts ...option.Option) resource.Resource { + return file.Have(path, opts...) +} + +// NoFile creates a file resource that is ensured to be absent. +func NoFile(path string, opts ...option.Option) resource.Resource { + return file.Absent(path, opts...) +} + +// Dir creates a directory resource. +func Dir(path string, opts ...option.Option) resource.Resource { + return dir.Have(path, opts...) +} + +// NoDir creates a directory resource that is ensured to be absent. +func NoDir(path string, opts ...option.Option) resource.Resource { + return dir.Absent(path, opts...) +} + +// Link creates a link resource (symbolic or hard). +func Link(path string, opts ...option.Option) resource.Resource { + return link.Have(path, opts...) +} + +// NoLink creates a link resource that is ensured to be absent. +func NoLink(path string, opts ...option.Option) resource.Resource { + return link.Absent(path, opts...) +} diff --git a/api/option/option.go b/api/option/option.go new file mode 100644 index 0000000..b5d2531 --- /dev/null +++ b/api/option/option.go @@ -0,0 +1,140 @@ +// Package option provides interface-based, resource-agnostic configuration +// options shared by the file, dir, and link resource packages. +package option + +import ( + "log" + "os" +) + +// Option configures a resource. It is applied to the concrete resource value +// (e.g. *file.File) during construction. +type Option func(any) + +// Capability interfaces. A resource implements only the setters it supports. +type ( + Owner interface{ SetOwner(string) } + Grouped interface{ SetGroup(string) } + Moded interface{ SetMode(os.FileMode) } + Sourced interface{ SetSource(string) } + Contented interface{ SetContent(string) } + FileModed interface{ SetFileMode(os.FileMode) } + Prunable interface{ SetPrune() } + Absentable interface{ SetAbsent() } + Linkable interface { + SetSymlink(target string) + SetHardlink(target string) + } +) + +// WithOwner sets the owning user of the resource. +func WithOwner(owner string) Option { + return func(t any) { + r, ok := t.(Owner) + if !ok { + log.Fatalf("%T does not support WithOwner", t) + } + r.SetOwner(owner) + } +} + +// WithGroup sets the owning group of the resource. +func WithGroup(group string) Option { + return func(t any) { + r, ok := t.(Grouped) + if !ok { + log.Fatalf("%T does not support WithGroup", t) + } + r.SetGroup(group) + } +} + +// WithMode sets the resource's own file mode. +func WithMode(mode os.FileMode) Option { + return func(t any) { + r, ok := t.(Moded) + if !ok { + log.Fatalf("%T does not support WithMode", t) + } + r.SetMode(mode) + } +} + +// WithSource sets the source path the resource is populated from. +func WithSource(source string) Option { + return func(t any) { + r, ok := t.(Sourced) + if !ok { + log.Fatalf("%T does not support WithSource", t) + } + r.SetSource(source) + } +} + +// WithContent sets literal content for the resource. +func WithContent(content string) Option { + return func(t any) { + r, ok := t.(Contented) + if !ok { + log.Fatalf("%T does not support WithContent", t) + } + r.SetContent(content) + } +} + +// WithFileMode sets the mode applied to regular files copied from a source +// tree (distinct from the resource's own mode). +func WithFileMode(mode os.FileMode) Option { + return func(t any) { + r, ok := t.(FileModed) + if !ok { + log.Fatalf("%T does not support WithFileMode", t) + } + r.SetFileMode(mode) + } +} + +// WithPrune enables reconciliation of extra destination entries during a +// source copy, and recursive removal during IsAbsent(). +func WithPrune() Option { + return func(t any) { + r, ok := t.(Prunable) + if !ok { + log.Fatalf("%T does not support WithPrune", t) + } + r.SetPrune() + } +} + +// IsAbsent marks the resource for removal. +func IsAbsent() Option { + return func(t any) { + r, ok := t.(Absentable) + if !ok { + log.Fatalf("%T does not support IsAbsent", t) + } + r.SetAbsent() + } +} + +// WithSymlink makes the resource a symbolic link pointing at target. +func WithSymlink(target string) Option { + return func(t any) { + r, ok := t.(Linkable) + if !ok { + log.Fatalf("%T does not support WithSymlink", t) + } + r.SetSymlink(target) + } +} + +// WithHardlink makes the resource a hard link pointing at target. +func WithHardlink(target string) Option { + return func(t any) { + r, ok := t.(Linkable) + if !ok { + log.Fatalf("%T does not support WithHardlink", t) + } + r.SetHardlink(target) + } +} diff --git a/examples/examples.go b/examples/examples.go index 346d74a..1a1df0b 100644 --- a/examples/examples.go +++ b/examples/examples.go @@ -3,44 +3,42 @@ package examples import ( "os" + . "codeberg.org/snonux/gonf/api" + . "codeberg.org/snonux/gonf/api/option" "codeberg.org/snonux/gonf/internal/resource" - "codeberg.org/snonux/gonf/internal/resource/dir" - "codeberg.org/snonux/gonf/internal/resource/file" - "codeberg.org/snonux/gonf/internal/resource/link" - . "codeberg.org/snonux/gonf/internal/resource/opt" ) func Run() error { // 1. Regular file with content - file.Have("/tmp/gonf_hello.txt", WithContent("Hello World!")) + File("/tmp/gonf_hello.txt", WithContent("Hello World!")) // 2. Regular file from a source template - file.Have("/tmp/gonf_example.conf", WithSource("assets/testfiles/test.tmpl")) + File("/tmp/gonf_example.conf", WithSource("assets/testfiles/test.tmpl")) // 3. Regular file with specific mode and owner - file.Have( + File( "/tmp/gonf_secret.txt", WithContent("top secret"), WithMode(0o600), ) // 4. A directory - dir.Have("/tmp/gonf_dir", WithMode(0o755)) + Dir("/tmp/gonf_dir", WithMode(0o755)) // 5. A symlink - link.Have("/tmp/gonf_link", WithSymlink("/tmp/gonf_hello.txt")) + Link("/tmp/gonf_link", WithSymlink("/tmp/gonf_hello.txt")) // 6. A hardlink - link.Have("/tmp/gonf_hardlink", WithHardlink("/tmp/gonf_hello.txt")) + Link("/tmp/gonf_hardlink", WithHardlink("/tmp/gonf_hello.txt")) // 7. Ensuring something is absent (two equivalent styles; each resource // path may only be declared once per run, so they use distinct paths) - file.Have("/tmp/gonf_old.txt", IsAbsent()) - file.Absent("/tmp/gonf_old_alt.txt") // Alternative way + File("/tmp/gonf_old.txt", IsAbsent()) + NoFile("/tmp/gonf_old_alt.txt") // Alternative way // 8. A directory tree copied from source, reconciled, with a distinct // file mode from the directory's own mode - dir.Have( + Dir( "/tmp/gonf_dir_from_source", WithSource("assets/testfiles"), WithPrune(), @@ -52,23 +50,23 @@ func Run() error { // (rather than reusing #8's path) to give WithPrune's recursive removal // something real to demonstrate. _ = os.MkdirAll("/tmp/gonf_stale_dir/nested", 0o755) - dir.Have("/tmp/gonf_stale_dir", IsAbsent(), WithPrune()) + Dir("/tmp/gonf_stale_dir", IsAbsent(), WithPrune()) _ = os.MkdirAll("/tmp/gonf_stale_dir_alt/nested", 0o755) - dir.Absent("/tmp/gonf_stale_dir_alt", WithPrune()) // Alternative way + NoDir("/tmp/gonf_stale_dir_alt", WithPrune()) // Alternative way // 10. Non-recursively removing an empty directory _ = os.Mkdir("/tmp/gonf_stale_empty_dir", 0o755) - dir.Have("/tmp/gonf_stale_empty_dir", IsAbsent()) + Dir("/tmp/gonf_stale_empty_dir", IsAbsent()) // 11. Ensuring a symlink is absent _ = os.Symlink("/tmp/gonf_hello.txt", "/tmp/gonf_stale_link") - link.Have("/tmp/gonf_stale_link", IsAbsent()) + Link("/tmp/gonf_stale_link", IsAbsent()) _ = os.Symlink("/tmp/gonf_hello.txt", "/tmp/gonf_stale_link_alt") - link.Absent("/tmp/gonf_stale_link_alt") // Alternative way + NoLink("/tmp/gonf_stale_link_alt") // Alternative way // 12. Ensuring a hardlink is absent _ = os.Link("/tmp/gonf_hello.txt", "/tmp/gonf_stale_hardlink") - link.Have("/tmp/gonf_stale_hardlink", IsAbsent()) + Link("/tmp/gonf_stale_hardlink", IsAbsent()) return resource.Apply() } diff --git a/internal/resource/dir/dir.go b/internal/resource/dir/dir.go index ba50caf..34b161d 100644 --- a/internal/resource/dir/dir.go +++ b/internal/resource/dir/dir.go @@ -8,7 +8,7 @@ import ( "strconv" "codeberg.org/snonux/gonf/internal/resource" - "codeberg.org/snonux/gonf/internal/resource/opt" + opt "codeberg.org/snonux/gonf/api/option" ) type Dir struct { diff --git a/internal/resource/dir/dir_test.go b/internal/resource/dir/dir_test.go index 8b90fac..6a5bb83 100644 --- a/internal/resource/dir/dir_test.go +++ b/internal/resource/dir/dir_test.go @@ -8,7 +8,7 @@ import ( resource "codeberg.org/snonux/gonf/internal/resource" "codeberg.org/snonux/gonf/internal/resource/file" - . "codeberg.org/snonux/gonf/internal/resource/opt" + . "codeberg.org/snonux/gonf/api/option" ) func TestHaveDirectoryCreate(t *testing.T) { diff --git a/internal/resource/dir/source.go b/internal/resource/dir/source.go index 2e5ed98..b94756d 100644 --- a/internal/resource/dir/source.go +++ b/internal/resource/dir/source.go @@ -9,7 +9,7 @@ import ( "codeberg.org/snonux/gonf/internal/resource/file" "codeberg.org/snonux/gonf/internal/resource/link" - "codeberg.org/snonux/gonf/internal/resource/opt" + opt "codeberg.org/snonux/gonf/api/option" ) // copySourceTree mirrors d.source into d.path, dispatching each entry by diff --git a/internal/resource/file/file.go b/internal/resource/file/file.go index 50ba6e3..402b348 100644 --- a/internal/resource/file/file.go +++ b/internal/resource/file/file.go @@ -11,7 +11,7 @@ import ( "text/template" "codeberg.org/snonux/gonf/internal/resource" - "codeberg.org/snonux/gonf/internal/resource/opt" + opt "codeberg.org/snonux/gonf/api/option" ) type File struct { diff --git a/internal/resource/file/file_test.go b/internal/resource/file/file_test.go index 0669b88..e84ab13 100644 --- a/internal/resource/file/file_test.go +++ b/internal/resource/file/file_test.go @@ -7,7 +7,7 @@ import ( "testing" "codeberg.org/snonux/gonf/internal/resource" - . "codeberg.org/snonux/gonf/internal/resource/opt" + . "codeberg.org/snonux/gonf/api/option" ) func TestGetChecksum(t *testing.T) { diff --git a/internal/resource/link/link.go b/internal/resource/link/link.go index 0e5582c..5a1824b 100644 --- a/internal/resource/link/link.go +++ b/internal/resource/link/link.go @@ -6,7 +6,7 @@ import ( "os" "codeberg.org/snonux/gonf/internal/resource" - "codeberg.org/snonux/gonf/internal/resource/opt" + opt "codeberg.org/snonux/gonf/api/option" ) type kind int diff --git a/internal/resource/link/link_test.go b/internal/resource/link/link_test.go index 20542bd..c8d9789 100644 --- a/internal/resource/link/link_test.go +++ b/internal/resource/link/link_test.go @@ -6,7 +6,7 @@ import ( "testing" "codeberg.org/snonux/gonf/internal/resource" - . "codeberg.org/snonux/gonf/internal/resource/opt" + . "codeberg.org/snonux/gonf/api/option" ) func TestHaveSymlinkCreateAndIdempotent(t *testing.T) { diff --git a/internal/resource/opt/opt.go b/internal/resource/opt/opt.go deleted file mode 100644 index 23f076d..0000000 --- a/internal/resource/opt/opt.go +++ /dev/null @@ -1,156 +0,0 @@ -// Package opt provides interface-based, resource-agnostic configuration -// options shared by the file, dir, and link resource packages. -// -// It is designed to be dot-imported at call sites so options read as bare -// WithMode(...) / WithOwner(...) calls regardless of the resource type: -// -// import ( -// "codeberg.org/snonux/gonf/internal/resource/file" -// . "codeberg.org/snonux/gonf/internal/resource/opt" -// ) -// -// file.Have("file.txt", WithOwner("paul"), WithMode(0o755)) -// -// Each option targets a small capability interface (Owner, Moded, ...). A -// resource implements only the setters it supports. Applying an option to a -// resource that lacks the matching interface (e.g. WithPrune on a file) is a -// programming error in the resource declaration and aborts the program via -// log.Fatalf. -package opt - -import ( - "log" - "os" -) - -// Option configures a resource. It is applied to the concrete resource value -// (e.g. *file.File) during construction. -type Option func(any) - -// Capability interfaces. A resource implements only the setters it supports. -type ( - Owner interface{ SetOwner(string) } - Grouped interface{ SetGroup(string) } - Moded interface{ SetMode(os.FileMode) } - Sourced interface{ SetSource(string) } - Contented interface{ SetContent(string) } - FileModed interface{ SetFileMode(os.FileMode) } - Prunable interface{ SetPrune() } - Absentable interface{ SetAbsent() } - Linkable interface { - SetSymlink(target string) - SetHardlink(target string) - } -) - -// WithOwner sets the owning user of the resource. -func WithOwner(owner string) Option { - return func(t any) { - r, ok := t.(Owner) - if !ok { - log.Fatalf("%T does not support WithOwner", t) - } - r.SetOwner(owner) - } -} - -// WithGroup sets the owning group of the resource. -func WithGroup(group string) Option { - return func(t any) { - r, ok := t.(Grouped) - if !ok { - log.Fatalf("%T does not support WithGroup", t) - } - r.SetGroup(group) - } -} - -// WithMode sets the resource's own file mode. -func WithMode(mode os.FileMode) Option { - return func(t any) { - r, ok := t.(Moded) - if !ok { - log.Fatalf("%T does not support WithMode", t) - } - r.SetMode(mode) - } -} - -// WithSource sets the source path the resource is populated from. -func WithSource(source string) Option { - return func(t any) { - r, ok := t.(Sourced) - if !ok { - log.Fatalf("%T does not support WithSource", t) - } - r.SetSource(source) - } -} - -// WithContent sets literal content for the resource. -func WithContent(content string) Option { - return func(t any) { - r, ok := t.(Contented) - if !ok { - log.Fatalf("%T does not support WithContent", t) - } - r.SetContent(content) - } -} - -// WithFileMode sets the mode applied to regular files copied from a source -// tree (distinct from the resource's own mode). -func WithFileMode(mode os.FileMode) Option { - return func(t any) { - r, ok := t.(FileModed) - if !ok { - log.Fatalf("%T does not support WithFileMode", t) - } - r.SetFileMode(mode) - } -} - -// WithPrune enables reconciliation of extra destination entries during a -// source copy, and recursive removal during IsAbsent(). -func WithPrune() Option { - return func(t any) { - r, ok := t.(Prunable) - if !ok { - log.Fatalf("%T does not support WithPrune", t) - } - r.SetPrune() - } -} - -// IsAbsent marks the resource for removal. -func IsAbsent() Option { - return func(t any) { - r, ok := t.(Absentable) - if !ok { - log.Fatalf("%T does not support IsAbsent", t) - } - r.SetAbsent() - } -} - -// WithSymlink makes the resource a symbolic link pointing at target. -func WithSymlink(target string) Option { - return func(t any) { - r, ok := t.(Linkable) - if !ok { - log.Fatalf("%T does not support WithSymlink", t) - } - r.SetSymlink(target) - } -} - -// WithHardlink makes the resource a hard link pointing at target. -func WithHardlink(target string) Option { - return func(t any) { - r, ok := t.(Linkable) - if !ok { - log.Fatalf("%T does not support WithHardlink", t) - } - r.SetHardlink(target) - } -} -- cgit v1.2.3