@alchemy.run/modal 0.0.0 → 2.0.0-beta.86

package/lib/Server.d.ts

@@ -0,0 +1,155 @@
+import * as functions from "@distilled.cloud/modal/functions";
+import { Platform, type Main, type MainRpc } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import type { Resource } from "alchemy/Resource";
+import type { HostRuntimeContext, ServerHost } from "alchemy/Runtime/Process";
+import type { ContainerProps } from "./Container.ts";
+import { type RuntimeAttributes } from "./internal/Runtime.ts";
+import type { MountContract } from "./Mounts.ts";
+import type { Providers } from "./Providers.ts";
+import type { DurationInput } from "./SandboxClient.ts";
+export interface ServerProps extends ContainerProps {
+    /**
+     * Region requests are routed through (`"us-east"`, `"us-west"`, `"eu-west"`,
+     * `"ap-south"`, ...). Containers run near it.
+     * @default "us-east"
+     */
+    routingRegion?: string;
+    /**
+     * Serve without Modal's proxy auth. By default every request needs the
+     * `Modal-Key` / `Modal-Secret` headers of a `Modal.WebhookToken`.
+     * @default false
+     */
+    unauthenticated?: boolean;
+    /** Serve HTTP/2 to the program. */
+    h2?: boolean;
+    /**
+     * Time in-flight requests get to finish when a container shuts down, at
+     * most an hour.
+     * @default 0
+     */
+    exitGracePeriod?: DurationInput;
+    /**
+     * Concurrent requests per container the autoscaler aims for; may be
+     * fractional (`1.5`). `0` turns autoscaling off.
+     */
+    targetConcurrency?: number;
+    /**
+     * Most concurrent requests per container; more get `429`.
+     * @default unlimited
+     */
+    maxConcurrency?: number;
+    /**
+     * Sticky sessions: each session is pinned to one container
+     * (`server.sessions.start()` in Modal's clients).
+     * @default false
+     */
+    sessioned?: boolean;
+}
+export interface ServerAttributes extends RuntimeAttributes {
+    /** The Server's URL. */
+    url: string | undefined;
+    /** Region requests are routed through. */
+    routingRegion: string;
+    /** Whether requests skip Modal's proxy auth. */
+    unauthenticated: boolean;
+}
+export type Server = Resource<"Modal.Server", ServerProps, ServerAttributes, {
+    env?: Record<string, any>;
+    mounts?: MountContract;
+    rpcCallers?: string[];
+}, Providers>;
+export type ServerServices = ServerHost;
+/**
+ * What the program returns: `fetch` for HTTP, and any other functions,
+ * its RPC methods.
+ */
+export type ServerShape = Main<ServerServices> | (Exclude<Main<ServerServices>, void> & MainRpc<ServerServices>);
+export type ServerRuntimeContext = HostRuntimeContext;
+/**
+ * A Modal Server: your program as a long-running HTTP server on Modal, with
+ * low-latency routing through one region and autoscaling on concurrent
+ * requests. Use it for APIs, model servers and anything that keeps
+ * connections open; use `Modal.Function` with `web` for simple endpoints.
+ *
+ * Alchemy bundles `main`, builds it into an image on Modal's builder (no
+ * Docker) and deploys the Server into its `Modal.App`. Each container starts
+ * the program, and Modal routes the Server's URL to its `fetch` handler.
+ * Requests need Modal's proxy auth headers unless `unauthenticated` is set:
+ * bind `Modal.FetchServer(server)` to call it from another runtime.
+ *
+ * ### Effect program
+ * **Example:** An API server
+ * ```typescript
+ * // src/Api.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Backend } from "./Backend.ts";
+ *
+ * export default class Api extends Modal.Server<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, app: Backend, routingRegion: "us-east" },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * ### Async program
+ * **Example:** A plain HTTP server, no Effect (it runs on Bun)
+ * ```typescript
+ * // src/Api.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import { Backend } from "./Backend.ts";
+ *
+ * export const Api = Modal.Server("Api", {
+ *   main: "./src/api-server.ts",
+ *   app: Backend,
+ *   unauthenticated: true,
+ *   env: { GREETING: "hello" },
+ * });
+ * export type ApiEnv = Modal.InferEnv<typeof Api>;
+ * ```
+ *
+ * ```typescript
+ * // src/api-server.ts
+ * import type { ApiEnv } from "./Api.ts";
+ *
+ * const env = process.env as unknown as ApiEnv;
+ *
+ * Bun.serve({ port: Number(process.env.PORT), fetch: () => new Response(env.GREETING) });
+ * ```
+ *
+ * ### Calling it
+ * **Example:** From a Cloudflare Worker, with proxy auth
+ * ```typescript
+ * const api = yield* Modal.FetchServer(Api);
+ * const response = yield* api.fetch(HttpClientRequest.get("/"));
+ * ```
+ *
+ * ### Scaling
+ * **Example:** Two warm containers, 20 requests each
+ * ```typescript
+ * export default class Api extends Modal.Server<Api>()(
+ *   "Api",
+ *   {
+ *     main: import.meta.url,
+ *     app: Backend,
+ *     minContainers: 2,
+ *     targetConcurrency: 20,
+ *     maxConcurrency: 50,
+ *     exitGracePeriod: "30 seconds",
+ *   },
+ *   program,
+ * ) {}
+ * ```
+ *
+ * @resource
+ * @product Server
+ */
+export declare const Server: Platform<Server, ServerServices, ServerShape, ServerRuntimeContext>;
+export declare const ServerProvider: () => import("effect/Layer").Layer<Provider.Provider<Server>, never, import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | functions.ModalOpContext>;
+//# sourceMappingURL=Server.d.ts.map

package/lib/Server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Server.d.ts","sources":["../src/Server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mCAAmC;IACnC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC;IAChC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD,wBAAwB;IACxB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,MAAM,GAAG,QAAQ,CAC3B,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC5E,SAAS,CACV,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC;AACxC;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,IAAI,CAAC,cAAc,CAAC,GACpB,CAAC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;AACpE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,oBAAoB,CAMtF,CAAC;AAsCF,eAAO,MAAM,cAAc,sOAsExB,CAAC"}

package/lib/Server.js

@@ -0,0 +1,184 @@
+import * as functions from "@distilled.cloud/modal/functions";
+import { Platform } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { environmentOf, seconds } from "./internal.js";
+import { ENTRYPOINT, RPC_SERVE_ENV } from "./internal/Entrypoint.js";
+import { createModalRuntimeContext } from "./internal/Rpc.js";
+import { resolveContainerProps, runtimeLifecycle, } from "./internal/Runtime.js";
+/**
+ * A Modal Server: your program as a long-running HTTP server on Modal, with
+ * low-latency routing through one region and autoscaling on concurrent
+ * requests. Use it for APIs, model servers and anything that keeps
+ * connections open; use `Modal.Function` with `web` for simple endpoints.
+ *
+ * Alchemy bundles `main`, builds it into an image on Modal's builder (no
+ * Docker) and deploys the Server into its `Modal.App`. Each container starts
+ * the program, and Modal routes the Server's URL to its `fetch` handler.
+ * Requests need Modal's proxy auth headers unless `unauthenticated` is set:
+ * bind `Modal.FetchServer(server)` to call it from another runtime.
+ *
+ * ### Effect program
+ * **Example:** An API server
+ * ```typescript
+ * // src/Api.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Backend } from "./Backend.ts";
+ *
+ * export default class Api extends Modal.Server<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, app: Backend, routingRegion: "us-east" },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * ### Async program
+ * **Example:** A plain HTTP server, no Effect (it runs on Bun)
+ * ```typescript
+ * // src/Api.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import { Backend } from "./Backend.ts";
+ *
+ * export const Api = Modal.Server("Api", {
+ *   main: "./src/api-server.ts",
+ *   app: Backend,
+ *   unauthenticated: true,
+ *   env: { GREETING: "hello" },
+ * });
+ * export type ApiEnv = Modal.InferEnv<typeof Api>;
+ * ```
+ *
+ * ```typescript
+ * // src/api-server.ts
+ * import type { ApiEnv } from "./Api.ts";
+ *
+ * const env = process.env as unknown as ApiEnv;
+ *
+ * Bun.serve({ port: Number(process.env.PORT), fetch: () => new Response(env.GREETING) });
+ * ```
+ *
+ * ### Calling it
+ * **Example:** From a Cloudflare Worker, with proxy auth
+ * ```typescript
+ * const api = yield* Modal.FetchServer(Api);
+ * const response = yield* api.fetch(HttpClientRequest.get("/"));
+ * ```
+ *
+ * ### Scaling
+ * **Example:** Two warm containers, 20 requests each
+ * ```typescript
+ * export default class Api extends Modal.Server<Api>()(
+ *   "Api",
+ *   {
+ *     main: import.meta.url,
+ *     app: Backend,
+ *     minContainers: 2,
+ *     targetConcurrency: 20,
+ *     maxConcurrency: 50,
+ *     exitGracePeriod: "30 seconds",
+ *   },
+ *   program,
+ * ) {}
+ * ```
+ *
+ * @resource
+ * @product Server
+ */
+export const Server = Platform("Modal.Server", {
+    createRuntimeContext: createModalRuntimeContext("Modal.Server"),
+    transformProps: resolveContainerProps,
+});
+const bootstrapEntry = (handler) => (importPath) => `
+import { bootstrap } from "@alchemy.run/modal/Bootstrap";
+import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
+
+await bootstrap(entrypoint);
+`;
+const DEFAULT_REGION = "us-east";
+const definitionOf = (props, context) => {
+    const region = props.routingRegion ?? DEFAULT_REGION;
+    return {
+        implementationName: ENTRYPOINT.server,
+        isServer: true,
+        isSessioned: props.sessioned ?? false,
+        routingRegion: region,
+        httpConfig: {
+            port: context.port,
+            proxyRegions: [region],
+            startupTimeout: Math.round(context.startupTimeout),
+            exitGracePeriod: Math.round(seconds(props.exitGracePeriod) ?? 0),
+            h2Enabled: props.h2 ?? false,
+            unauthenticated: props.unauthenticated ?? false,
+        },
+        maxConcurrentInputs: props.maxConcurrency ?? 0,
+        supportedInputFormats: [],
+        supportedOutputFormats: [],
+    };
+};
+export const ServerProvider = () => Provider.effect(Server, Effect.gen(function* () {
+    const lifecycle = yield* runtimeLifecycle({
+        type: "Modal.Server",
+        definition: (props, context) => {
+            const definition = definitionOf(props, context);
+            return props.targetConcurrency === undefined
+                ? definition
+                : {
+                    ...definition,
+                    autoscalerSettings: { targetConcurrencyFloat: props.targetConcurrency },
+                };
+        },
+        bootstrap: bootstrapEntry,
+        // Behind proxy auth Modal authenticates every request, so the
+        // program serves RPC; an unauthenticated Server never does.
+        env: (props) => props.unauthenticated ? {} : { [RPC_SERVE_ENV]: "1" },
+    });
+    /** The Server's URL: Modal assigns it once the App is published. */
+    const urlOf = Effect.fn(function* (attributes, published) {
+        if (published?.[0])
+            return published[0];
+        const found = yield* functions
+            .getFunction({
+            appName: attributes.appName ?? "",
+            objectTag: attributes.name,
+            environmentName: environmentOf(attributes.environment),
+        })
+            .pipe(Effect.map((response) => response.handleMetadata?.ExperimentalFlashUrls?.[0]), Effect.repeat({
+            schedule: Schedule.spaced("2 seconds"),
+            until: (url) => url !== undefined,
+            times: 10,
+        }));
+        return found;
+    });
+    return {
+        stables: lifecycle.stables,
+        diff: lifecycle.diff,
+        read: Effect.fn(function* ({ output }) {
+            const found = yield* lifecycle.read({ output });
+            return found === undefined ? undefined : output;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session, bindings }) {
+            const { attributes, metadata } = yield* lifecycle.reconcile({
+                id,
+                news,
+                output,
+                session,
+                bindings,
+            });
+            return {
+                ...attributes,
+                url: yield* urlOf(attributes, metadata?.ExperimentalFlashUrls),
+                routingRegion: news.routingRegion ?? DEFAULT_REGION,
+                unauthenticated: news.unauthenticated ?? false,
+            };
+        }),
+        delete: lifecycle.delete,
+    };
+}));
+//# sourceMappingURL=Server.js.map

package/lib/Server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Server.js","sources":["../src/Server.ts"],"names":[],"mappings":"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"}

package/lib/ServiceUser.d.ts

@@ -0,0 +1,139 @@
+import * as environment from "@distilled.cloud/modal/environment";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { type EnvironmentInput } from "./internal.ts";
+import type { Providers } from "./Providers.ts";
+import type { DurationInput } from "./SandboxClient.ts";
+declare const ServiceUserUnexpectedResponse_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Modal.ServiceUserUnexpectedResponse";
+} & Readonly<A>;
+export declare class ServiceUserUnexpectedResponse extends ServiceUserUnexpectedResponse_base<{
+    readonly message: string;
+}> {
+}
+declare const ServiceUsersNotAvailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "Modal.ServiceUsersNotAvailable";
+} & Readonly<A>;
+/**
+ * The workspace's plan has no service users (Modal's Starter plan). Bindings
+ * create one per host; `Modal.DeployerHostIdentity` binds the deployer's token
+ * instead.
+ */
+export declare class ServiceUsersNotAvailable extends ServiceUsersNotAvailable_base<{
+    readonly message: string;
+}> {
+}
+/** A role a scoped service user holds in one environment. */
+export interface ServiceUserEnvironmentRole {
+    /** The environment: its name, or a yielded `Modal.Environment`. */
+    readonly environment: EnvironmentInput;
+    /** `viewer` reads; `contributor` also deploys and writes. */
+    readonly role: "viewer" | "contributor";
+}
+export interface ServiceUserProps {
+    /**
+     * Service user name, unique in the workspace. If omitted, one is generated
+     * from the stack, stage and logical ID. Changing it replaces the user (and
+     * its token).
+     */
+    name?: string;
+    /**
+     * Limit the user to the environments in {@link environments}. An unscoped
+     * user acts on the whole workspace. Changing it replaces the user.
+     * @default true
+     */
+    scoped?: boolean;
+    /** Roles of a scoped user, per environment. */
+    environments?: ServiceUserEnvironmentRole[];
+    /**
+     * Expire the user's token after this long. Changing it replaces the user.
+     * @default never
+     */
+    expiresIn?: DurationInput;
+}
+export interface ServiceUserAttributes {
+    /** Service user ID. */
+    serviceUserId: string;
+    /** Service user name. */
+    name: string;
+    /** Token ID (`ak-…`), the `MODAL_TOKEN_ID` of the user. */
+    tokenId: string;
+    /** Token secret (`as-…`), the `MODAL_TOKEN_SECRET` of the user. */
+    tokenSecret: Redacted.Redacted<string>;
+    /** Whether the user is limited to its environments. */
+    scoped: boolean;
+    /** Roles by environment name. */
+    environments: Record<string, "viewer" | "contributor">;
+}
+/**
+ * A Modal service user: a workspace identity with its own token pair, for
+ * CI or another system. A scoped user acts only in the environments you
+ * grant it, as a `viewer` or a `contributor`.
+ *
+ * Modal shows a service user's token secret once, at creation, so a user
+ * deleted outside Alchemy is recreated with a new token on the next deploy,
+ * and an existing user can't be adopted.
+ *
+ * ### Creating a service user
+ * **Example:** CI that deploys to one environment
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Staging = Modal.Environment("Staging", {});
+ * export const Deployer = Modal.ServiceUser("Deployer", {
+ *   environments: [{ environment: Staging, role: "contributor" }],
+ * });
+ * ```
+ *
+ * **Example:** A short-lived, read-only token
+ * ```typescript
+ * export const Auditor = Modal.ServiceUser("Auditor", {
+ *   environments: [{ environment: "main", role: "viewer" }],
+ *   expiresIn: "7 days",
+ * });
+ * ```
+ *
+ * ### Using its token
+ * **Example:** Hand the pair to a Worker that calls Modal as the user
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Effect from "effect/Effect";
+ *
+ * export const Ci = Effect.gen(function* () {
+ *   const deployer = yield* Deployer;
+ *   return yield* Cloudflare.Worker("Ci", {
+ *     main: "./src/ci.ts",
+ *     env: { MODAL_TOKEN_ID: deployer.tokenId, MODAL_TOKEN_SECRET: deployer.tokenSecret },
+ *   });
+ * });
+ * ```
+ *
+ * @resource
+ * @product Workspace
+ */
+export declare const ServiceUser: import("alchemy/Resource").ResourceConstructor<ServiceUser, Providers> & Effect.Effect<import("alchemy/Resource").ResourceConstructor<ServiceUser, never>, never, never> & {
+    Self: import("alchemy/Self").Self<ServiceUser>;
+    Provider: Provider.Provider<ServiceUser>;
+    Aliases: readonly string[] | undefined;
+    ref(id: string, options?: {
+        stage?: string;
+        stack?: string;
+    }): Effect.Effect<ServiceUser, never, never>;
+} & ((id: string, props: import("./internal/Declared.ts").DeclaredProps<ServiceUserProps>) => Effect.Effect<ServiceUser, never, Providers>);
+export type ServiceUser = Resource<"Modal.ServiceUser", ServiceUserProps, ServiceUserAttributes, {
+    /**
+     * Roles contributed by bindings: a binding on a host grants the host's
+     * service user the role it needs on the bound resource's environment
+     * (`undefined` is the workspace default). The strongest role per
+     * environment wins.
+     */
+    environments?: Array<{
+        readonly environment: string | undefined;
+        readonly role: "viewer" | "contributor";
+    }>;
+}, Providers>;
+export declare const ServiceUserProvider: () => import("effect/Layer").Layer<Provider.Provider<ServiceUser>, never, import("alchemy/Stack").Stack | import("alchemy/Stage").Stage | environment.ModalOpContext>;
+export {};
+//# sourceMappingURL=ServiceUser.d.ts.map

package/lib/ServiceUser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceUser.d.ts","sources":["../src/ServiceUser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,WAAW,MAAM,oCAAoC,CAAC;AAIlE,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAwB,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,KAAK,gBAAgB,EAAkC,MAAM,eAAe,CAAC;AAEtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;;;;AAExD,qBAAa,6BAA8B,SAAQ,mCAEjD;IACA,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;;;;AAEL;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,8BAAmD;IAC/F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;CAAG;AAEL,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAC5C;;;OAGG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,uBAAuB;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvC,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,GAAG,aAAa,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,WAAW;;;;;;;;2IAAwE,CAAC;AAEjG,MAAM,MAAM,WAAW,GAAG,QAAQ,CAChC,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB;IACE;;;;;OAKG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;QACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;QACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;KACzC,CAAC,CAAC;CACJ,EACD,SAAS,CACV,CAAC;AAyCF,eAAO,MAAM,mBAAmB,uKAkH7B,CAAC"}