1import type * as ECS from "@distilled.cloud/aws/ecs";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Cluster } from "./Cluster.ts";
5import type { Task } from "./Task.ts";
6
7export interface StartTaskRequest extends Omit<
8 ECS.StartTaskRequest,
9 "cluster" | "taskDefinition"
10> {}
11
12/**
13 * Runtime binding for `ecs:StartTask`.
14 *
15 * Bind this operation to a `Cluster` and `Task` inside a function runtime to
16 * get a callable that places the bound task definition on specific container
17 * instances (EC2/EXTERNAL launch types — unlike `RunTask`, which lets ECS
18 * pick placement). The cluster and task definition ARNs are injected
19 * automatically; the host is granted `ecs:StartTask` on the task definition
20 * plus `iam:PassRole` on the task and execution roles.
21 * ### Running Tasks
22 * **Example:** Start a Task on a Specific Container Instance
23 * ```typescript
24 * const controller = yield* AWS.Lambda.Function(
25 * "PlacementController",
26 * { main: import.meta.url },
27 * Effect.gen(function* () {
28 * // init: bind the launch (IAM grants happen here)
29 * const startTask = yield* AWS.ECS.StartTask(cluster, task);
30 *
31 * return {
32 * fetch: Effect.gen(function* () {
33 * // runtime: place the task on a chosen instance
34 * const response = yield* startTask({
35 * containerInstances: [containerInstanceArn],
36 * startedBy: "placement-controller",
37 * });
38 * return yield* HttpServerResponse.json({
39 * taskArn: response.tasks?.[0]?.taskArn,
40 * });
41 * }),
42 * };
43 * }),
44 * );
45 * ```
46 *
47 * @binding
48 */
49export interface StartTask extends Binding.Service<
50 StartTask,
51 "AWS.ECS.StartTask",
52 (
53 cluster: Cluster,
54 task: Task,
55 ) => Effect.Effect<
56 (
57 request: StartTaskRequest,
58 ) => Effect.Effect<ECS.StartTaskResponse, ECS.StartTaskError>
59 >
60> {}
61export const StartTask = Binding.Service<StartTask>("AWS.ECS.StartTask");