Skip to main content

Endpoint DSL

Each part of an endpoint group: a route of the controller, its spec and its commands. osapi controller endpoint spec get prints the same list from this build. Building an endpoint tells how to write one.

Definition​

Register(Define(name, doc, options...))​

Declares the group and adds it to the registry. The commands and the tests read the registry. Each path of the group starts /api/<name>.

Use: One time, in <group>.go under internal/controller/endpoints/<group>: var Group = endpoint.Register(endpoint.Define(...)). Add its import to internal/controller/endpoints/all.

Options of Define​

Title("title")​

Sets the title of the group's spec. The joined spec puts it in front of each tag, and the UI's client files get their names from the result.

Use: When a group moves from a hand-written spec: copy its info.title, so no client file is renamed.

Uses[Deps]()​

Names the struct of what the group's handlers use, such as the job client. The controller gives one at startup, and a test gives one with fakes. It is the place of the host in a behavior.

Use: In each group that is served. Keep it to interfaces, so a test can fake each one.

Doc[T]("description")​

Describes T, a named type, in its schema. Go has no tag on a type, so a group says it here.

Use: For each type whose schema has a description, such as one that another spec defines too: the join fails when two specs define one schema in different words.

Example[T]("field", "example")​

Gives the field of T with that json name its example in the schema.

Use: For an example with a double quote, such as a JSON document. A struct tag cannot keep the backslash of a quote, because the formatters drop it.

Tag("name", "display", "doc")​

Sets the tag of each operation, its name in the docs and its description.

Use: When a group moves: copy its tag. A new group can leave it; the tag is then the group's name.

CommandLong("text")​

Is the rest of the help of the group's command, after its one line.

Use: When the group's command needs more than its one line, such as what most of its commands read.

SubDoc("segment", "short")​

Is the one line of help of the command that a Sub segment makes, such as trace in osapi client telemetry trace. Without it, the command says <Segment> commands.

Use: For each Sub segment of the group, so its command says what it holds.

CommandNotes("text")​

Adds a Notes section to the page of the group's own command, such as a link to a page that tells more about the group.

Use: When the group's command has a page of its own to point at, as each behavior's does.

Prefix("next/node/{hostname}")​

Puts each path of the group under a prefix, between /api/ and the group's name. Each {field} of the prefix is an in:"path" field of each method's input, which is not the method's key.

Use: For the groups that the behavior generator writes, whose paths start with the target host. A group of the controller has none. The fixed segments are the command's path too: next node sysctl.

Methods​

Get[In, Out]("name")​

A GET that takes In and answers with Out. Its permission is <group>:read.

Use: For a read.

Post[In, Out]("name")​

A POST that takes In and answers with Out. Its permission is <group>:write.

Use: For a create, or an action such as drain.

Put[In, Out]("name")​

A PUT that takes In and answers with Out. Its permission is <group>:write.

Use: For an update of the thing the key names.

Delete[In, Out]("name")​

A DELETE that takes In and answers with Out. Its permission is <group>:write.

Use: For a removal.

Refinements of a method​

.Handle(fn)​

Sets the function that runs the method: func(ctx context.Context, d Deps, in In) (Out, error). The generated route decodes and validates In, calls it, and maps its error with Errors. Only the route calls it; other code that needs the work goes through the API.

Use: On each method of a group that Uses a type. Validate checks the signature.

.Sub("segment")​

Puts a fixed segment after the group's name, before the key: /api/<group>/<segment>[/{key}]. When the segment is not the method's name, the CLI command is under it too: osapi client <group> <segment> <method>.

Use: For a path beside the key, such as /api/agent/pending, or before it, such as /api/telemetry/trace/{id}.

.Action("segment")​

Puts a segment after the key: /api/<group>/{key}/<segment>.

Use: For an action on one thing, such as /api/agent/{hostname}/drain. Needs a key.

.ID("operationId")​

Sets the operationId. The Go SDK and the UI client get their names from it. Without it, the ID is the verb, the group, the Sub and the name.

Use: When a group moves: keep the ID of the hand-written spec, so no name that a program calls changes.

.Describe("summary")​

Sets the summary: what the method does, in one line.

Use: Always.

.Explain("text")​

Sets the description: the rest of what a caller needs to know.

Use: When the summary is not enough, such as what occurs when two agents share a hostname.

.Returns("doc")​

Describes the response of a success. Without it, the summary describes it.

Use: When the response needs its own words, such as "List of active agents.".

.Command("short", "long")​

Sets the CLI command's own help: its one line and the rest. Without it, the command has the summary and the description of the API. The one line, and the doc of each input field that becomes a flag's help, start with a capital letter and have no period at the end; the long help is sentences. A test of every command holds this.

Use: When the CLI needs words for a person at a shell, such as what the command reads and what to run next.

.Fails("doc", in)​

Declares an input that the API refuses with 400: the method's input, with the other fields valid and one rule broken. A test sends each one through the routes. Each rule of an input field has a .Fails input that breaks it, which the API refuses with 400. An endpoint's required needs one, with the field empty; a behavior's needs none, as its generated tests leave the field out. A path field's required, and a min of 1 on a string that is required, optional or in the path, need none: their only bad value is empty.

Use: For each rule of each input field, as validate requires, and for each input that the method refuses for another reason.

.Example("--flag value", "doc")​

Adds an example of the CLI command: the flags after osapi client <group> <method>, and, when given, what it shows, as a # line above it. The help and the CLI page show each one.

Use: At least one for each method: the call a person makes most.

.Use("name")​

Names the CLI command apart from the method. A method whose Sub differs from its command name goes under a command of the Sub.

Use: When the command's verb is a method name the group has already, such as list under pending beside the group's own list.

.Location("field")​

Gives a 201 the Location header: the group's path and the value of the output's field with that json name.

Use: For each method that creates a resource and answers 201, such as job retry with job_id.

.Answers(code, "doc")​

Adds a status that the method answers with its own output, not an ErrorResponse. The method returns its output with endpoint.Answer(code).

Use: For a probe whose failure has a body that says what failed, such as the 503 of health ready.

.Notes("text")​

Adds a Notes section to the CLI command's page.

Use: For what a person needs that the help does not say, such as what --json has that the table does not.

.Result("text")​

Adds a Result section to the CLI command's page.

Use: For what the command does in a case that needs words, such as when two agents share a hostname.

.Permission("group:verb")​

Names the permission the method needs, in place of <group>:read or <group>:write.

Use: When a different permission covers it, such as agent:read for facts, or trace:read for telemetry.

.Public()​

Makes the method need no token. It has no 401 or 403.

Use: Only for the health probes that a load balancer calls.

.Status(code)​

Sets the status of a success. 204 has no body.

Use: For 201 after a create or a retry, or 204 after a delete with nothing to return.

.Says("state")​

Sets what the CLI prints for a method that answers with no body: the key of the input, then the text, such as web-01 draining. Without it, the CLI prints the past tense of the method, such as m-1 admitted for admit.

Use: On a method that answers 204 and whose result is a state, not the past tense of the method, such as drain.

.Errors(errors...)​

Maps the errors a method returns to status codes. An error that is not in the list is a 500. Each method also gets 400 when it has an input, 401 and 403 when it is not public, and 500.

Use: For each answer a caller acts on, such as 404 or 409. Never map a failure of the controller to 409.

Errors a method maps​

Errorf(sentinel, "format", args...)​

Is an error whose text is the message, and that errors.Is matches to sentinel. The answer has the status that Errors maps sentinel to, and the message as its error.

Use: In a handler, to answer 404 or 409 with a message that names what it was called with, such as no pending agent with hostname "web-01".

Internal("msg", cause)​

Is a failure of the controller whose cause stays out of the answer: the caller gets msg and a 500, and the log gets the cause.

Use: When the cause has what a caller must not see, such as the address or the error of a backend.

NotFound(err, "doc")​

Maps err to 404.

Use: When the thing the key names is not there.

Conflict(err, "doc")​

Maps err to 409.

Use: When the state of the thing does not allow the call, such as an agent that is already drained.

Answer(code)​

Returned with the method's output, sends that output with code: a status that .Answers added.

Use: When a probe fails and its body says what failed, such as health ready's 503.

Forbidden(err, "doc")​

Maps err to 403. Its doc is the 403's description, so say the permission failure too.

Use: When the token may make the request, but not on this thing, such as a write to a file that osapi owns.

Invalid(err, "doc")​

Maps err to 400. Its doc is the 400's description, so say the decode failures too.

Use: When the request is well formed but the method cannot do it, such as a retry of a job with no operation data.

Unavailable(err, "doc")​

Maps err to 503.

Use: When a backend the method needs is not set, such as the trace backend.

What a Deps takes​

an interface of the group, in deps.go​

Each field of Deps is an interface that the group declares in its deps.go, with only the methods that its handlers call. internal/controller/handlers.go gives the real service of the controller. The tests give the mockgen mock from the group's mocks/, so a handler test sets what each call returns and asserts each call it makes.

Use: For each service that a handler uses. Declare a narrow interface, not the concrete type, and never write a fake by hand. A group whose service the controller may not have, such as a store with no bucket, checks for nil.

Jobs​

The job client of the controller: it lists and reads the agents and the jobs, sets the drain flag, writes the timeline of an agent, and deletes and retries jobs. handlers.go gives d.jobs.

Use: For a group that reads or changes the agents or the jobs, such as agent, job and admission. A request that runs on a host is a behavior, not a Jobs call of an endpoint.

Store​

A store of the controller in its own KV bucket: the admission records of the agents, or the entries of the audit log.

Use: For the group that owns the records. A Store can be nil when the controller has no bucket for it; the group answers that the feature is off.

Objects, States​

The Object Store, which holds the files that osapi client file upload stores, and the file-state KV, whose keys are the files that agents deployed. fileDeps in handlers.go opens both.

Use: For the file group. An agent reads an object through the object behavior, not through an endpoint.

Health​

The health.Reporter of the controller: the state of NATS, the controller and its parts, for the health, controller, nats and agent groups.

Use: For a group that reports whether a part of osapi is up.

Traces​

The TraceReader: it reads one trace from the tracing backend that the config names, for osapi client telemetry trace get.

Use: For the telemetry group.

Tags on input and output fields​

param:"Name"​

Makes a path field a shared parameter: the spec has it once, under components.parameters.Name, and each operation refers to it.

Use: On a path field that each method of a group has, such as the hostname of a behavior's target.

in:"path"​

Makes the input field the key: {name} in the path. It is required. A method has at most one, besides the fields that the group's Prefix names.

Use: For the field that names the thing, such as hostname or id.

in:"query"​

Makes the input field a query parameter.

Use: For a filter, a page or an option, such as status, limit or force.

in:"form"​

Makes the field a part of a multipart/form-data body. A []byte field is the file, a string of format binary.

Use: For an upload of a file, such as POST /api/file.

in:"body"​

Makes the field's type the whole request body. Without it, the input's other fields are the body, as one object. The body is optional unless the field is validate:"required".

Use: When the body is a named schema, such as a retry request.

flag:"name"​

Names the field's CLI flag. Without it, the flag is the json name with _ as -. A field of an in:"body" struct is a flag too.

Use: When the flag has a name that the CLI uses elsewhere, such as --target for target_hostname.

short:"T"​

Gives the field's CLI flag a one-letter shorthand.

Use: When the CLI uses that shorthand elsewhere, such as -T for a target.

json:"name"​

Names the field in JSON, the parameter and the schema property. In an output type, a field without ,omitempty or ,omitzero is required.

Use: On each field.

doc:"..."​

Describes the field in the spec.

Use: On each field a caller reads or sets.

example:"..."​

Gives the field an example in the spec and the API docs: a number for an integer or a number, true or false for a boolean, and the text for the rest.

Use: On each field a caller reads, so the docs show a value.

default:"20"​

Gives a field its default in the spec, and its CLI flag the same value. The method still sees the zero value when the caller sends none, and applies the default itself.

Use: For an optional query parameter, such as limit.

pattern:"^...$"​

Gives a string field a regular expression, in the spec, and the generated route answers 400 for a value that does not match.

Use: For an ID of a fixed form, such as a trace ID of 32 hexadecimal characters.

validate:"..."​

The rules the server checks before the method runs: a value that breaks one is a 400 with {"error": "..."}. required makes the field required, oneof gives an enum, min, max and len the length of a string, the items of an array or the bounds of a number, startswith a pattern, and uuid, email, hostname, ip, ipv4, ipv6, cidr, url and uri a format. The spec carries these, and the whole tag in x-oapi-codegen-extra-tags. A custom rule, such as sysctl_key, needs its schema from rule.Register; a rule with none fails the spec. In an endpoint, the generated route checks them before the handler runs, and a handler runs only from its route: TestHandlersRunFromRoutes, in internal/controller/endpoints/all, fails a call of it from other code. The author writes no check.

Use: On each input field. A field with no limit is validate:"omitempty"; validate refuses an input field with no tag.

rule.Register("tag", rule.Pattern(re))​

Declares what a custom validate rule means in the spec: rule.Pattern(re), rule.Format(f), or rule.None for a rule that the spec cannot show, such as a target the controller resolves.

Use: Beside the validator of a new custom rule, in internal/validation.

time.Time​

Is a string with the date-time format. An int64 is an integer of format int64 and the other integers have none; a float64 is a number of format double and a float32 has none; as oapi-codegen maps them back.

Use: For a timestamp. Tag an optional one ,omitzero: ,omitempty does not leave out a zero time.

a named struct, or a struct with no name​

A named struct is a schema in the components, with its name. A struct with no name, or an alias of one, is in place.

Use: Give a type the name its schema has. Use an alias of a struct with no name, such as Message, for a schema that the spec has in place.

What holds a group to its spec​

TestEndpointParity​

Compares the contract of a group's spec with its hand-written spec, line by line: tags, operations, parameters, auth, bodies, responses and schemas. Prose is not compared.

Use: Add a row to moving in internal/controller/endpoints/all/parity_public_test.go for a group that moves. A difference on purpose is accepted with its reason and an issue.

SentEmpty(fields)​

The optional rule: each optional field of a request body, with omitempty in its validate tag and none in its json tag, which a client would send as "" or 0. controller endpoint validate checks each write with it, and behavior validate checks each behavior write's body with the same func.

Use: Add ,omitempty to the json tag of each field it names.

TestJoinedSpec​

Holds the joined spec to its contract, internal/apicontract/testdata/joined.golden.

Use: When you change the API on purpose, run it with -update and keep the diff.

osapi controller endpoint openapi get --name <group>​

Prints the group's spec, as the definition makes it.

Use: To read the prose beside the hand-written spec.

go generate ./internal/controller/endpoints/all​

Writes, for each group that Uses a type, gen/api.yaml, the routes in gen/api.go, the decoders in gen/decode.go and the CLI commands in gen/cli.go, one for each method under osapi client <group>, and internal/controller/endpoints/all/gen, which registers every group's routes and commands. just generate then joins gen/api.yaml into the main spec.

Use: After each change to a group. go-generate-check fails when a gen/ file is stale. Never edit a gen/ file.

osapi controller endpoint create --name <group> --description "..."​

Writes a new group under internal/controller/endpoints/<group>: a list and a get, an empty Deps, its types and the tests of its methods, and adds its import to internal/controller/endpoints/all. It builds, validates and passes its tests; endpoint-scaffold-check in just test holds it to that.

Use: To start a new group. Then run go generate ./internal/controller/endpoints/all and just generate, and change it.

Deps in internal/controller/handlers.go​

The controller gives each group its Deps, such as agentDeps. An empty Deps needs no wiring. A group whose Deps has a field and is not given stops the controller at startup.

Use: When a group's Deps gets its first field: add a line there, and a nil pointer must be a nil interface.

Generated, never edited​

internal/controller/endpoints/<group>/gen/​

The routes, decoders, CLI commands and spec of the group, from go generate ./internal/controller/endpoints/all.

Use: Change the definition, then generate. A generated file that is wrong is fixed in the definition or in internal/controller/endpoint/gen.

internal/controller/endpoints/<group>/mocks/​

The doubles of the group's Deps, from go generate ./internal/controller/endpoints/<group>/mocks.

Use: Run it again after deps.go changes.

internal/controller/endpoints/all/gen/​

The import of each group's gen package, so the controller registers its routes and commands, from go generate ./internal/controller/endpoints/all.

Use: Change the definition, then generate. A generated file that is wrong is fixed in the definition or in internal/controller/endpoint/gen.

docs/docs/sidebar/usage/cli/​

The CLI pages, from just cli-docs-generate. The help of an endpoint command comes from .Command, .Example, .Notes, .Result and each input field's doc.

Use: Change the definition, then generate. A generated file that is wrong is fixed in the definition or in internal/controller/endpoint/gen.

internal/controller/api/gen/, pkg/sdk/client/gen/, ui/src/sdk/gen/, docs/docs/gen/​

The joined spec, the SDK, the UI client and the API pages, from just generate.

Use: Change the definition, then generate. A generated file that is wrong is fixed in the definition or in internal/controller/endpoint/gen.