Service

The cloud.Service class represents a cloud service that has a start and optional stop lifecycle.

Services are a common way to define long running code, such as microservices.

Usage

Creating a service

When defining a service, the first argument is an inflight closure that represents the service handler. This handler is responsible to perform any initialization activity and return asynchronously when initialization is complete.

bring cloud;

new cloud.Service(inflight () => {
  // ...
  // kick off any initialization activities asynchronously
  // ...
  log("Service started...");
});

Disable auto-start

By default the service resource will start automatically, however this can be disabled by passing autoStart: false to the constructor.

bring cloud;

let handler = inflight () => {
  log("service started...");
};

let service = new cloud.Service(handler, autoStart: false);

Service cleanup

Optionally, the service handler inflight closure can return another inflight closure which will be called when the service is stopped. Using a return closure allows naturally passing context between the async calls.

bring cloud;

new cloud.Service(inflight() => {
  let server = startHttpServer();
  log("Service started...");
  return () => {
    log("Service stopped...");
    server.close();
  };
});

Stopping and starting a service

The inflight methods start() and stop() are used exactly how they sound, to stop and start the service. The method started() returns a bool indicating if the service is currently started.

Here is an example of using a service that will track how often it is started and stopped using counters.

An important aspect to note is that consecutive starts and stops have no affect on a service. For example, if a service.start() is called on a service that is already started, nothing will happen.

bring cloud;

let startCounter = new cloud.Counter() as "start counter";
let stopCounter = new cloud.Counter() as "stop counter";

let handler = inflight() => {
  let i = startCounter.inc();
  log("Service started for the ${i}th time...");
  return () => {
    let i = stopCounter.inc();
    log("Service stopped for the ${i}th time...");
  };
};

let service = new cloud.Service(handler, autoStart: false);

// Functions to stop and start the service
new cloud.Function(inflight() => {
  service.start();
  assert(service.started());
}) as "start service";

new cloud.Function(inflight() => {
  service.stop();
  assert(!service.started());
}) as "stop service";

Target-specific details

Simulator (`sim`)

Within the context of the simulator, services are just spawned processes ran within a node vm.

AWS (`tf-aws` and `awscdk`)

Within the context of AWS, services are created using AWS ECS, with a capacity provider of FARGATE. This also requires a VPC and a related resources such as security groups, subnets, and an internet gateway, etc. If a VPC is not specified in wing.toml, a default VPC will be created.

The inflight closures are packaged up into a docker image and pushed to an AWS ECR repository.

Azure (`tf-azure`)

🚧 Not supported yet (tracking issue: #1307)

GCP (`tf-gcp`)

🚧 Not supported yet (tracking issue: #1308)

API Reference

Service

Implements: IInflightHost

A long-running service.

Initializers

bring cloud;

new cloud.Service(handler: IServiceHandler, props?: ServiceProps);

Name	Type	Description
`handler`	`IServiceHandler`	No description.
`props`	`ServiceProps`	No description.

`handler`^Required

Type: IServiceHandler

`props`^Optional

Type: ServiceProps

Methods

Preflight Methods

Name	Description
`addEnvironment`	Add an environment variable to the function.

Inflight Methods

Name	Description
`start`	Start the service.
`started`	Indicates whether the service is started.
`stop`	Stop the service.

`addEnvironment`

addEnvironment(name: str, value: str): void

Add an environment variable to the function.

`name`^Required

Type: str

`value`^Required

Type: str

`start`

inflight start(): void

Start the service.

`started`

inflight started(): bool

Indicates whether the service is started.

`stop`

inflight stop(): void

Stop the service.

Static Functions

Name	Description
`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 cloud;

cloud.Service.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.

`host`^Required

Type: IInflightHost

`ops`^Required

Type: MutArray<str>

`toInflight`

bring cloud;

cloud.Service.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.

`obj`^Required

Type: IResource

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`env`	`MutMap<str>`	Returns the set of environment variables for this function.

`node`^Required

node: Node;

Type: constructs.Node

The tree node.

`env`^Required

env: MutMap<str>;

Type: MutMap<str>

Returns the set of environment variables for this function.

Structs

ServiceOnStartOptions

Options for Service.onStart.

Initializer

bring cloud;

let ServiceOnStartOptions = cloud.ServiceOnStartOptions{ ... };

Properties

Name	Type	Description
`concurrency`	`num`	The maximum concurrent invocations that can run at one time.
`env`	`MutMap<str>`	Environment variables to pass to the function.
`logRetentionDays`	`num`	Specifies the number of days that function logs will be kept.
`memory`	`num`	The amount of memory to allocate to the function, in MB.
`timeout`	`duration`	The maximum amount of time the function can run.

`concurrency`^Optional

concurrency: num;

Type: num
Default: platform specific limits (100 on the simulator)

The maximum concurrent invocations that can run at one time.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: No environment variables.

Environment variables to pass to the function.

`logRetentionDays`^Optional

logRetentionDays: num;

Type: num
Default: 30

Specifies the number of days that function logs will be kept.

Setting negative value means logs will not expire.

`memory`^Optional

memory: num;

Type: num
Default: 1024

The amount of memory to allocate to the function, in MB.

`timeout`^Optional

timeout: duration;

Type: duration
Default: 1m

The maximum amount of time the function can run.

ServiceProps

Options for Service.

Initializer

bring cloud;

let ServiceProps = cloud.ServiceProps{ ... };

Properties

Name	Type	Description
`autoStart`	`bool`	Whether the service should start automatically.
`env`	`MutMap<str>`	Environment variables to pass to the function.

`autoStart`^Optional

autoStart: bool;

Type: bool
Default: true

Whether the service should start automatically.

If false, the service will need to be started manually by calling the inflight start() method.

`env`^Optional

env: MutMap<str>;

Type: MutMap<str>
Default: No environment variables.

Environment variables to pass to the function.

Protocols

IServiceHandler

Extends: IInflight
Implemented By: IServiceHandler

Inflight client: @winglang/sdk.cloud.IServiceHandlerClient

Executed when a cloud.Service is started.

IServiceHandlerClient

Implemented By: IServiceHandlerClient

Inflight client for IServiceHandler.

Methods

Name	Description
`handle`	Handler to run when the service starts.

`handle`

inflight handle(): IServiceStopHandler?

Handler to run when the service starts.

This is where you implement the initialization logic of the service, start any activities asynchronously.

DO NOT BLOCK! This handler should return as quickly as possible. If you need to run a long running process, start it asynchronously.

Example

bring cloud;

new cloud.Service(inflight () => {
  log("starting service...");
  return () => {
    log("stoping service...");
  };
});

IServiceStopHandler

Extends: IInflight
Implemented By: IServiceStopHandler

Inflight client: @winglang/sdk.cloud.IServiceStopHandlerClient

Executed when a cloud.Service is stopped.

IServiceStopHandlerClient

Implemented By: IServiceStopHandlerClient

Inflight client for IServiceStopHandler.

Methods

Name	Description
`handle`	Handler to run when the service stops.

`handle`

inflight handle(): void

Handler to run when the service stops.

This is where you implement the cleanup logic of the service, stop any activities asychronously.

Usage​

Creating a service​

Disable auto-start​

Service cleanup​

Stopping and starting a service​

Target-specific details​

Simulator (sim)​

AWS (tf-aws and awscdk)​

Azure (tf-azure)​

GCP (tf-gcp)​

API Reference ​

Service ​

Initializers ​

handlerRequired ​

propsOptional ​

Methods ​

Preflight Methods​

Inflight Methods​

addEnvironment ​

nameRequired ​

valueRequired ​

start ​

started ​

stop ​

Static Functions ​

onLiftType ​

hostRequired ​

opsRequired ​

toInflight ​

objRequired ​

Properties ​

nodeRequired ​

envRequired ​

Structs ​

ServiceOnStartOptions ​

Initializer ​

Properties ​

concurrencyOptional ​

envOptional ​

logRetentionDaysOptional ​

memoryOptional ​

timeoutOptional ​

ServiceProps ​

Initializer ​

Properties ​

autoStartOptional ​

envOptional ​

Protocols ​

IServiceHandler ​

IServiceHandlerClient ​

Methods ​

handle ​

IServiceStopHandler ​

IServiceStopHandlerClient ​

Methods ​

handle ​

Usage

Creating a service

Disable auto-start

Service cleanup

Stopping and starting a service

Target-specific details

Simulator (`sim`)

AWS (`tf-aws` and `awscdk`)

Azure (`tf-azure`)

GCP (`tf-gcp`)

API Reference

Service

Initializers

`handler`^Required

`props`^Optional

Methods

Preflight Methods

Inflight Methods

`addEnvironment`

`name`^Required

`value`^Required

`start`

`started`

`stop`

Static Functions

`onLiftType`

`host`^Required

`ops`^Required

`toInflight`

`obj`^Required

Properties

`node`^Required

`env`^Required

Structs

ServiceOnStartOptions

Initializer

Properties

`concurrency`^Optional

`env`^Optional

`logRetentionDays`^Optional

`memory`^Optional

`timeout`^Optional

ServiceProps

Initializer

Properties

`autoStart`^Optional

`env`^Optional

Protocols

IServiceHandler

IServiceHandlerClient

Methods

`handle`

IServiceStopHandler

IServiceStopHandlerClient

Methods

`handle`