@microagi/alchemy-gcp 0.2.0 → 0.3.0

package/lib/Run/Validation.js.map

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

package/lib/Run/index.d.ts

@@ -0,0 +1,51 @@
+import type * as run from "@distilled.cloud/gcp/run-v2";
+export { Job, JobProvider } from "./Job.ts";
+export type { JobAttributes, JobProps } from "./Job.ts";
+export { jobIamMember, serviceIamMember } from "./IamMember.ts";
+export type { RunIamBinding, RunIamBindingContract } from "./IamSync.ts";
+export { Service, ServiceProvider } from "./Service.ts";
+export type { ServiceAttributes, ServiceProps } from "./Service.ts";
+/**
+ * Clean aliases for the most commonly-used Cloud Run v2 SDK types,
+ * re-exported from `@distilled.cloud/gcp/run-v2` so consumers don't
+ * need to import from the underlying SDK directly. The aliases are
+ * type-only — they share identity with the distilled types, so values
+ * are interchangeable.
+ *
+ * The `GoogleCloudRunV2*` prefix on the SDK types is generated from
+ * the GCP Discovery Document and is awkward to consume; these aliases
+ * mirror the casing the GCP REST docs use ("RevisionTemplate",
+ * "Container", "TrafficTarget"), which is what most users will
+ * already have in their heads.
+ *
+ * @example
+ * ```typescript
+ * import * as GCP from "@microagi/alchemy-gcp";
+ *
+ * const template: GCP.RevisionTemplate = {
+ *   containers: [{ image: "..." }],
+ * };
+ * ```
+ */
+export type RevisionTemplate = run.GoogleCloudRunV2RevisionTemplate;
+export type ExecutionTemplate = run.GoogleCloudRunV2ExecutionTemplate;
+export type TaskTemplate = run.GoogleCloudRunV2TaskTemplate;
+export type Container = run.GoogleCloudRunV2Container;
+export type ContainerPort = run.GoogleCloudRunV2ContainerPort;
+export type EnvVar = run.GoogleCloudRunV2EnvVar;
+export type EnvVarSource = run.GoogleCloudRunV2EnvVarSource;
+export type ResourceRequirements = run.GoogleCloudRunV2ResourceRequirements;
+export type Probe = run.GoogleCloudRunV2Probe;
+export type VpcAccess = run.GoogleCloudRunV2VpcAccess;
+export type NetworkInterface = run.GoogleCloudRunV2NetworkInterface;
+export type NodeSelector = run.GoogleCloudRunV2NodeSelector;
+export type TrafficTarget = run.GoogleCloudRunV2TrafficTarget;
+export type TrafficTargetStatus = run.GoogleCloudRunV2TrafficTargetStatus;
+export type ServiceScaling = run.GoogleCloudRunV2ServiceScaling;
+export type BinaryAuthorization = run.GoogleCloudRunV2BinaryAuthorization;
+export type Volume = run.GoogleCloudRunV2Volume;
+export type VolumeMount = run.GoogleCloudRunV2VolumeMount;
+export type Condition = run.GoogleCloudRunV2Condition;
+export type ExecutionReference = run.GoogleCloudRunV2ExecutionReference;
+export type SecretKeySelector = run.GoogleCloudRunV2SecretKeySelector;
+//# sourceMappingURL=index.d.ts.map

package/lib/Run/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Run/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,GAAG,MAAM,6BAA6B,CAAC;AAExD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,gCAAgC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,iCAAiC,CAAC;AACtE,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,4BAA4B,CAAC;AAC5D,MAAM,MAAM,SAAS,GAAG,GAAG,CAAC,yBAAyB,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,6BAA6B,CAAC;AAC9D,MAAM,MAAM,MAAM,GAAG,GAAG,CAAC,sBAAsB,CAAC;AAChD,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,4BAA4B,CAAC;AAC5D,MAAM,MAAM,oBAAoB,GAAG,GAAG,CAAC,oCAAoC,CAAC;AAC5E,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,qBAAqB,CAAC;AAC9C,MAAM,MAAM,SAAS,GAAG,GAAG,CAAC,yBAAyB,CAAC;AACtD,MAAM,MAAM,gBAAgB,GAAG,GAAG,CAAC,gCAAgC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,4BAA4B,CAAC;AAC5D,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,6BAA6B,CAAC;AAC9D,MAAM,MAAM,mBAAmB,GAAG,GAAG,CAAC,mCAAmC,CAAC;AAC1E,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,8BAA8B,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,GAAG,CAAC,mCAAmC,CAAC;AAC1E,MAAM,MAAM,MAAM,GAAG,GAAG,CAAC,sBAAsB,CAAC;AAChD,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,2BAA2B,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG,GAAG,CAAC,yBAAyB,CAAC;AACtD,MAAM,MAAM,kBAAkB,GAAG,GAAG,CAAC,kCAAkC,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,iCAAiC,CAAC"}

package/lib/Run/index.js

@@ -0,0 +1,4 @@
+export { Job, JobProvider } from "./Job.js";
+export { jobIamMember, serviceIamMember } from "./IamMember.js";
+export { Service, ServiceProvider } from "./Service.js";
+//# sourceMappingURL=index.js.map

package/lib/Run/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Run/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./CloudResourceManager/index.ts";
 export * from "./Compute/index.ts";
 export * from "./Container/index.ts";
 export * from "./ManagedLustre/index.ts";
+export * from "./Run/index.ts";
 export * from "./ServiceNetworking/index.ts";
 export * from "./ServiceUsage/index.ts";
 export * from "./Providers.ts";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}

package/lib/index.js

@@ -4,6 +4,7 @@ export * from "./CloudResourceManager/index.js";
 export * from "./Compute/index.js";
 export * from "./Container/index.js";
 export * from "./ManagedLustre/index.js";
+export * from "./Run/index.js";
 export * from "./ServiceNetworking/index.js";
 export * from "./ServiceUsage/index.js";
 export * from "./Providers.js";

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAKhC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,EACL,sBAAsB,EACtB,OAAO,GACR,MAAM,wBAAwB,CAAC;AAKhC,cAAc,iCAAiC,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@microagi/alchemy-gcp",
-  "version": "0.2.0",
-  "description": "GCP provider for Alchemy v2 (Effect-based IaC). Resources for Project, Cluster, NodePool, Compute, ManagedLustre, ServiceUsage, ServiceNetworking, with ADC-backed credentials and target-side IAM bindings.",
+  "version": "0.3.0",
+  "description": "GCP provider for Alchemy v2 (Effect-based IaC). Resources for Project, Cluster, NodePool, Compute, ManagedLustre, ServiceUsage, ServiceNetworking, Cloud Run (Service + Job + IAM), with ADC-backed credentials and target-side IAM bindings.",
   "keywords": [
     "alchemy",
     "alchemy-effect",
@@ -31,6 +31,7 @@
   "files": [
     "lib",
     "src",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -57,10 +58,10 @@
     "effect": ">=4.0.0-beta.60 || >=4.0.0"
   },
   "devDependencies": {
-    "@distilled.cloud/gcp": "0.19.0",
+    "@distilled.cloud/gcp": "workspace:*",
     "@types/bun": "latest",
     "@types/node": "latest",
-    "alchemy": "2.0.0-beta.34",
+    "alchemy": "workspace:*",
     "effect": ">=4.0.0-beta.60 || >=4.0.0",
     "typescript": "^6.0.3"
   },

package/src/Container/Cluster.ts

@@ -88,6 +88,31 @@ export type ClusterProps = {
     networkPolicyConfig?: { disabled?: boolean };
     gcePersistentDiskCsiDriverConfig?: { enabled?: boolean };
     gcsFuseCsiDriverConfig?: { enabled?: boolean };
+    /**
+     * Managed Lustre CSI driver (mount `GCP.ManagedLustreInstance`
+     * volumes as ReadWriteMany PVCs from pods). Driver is installed
+     * cluster-wide once enabled; the StorageClass + PV bindings are
+     * still authored by the consumer.
+     */
+    lustreCsiDriverConfig?: {
+      enabled?: boolean;
+      /**
+       * Workaround for a port conflict between the Lustre CSI driver
+       * and `gke-metadata-server`. Required ONLY when the cluster's
+       * GKE node version is older than `1.33.2-gke.4655000` AND you
+       * are mounting a `ManagedLustreInstance` with
+       * `gkeSupportEnabled: true`. Deprecated otherwise — leave
+       * unset on modern node versions.
+       */
+      enableLegacyLustrePort?: boolean;
+      /**
+       * Disable the driver's multi-NIC auto-configuration. By
+       * default it discovers and binds every suitable NIC on each
+       * node for maximum I/O throughput. Set true only if multi-NIC
+       * causes a problem in your network topology.
+       */
+      disableMultiNic?: boolean;
+    };
     gkeBackupAgentConfig?: { enabled?: boolean };
     dnsCacheConfig?: { enabled?: boolean };
     configConnectorConfig?: { enabled?: boolean };

package/src/Providers.ts

@@ -17,6 +17,8 @@ import {
   ManagedLustreInstance,
   ManagedLustreInstanceProvider,
 } from "./ManagedLustre/Instance.ts";
+import { Job, JobProvider } from "./Run/Job.ts";
+import { Service, ServiceProvider } from "./Run/Service.ts";
 import {
   PsaConnection,
   PsaConnectionProvider,
@@ -57,6 +59,8 @@ export const providers = () =>
       SharedVpcServiceProject,
       PsaConnection,
       ManagedLustreInstance,
+      Service,
+      Job,
     ]),
   ).pipe(
     Layer.provide(
@@ -72,6 +76,8 @@ export const providers = () =>
         SharedVpcServiceProjectProvider(),
         PsaConnectionProvider(),
         ManagedLustreInstanceProvider(),
+        ServiceProvider(),
+        JobProvider(),
       ),
     ),
     Layer.provideMerge(fromAuthProvider()),

package/src/Run/IamMember.ts

@@ -0,0 +1,79 @@
+import * as Effect from "effect/Effect";
+import type { Job } from "./Job.ts";
+import type { Service } from "./Service.ts";
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a Cloud Run
+ * {@link Service}.
+ *
+ * Target-side binding — see
+ * {@link import("../Compute/SubnetworkIamMember.ts").subnetworkIamMember}
+ * for the pattern, the SID-collision pitfall, and why `key` exists.
+ * Service's `reconcile` merges all bindings into a single
+ * `setIamPolicy` call against the service, preserving foreign roles
+ * and members on the policy. To remove a binding, drop the call and
+ * re-deploy — the provider is additive within the bindings we
+ * declared, but does NOT prune.
+ *
+ * The most common usage:
+ *
+ * - **Public invoker:** `{ role: "roles/run.invoker", member: "allUsers" }`
+ *   makes the service publicly reachable. Prefer this over
+ *   `invokerIamDisabled: true` on the {@link Service} props — declarative
+ *   IAM is auditable in `setIamPolicy` history; `invokerIamDisabled`
+ *   is a flag with no audit trail.
+ * - **Service-to-service:** a downstream service's runtime SA bound
+ *   to `roles/run.invoker` on the upstream service.
+ *
+ * @example Public Cloud Run service
+ * ```typescript
+ * const api = yield* GCP.Service("PublicApi", { ... });
+ * yield* GCP.serviceIamMember(api, "PublicInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: "allUsers",
+ * });
+ * ```
+ *
+ * @example Service-to-service auth
+ * ```typescript
+ * const upstream = yield* GCP.Service("Upstream", { ... });
+ * yield* GCP.serviceIamMember(upstream, "DownstreamCaller", {
+ *   role: "roles/run.invoker",
+ *   member: `serviceAccount:${downstreamSa.email}`,
+ * });
+ * ```
+ */
+export const serviceIamMember = (
+  service: Service,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  service.bind`IamMember(${service}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;
+
+/**
+ * Bind a single `(role, member)` IAM grant onto a Cloud Run {@link Job}.
+ *
+ * Same target-side pattern as {@link serviceIamMember}. The most
+ * common Job binding is `roles/run.invoker` on the service account
+ * that triggers the job (Cloud Scheduler, Eventarc, Workflows, or a
+ * developer's user identity).
+ *
+ * @example Letting a Cloud Scheduler SA trigger the job
+ * ```typescript
+ * const nightly = yield* GCP.Job("Nightly", { ... });
+ * yield* GCP.jobIamMember(nightly, "SchedulerInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: `serviceAccount:${schedulerSa.email}`,
+ * });
+ * ```
+ */
+export const jobIamMember = (
+  job: Job,
+  key: string,
+  args: { role: string; member: string },
+): Effect.Effect<void> =>
+  job.bind`IamMember(${job}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+  }) as unknown as Effect.Effect<void>;

package/src/Run/IamSync.ts

@@ -0,0 +1,134 @@
+import type * as run from "@distilled.cloud/gcp/run-v2";
+import type { ResourceBinding } from "alchemy/Resource";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+
+/**
+ * Common shape of Cloud Run's `getIamPolicy` / `setIamPolicy` request
+ * inputs — Service and Job declare nominally distinct request types,
+ * but both reduce to `{ resource, body? }` plus the version query for
+ * get. We model the operation surface generically so {@link makeSyncIam}
+ * can serve both targets without duplication.
+ *
+ * @internal
+ */
+type GetIamPolicyOp = (input: {
+  resource: string;
+  "options.requestedPolicyVersion"?: number;
+}) => Effect.Effect<run.GoogleIamV1Policy, unknown, never>;
+
+type SetIamPolicyOp = (input: {
+  resource: string;
+  body?: run.GoogleIamV1SetIamPolicyRequest;
+}) => Effect.Effect<run.GoogleIamV1Policy, unknown, never>;
+
+/**
+ * Single `(role, members)` entry on a Cloud Run target's IAM policy.
+ * Identical shape between Service and Job — both Cloud Run resources
+ * speak the same `iam.v1.Policy`, so the binding contract is shared.
+ *
+ * @example
+ * ```typescript
+ * yield* GCP.serviceIamMember(svc, "PublicInvoker", {
+ *   role: "roles/run.invoker",
+ *   member: "allUsers",
+ * });
+ * ```
+ */
+export type RunIamBinding = {
+  /** IAM role, e.g. `"roles/run.invoker"`. */
+  role: string;
+  /** Principals, e.g. `["allUsers"]` or `["serviceAccount:foo@bar.iam.gserviceaccount.com"]`. */
+  members: ReadonlyArray<string>;
+};
+
+/**
+ * Binding contract for a Cloud Run target — services and jobs both
+ * accept a list of `iamBindings` records via the alchemy `.bind`
+ * mechanism. The reconciler reads `bindings` from its arguments and
+ * routes them through {@link makeSyncIam}.
+ */
+export type RunIamBindingContract = {
+  iamBindings: ReadonlyArray<RunIamBinding>;
+};
+
+/**
+ * Build a reusable `syncIam` step parametrised by the resolved
+ * `getIamPolicy` / `setIamPolicy` callables. Cloud Run's Service and
+ * Job IAM endpoints have identical request/response shapes (both
+ * `resource: "projects/{p}/locations/{l}/{kind}/{n}"`), so the same
+ * helper works for both — the caller just hands in the right pair of
+ * callables.
+ *
+ * Semantics, mirroring `Compute/Subnetwork.ts`:
+ *
+ * - **Union bindings per role across all `.bind` callers.** Multiple
+ *   capabilities granting the same role get their members merged into
+ *   a single binding.
+ * - **Preserve foreign roles and members verbatim.** We never displace
+ *   bindings we didn't author. The provider is additive — to remove a
+ *   binding, drop the `.bind` call and re-deploy (a future revision
+ *   could narrow this; for now it matches the existing idiom).
+ * - **Etag round-trip.** `getIamPolicy` returns an etag; we pass it
+ *   through `setIamPolicy` so a concurrent edit racing us surfaces as
+ *   `Conflict`. We retry exponentially up to ~1.5 min — enough to
+ *   absorb normal CI/human contention without masking real failures.
+ */
+export const makeSyncIam =
+  (api: { getIamPolicy: GetIamPolicyOp; setIamPolicy: SetIamPolicyOp }) =>
+  (args: {
+    /** Fully-qualified resource name: `projects/{p}/locations/{l}/{kind}/{n}`. */
+    resource: string;
+    bindings: ReadonlyArray<ResourceBinding<RunIamBindingContract>>;
+  }) =>
+    Effect.gen(function* () {
+      const desiredByRole = new Map<string, Set<string>>();
+      for (const b of args.bindings) {
+        for (const ib of b.data.iamBindings) {
+          const set = desiredByRole.get(ib.role) ?? new Set<string>();
+          for (const m of ib.members) set.add(m);
+          desiredByRole.set(ib.role, set);
+        }
+      }
+      if (desiredByRole.size === 0) return;
+
+      const current = yield* api.getIamPolicy({
+        resource: args.resource,
+        "options.requestedPolicyVersion": 3,
+      });
+
+      const bindings = (current.bindings ?? []).map((b) => ({
+        ...b,
+        members: [...(b.members ?? [])],
+      }));
+      let mutated = false;
+      for (const [role, members] of desiredByRole) {
+        let existing = bindings.find((b) => b.role === role && !b.condition);
+        if (!existing) {
+          existing = { role, members: [] };
+          bindings.push(existing);
+        }
+        const merged = new Set([...(existing.members ?? []), ...members]);
+        if (merged.size !== (existing.members?.length ?? 0)) mutated = true;
+        existing.members = [...merged];
+      }
+      if (!mutated) return;
+
+      yield* api.setIamPolicy({
+        resource: args.resource,
+        body: {
+          policy: {
+            ...current,
+            bindings,
+            version: 3,
+          },
+        },
+      });
+    }).pipe(
+      Effect.retry({
+        schedule: Schedule.exponential(Duration.seconds(2)).pipe(
+          Schedule.both(Schedule.recurs(8)),
+        ),
+      }),
+    );