From 9d1ace145f3c9df3a99e1c0797587a0a34b096ed Mon Sep 17 00:00:00 2001 From: Nathan Flurry Date: Fri, 8 Aug 2025 16:08:45 -0700 Subject: [PATCH] feat: add driver context access in createVars function --- site/public/llms-full.txt | 96 +++++++++++++++++++ .../docs/actors/ephemeral-variables.mdx | 32 +++++++ site/src/content/docs/drivers/redis.mdx | 39 ++++++++ .../hosting-providers/cloudflare-workers.mdx | 68 +++++++++++++ 4 files changed, 235 insertions(+) diff --git a/site/public/llms-full.txt b/site/public/llms-full.txt index 3d0f00d1a2..b06062e380 100644 --- a/site/public/llms-full.txt +++ b/site/public/llms-full.txt @@ -1143,6 +1143,34 @@ const counter = actor(, }); ``` +## Accessing Driver Context + +The `createVars` function receives a second parameter that provides access to driver-specific context. This allows you to interact with the underlying infrastructure directly within your actor's ephemeral variables. + +```typescript +const myActor = actor(, + + // The second parameter provides driver-specific context + createVars: (ctx, driver) => ; + }, + + actions: + if (driver?.ctx) + + return "Driver accessed"; + } + } +}); +``` + +The structure of the driver context depends on which driver you're using: + +- **Cloudflare Workers**: `` +- **Redis**: `` +- **Local**: No driver context provided + +This driver context enables advanced use cases where you need direct access to platform-specific features alongside Rivet's actor abstraction. + ## Using Variables Vars can be accessed and modified through the context object with `c.vars`: @@ -4007,6 +4035,46 @@ Deploy your Redis-powered actors on these hosting providers: Deploy on Railway with automatic scaling and managed infrastructure. +## Accessing Driver Context with createVars + +The Redis driver provides access to the underlying Redis connection through the driver context in `createVars`. This allows you to perform Redis operations directly within your actors. + +```typescript +const myActor = actor(, + + // Access Redis connection through driver context + createVars: (ctx, driver: DriverContext) => ; + }, + + actions: `, value, 'EX', 3600); + + // Also store locally for fast access + c.vars.cacheData.set(key, value); + + return "Cached successfully"; + }, + + // Example: Get cached value + getCachedValue: async (c, key: string) => + + // Fallback to Redis + const value = await c.vars.redis.get(`cache:$`); + if (value) + + return value; + } + } +}); +``` + +The Redis driver context type is exported as `DriverContext` from `@rivetkit/redis` and contains: + +```typescript +interface DriverContext +``` + +This gives you full access to all Redis operations while still benefiting from Rivet's actor model for state management and horizontal scaling. + ## Examples Example using Redis driver with Hono web framework. @@ -4785,6 +4853,34 @@ wrangler deploy Your actors will now run on Cloudflare's global edge network with persistent state backed by Durable Objects. +## Accessing Driver Context with createVars + +The Cloudflare Workers driver provides access to the Durable Object state and environment through the driver context in `createVars`. This enables direct interaction with Cloudflare's platform features. + +```typescript +const myActor = actor(, + + // Access Durable Object state through driver context + createVars: (ctx, driver: DriverContext) => ; + }, + + actions: ; + }, + + // Example: Access environment bindings + accessEnvBindings: async (c) => + } +}); +``` + +The Cloudflare Workers driver context type is exported as `DriverContext` from `@rivetkit/cloudflare-workers` and contains: + +```typescript +interface DriverContext +``` + +While you have access to the Durable Object state, be cautious when directly modifying KV storage or alarms, as this may interfere with RivetKit's internal operations and potentially break actor functionality. Use these features for read-only operations or additional custom logic that doesn't conflict with RivetKit's state management. + ## Examples Example using Cloudflare Workers with Hono web framework. diff --git a/site/src/content/docs/actors/ephemeral-variables.mdx b/site/src/content/docs/actors/ephemeral-variables.mdx index 497a6e2fd2..ca249d58d2 100644 --- a/site/src/content/docs/actors/ephemeral-variables.mdx +++ b/site/src/content/docs/actors/ephemeral-variables.mdx @@ -118,3 +118,35 @@ Use `state` when: - The data must be preserved across actor sleeps, restarts, updates, or crashes - The information is essential to the actor's core functionality and business logic + +## Advanced + +### Accessing Driver Context + +The `createVars` function receives a second parameter that provides access to driver-specific context. This allows you to access driver-specific functionality. + +For example, the Redis driver exposes access to the Redis instance: + +```typescript +import { actor, ActorInitContext } from "@rivetkit/actor"; +import { DriverContext } from "@rivetkit/redis"; + +const myActor = actor({ + state: { count: 0 }, + + // The second parameter provides driver-specific context + createVars: (ctx: ActorInitContext, driver: DriverContext) => ({ driver }), + + actions: { + accessDriverFeatures: (c) => { + // Access Redis + const redis = c.vars.driver.redis; + const keyPrefix = c.vars.driver.keyPrefix; + // ...etc... + } + } +}); +``` + +Consult the documentation for each driver to learn more about their respective `DriverContext` types. + diff --git a/site/src/content/docs/drivers/redis.mdx b/site/src/content/docs/drivers/redis.mdx index f897c5e270..5523e9b65f 100644 --- a/site/src/content/docs/drivers/redis.mdx +++ b/site/src/content/docs/drivers/redis.mdx @@ -129,3 +129,42 @@ Example using Redis driver with Hono web framework. Basic Redis driver setup and configuration example. + +## Advanced + +### Driver Context + +The Redis driver provides access to the underlying Redis connection through the driver context in `createVars`. + +```typescript +import { actor, ActorInitContext } from "@rivetkit/actor"; +import type { DriverContext } from "@rivetkit/redis"; + +const myActor = actor({ + state: { count: 0 }, + + // Save the Redis driver context + createVars: (ctx: ActorInitContext, driver: DriverContext) => ({ redis: driver.redis }), + + actions: { + // Example: Access Redis directly (not recommended in practice) + getRedisValue: async (c, key: string) => { + // Use the Redis client from driver context + return await c.vars.redis.get(key); + }, + } +}); +``` + +The Redis driver context type is exported as `DriverContext` from `@rivetkit/redis`: + +```typescript +interface DriverContext { + redis: ioredis.Redis; + keyPrefix: string; // Key prefix that all RivetKit data is stored under +} +``` + + +While you have access to the Redis client, be cautious when directly modifying keys under the `keyPrefix`, as this may interfere with RivetKit's internal operations and potentially break actor functionality. + diff --git a/site/src/content/docs/hosting-providers/cloudflare-workers.mdx b/site/src/content/docs/hosting-providers/cloudflare-workers.mdx index 61e0734f6b..8f1c7834b1 100644 --- a/site/src/content/docs/hosting-providers/cloudflare-workers.mdx +++ b/site/src/content/docs/hosting-providers/cloudflare-workers.mdx @@ -141,3 +141,71 @@ Example using Cloudflare Workers with Hono web framework. Basic Cloudflare Workers setup and configuration example. + +## Advanced + +### Accessing Environment Bindings + +You can access Cloudflare Workers environment bindings directly using the importable `env`: + +```typescript +import { env } from "cloudflare:workers"; + +// Access environment variables and secrets in top-level scope +const API_KEY = env.API_KEY; +const LOG_LEVEL = env.LOG_LEVEL || "info"; + +// Use bindings in your actor +const myActor = actor({ + state: { count: 0 }, + + actions: { + // Access KV, D1, or other bindings during request handling + getFromKV: async (c, key: string) => { + // Access additional KV namespaces defined in wrangler.json + if (env.MY_CACHE_KV) { + return await env.MY_CACHE_KV.get(key); + } + } + } +}); +``` + +### Driver Context + +The Cloudflare Workers driver provides access to the Durable Object state and environment through the driver context in `createVars`. + +```typescript +import { actor, ActorInitContext } from "@rivetkit/actor"; +import type { DriverContext } from "@rivetkit/cloudflare-workers"; + +const myActor = actor({ + state: { count: 0 }, + + // Save the Cloudflare driver context + createVars: (ctx: ActorInitContext, driver: DriverContext) => ({ + state: driver.state, + }), + + actions: { + // Example: Access Durable Object info (not recommended in practice) + kvGet: (c, key: string) => { + const doState = c.vars.state; + return await doState.storage.get(key) + }, + } +}); +``` + +The Cloudflare Workers driver context type is exported as `DriverContext` from `@rivetkit/cloudflare-workers`: + +```typescript +interface DriverContext { + state: DurableObjectState; +} +``` + + +While you have access to the Durable Object state, be cautious when directly modifying KV storage or alarms, as this may interfere with RivetKit's internal operations and potentially break actor functionality. + +