workarounds

package
v0.3.2 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: 4 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 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.

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.

Jump to

Keyboard shortcuts

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