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.
| Option | Meaning |
|---|---|
app | The route Layer. It can use the local and the linked services |
layer | The Layer of local services and storage. It must include alarmSlotLayer(state.raw.storage) |
wakeups | More wakeups. They run after stream expiry |
links | The 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.
Alchemy.ObjectLink
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.