Documentation
¶
Overview ¶
Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator. The importer writes it from an OpenAPI document (after the workarounds have patched the document); the generator reads only this, never the document. It is checked in under api-defs/<service>-<version>/, one JSON file per spec tag plus Service.json, so a spec refresh shows up as a readable diff and the differ can report what changed in API terms.
Everything the generator needs is decided here rather than in the generator: Go names, Go-facing types, expected status codes, which operations page, and which tag owns each model.
Index ¶
- Constants
- func GroupFile(name string) string
- func Marshal(v any) ([]byte, error)
- func Save(svc *Service, dir string) error
- func Validate(svc *Service) error
- type Argument
- type Body
- type Call
- type CommandSet
- type Constant
- type ConstantValue
- type Field
- type Group
- type IDKind
- type Member
- type Model
- type ObjectType
- type Operation
- type Option
- type Pageable
- type PathParameter
- type Service
- type TypeRef
Constants ¶
const ( QueryGet = "get" QueryCount = "count" )
QueryGet and QueryCount are the forms of a query beside the list: the flag in its options that asks for one record, which the server refuses to answer when the filters match none, and the one that asks for how many match.
const ( InQuery = "Query" InHeader = "Header" )
Option locations.
const CommonGroup = "Common"
CommonGroup owns the models and constants that more than one tag's operations use (or none do).
const JSONContentType = "application/json"
JSONContentType is the ContentType of every body that is JSON.
const OwnItem = "$item"
OwnItem is what a named type's name may say in place of the field's own type, or a list's element, as the package names it (truenasrpc.Set[$item] on a list of an enum is truenasrpc.Set[ReplicationDirection]), so a type wrapping the field's own survives the package renaming it.
const ServiceFile = "Service.json"
ServiceFile is the service description inside a definitions directory; every other JSON file there is one group.
Variables ¶
This section is empty.
Functions ¶
func GroupFile ¶ added in v0.9.0
GroupFile is the file a group's definitions are in: <Name>.json, but for a group named Service (TrueNAS has a service namespace), whose file would be the service description's, and is Service.group.json instead.
func Marshal ¶
Marshal renders a value the way the definition files hold it: indented, without HTML escaping (descriptions carry < and &), with a final newline.
func Save ¶
Save writes a definitions directory, removing group files that no longer have a group so a tag that disappears from the document disappears here.
Types ¶
type Argument ¶ added in v0.9.0
type Argument struct {
Name string `json:"Name"`
Argument string `json:"Argument"`
Type TypeRef `json:"Type"`
Required bool `json:"Required,omitempty"`
Description string `json:"Description,omitempty"`
}
Argument is one value a JSON-RPC method takes, by position: Name as the server names it, Argument the Go argument, and Required whether the server insists on it; one not required may be left off the end of the call.
type Body ¶
type Body struct {
// ContentType is the media type sent or expected. A wildcard such as
// image/* means the caller names the concrete type.
ContentType string `json:"ContentType"`
// Type is RawFile for bodies that are not JSON, but for an answer that
// is text read whole, which is a String of another ContentType than
// JSON's.
Type TypeRef `json:"Type"`
}
Body is a request or response body.
type Call ¶ added in v0.9.0
type Call struct {
Method string `json:"Method"`
Job bool `json:"Job,omitempty"`
Filterable bool `json:"Filterable,omitempty"`
// Form is the one-record (QueryGet) or count (QueryCount) form of a query, which the method asks for by setting that flag in
// the query's options; the plain form, answering the list, has none.
Form string `json:"Form,omitempty"`
Item bool `json:"Item,omitempty"`
NoAuth bool `json:"NoAuth,omitempty"`
Read bool `json:"Read,omitempty"`
Roles []string `json:"Roles,omitempty"`
// Downloadable marks a method whose answer is a file, which the generated <Name>To writes out through a connection that
// can carry one; Uploadable one that takes files beside its arguments, which the generated method takes as readers.
Downloadable bool `json:"Downloadable,omitempty"`
Uploadable bool `json:"Uploadable,omitempty"`
}
Call is what a JSON-RPC method says of itself: Method is its name as the server takes it, Job that the server runs it as a job, Filterable that it is a query taking filters and options and answering a list, Item that it acts on one record by its id, NoAuth that it may be called before logging in, Read that it changes nothing (worked out from the roles the service config names), and Roles the roles that may call it as the server names them.
type CommandSet ¶ added in v0.8.0
type CommandSet struct {
Get string `json:"Get"`
Status string `json:"Status"`
Finished []string `json:"Finished"`
Failed []string `json:"Failed,omitempty"`
}
CommandSet is how a queued command is followed: Get is the Go name of the operation that answers one by its id, Status the field of its answer that says how far it is, Finished the values that mean it is over and Failed those among them that mean it failed.
type Constant ¶
type Constant struct {
Name string `json:"Name"`
SchemaName string `json:"SchemaName"`
Description string `json:"Description,omitempty"`
Values []ConstantValue `json:"Values"`
}
Constant is a string enum.
type ConstantValue ¶
type ConstantValue struct {
// Name is the Go constant name.
Name string `json:"Name"`
Value string `json:"Value"`
}
ConstantValue is one member of an enum.
type Field ¶
type Field struct {
Name string `json:"Name"`
JSONName string `json:"JsonName"`
Description string `json:"Description,omitempty"`
Type TypeRef `json:"Type"`
Nullable bool `json:"Nullable,omitempty"`
// Required is set when the document says an object must carry the
// property, for a service whose config holds it to that (SendRequired):
// the generated field is then always sent, its zero included.
Required bool `json:"Required,omitempty"`
// KeepsNull makes the generated field a pointer, so the document's null
// is told from a number's zero, and a string left out from one sent
// empty: the fields the service config names in KeepNull. Every other
// number and string is held by value.
KeepsNull bool `json:"KeepsNull,omitempty"`
}
Field is one property of a model.
type Group ¶
type Group struct {
// Name is the Go-facing name used in file names, e.g. "LibraryStructure".
Name string `json:"Name"`
// Tag is the tag as the document spells it, e.g. "LibraryStructureService";
// empty for the common group.
Tag string `json:"Tag,omitempty"`
Operations []Operation `json:"Operations,omitempty"`
Models []Model `json:"Models,omitempty"`
Constants []Constant `json:"Constants,omitempty"`
}
Group is one spec tag: its operations, and the models and constants no other tag uses.
type IDKind ¶ added in v0.7.0
type IDKind struct {
Name string `json:"Name"`
Base ObjectType `json:"Base"`
// Shape is the regular expression every value of the kind matches, over its text, and Example a value of it; empty for a kind with no shape.
Shape string `json:"Shape,omitempty"`
Example string `json:"Example,omitempty"`
}
IDKind is one kind of id, a named type over an int, an int64 or a string.
type Member ¶ added in v0.9.0
Member is one record a union is one of: the model, and the values of the union's Discriminator that name it, in order, none where the document gives none; several where the document sends several kinds to one record (a mirror, a stripe and three raidz levels are all one vdev record).
type Model ¶
type Model struct {
Name string `json:"Name"`
// SchemaName is the component schema; empty for an object declared
// inline in another model's property.
SchemaName string `json:"SchemaName,omitempty"`
Description string `json:"Description,omitempty"`
Fields []Field `json:"Fields,omitempty"`
// Union lists the variants when the schema is a oneOf/anyOf; such a
// model has no fields and is raw JSON for the caller to decode.
Union []string `json:"Union,omitempty"`
// Members, for a service with TypedUnions, are the records the union is one of, each a model, with the value of
// Discriminator that names it where the document says which field the records name themselves by; the generated type
// holds the record as it came and hands it over as the member asked for.
Discriminator string `json:"Discriminator,omitempty"`
Members []Member `json:"Members,omitempty"`
// WrittenWhole marks a model callers read and write back whole - a
// settings object - so its empty strings and zero numbers are sent
// rather than left out: the server reads a field left out as null,
// which is not the value that was read, and not a value it will save.
WrittenWhole bool `json:"WrittenWhole,omitempty"`
}
Model is an object schema, or a oneOf/anyOf union kept as raw JSON.
type ObjectType ¶
type ObjectType string
ObjectType is the kind of a TypeRef.
const ( Boolean ObjectType = "Boolean" Integer ObjectType = "Integer" Integer64 ObjectType = "Integer64" Float ObjectType = "Float" Double ObjectType = "Double" String ObjectType = "String" List ObjectType = "List" Dictionary ObjectType = "Dictionary" Reference ObjectType = "Reference" RawObject ObjectType = "RawObject" Any ObjectType = "Any" RawFile ObjectType = "RawFile" // DateTime and Date are strings the document declares as a date and // time or a day, held as the package's Time and Day when the service // gives the layouts it writes them in (Service.Dates, Days). DateTime ObjectType = "DateTime" Date ObjectType = "Date" // UnixSeconds and UnixMillis are integers a workaround declares a date // (seconds or milliseconds since 1970), held as the package's Unix and // UnixMilli, which read a number and write one back. UnixSeconds ObjectType = "UnixSeconds" UnixMillis ObjectType = "UnixMillis" // ID is a kind of id the service tells apart (Service.IDs), named in // ReferenceName, held as a named type over its base. ID ObjectType = "ID" // Named is a value held as a Go type a workaround names (GoType, Import), for a value the server writes in a form of its // own that the document cannot describe; the type reads and writes its own JSON. Named ObjectType = "Named" )
The object types. Integer is a 32-bit integer (Go int), Integer64 a 64-bit one; Float is float32 and Double float64. RawObject is JSON the caller decodes (untyped objects, unions, binary strings); Any is a value of no declared type; RawFile is a body that is not JSON.
type Operation ¶
type Operation struct {
// Name is the Go method name.
Name string `json:"Name"`
OperationID string `json:"OperationId,omitempty"`
Method string `json:"Method"`
// Path is the document's path template, e.g. /Items/{Id}/Similar.
Path string `json:"Path"`
Description string `json:"Description,omitempty"`
Deprecated bool `json:"Deprecated,omitempty"`
// PathParameters are the template placeholders in path order.
PathParameters []PathParameter `json:"PathParameters,omitempty"`
// Options are the query and header parameters, the options struct.
Options []Option `json:"Options,omitempty"`
// Request is the request body; nil when the operation takes none.
Request *Body `json:"Request,omitempty"`
// Response is the success response body; nil when there is none.
Response *Body `json:"Response,omitempty"`
ExpectedStatusCodes []int `json:"ExpectedStatusCodes"`
// Pageable is set for the list operations, which also get a Complete
// method that pages through every result.
Pageable *Pageable `json:"Pageable,omitempty"`
// Commands is set on an operation that queues commands named in its body, and says how a queued one is followed; Command is set
// on each command's own operation, one per name, which sends the same request with its name fixed and also gets an AndWait.
Commands *CommandSet `json:"Commands,omitempty"`
Command string `json:"Command,omitempty"`
// Call is set on an operation that is a JSON-RPC method rather than a request to a path (Method is "CALL" and Path the
// method's name), and Arguments are what it takes, in the order they are sent; it has no path parameters, options, request
// body or status codes.
Call *Call `json:"Call,omitempty"`
Arguments []Argument `json:"Arguments,omitempty"`
}
Operation is one HTTP method on one path, and one method on the client.
type Option ¶
type Option struct {
// Name is the parameter as sent.
Name string `json:"Name"`
// Field is the Go field name.
Field string `json:"Field"`
In string `json:"In"`
Description string `json:"Description,omitempty"`
Deprecated bool `json:"Deprecated,omitempty"`
// Required is set when the document says the operation needs the option.
Required bool `json:"Required,omitempty"`
Type TypeRef `json:"Type"`
// CommaSeparated sends a List as one comma-separated value; otherwise
// each element is sent under the parameter's name.
CommaSeparated bool `json:"CommaSeparated,omitempty"`
// DeepObject sends a Dictionary as one parameter per key, name[key]=value
// (OpenAPI's deepObject style, which Jellyfin's stream options use);
// otherwise the dictionary goes as one JSON string.
DeepObject bool `json:"DeepObject,omitempty"`
}
Option is one query or header parameter, a field of the options struct.
type Pageable ¶
type Pageable struct {
// StartIndexOption and LimitOption are the options fields: where a page
// starts and how many results it holds. LimitOption is empty for a
// service whose page size is the server's to choose; the pager then
// takes the first page's size as the page size.
StartIndexOption string `json:"StartIndexOption"`
LimitOption string `json:"LimitOption,omitempty"`
// ByPage is set when the list pages by page number: StartIndexOption is
// then the page wanted, counted from 1, rather than the index of its
// first result.
ByPage bool `json:"ByPage,omitempty"`
// FirstPage is the number of the first page where the list pages by number and does not count from 1; First is the number to read.
FirstPage *int `json:"FirstPage,omitempty"`
// ItemsField and TotalField are fields of the response model.
ItemsField string `json:"ItemsField"`
TotalField string `json:"TotalField"`
ItemType TypeRef `json:"ItemType"`
}
Pageable says how a list operation pages.
type PathParameter ¶
type PathParameter struct {
// Name is the placeholder as the template spells it.
Name string `json:"Name"`
// Argument is the Go argument name.
Argument string `json:"Argument"`
Type TypeRef `json:"Type"`
}
PathParameter is a placeholder of the path template.
type Service ¶
type Service struct {
// Name is the service's name in the pandorest config and the
// prefix of its api-defs directory, e.g. "emby" for emby-4.10.0.40.
Name string `json:"Name"`
// Package is the Go package the generator writes, e.g. "emby".
Package string `json:"Package"`
// Title and APIVersion are the document's info block.
Title string `json:"Title"`
APIVersion string `json:"ApiVersion"`
// Source is the document the definitions were imported from.
Source string `json:"Source"`
// Auth names how the service authenticates: the base client's
// authorizer the default client.go wraps New's token in.
Auth string `json:"Auth"`
// Workarounds lists the importer workarounds applied, in order.
Workarounds []string `json:"Workarounds"`
// Dates and Days are the layouts the service writes a date and time
// and a day in, first the one it is sent in; empty, dates are strings.
Dates []string `json:"Dates,omitempty"`
Days []string `json:"Days,omitempty"`
// DatesKeepUnread and DaysKeepUnread read a date no layout reads as
// zero with its text kept, rather than failing the decode.
DatesKeepUnread bool `json:"DatesKeepUnread,omitempty"`
DaysKeepUnread bool `json:"DaysKeepUnread,omitempty"`
// IDs are the kinds of id the package declares types for.
IDs []IDKind `json:"IDs,omitempty"`
Groups []Group `json:"-"`
}
Service describes one server's API. It is Service.json; the groups are the per-tag files next to it.
func (*Service) IDBase ¶ added in v0.7.0
func (s *Service) IDBase(kind string) ObjectType
IDBase is the base type of a kind of id, or "" for a kind the service does not declare.
func (*Service) IDKind ¶ added in v0.7.0
IDKind is a kind of id by name, or nil for one the service does not declare.
func (*Service) Operations ¶
Operations returns every operation of the service.
type TypeRef ¶
type TypeRef struct {
Type ObjectType `json:"Type"`
// ReferenceName names the model or constant of a Reference.
ReferenceName string `json:"ReferenceName,omitempty"`
// NestedItem is the element type of a List or Dictionary.
NestedItem *TypeRef `json:"NestedItem,omitempty"`
// GoType is the Go type a Named value is held as, written as a package uses it (truenasrpc.Secret[int]), and Import the
// path it comes from; the type reads and writes its own JSON.
GoType string `json:"GoType,omitempty"`
Import string `json:"Import,omitempty"`
}
TypeRef is the type of a field, parameter or body.