Skip to Content
Reference@streamsy/serve

Alchemy

Reference for the host exports in @streamsy/serve/alchemy. They adapt routing, object clients, and object handlers to Alchemy Effects.

import * as Alchemy from "@streamsy/serve/alchemy";
import type * as Cloudflare from "@streamsy/serve/cloudflare";
import type * as Workers from "@cloudflare/workers-types";
import type { DurableObject } from "@alchemy.run/cloudflare";
import type { Context, Effect, Layer, Option, Scope } from "effect";
import type {
  HttpRouter,
  HttpServerError,
  HttpServerRequest,
  HttpServerRespondable,
  HttpServerResponse,
} from "effect/http";
import type { Storage, StorageFault, Streamsy } from "@streamsy/core";

@streamsy/serve/alchemy provides the Effect handlers of a Streamsy host on Alchemy: a router for the Worker, and the fetch and alarm handlers of each Durable Object. See Alchemy.

Alchemy handlers

Alchemy.router

declare function router(options: {
  readonly objects: Pick<DurableObject, "getByName">;
  readonly prefix?: `/${string}`;
  readonly placement?: Alchemy.Placement;
}): Effect.Effect<
  HttpServerResponse.HttpServerResponse,
  HttpServerError.HttpServerError,
  HttpServerRequest.HttpServerRequest
>;

Alchemy.router returns an Effect that forwards the current HTTP request to the object that placement names, and succeeds with the response of the object. Authenticate the caller before you run this Effect.

objects is an Alchemy namespace binding. prefix defaults to /, and placement defaults to Placement.byStream(). The rules for the prefix, reserved paths, and placement failures are those of Cloudflare.router. The object gets the request unchanged. When the stub fails with HttpServerError, the Effect fails with the same error.

Alchemy.objectFetch

declare function objectFetch(objects: Pick<DurableObject, "getByName">): Alchemy.ObjectFetch;

Alchemy.objectFetch turns an Alchemy namespace binding into the ObjectFetch transport that ObjectStreams.layer and ObjectLink.client take. When the transport runs, it calls getByName, converts the web request into an Effect HTTP request, and converts the response back to a web Response.

When the stub fails, the transport fails with an HttpClientError whose reason is a TransportError with the original cause.

Alchemy.objectHandlers

declare function objectHandlers<R = never, L = never>(options: {
  readonly app: ObjectApp<R | L>;
  readonly layer: Layer.Layer<Storage | AlarmSlot | R, StorageFault, L>;
  readonly wakeups?: ReadonlyArray<Alchemy.WakeupSource<Storage | R | L>>;
  readonly links?: ReadonlyArray<Alchemy.LinkClient<L>>;
}): Effect.Effect<Alchemy.ObjectHandlers, never, Scope.Scope>;

// ObjectApp has no exported name. It is the route Layer that the object hosts accept.
type ObjectApp<R = never> = Layer.Layer<
  never,
  never,
  | HttpRouter.HttpRouter
  | HttpRouter.Request.From<"Requires", Storage | Cloudflare.Wakeups | R>
  | HttpRouter.Request.From<"Error", HttpServerRespondable.Respondable>
>;

// AlarmSlot has no exported name. alarmSlotLayer provides this service.
interface AlarmSlot extends Context.ServiceClass.Shape<
  "@streamsy/serve/cloudflare/AlarmSlot",
  {
    readonly current: Effect.Effect<Option.Option<number>, never, never>;
    readonly arm: (at: number) => Effect.Effect<void, never, never>;
    readonly clear: Effect.Effect<void, never, never>;
  }
> {}

Alchemy.objectHandlers returns the fetch and alarm handlers of an Alchemy Durable Object. Both handlers share one acquisition of storage and services, which runs on first use. The scope of the instance owns the acquisition, and releases it when the scope closes.

OptionMeaning
appThe route Layer. It can use the local and the linked services
layerThe Layer of local services and storage. It must include alarmSlotLayer(state.raw.storage)
wakeupsMore wakeups. They run after stream expiry
linksThe clients of streams on other objects, as an array

The rules for acquisition, reconciliation, and link clashes are those of StreamsyObject. When the acquisition fails, the host closes its scope, fetch answers 503 with Retry-After: 1, and the next call acquires again. When the acquisition fails during an alarm, alarm dies, so the platform retries the alarm.

Alchemy.ObjectHandlers

type ObjectHandlers = {
  readonly fetch: Effect.Effect<
    HttpServerResponse.HttpServerResponse,
    never,
    HttpServerRequest.HttpServerRequest
  >;
  readonly alarm: () => Effect.Effect<void, never, never>;
};

Alchemy.ObjectHandlers holds the handlers that objectHandlers returns. fetch answers the current HTTP request. alarm() runs a turn of the wakeup scheduler. The platform calls alarm on its own, never from a fetch.

Shared Cloudflare exports

These exports are the same values and types as the exports of @streamsy/serve/cloudflare. Each section checks the shared signature, and links to the Cloudflare section for the rules.

Alchemy.Placement

type Placement = Cloudflare.Placement;
declare const Placement: typeof Cloudflare.Placement;

Alchemy.Placement re-exports Cloudflare.Placement unchanged.

Alchemy.rule

declare const rule: typeof Cloudflare.rule;

Alchemy.rule re-exports Cloudflare.rule unchanged.

Alchemy.Wakeup

type Wakeup<R = never> = Cloudflare.Wakeup<R>;
declare const Wakeup: typeof Cloudflare.Wakeup;

Alchemy.Wakeup re-exports Cloudflare.Wakeup unchanged.

Alchemy.Wakeups

type Wakeups = Cloudflare.Wakeups;
declare const Wakeups: typeof Cloudflare.Wakeups;

Alchemy.Wakeups re-exports Cloudflare.Wakeups unchanged.

Alchemy.WakeupProgress

type WakeupProgress = Cloudflare.WakeupProgress;

Alchemy.WakeupProgress re-exports Cloudflare.WakeupProgress unchanged.

Alchemy.WakeupSource

type WakeupSource<R = never> = Cloudflare.WakeupSource<R>;

Alchemy.WakeupSource re-exports Cloudflare.WakeupSource unchanged.

Alchemy.alarmSlotLayer

declare const alarmSlotLayer: typeof Cloudflare.alarmSlotLayer;

Alchemy.alarmSlotLayer re-exports Cloudflare.alarmSlotLayer unchanged.

Alchemy.ObjectStreams

declare const ObjectStreams: typeof Cloudflare.ObjectStreams;

Alchemy.ObjectStreams re-exports Cloudflare.ObjectStreams unchanged.

Alchemy.ObjectFetch

type ObjectFetch = Cloudflare.ObjectFetch;

Alchemy.ObjectFetch re-exports Cloudflare.ObjectFetch unchanged.

Alchemy.ObjectStreamsOptions

type ObjectStreamsOptions = Cloudflare.ObjectStreamsOptions;

Alchemy.ObjectStreamsOptions re-exports Cloudflare.ObjectStreamsOptions unchanged.

type ObjectLink<Keys extends ReadonlyArray<Streamsy.Any>> = Cloudflare.ObjectLink<Keys>;
declare const ObjectLink: typeof Cloudflare.ObjectLink;

Alchemy.ObjectLink re-exports Cloudflare.ObjectLink unchanged.

Alchemy.LinkAccess

type LinkAccess = Cloudflare.LinkAccess;

Alchemy.LinkAccess re-exports Cloudflare.LinkAccess unchanged.

Alchemy.LinkClient

type LinkClient<I> = Cloudflare.LinkClient<I>;

Alchemy.LinkClient re-exports Cloudflare.LinkClient unchanged.

Alchemy.LinkRoutes

type LinkRoutes<I> = Cloudflare.LinkRoutes<I>;

Alchemy.LinkRoutes re-exports Cloudflare.LinkRoutes unchanged.

Alchemy.ObjectLinkOptions

type ObjectLinkOptions<Keys extends ReadonlyArray<Streamsy.Any>> =
  Cloudflare.ObjectLinkOptions<Keys>;

Alchemy.ObjectLinkOptions re-exports Cloudflare.ObjectLinkOptions unchanged.

On this page