alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/lib/Railway/Volume.d.ts

@@ -0,0 +1,265 @@
+import type { EnvironmentResponseVolumeInstancesEdgesItemNode, VolumeState } from "@distilled.cloud/railway";
+import * as railway from "@distilled.cloud/railway";
+import * as Effect from "effect/Effect";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { type Project } from "./Project.ts";
+import type { Providers } from "./Providers.ts";
+/**
+ * A resource-valued prop: the resource itself, or an Effect that produces
+ * it (so `yield* Project(...)` and `Project(...)` both type-check).
+ */
+type Ref<T> = T | Effect.Effect<T, never, Providers>;
+/**
+ * Environment identity a Volume is deployed into. Accepts a
+ * `Railway.Project` (its primary environment), a `Railway.Environment`,
+ * or an `{ environmentId }` stub.
+ */
+export type VolumeEnvironment = {
+    readonly environmentId: string;
+};
+/**
+ * Service identity a Volume can attach to at create time. Accepts a
+ * `Railway.Service` or a `{ serviceId }` stub. Subsequent attach is
+ * `MountVolume` — omit `service` to leave the volume disconnected.
+ */
+export type VolumeService = {
+    readonly serviceId: string;
+};
+export interface VolumeProps {
+    /**
+     * Parent Railway Project. Changing it replaces the Volume.
+     */
+    project: Ref<Project>;
+    /**
+     * Environment to deploy the volume instance into. Accepts a
+     * `Railway.Project` (primary environment), a `Railway.Environment`, or
+     * `{ environmentId }`. Defaults to the project's primary environment.
+     * Changing it replaces the Volume.
+     */
+    environment?: Ref<VolumeEnvironment>;
+    /**
+     * Path in the container to mount the volume. Updates in place via
+     * `volumeInstanceUpdate`.
+     */
+    mountPath: string;
+    /**
+     * Region for the volume instance (`us-west2`, `us-east4`, …). If
+     * omitted, Railway picks the default. Changing it replaces the Volume.
+     */
+    region?: string;
+    /**
+     * Service to attach the volume to. If omitted, the volume is
+     * disconnected — attach later with MountVolume. Accepts a
+     * `Railway.Service` or `{ serviceId }`. Updating it attaches or moves
+     * the volume in place.
+     */
+    service?: Ref<VolumeService>;
+    /**
+     * Requested provisioned size in megabytes (Railway IaC parity).
+     *
+     * The public GraphQL `VolumeCreateInput` has no `size`/`sizeMB` field,
+     * and `VolumeInstanceUpdateInput` cannot grow a volume — growing is
+     * Pro-dashboard-only. Alchemy records this prop and reports the cloud
+     * plan default on the observed `sizeMB` attribute. Changing it does
+     * not call an API.
+     */
+    sizeMB?: number;
+}
+export type Volume = Resource<"Railway.Volume", VolumeProps, {
+    /** Railway volume id. */
+    volumeId: string;
+    /** Volume instance id in the target environment. */
+    volumeInstanceId: string;
+    /** Physical volume name (unique per project). */
+    name: string;
+    /** Parent Railway project id. */
+    projectId: string;
+    /** Environment the instance is deployed in. */
+    environmentId: string;
+    /** Mount path in the container. */
+    mountPath: string;
+    /** Region the instance lives in, if Railway reported one. */
+    region: string | undefined;
+    /** Attached service id, if any. */
+    serviceId: string | undefined;
+    /** Observed instance state (`READY`, `UPDATING`, …). */
+    state: VolumeState | undefined;
+    /**
+     * Observed provisioned size in MB. Railway picks this from the
+     * workspace plan; the public create/update APIs cannot set it.
+     */
+    sizeMB: number;
+    /** RFC3339 creation timestamp. */
+    createdAt: string;
+}, never, Providers>;
+declare const VolumeResource: import("../Resource.ts").ResourceClass<Volume>;
+/**
+ * A Railway.Volume is block disk in a Project. Create it disconnected
+ * (no `service`) and attach later with `MountVolume`, or pass `service`
+ * to attach at create time.
+ *
+ * Railway has no labels. Ownership is stamped into the volume name via
+ * `createPhysicalName`. `mountPath` updates in place. Changing `project`,
+ * `environment`, or `region` replaces the Volume.
+ *
+ * @see https://docs.railway.com/guides/volumes
+ * @see https://docs.railway.com/integrations/api/manage-volumes
+ *
+ * ### Create a Volume
+ * Pass a Project and a mount path. Alchemy generates a unique name.
+ * The volume is disconnected until you attach a Service.
+ *
+ * **Example:** Disconnected volume
+ * ```typescript
+ * const site = yield* Railway.Project("Site");
+ * const data = yield* Railway.Volume("Data", {
+ *   project: site,
+ *   mountPath: "/data",
+ * });
+ * ```
+ *
+ * :::caution[Changing `project` replaces the Volume]
+ * The Volume is created in the new Project. The old Volume is deleted.
+ * :::
+ *
+ * ### Mount path
+ * `mountPath` is the path in the container. Updating it is in place.
+ *
+ * **Example:** Update the mount path
+ * ```typescript
+ * const data = yield* Railway.Volume("Data", {
+ *   project: site,
+ *   mountPath: "/app/data",
+ * });
+ * ```
+ *
+ * ### Environment
+ * Defaults to the Project's primary environment. Pass a
+ * `Railway.Environment` (or `{ environmentId }`) to target another one.
+ *
+ * **Example:** Extra environment
+ * ```typescript
+ * const staging = yield* Railway.Environment("Staging", { project: site });
+ * const data = yield* Railway.Volume("StagingData", {
+ *   project: site,
+ *   environment: staging,
+ *   mountPath: "/data",
+ * });
+ * ```
+ *
+ * :::caution[Changing `environment` replaces the Volume]
+ * The Volume is created in the new environment. The old Volume is deleted.
+ * :::
+ *
+ * ### Region
+ * Omit `region` to use Railway's default. Changing it replaces the Volume.
+ *
+ * **Example:** Pin a region
+ * ```typescript
+ * const data = yield* Railway.Volume("Data", {
+ *   project: site,
+ *   mountPath: "/data",
+ *   region: "us-west2",
+ * });
+ * ```
+ *
+ * :::caution[Changing `region` replaces the Volume]
+ * Volumes cannot move region. A new Volume is created, then the old one
+ * is deleted.
+ * :::
+ *
+ * ### Size
+ * `sizeMB` on attributes is the observed plan default. Railway's public
+ * `VolumeCreateInput` has no size field; growing is Pro-dashboard-only.
+ * Passing `sizeMB` on props is IaC-parity documentation — it is not
+ * applied.
+ *
+ * **Example:** Observed size
+ * ```typescript
+ * const data = yield* Railway.Volume("Data", {
+ *   project: site,
+ *   mountPath: "/data",
+ * });
+ * // data.sizeMB is the plan default (e.g. 5120 on Hobby)
+ * ```
+ *
+ * ### Attach to a Service
+ * Pass `service` to attach at create time. Omit it and attach later with
+ * `MountVolume`. One volume per service.
+ *
+ * **Example:** Create-time attach
+ * ```typescript
+ * const api = yield* Railway.Service("Api", {
+ *   project: site,
+ *   image: "hashicorp/http-echo",
+ * });
+ * const data = yield* Railway.Volume("Data", {
+ *   project: site,
+ *   mountPath: "/data",
+ *   service: api,
+ * });
+ * ```
+ *
+ * :::caution[One volume per service]
+ * A second volume on the same Service fails with
+ * `Railway.MultipleVolumes`. Railway does not give each replica its
+ * own disk.
+ * :::
+ *
+ * ### Backups
+ * Snapshot a mounted volume with {@link VolumeBackup}. Railway only
+ * backups attached volumes. Restore is destructive — see
+ * `restoreVolumeBackup`.
+ *
+ * **Example:** Manual snapshot
+ * ```typescript
+ * const snap = yield* Railway.VolumeBackup("Nightly", { volume: data });
+ * ```
+ *
+ * ### Module-scope declarations
+ * Declare the Project once. Pass it into every child. Resource-valued
+ * props accept the resource or an Effect producing it.
+ *
+ * **Example:** Module-scope Volume
+ * ```typescript
+ * // src/data.ts
+ * import * as Railway from "alchemy/Railway";
+ *
+ * export const Site = Railway.Project("Site");
+ * export const Data = Railway.Volume("Data", {
+ *   project: Site,
+ *   mountPath: "/data",
+ * });
+ * ```
+ *
+ * @resource
+ */
+export declare const Volume: typeof VolumeResource;
+declare const VolumeNotCreated_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: "Railway.VolumeNotCreated";
+} & Readonly<A>;
+export declare class VolumeNotCreated extends VolumeNotCreated_base<{
+    name: string;
+    projectId: string;
+}> {
+}
+declare const VolumeProjectRequired_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: "Railway.VolumeProjectRequired";
+} & Readonly<A>;
+export declare class VolumeProjectRequired extends VolumeProjectRequired_base<{
+    message: string;
+}> {
+}
+declare const VolumeEnvironmentRequired_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: "Railway.VolumeEnvironmentRequired";
+} & Readonly<A>;
+export declare class VolumeEnvironmentRequired extends VolumeEnvironmentRequired_base<{
+    message: string;
+}> {
+}
+/** Volumes currently attached to a service instance. Used by Service reconcile. */
+export declare const listServiceVolumes: (environmentId: string, projectId: string, serviceId: string) => Effect.Effect<EnvironmentResponseVolumeInstancesEdgesItemNode[], railway.BadRequest | railway.Conflict | railway.Forbidden | import("effect/unstable/http/HttpClientError").HttpClientError | railway.Locked | railway.RailwayForbidden | railway.RailwayInternalError | railway.RailwayParseError | railway.RailwayPlanLimitExceeded | railway.RailwayRateLimited | railway.RailwayServiceDomainCreateFailed | railway.RailwayUnauthenticated | railway.RailwayValidationError | railway.UnknownRailwayError | railway.UnprocessableEntity | import("@distilled.cloud/axiom").DefaultErrors, railway.RailwayOpContext>;
+export declare const VolumeProvider: () => import("effect/Layer").Layer<Provider.Provider<Volume>, never, import("./Environment.ts").RailwayEnvironment | import("../Stack.ts").Stack | import("../Stage.ts").Stage | railway.RailwayOpContext>;
+export {};
+//# sourceMappingURL=Volume.d.ts.map

package/lib/Railway/Volume.d.ts.map

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