Skip to main content

API Reference

Resources ​

Container ​

Represents a container running in the Wing Simulator.

Initializers ​

bring sim;

new sim.Container(props: ContainerProps);
NameTypeDescription
props
ContainerProps
No description.
propsRequired ​

Methods ​

Preflight Methods​
NameDescription
toSimulator
Convert this resource to a resource schema for the simulator.
toSimulator ​
toSimulator(): ToSimulatorOutput

Convert this resource to a resource schema for the simulator.

Static Functions ​

NameDescription
onLiftType
A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight
Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.
onLiftType ​
bring sim;

sim.Container.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

hostRequired ​
opsRequired ​
  • Type: MutArray<str>
toInflight ​
bring sim;

sim.Container.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

objRequired ​

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
hostPort
strA token that resolves to the host port of this container.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.

hostPortOptional ​
hostPort: str;
  • Type: str

A token that resolves to the host port of this container.

Policy ​

Implementation of sim.Policy.

Initializers ​

bring sim;

new sim.Policy(props: PolicyProps);
NameTypeDescription
props
PolicyProps
No description.
propsRequired ​

Methods ​

Preflight Methods​
NameDescription
addStatement
Adds a statement to the policy.
toSimulator
Convert this resource to a resource schema for the simulator.
addStatement ​
addStatement(resource: IResource, op: str): void

Adds a statement to the policy.

resourceRequired ​
opRequired ​
  • Type: str
toSimulator ​
toSimulator(): ToSimulatorOutput

Convert this resource to a resource schema for the simulator.

Static Functions ​

NameDescription
onLiftType
A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight
Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.
onLiftType ​
bring sim;

sim.Policy.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

hostRequired ​
opsRequired ​
  • Type: MutArray<str>
toInflight ​
bring sim;

sim.Policy.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

objRequired ​

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.

Resource ​

A backend for a simulated resource.

Initializers ​

bring sim;

new sim.Resource(factory: IResourceFactory);
NameTypeDescription
factory
IResourceFactory
No description.
factoryRequired ​

Methods ​

Preflight Methods​
NameDescription
addEnvironment
Add an environment variable to make available to the inflight code.
addPermission
Add a simulated permission to this inflight host.
createToken
Obtain a token that can be used to reference an attribute of this resource that is only resolved once the resource is started in the simulator.
toSimulator
Convert this resource to a resource schema for the simulator.
Inflight Methods​
NameDescription
call
Call a method on the resource.
addEnvironment ​
addEnvironment(name: str, value: str): void

Add an environment variable to make available to the inflight code.

nameRequired ​
  • Type: str
valueRequired ​
  • Type: str
addPermission ​
addPermission(resource: IResource, op: str): void

Add a simulated permission to this inflight host.

resourceRequired ​
opRequired ​
  • Type: str
createToken ​
createToken(name: str): str

Obtain a token that can be used to reference an attribute of this resource that is only resolved once the resource is started in the simulator.

If the token is used in inflight code or in the configuration of a simulated resource (e.g. as an environment variable), the relevant resource will automatically take a dependency on the resource the token belongs to.

nameRequired ​
  • Type: str

The name of the token.

toSimulator ​
toSimulator(): ToSimulatorOutput

Convert this resource to a resource schema for the simulator.

call ​
inflight call(method: str, args?: MutArray<Json>): Json

Call a method on the resource.

methodRequired ​
  • Type: str
argsOptional ​
  • Type: MutArray<Json>

Static Functions ​

NameDescription
onLiftType
A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight
Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.
onLiftType ​
bring sim;

sim.Resource.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

hostRequired ​
opsRequired ​
  • Type: MutArray<str>
toInflight ​
bring sim;

sim.Resource.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

objRequired ​

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.

State ​

Key/value in-memory state for the simulator.

Use the preflight method token(key) to obtain a token that can be used to reference the value of the state at runtime.

During deployment (i.e. cloud.OnDeploy or cloud.Service startup), you must call the inflight method set(key, value) to set the runtime value. The value will be available at runtime through the inflight method get(key) (or resolved as a token).

See tests for examples.

Initializers ​

bring sim;

new sim.State();
NameTypeDescription

Methods ​

Preflight Methods​
NameDescription
token
Returns a token that can be used to retrieve the value of the state after the simulation has run.
toSimulator
Convert this resource to a resource schema for the simulator.
Inflight Methods​
NameDescription
get
Gets the runtime state of this object.
set
Sets the state of runtime a runtime object.
tryGet
Checks if runtime state exists for this object and returns it's value.
token ​
token(key: str): str

Returns a token that can be used to retrieve the value of the state after the simulation has run.

keyRequired ​
  • Type: str

The object key retrieved through the inflight state.get().

toSimulator ​
toSimulator(): ToSimulatorOutput

Convert this resource to a resource schema for the simulator.

get ​
inflight get(key: str): Json

Gets the runtime state of this object.

Throws if there is no value for the given key.

keyRequired ​
  • Type: str

The object's key.

set ​
inflight set(key: str, value: Json): void

Sets the state of runtime a runtime object.

keyRequired ​
  • Type: str

The object's key.

valueRequired ​

The object's value.

tryGet ​
inflight tryGet(key: str): Json?

Checks if runtime state exists for this object and returns it's value.

If no value exists, returns nil.

keyRequired ​
  • Type: str

The object's key.

Static Functions ​

NameDescription
onLiftType
A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight
Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.
onLiftType ​
bring sim;

sim.State.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

hostRequired ​
opsRequired ​
  • Type: MutArray<str>
toInflight ​
bring sim;

sim.State.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

objRequired ​

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.

Structs ​

ContainerProps ​

Initialization properties for sim.Container.

Initializer ​

bring sim;

let ContainerProps = sim.ContainerProps{ ... };

Properties ​

NameTypeDescription
image
strA name of a public Docker image to pull and run or a path to a local directory with a Dockerfile.
name
strA name for the container.
args
MutArray<str>Container arguments.
containerPort
numInternal container port to expose.
entrypoint
strContainer entrypoint.
env
MutMap<str>Environment variables to set in the container.
network
strDocker network to use for the container - such as 'host', 'bridge', etc.
sourceHash
strAn explicit source hash that represents the container source.
sourcePattern
strA glob of local files to consider as input sources for the container, relative to the build context directory.
volumes
MutArray<str>Volume mount points.
imageRequired ​
image: str;
  • Type: str

A name of a public Docker image to pull and run or a path to a local directory with a Dockerfile.

nameRequired ​
name: str;
  • Type: str

A name for the container.

argsOptional ​
args: MutArray<str>;
  • Type: MutArray<str>
  • Default: []

Container arguments.

containerPortOptional ​
containerPort: num;
  • Type: num
  • Default: no port exposed

Internal container port to expose.

entrypointOptional ​
entrypoint: str;
  • Type: str
  • Default: default image entrypoint

Container entrypoint.

envOptional ​
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: {}

Environment variables to set in the container.

networkOptional ​
network: str;
  • Type: str
  • Default: default docker network

Docker network to use for the container - such as 'host', 'bridge', etc.

https://docs.docker.com/network.

Example

'host'
sourceHashOptional ​
sourceHash: str;
  • Type: str
  • Default: calculated based on the source files

An explicit source hash that represents the container source.

if not set, and sourcePattern is set, the hash will be calculated based on the content of the source files.

sourcePatternOptional ​
sourcePattern: str;
  • Type: str
  • Default: all files

A glob of local files to consider as input sources for the container, relative to the build context directory.

volumesOptional ​
volumes: MutArray<str>;
  • Type: MutArray<str>
  • Default: []

Volume mount points.

Example

['/host:/container']

PolicyProps ​

Options for sim.Policy.

Initializer ​

bring sim;

let PolicyProps = sim.PolicyProps{ ... };

Properties ​

NameTypeDescription
principal
IResource
The resource to which the policy is attached.
principalRequired ​
principal: IResource;

The resource to which the policy is attached.

Protocols ​

IResource ​

Contract that a resource backend must implement.

Methods ​

NameDescription
onStop
Runs when the resource is stopped.
onStop ​
onStop(): void

Runs when the resource is stopped.

IResourceContext ​

Context for implementing a simulator resource.

Methods ​

NameDescription
log
Log a message at the current point in time.
resolveToken
Resolves a token value.
statedir
The directory for the resource's state.
log ​
inflight log(message: str, level?: LogLevel): void

Log a message at the current point in time.

Defaults to info level.

messageRequired ​
  • Type: str

The message to log.

levelOptional ​

The severity of the message.

resolveToken ​
inflight resolveToken(name: str, value: str): void

Resolves a token value.

All tokens must be resolved during the constructor of the resource.

nameRequired ​
  • Type: str

The name of the token.

valueRequired ​
  • Type: str

The value of the token.

statedir ​
statedir(): str

The directory for the resource's state.

IResourceFactory ​

Inflight client: @winglang/sdk.sim.IResourceFactoryClient

A resource with an inflight "handle" method that can be passed to the sim.Resource constructor.

IResourceFactoryClient ​

A resource with an inflight "handle" method that can be passed to the sim.Resource constructor.

Methods ​

NameDescription
handle
Function that will be called to initialize the simulator resource.
handle ​
inflight handle(context: IResourceContext): IResource?

Function that will be called to initialize the simulator resource.

To implement a shutdown sequence, return an object that implements the IResource inflight interface with an onStop() method.

contextRequired ​

ISimulatorInflightHost ​

Interfaces shared by all preflight classes that host inflight code.

Methods ​

NameDescription
addPermission
Add a simulated permission to this inflight host.
addPermission ​
addPermission(resource: IResource, op: str): void

Add a simulated permission to this inflight host.

resourceRequired ​

The resource to add.

opRequired ​
  • Type: str

The action to add.

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.

ISimulatorResource ​

Interfaces shared by all preflight classes targeting the simulator.

Methods ​

NameDescription
toSimulator
Convert this resource to a resource schema for the simulator.
toSimulator ​
toSimulator(): ToSimulatorOutput

Convert this resource to a resource schema for the simulator.

Properties ​

NameTypeDescription
node
constructs.NodeThe tree node.
nodeRequired ​
node: Node;
  • Type: constructs.Node

The tree node.