settings

package
v0.93.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package settings reads gofastr.settings.yml, the one committed file that holds a project's gofastr configuration. Each top-level section belongs to one reader: codegen and endpoints to `gofastr generate`, contracts to `gofastr verify`, isolation to the running app, unmounted to the CLI's record of copied packages. This package finds the file and checks its top level; each reader decodes its own section. The unmounted and endpoints sections are decoded here, since several commands share each.

Index

Constants

View Source
const FileName = "gofastr.settings.yml"

FileName is the settings file's name at the project root.

Variables

This section is empty.

Functions

func CheckEndpoints added in v0.93.0

func CheckEndpoints(entries []Endpoint) error

CheckEndpoints checks entries the way DecodeEndpoints checks a decoded list: each entry's shape, then that no two share a name or a route.

func FormatEndpoints added in v0.93.0

func FormatEndpoints(entries []Endpoint) string

FormatEndpoints renders entries as the endpoints section, the bytes SetEndpoints writes.

func IsProjectRoot

func IsProjectRoot(dir string) bool

IsProjectRoot reports whether dir holds a project root marker.

func IsSection

func IsSection(name string) bool

IsSection reports whether name is one of the file's reader sections, for a reader of another file that wants to point a misplaced key here.

func SearchDirs

func SearchDirs(start string) ([]string, error)

SearchDirs lists the directories Find searches: start and each parent up to and including the project root. With no root marker anywhere above start it returns start alone: an unmarked tree says nothing about where the project ends.

func SetEndpoints added in v0.93.0

func SetEndpoints(p string, entries []Endpoint) error

SetEndpoints writes entries as the endpoints section of the settings file at p, the way SetUnmounted writes its section: the rest of the file keeps its bytes, the section is replaced whole, and the result must read back as exactly entries before it is written.

func SetUnmounted

func SetUnmounted(p string, entries []Unmounted) error

SetUnmounted writes entries as the unmounted section of the settings file at p, creating the file when it does not exist. The rest of the file keeps its bytes and comments, trailing blank lines aside; the unmounted section is gofastr's to write, so it is replaced whole (an empty list removes it, and the file with it when nothing else is left). The result is parsed back before it is written and must hold exactly entries, so a write never leaves a file the readers refuse or a section the rewrite failed to find.

Types

type Endpoint added in v0.93.0

type Endpoint struct {
	// Name is the endpoint's snake_case name. The generated calls are named
	// after it: RefundOrder in Go, refundOrder in JS, refund-order in the
	// CLI.
	Name string
	// Entity is the entity the route hangs under.
	Entity string
	// Method is the HTTP method, upper case.
	Method string
	// Path is relative to the entity's route: "{id}/refund" on orders
	// serves /orders/{id}/refund.
	Path string
	// Handler links the Go handler: a file in the entities package and the
	// func or var in it, "entities/refunds.go#RefundOrder".
	Handler string
	// Description is one line of prose for docs, OpenAPI and the MCP tool.
	Description string
	// MCP also registers the endpoint as an MCP tool.
	MCP bool
	// Public serves callers with no session, over HTTP and as an MCP tool.
	// Without it both answer only a signed-in caller.
	Public bool
}

Endpoint is one entry of the endpoints section: a custom route on an entity, served by a typed handler the entry links to. `gofastr generate` reads the handler's input and output types from the Go source and writes the registration, and the generated Go client, JS SDK and CLI each get a typed call for it.

func DecodeEndpoints added in v0.93.0

func DecodeEndpoints(section *coreyaml.Node, at string) ([]Endpoint, error)

DecodeEndpoints decodes an endpoints list, checking it the way the settings file's section is checked. at names the list in errors. The app spec's endpoints: key decodes through it, so an app spec holds exactly what the settings section holds.

func (Endpoint) HandlerFile added in v0.93.0

func (e Endpoint) HandlerFile() string

HandlerFile is the linked file, slash-separated and relative to the settings file.

func (Endpoint) HandlerName added in v0.93.0

func (e Endpoint) HandlerName() string

HandlerName is the linked func or var.

func (Endpoint) PathParams added in v0.93.0

func (e Endpoint) PathParams() []string

PathParams lists the {name} segments of Path in order.

func (Endpoint) Validate added in v0.93.0

func (e Endpoint) Validate() error

Validate checks one entry's shape. Whether the entity exists and the handler's types fit is the generator's check: it needs the source.

type File

type File struct {
	// Path is the file's path, absolute when Find located it.
	Path string
	// Dir is the directory holding the file: the project root its
	// relative paths resolve against.
	Dir string
	// contains filtered or unexported fields
}

File is a parsed settings file.

func Find

func Find(start, section string) (f File, ok bool, err error)

Find looks for FileName in start and each parent up to the project root (the first directory holding go.work, go.mod or .git), never past it. A settings file can name a command that generate runs, so one planted in a shared ancestor (a workspace parent, /tmp, $HOME) must never apply. With no project root above start, only start itself is searched. ok is false when no settings file is found.

section names the reader. A file that used to hold that section on its own (gofastr.codegen.yml for codegen) is an error naming where its content goes now.

func Load

func Load(path string) (File, error)

Load reads and checks the settings file at path.

func Parse

func Parse(path string, data []byte) (File, error)

Parse checks a settings document: a map whose keys are known sections, with version 1 when a version is given. An empty document is a file with no sections.

func (File) Endpoints added in v0.93.0

func (f File) Endpoints() ([]Endpoint, error)

Endpoints decodes the endpoints section, nil when the file has none. Every key is checked: an entry lands in generated Go, so a value outside its shape is refused here rather than escaped later.

func (File) Root

func (f File) Root() *coreyaml.Node

Root returns the whole parsed document, for a reader whose decoder takes the file with its section in place.

func (File) Section

func (f File) Section(name string) *coreyaml.Node

Section returns the named top-level section, or nil when the file has none.

func (File) Unmounted

func (f File) Unmounted() ([]Unmounted, error)

Unmounted decodes the unmounted section, nil when the file has none.

type Unmounted

type Unmounted struct {
	// Source is the upstream import path the copy was made from.
	Source string
	// Version is the gofastr version copied: a release tag, or dev for a
	// copy made from a checkout.
	Version string
	// Path is the copy's directory, slash-separated and relative to the
	// settings file.
	Path string
	// Date is the day the copy was made, YYYY-MM-DD.
	Date string
}

Unmounted is one entry of the unmounted section: a gofastr package the project copied into its own tree with `gofastr unmount`. The section is the CLI's registry of copies; `gofastr unmount` and `gofastr remount` write it, and verify, upgrade and audit read it.

func (Unmounted) Validate

func (u Unmounted) Validate() error

Validate checks one entry: an import path, a plain version, a local slash path and a calendar date. Every field lands in YAML and in generated Go, so nothing outside those shapes is written or read.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL