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.