workarounds

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: GPL-3.0 Imports: 11 Imported by: 1

Documentation

Overview

Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds. The workarounds themselves live with the documents, in the repository that vendors them; this package is the interface they implement, the helpers they share, and the test every one of them must pass (Verify).

Every workaround patches the loaded document before it is normalised, and every one first checks that the bug it fixes is still there: when the document no longer has the problem (a refreshed spec declares the missing parameter, the duplicate operationId is gone) the workaround fails the import instead of silently doing nothing, so dead workarounds get deleted rather than accumulating. The applied names are recorded in the service's definitions.

Only the shape of the document belongs in a workaround: what an operation takes and answers. Behaviour the document cannot express (Emby keying watch state by provider id, a filter it silently drops) stays in the hand-written code over the generated SDK, next to the live tests that found it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddParameters

func AddParameters(spec *openapi.Spec, targets []string, params ...Param) error

AddParameters adds undeclared parameters to operations, each target a method and a path ("GET /Items"), failing when any target already declares one of them.

func Apply

func Apply(all []Workaround, service string, spec *openapi.Spec, log func(string)) ([]string, error)

Apply runs every workaround in all that is for a service, in order, logging each, and returns the names applied.

func JSONResponse

func JSONResponse(op *openapi.Operation, what string) (*openapi.MediaType, error)

JSONResponse is an operation's 200 application/json media type, or the error a workaround returns when the document no longer declares one, rather than a nil pointer where a message is promised. what names the operation in that error.

func Operation

func Operation(spec *openapi.Spec, method, path string) (*openapi.Operation, error)

Operation finds an operation a workaround targets.

func Property

func Property(spec *openapi.Spec, schema, name string) (*openapi.Schema, error)

Property finds a component schema's property.

func Verify

func Verify(all []Workaround, load func(service string) (*openapi.Spec, error)) error

Verify is the test a repository's workarounds must pass, against the documents it vendors: load reads a fresh copy of a service's document. No two workarounds share a name; each is named for its service and says what bug it fixes; the bug is in the document; applying it to the document it already fixed fails, the cheapest stand-in for a document fixed upstream, so it would notice the bug being gone; and on a document that has lost the 200 responses it reads it returns rather than panics. Every problem found is in the error, one to a line.

Each workaround meets its document as the ones before it in the list have left it, in order, which is how Apply applies them: a workaround may depend on a shape an earlier one declared (an enum on an answer the document said nothing of), so it is asked whether it applies to that document, and whether applying it again to the same fails. The no-panic check is on the raw document.

Types

type About added in v0.6.0

type About struct {
	Name, Service, Bug string
}

About is what a default workaround is called, the service it is for and the bug it fixes: what one written by hand says with its Name, Service and Bug methods.

type Answer added in v0.6.0

type Answer struct {
	// contains filtered or unexported fields
}

Answer is what an operation answers, as a default workaround says it: one of JSON, JSONString, Model, ListOf, Shape, File and Text.

func File added in v0.6.0

func File(mediaType string) Answer

File is an answer of a media type that is not JSON, left for the caller to read: an image, a download, a log.

func JSON added in v0.6.0

func JSON() Answer

JSON is JSON of no declared shape, which a method holds raw.

func JSONString added in v0.6.0

func JSONString() Answer

JSONString is a JSON string: text in quotes.

func ListOf added in v0.6.0

func ListOf(schema string) Answer

ListOf is a JSON list of one of the document's component schemas.

func Model added in v0.6.0

func Model(schema string) Answer

Model is JSON that decodes into one of the document's component schemas.

func Shape added in v0.6.0

func Shape(schema *openapi.Schema) Answer

Shape is JSON of a shape the workaround gives, for a document that keeps its schemas with its operations and has none to name.

func Text added in v0.6.0

func Text(mediaType string) Answer

Text is short text that is not JSON, read whole into a string: a path, a version, a pong. It is held as it was sent whatever the server calls it, since one that sends bare text may label it JSON. A long text is a File.

func (Answer) String added in v0.6.0

func (a Answer) String() string

type CommandSet added in v0.8.0

type CommandSet struct {
	Post     string
	Get      string
	Status   string
	Finished []string
	Failed   []string
	Commands map[string]map[string]*openapi.Schema
}

CommandSet is what Commands declares: Post is the operation that queues a command named in its body ("POST /api/v3/command"), Get the one that answers a queued command by its id, Status the field of that answer that says how far the command is, Finished the values that mean it is over and Failed those among them that mean it failed, and Commands each command's name as the server takes it with the fields its body carries beside the name.

type Correction added in v0.6.0

type Correction struct {
	Declared Answer
	Answers  Answer
}

Correction is an answer a document gets wrong: what it declares, and what the server answers.

func ListDeclaredAsOne added in v0.6.0

func ListDeclaredAsOne(schema string) Correction

ListDeclaredAsOne is the commonest correction: the document declares one of a schema, and the server answers a list of them (an update of many that answers every record it changed).

type Enum added in v0.7.0

type Enum struct {
	Name   string
	Values []string
	In     []string
}

Enum is what UndeclaredEnums declares a property to be: its values, as the server writes them, and the name of the type the package holds it as (ContainerState), the property's own name capitalised when empty. In narrows it to some places, for a name whose values differ by place; empty is everywhere. A place is an operation ("GET /api/stacks") or a component schema ("Container"), and may name a path inside it: "GET /api/stacks .status" is the property at the top of the answer alone, "GET /api/stacks containerDetails.status" the one at that path, with lists adding nothing to a path, which is the form the sweep prints a value's place in.

type Joined added in v0.7.0

type Joined struct {
	Of string
	In []string
}

Joined is what JoinedLists declares a string parameter to carry: a list of Of, an enum schema's name or "string", sent as one comma-joined value. In narrows it to some operations ("GET /Items"); empty is every operation that takes the parameter.

type Param

type Param struct {
	Name        string
	In          string
	Type        string
	Description string
}

Param is a parameter a workaround adds: In is openapi.InQuery, InHeader or InPath, and Type one of the openapi types. A header named Accept is how a caller is given the say over what one call asks for, for a server that chooses its answer by it: the option, when set, is the whole header.

type Workaround

type Workaround interface {
	// Name identifies the workaround in logs and in Service.json; it starts
	// with its service's name and a dash.
	Name() string
	// Service is the config service name it applies to.
	Service() string
	// Bug says what is wrong with the document and how the server behaves.
	Bug() string
	// Apply patches the document, or returns an error when the bug it fixes
	// is not there (fixed upstream, or the operation is gone).
	Apply(spec *openapi.Spec) error
}

Workaround fixes one bug in one service's document.

func AlsoAnswers added in v0.7.0

func AlsoAnswers(about About, answers map[string]map[int]Answer) Workaround

AlsoAnswers is for an operation that answers a body at a status its document gives none, success or not (the *arr's test of every provider: a list of results, documented as nothing, as a 200 when all pass and a 400 when any fails): answers says, by method and path, what each status answers, and a status the document does not list is added. With ExpectSameShape on the service, a failure status that answers the success's shape is decoded as an answer. It fails for a status that declares a body already.

func Commands added in v0.8.0

func Commands(about About, set CommandSet) Workaround

Commands is for a server that queues work by name through one operation whose document declares the body as an open record (the *arr's POST /api/v3/command, "{"name": "RefreshSeries", "seriesId": 12}"), so that a caller writes the name and the fields into a map nobody checks. Each command becomes a schema of its own, <Name>Command, with the fields given and the name, and the generated package has a method per command that fixes the name, an AndWait form that polls the queued command until the server says it finished, and WaitForCommand for one queued the plain way. It fails for an operation that is not there, a Post that takes no JSON body, a status with no finished values, a command with no name, a schema the document has, and a Post declared twice.

func DeclaredSchemas added in v0.7.0

func DeclaredSchemas(about About, schemas map[string]*openapi.Schema) Workaround

DeclaredSchemas is for a record a document leaves out altogether (the *arr's result of testing a provider), which a workaround then refers to by name: each schema is added to the document's components. It fails for a name the document has, which is how a document that caught up retires the line.

func DeclaredShapes added in v0.9.0

func DeclaredShapes(about About, fields map[string]*openapi.Schema) Workaround

DeclaredShapes is for a field the document leaves open, a record of no declared fields or a value of no type, that the server writes in a stable shape a program reads (a scrub's state, a task's last run): each field, named <schema>.<property>, takes the schema given, a record declared in place, which becomes a model named for the place, or a reference to one DeclaredSchemas added. It fails for a schema or property that is not there, and for one the document gives a shape now.

func EnumValues added in v0.7.0

func EnumValues(about About, values map[string][]string) Workaround

EnumValues is for an enum the document declares whose server answers a value it does not list (Sonarr's series status answering upcoming): each named component schema gains the values given, so the generated constant exists and Known accepts it and the sweep stops failing the answer. It fails for a schema that is not there or not an enum of strings, and for a value the document lists already, which is how a document that caught up retires the line.

func JoinedLists added in v0.7.0

func JoinedLists(about About, lists map[string]Joined) Workaround

JoinedLists is for the parameters a document declares as one string that the server reads as several values joined by commas (Emby's IncludeItemTypes), so that the package also takes a list, of an enum or of strings, and a caller hands two servers the same list where one takes it joined and the other repeated. The string stays as it is; the list is added beside it as <Field>List, sent under the same name joined, so no caller moves. It fails for a name no plain string parameter has, an Of that is not an enum schema of the document or "string", and an In that matches nothing.

func NamedTypes added in v0.9.0

func NamedTypes(about About, importPath string, fields map[string]string) Workaround

NamedTypes is for a field the server writes in a form of its own that the document cannot describe: a secret it hides from some callers behind a placeholder whatever the field's type, a list it writes two ways. Each field, named <schema>.<property>, is held as the Go type given, written as a package uses it (truenasrpc.Secret[int]) and imported from importPath; the type reads and writes its own JSON. client.Secret[T] is the one for a hidden value. $item in the type stands for the field's own type, or a list's element, as the package names it (truenasrpc.Set[$item]), so the workaround survives the package renaming an enum. It fails for a schema or property that is not there.

func NotAPI added in v0.6.0

func NotAPI(about About, paths ...string) Workaround

NotAPI is for the paths a document lists that are not the API's: the web interface's page, its static files, its login form, which answer HTML to a browser and nothing a client reads. They are taken out of the document. It fails for any that is not there.

func NumberedPathIDs added in v0.7.0

func NumberedPathIDs(about About) Workaround

NumberedPathIDs is for a path parameter a document types as text on one operation and as a number on another of the same path (Sonarr's PUT /tag/{id} takes a string where its GET and DELETE take an integer), which leaves a caller formatting a number it holds. The text one becomes the number the other declares, format kept. A parameter only ever typed as text, a log file's name, is left alone. It fails when it reaches nothing, which is how a document that was fixed is noticed.

func OneRecord added in v0.7.0

func OneRecord(about About, records map[string][]string) Workaround

OneRecord is for a document that declares the same record inline wherever it appears (Dockhand's notification config, declared six times over as many operations), so that the generated package has a model per place and a caller converts between them. Each name is a model to make, and its places are where the record is declared, as a workaround's In names them: an operation and a path inside its answer or its body ("GET /api/notifications config", "POST /api/notifications config", the request and the answer both where an operation has the path on each). Every place becomes a reference to one component schema of the name, so the operations share one model. It fails for a name the document has a schema of already, a place that matches nothing, fewer than two places, and a place whose record differs from the first's, naming the property, which is the check a conversion never made.

func UndeclaredAnswers added in v0.6.0

func UndeclaredAnswers(about About, answers map[string]Answer) Workaround

UndeclaredAnswers is for operations that declare a success with no content, so that nothing says whether they answer JSON, and in what shape, or a file: answers says what each does, by method and path. It fails for any that declares its answer now.

func UndeclaredDates added in v0.7.0

func UndeclaredDates(about About, names ...string) Workaround

UndeclaredDates is for the dates a document declares as plain strings (Dockhand's createdAt, startedAt, expiresAt), so that nothing marks them for the service's Dates: every string property with one of the names, wherever it sits in the document, is declared a date-time. It fails for a name no string property has, which is how a field the server renames is noticed, and for one every property of which is declared a date now.

func UndeclaredDatesExcept added in v0.7.0

func UndeclaredDatesExcept(about About, except map[string][]string, names ...string) Workaround

UndeclaredDatesExcept is UndeclaredDates for a name that is a date everywhere but in some places, where the same name is a string of something else: except says, by operation ("GET /api/audit") or component schema ("Note"), which of the names to leave alone there. It fails for an exception that excludes nothing, which is how a document that changed is noticed.

func UndeclaredDays added in v0.7.0

func UndeclaredDays(about About, names ...string) Workaround

UndeclaredDays is UndeclaredDates for a day without a time (TMDB's release_date, written 2006-01-02), declared a date.

func UndeclaredDaysExcept added in v0.7.0

func UndeclaredDaysExcept(about About, except map[string][]string, names ...string) Workaround

UndeclaredDaysExcept is UndeclaredDatesExcept for days.

func UndeclaredEnums added in v0.7.0

func UndeclaredEnums(about About, enums map[string]Enum) Workaround

UndeclaredEnums is for the strings a document declares plain whose values the server draws from a fixed set (Dockhand's state, protocol, mode), so that the package holds them as a typed enum with its values as constants, and the sweep fails an answer carrying a value the set does not list. It adds a component schema for each enum and points every string property or parameter of the name at it. It fails for a name nothing has, for an enum with no values, and for a type name a different schema already has.

func UndeclaredParameters added in v0.6.0

func UndeclaredParameters(about About, targets []string, params ...Param) Workaround

UndeclaredParameters is for operations that read a parameter their document does not declare: targets are the operations, by method and path, and params what each of them is given. It fails when any already declares one of them. A header named Accept gives the caller the say over what one call asks for (see Param).

func UndeclaredProperties added in v0.6.0

func UndeclaredProperties(about About, properties map[string]map[string]*openapi.Schema) Workaround

UndeclaredProperties is for the fields a server sends, and reads back, that its document does not declare, so that a model drops them without a word: properties says, by component schema, what to add. It fails for any the schema declares now.

func UndeclaredUnixDates added in v0.7.0

func UndeclaredUnixDates(about About, unit string, names ...string) Workaround

UndeclaredUnixDates is for the dates a document declares as integers, which are seconds or milliseconds since 1970 (unit "seconds" or "milliseconds"): every integer property with one of the names is declared one, for the generated Unix or UnixMilli, which reads a number and writes one back. A document never declares an epoch, so this is the only way a field becomes one. It fails as UndeclaredDates does.

func WrongAnswers added in v0.6.0

func WrongAnswers(about About, corrections map[string]Correction) Workaround

WrongAnswers is for operations that declare one answer where the server gives another: a JSON string that is sent as bare text, one record where the server sends a list of them. corrections says, by method and path, what each declares and what it answers. It fails for any that no longer declares what its correction says, which is how a document that was fixed, or changed again, is noticed.

func WrongStatus added in v0.6.0

func WrongStatus(about About, declared int, answers map[int][]string) Workaround

WrongStatus is for operations documented as answering one status that answer another with the same body: a create documented as 200 that answers 201 Created. answers lists, under each status the server really gives, the operations that give it, by method and path. It fails for any that no longer documents the declared status, or documents the other already.

Jump to

Keyboard shortcuts

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