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
- func CheckEndpoints(entries []Endpoint) error
- func FormatEndpoints(entries []Endpoint) string
- func IsProjectRoot(dir string) bool
- func IsSection(name string) bool
- func SearchDirs(start string) ([]string, error)
- func SetEndpoints(p string, entries []Endpoint) error
- func SetUnmounted(p string, entries []Unmounted) error
- type Endpoint
- type File
- type Unmounted
Constants ¶
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
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
FormatEndpoints renders entries as the endpoints section, the bytes SetEndpoints writes.
func IsProjectRoot ¶
IsProjectRoot reports whether dir holds a project root marker.
func IsSection ¶
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 ¶
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
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 ¶
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
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
HandlerFile is the linked file, slash-separated and relative to the settings file.
func (Endpoint) HandlerName ¶ added in v0.93.0
HandlerName is the linked func or var.
func (Endpoint) PathParams ¶ added in v0.93.0
PathParams lists the {name} segments of Path in order.
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 ¶
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 Parse ¶
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
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 ¶
Root returns the whole parsed document, for a reader whose decoder takes the file with its section in place.
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.