Simulation¶

The simulator of a provider package (sim/sim.yaml).

Schema: simulation.json. Explanations and examples: configuration model.

Field	Type	Required	Description
`apiVersion`	`tapyr/v1alpha1`	yes	Version of the configuration format.
`kind`	`Simulation`	yes	Kind of the document.
`metadata`	ObjectMeta	yes	Name and description of the document.
`spec`	SimulationSpec	yes	Specification of the document.

ObjectMeta¶

ObjectMeta identifies a document.

Field	Type	Required	Description
`description`	string		Description is free text for humans.
`name`	Name	yes	Name of the document, unique per kind.

SimulationSpec is the specification of a Simulation.

Field	Type	Required	Description
`auth`	SimulationAuth		Auth lists the credentials the simulator accepts. The way they are checked follows the provider auth type.
`basePath`	string		`basePath` is the path prefix of the API (the path part of the provider base URL). Routes are relative to it. Default `/`. Pattern `^/`.
`headers`	map of string to string		Headers added to every response, computed from the limit state: "limit:<name>.max", "limit:<name>.remaining" or "limit:<name>.reset" (seconds until the window resets).
`inventory`	SimulationInventory		Inventory generates synthetic items for templated fixtures.
`portOffset`	integer		`portOffset` is the port of the simulator in tapyr sim --all, as an offset from --listen-base, so that adding a package does not move the others. Simulators without one take the ports after the largest declared offset, in provider name order. Minimum 0.
`routes`	list of SimulationRoute	yes	Routes served by the simulator. Unknown routes return 404. Minimum items 1.

Type: string. Pattern ^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$.

SimulationAuth configures the credentials accepted by the simulator.

Field	Type	Description
`accept`	SimulationCredentials	Accept lists the accepted credentials. They are fake values by design.
`loginResponse`	string	`loginResponse` is a JSON fixture answered by the login endpoint, relative to the sim/ directory; {token} and {expiresIn} (seconds) are replaced. Default: {"token": "{token}", "expiresIn": {expiresIn}}.
`tokenLifetime`	Duration	`tokenLifetime` of the tokens issued by the token and login endpoints, in simulated time. Default `10m`.

SimulationInventory is a synthetic inventory: sets of items, each item under a parent item of another set.

Field	Type	Required	Description
`seed`	integer		Seed of the generated values. The same seed gives the same items and the same dynamics. Default `42`.
`sets`	list of SimulationSet	yes	Sets of items, generated in order: a parent set comes first. Minimum items 1.

SimulationRoute is an endpoint of the simulator.

Field	Type	Required	Description
`method`	string		Method of the route. Default `GET`. One of `GET`, `HEAD`, `POST`.
`pagination`	string		Pagination serves the fixture items page by page. Its parameters come from the job templates requesting this path, or from the provider. Default `none`. One of `none`, `offset`, `page`, `link_header`, `cursor`, `expression`.
`path`	string	yes	Path of the route, relative to basePath, with {var} segments. Pattern `^/`.
`response`	SimulationResponse	yes	Response returned by the route.

SimulationCredentials are accepted credentials per auth type.

Field	Type	Description
`basic`	list of SimulationBasicCredential	Basic credentials accepted with auth type basic.
`bearer`	list of string	Bearer tokens accepted with auth type bearer.
`clients`	list of SimulationClient	Clients accepted by the token endpoint with auth type oauth2_client_credentials.
`header`	list of string	Header values accepted with auth type header.
`logins`	list of SimulationBasicCredential	Logins accepted by the login endpoint with auth type session_login: the login body must carry both values.
`plugin`	object	Plugin holds the credentials accepted by the simulator side of an auth plugin (type plugin), read by the plugin.

Type: string. Pattern ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$. Examples 30s, 5m, 1h30m.

SimulationSet is a set of generated items.

Field	Type	Required	Description
`count`	integer	yes	Count of items (per parent item when Parent is set). Minimum 0. Maximum 100000.
`name`	Name	yes	Name of the set, used by the template helpers.
`parent`	Name		Parent set: count items are generated under each of its items.

SimulationResponse is the response of a route.

Field	Type	Description
`file`	string	File is the JSON fixture, relative to the sim/ directory. {var} placeholders are replaced by the route variables. Paginated routes need a JSON array, or a list at ItemsField. Minimum length 1.
`headers`	map of string to string	Headers added to the response.
`itemsField`	string	`itemsField` is the dotted path of the list a paginated route serves page by page, inside an envelope; empty for a top-level array.
`status`	integer	Status code of the response. Default `200`. Minimum 100. Maximum 599.
`template`	string	Template is a Go text/template fixture rendering JSON, relative to the sim/ directory (see docs/spec/08-simulator.md for its data and helpers). Exactly one of file and template is set. Minimum length 1.

SimulationBasicCredential is a username and password pair.

Field	Type	Required	Description
`password`	string	yes	Password accepted.
`username`	string	yes	Username accepted.

SimulationClient is an OAuth 2.0 client.

Field	Type	Required	Description
`clientId`	string	yes	`clientId` accepted.
`clientSecret`	string	yes	`clientSecret` accepted.