Railway.Bucket reference

Bucket

Source: src/Railway/Bucket.ts

A Railway.Bucket is S3-compatible object storage in a Project. Each environment gets its own isolated instance and credentials. Bind PutObject / GetObject (and the other S3 object ops) in Service init — Alchemy injects the endpoint and credentials.

Railway has no labels. Ownership is stamped into the display name via createPhysicalName. name updates in place. Changing project, environment, or region replaces the Bucket.

Bucket: Create a Bucket

Pass a Project. Alchemy generates a unique name and deploys to the project’s primary environment in sjc.

const site = yield* Railway.Project("Site");
const data = yield* Railway.Bucket("Data", { project: site });

Changing project replaces the Bucket

The Bucket is created in the new Project. The old Bucket is deleted.

Bucket: A stable name

Pass name when you need a stable display name. The S3 API name is this plus a short hash (s3BucketName).

const data = yield* Railway.Bucket("Data", {
  project: site,
  name: "uploads",
});

Bucket: Region

Omit region to use sjc. Changing it replaces the Bucket.

const data = yield* Railway.Bucket("Data", {
  project: site,
  region: "iad",
});

Changing region replaces the Bucket

Railway cannot move a bucket. A new Bucket is created, then the old one is deleted.

Bucket: Environment

Defaults to the Project’s primary environment. Pass a Railway.Environment (or { environmentId }) to target another one.

const staging = yield* Railway.Environment("Staging", { project: site });
const data = yield* Railway.Bucket("StagingData", {
  project: site,
  environment: staging,
});

Changing environment replaces the Bucket

The Bucket instance is created in the new environment. The old instance is deleted.

Bucket: Put and get objects

Railway buckets speak the S3 API. Bind PutObject / GetObject in Service init.

import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";

export default class Api extends Railway.Service<Api>()(
  "Api",
  { project: Site, main: import.meta.url },
  Effect.gen(function* () {
    const putObject = yield* Railway.PutObject(Data);
    const getObject = yield* Railway.GetObject(Data);

    return {
      fetch: Effect.gen(function* () {
        yield* putObject({
          Key: "hello.txt",
          Body: "hello",
          ContentType: "text/plain",
        });
        const obj = yield* getObject({ Key: "hello.txt" });
        return HttpServerResponse.json({ ok: obj.ETag !== undefined });
      }),
    };
  }).pipe(Effect.provide([Railway.PutObjectHttp, Railway.GetObjectHttp])),
) {}

Bucket: Module-scope declarations

Declare the Project once. Pass it into every child. Resource-valued props accept the resource or an Effect producing it.

src/data.ts

import * as Railway from "alchemy/Railway";

export const Site = Railway.Project("Site");
export const Data = Railway.Bucket("Data", { project: Site });

DeleteObject

Source: src/Railway/DeleteObject.ts

Runtime binding for Railway DeleteObject over the S3 API.

Bind this operation to a Bucket in Service init. Provide DeleteObjectHttp.

DeleteObject: Deleting Objects

const deleteObject = yield* Railway.DeleteObject(Data);
yield* deleteObject({ Key: "hello.txt" });

DeleteObjectHttp

Source: src/Railway/DeleteObjectHttp.ts Kind: Layer · Provides: Railway.DeleteObject

HTTP implementation of DeleteObject. Calls distilled S3 deleteObject against the Railway endpoint with the bucket’s credentials.

GetObject

Source: src/Railway/GetObject.ts

Runtime binding for Railway GetObject over the S3 API.

Bind this operation to a Bucket in Service init. Provide GetObjectHttp.

GetObject: Reading Objects

const getObject = yield* Railway.GetObject(Data);

const text = yield* getObject({ Key: "hello.txt" }).pipe(
  Effect.flatMap((result) =>
    Stream.mkString(Stream.decodeText(result.Body!)),
  ),
);

GetObjectHttp

Source: src/Railway/GetObjectHttp.ts Kind: Layer · Provides: Railway.GetObject

HTTP implementation of GetObject. Calls distilled S3 getObject against the Railway endpoint with the bucket’s credentials.

HeadObject

Source: src/Railway/HeadObject.ts

Runtime binding for Railway HeadObject over the S3 API.

Bind this operation to a Bucket in Service init. Provide HeadObjectHttp.

HeadObject: Inspecting Objects

const headObject = yield* Railway.HeadObject(Data);
const head = yield* headObject({ Key: "hello.txt" });

HeadObjectHttp

Source: src/Railway/HeadObjectHttp.ts Kind: Layer · Provides: Railway.HeadObject

HTTP implementation of HeadObject. Calls distilled S3 headObject against the Railway endpoint with the bucket’s credentials.

ListObjectsV2

Source: src/Railway/ListObjectsV2.ts

Runtime binding for Railway ListObjectsV2 over the S3 API.

Bind this operation to a Bucket in Service init. Provide ListObjectsV2Http.

ListObjectsV2: Listing Objects

const listObjects = yield* Railway.ListObjectsV2(Data);
const result = yield* listObjects({ Prefix: "jobs/", MaxKeys: 100 });

ListObjectsV2Http

Source: src/Railway/ListObjectsV2Http.ts Kind: Layer · Provides: Railway.ListObjectsV2

HTTP implementation of ListObjectsV2. Calls distilled S3 listObjectsV2 against the Railway endpoint with the bucket’s credentials.

PutObject

Source: src/Railway/PutObject.ts

Runtime binding for Railway PutObject over the S3 API.

Bind this operation to a Bucket in Service init. The bucket name, endpoint, and credentials are injected automatically. Provide PutObjectHttp.

PutObject: Writing Objects

const putObject = yield* Railway.PutObject(Data);

yield* putObject({
  Key: "hello.txt",
  Body: "Hello, world!",
  ContentType: "text/plain",
});

PutObjectHttp

Source: src/Railway/PutObjectHttp.ts Kind: Layer · Provides: Railway.PutObject

HTTP implementation of PutObject. Calls distilled S3 putObject against the Railway endpoint with the bucket’s credentials.