workarounds

package
v0.6.1 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 8 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.

Types

type About added in v0.6.0

type About struct {
	Name, Service, Bug string
}

About is what a ready-made 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 ready-made 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 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 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 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 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 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 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