pandorest

package module
v0.9.0 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: 16 Imported by: 1

README

pandorest

GitHub release Go Version License build test lint coverage

pandorest turns a server's API document into a typed Go client, with a test for every operation. It reads an OpenAPI document, or a server's own list of its JSON-RPC methods, and writes a package a program can call without reading the document.

The document is the source of truth, and what it gets wrong is fixed by a named workaround that fails the day the bug goes. Nothing is guessed at: a document that does not say what an operation answers fails the import until a workaround says.

It follows Pandora, the generator behind go-azure-sdk, scaled down to a few documents in one repository:

api-defs/
  emby-openapi-4.10.0.40.json ──┐               ┌─ emby-4.10.0.40/*.json ──┐
  jellyfin-openapi-12.1.0.json ─┼─ import ──────┼─ jellyfin-12.1.0/*.json ─┼─ generate ─ sdk/emby, sdk/jf, sdk/tmdb
  tmdb-openapi-2026.09.22.json ─┘ (workarounds) └─ tmdb-2026.09.22/*.json ─┘
                                                        │
                                         diff ──────────┘  (what a refreshed document changes)

Install

go get github.com/katbyte/pandorest

Quick start

A repository keeps its documents under api-defs/, a description of each service, and the workarounds for its document's bugs, and hands them over from a short main:

// sdk/pandorest/main.go
package main

import (
	"github.com/katbyte/pandorest"
	"github.com/katbyte/pandorest/config"

	"github.com/katbyte/sonarr-mcp/sdk/pandorest/workarounds"
)

func main() {
	pandorest.Main(pandorest.Config{
		Services: []config.Service{{
			Name:          "sonarr",
			Package:       "sonarr",
			Output:        "sdk/sonarr",
			Naming:        config.PathNaming,
			PathPrefix:    "/api/v3",
			Auth:          "APIKey",
			ClientService: "service", // sdk/sonarr/service.go, written by hand
			Paging:        &config.Paging{Start: "page", Limit: "pageSize", Items: "records", Total: "totalRecords", ByPage: true},
		}},
		Workarounds: workarounds.All,
	})
}

Then, from the repository root:

go run ./sdk/pandorest import      # the document into its definitions, with the workarounds applied
go run ./sdk/pandorest generate    # the package, from the definitions
go run ./sdk/pandorest diff        # what the document changes against the definitions, breaking changes marked
go run ./sdk/pandorest check       # the definitions match the document and every operation has a method
go run ./sdk/pandorest resolve     # which document and definitions each service is at

-service a,b limits a command to some services. -root runs it against another checkout. -version picks one vendored version. diff -old <dir> -new <dir> compares two definitions directories. check -uncalled lists the methods nothing in the repository calls, and -callers tools/ counts callers in one directory.

The clients it generates

Each lives in the repository that vendors its document, beside the MCP server built on it.

Server Package Repository
Emby 4.10.0.40 github.com/katbyte/embyfin-mcp/sdk/emby embyfin-mcp
Jellyfin 12.1.0 github.com/katbyte/embyfin-mcp/sdk/jf embyfin-mcp
TMDB (document of 2026-09-22) github.com/katbyte/embyfin-mcp/sdk/tmdb embyfin-mcp
Sonarr 4.0.20.3014 github.com/katbyte/sonarr-mcp/sdk/sonarr sonarr-mcp
Radarr 6.4.4.10685 github.com/katbyte/radarr-mcp/sdk/radarr radarr-mcp
Prowlarr 2.6.5.5623 github.com/katbyte/prowlarr-mcp/sdk/prowlarr prowlarr-mcp
Dockhand 1.0.51 github.com/katbyte/dockhand-mcp/sdk/dockhand dockhand-mcp

How it works

A service is a config.Service: its name, package, how methods are named, how the server takes its credential, how its lists page, which dates and ids are typed. Only the first four fields are required. The rest, with examples, is in docs/configuration.md.

Import turns the document into definitions, plain JSON files that are checked in and reviewed. It is strict: anything the document leaves unsaid fails the import with every problem listed, rather than being guessed at. A bug in the document is fixed by a workaround, which must fail when the bug is gone, so a refreshed document that fixes it names the workaround to delete. The common bugs have ready-made workarounds. All of it is in docs/importing.md, with the diff that shows what a refreshed document changes.

Generate writes the package from the definitions alone, in a flat layout or, like go-azure-sdk, as a package per tag. A method takes a context, the path parameters, the body and an options struct, and returns the decoded answer with the HTTP response. Every operation gets a test against a canned server. What the generated code looks like, and how to read an answer, a file or a list, is in docs/generated-code.md.

The read sweep is the test against the real server, for a repository's live suite: every read called on the generated client, each answer held to decode and to carry something, and every operation that cannot answer excused by name. It is in docs/sweep.md.

The base client is what every generated package sends through, with retries, a size limit and a trace that hides credentials. What is one server's own about being talked to goes in a short file the repository writes by hand. It is in docs/base-client.md.

A JSON-RPC server with no OpenAPI document, such as TrueNAS, gives its own list of methods instead. Each becomes a call with its arguments in order, and the generated New takes a connection the repository writes. The package never sees a socket.

Pieces

Package Does
pandorest the commands: import, generate, diff, check, resolve
config a service: its documents, paths, naming and options
openapi reads the OpenAPI document
jsonrpc reads a server's list of its JSON-RPC methods into the same form
importer/workarounds what a workaround is, the helpers they share, and the test they must pass
importer turns a patched document into definitions, strictly
definitions the contract between import and generate: JSON per version per tag
differ reports what changed between two sets of definitions
generator writes the package from the definitions
sweep calls every read of a generated client against a real server, for a live test
client the base client every generated package sends through

How this is built

The code is written with Claude Code. I then review it and prune or rework it until it has the shape I want: I set the design and the scope, and decide what stays.

This is a library, so it has no server of its own to test against. Its tests are unit tests under the race detector, and generator tests that write a package from a small document, then build it, vet it and run its generated tests. The live tests against real servers are in the repositories that use it, one per server, where each runs its generated client against the server itself.

CI runs build, tests with coverage, golangci-lint, CodeQL, govulncheck, a check that go.mod is tidy, markdownlint, typos, shellcheck, actionlint and a workflow lint, and zizmor for workflow security.

Development

make tools      # build the pinned dev tools into .tools/bin
make check-all  # build + test + lint + actionlint + yamllint + shellcheck + typos + depscheck
make cover      # tests with coverage

Nothing is vendored. The only dependency is go-kt. Tool versions are pinned in .tools/go.mod. Releases are described in CONTRIBUTING.md.

Documentation

Overview

Package pandorest generates typed Go Services from vendored OpenAPI documents. It is inspired by Pandora, the go-azure-sdk generator (https://github.com/hashicorp/pandora), and keeps its pipeline, scaled down to a handful of documents in one repository:

import    <dir>/<service>-openapi-<version>.json -> workarounds -> <dir>/<service>-<version>/*.json
generate  <dir>/<service>-<version> -> the service's package

A service's document and definitions are named by the document's version, and the highest version present is the one imported and generated from.

diff      what a refreshed spec changes, against the checked-in definitions
check     the definitions match the spec and the package has every method
resolve   which document and definitions each service is at

A repository that generates an SDK keeps what is its own - the documents, the services they describe and the workarounds for their bugs - and a main of a few lines that hands them to this package:

func main() {
	pandorest.Main(pandorest.Config{Services: services, Workarounds: workarounds})
}

which it runs from its root, as its make targets do:

go run ./sdk/pandorest import
go run ./sdk/pandorest generate -service jellyfin
go run ./sdk/pandorest diff
go run ./sdk/pandorest diff -old api-defs/emby-4.9.0.30 -new api-defs/emby-4.10.0.40

The packages it writes send their requests through the client package, the base client they share. See the README for the design and how to refresh a spec.

Index

Constants

This section is empty.

Variables

View Source
var ErrChanges = errors.New("the definitions differ")

ErrChanges is what diff -exit-code returns when there are changes.

Functions

func Main

func Main(cfg Config)

Main runs the command the process was started with, and exits 1 when it fails. It is the whole of a repository's generator main.

func Run

func Run(cfg Config, args []string, stdout, stderr io.Writer) error

Run runs one command: args are the command and its flags, stdout takes what it reports and stderr its log.

Types

type Config

type Config struct {
	// Services are the APIs, in the order the commands process them.
	Services []config.Service
	// Workarounds are the fixes for the bugs in the services' documents, in
	// the order they are applied; each names the service it is for.
	Workarounds []workarounds.Workaround
}

Config is what a repository generates its Services from.

Directories

Path Synopsis
Package client is the base client every SDK pandorest generates sends its requests through, after go-azure-sdk's sdk/client: one copy in place of the one each repository used to keep.
Package client is the base client every SDK pandorest generates sends its requests through, after go-azure-sdk's sdk/client: one copy in place of the one each repository used to keep.
Package config describes the services pandorest imports and generates, the equivalent of Pandora's resource-manager.hcl.
Package config describes the services pandorest imports and generates, the equivalent of Pandora's resource-manager.hcl.
Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator.
Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator.
Package differ reports what changed between two sets of definitions in API terms, after Pandora's data-api-differ: operations, options, bodies, models, fields and enum values added, removed or changed, with the changes that would break a caller of the generated SDK marked.
Package differ reports what changed between two sets of definitions in API terms, after Pandora's data-api-differ: operations, options, bodies, models, fields and enum values added, removed or changed, with the changes that would break a caller of the generated SDK marked.
Package generator writes a Go SDK package from a service's definitions, the way Pandora's generator-go-sdk writes go-azure-sdk: it reads nothing but the definitions, and every decision it makes about the API was already made by the importer.
Package generator writes a Go SDK package from a service's definitions, the way Pandora's generator-go-sdk writes go-azure-sdk: it reads nothing but the definitions, and every decision it makes about the API was already made by the importer.
Package importer turns a vendored OpenAPI document into definitions, the way Pandora's importer-rest-api-specs does for Azure: load the document, apply the named workarounds for its known bugs, then normalise it into the definitions model (Go names, types, status codes, paging, and which tag owns each model).
Package importer turns a vendored OpenAPI document into definitions, the way Pandora's importer-rest-api-specs does for Azure: load the document, apply the named workarounds for its known bugs, then normalise it into the definitions model (Go names, types, status codes, paging, and which tag owns each model).
workarounds
Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds.
Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds.
Package jsonrpc reads a server's own description of its JSON-RPC methods into the document the importer takes, so that a server with no OpenAPI document (TrueNAS, whose REST API is going) gets the same generated package as one with.
Package jsonrpc reads a server's own description of its JSON-RPC methods into the document the importer takes, so that a server with no OpenAPI document (TrueNAS, whose REST API is going) gets the same generated package as one with.
Package openapi decodes the subset of an OpenAPI 3 document the importer reads.
Package openapi decodes the subset of an OpenAPI 3 document the importer reads.
Package sweep is the read sweep a repository runs against a real server: every GET operation in a service's definitions, called on the generated SDK with arguments resolved from the suite's fixtures, and its answer decoded (or its file read).
Package sweep is the read sweep a repository runs against a real server: every GET operation in a service's definitions, called on the generated SDK with arguments resolved from the suite's fixtures, and its answer decoded (or its file read).

Jump to

Keyboard shortcuts

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