Feature Request: Access to Platform-Specific Context Objects in Workflow Handlers

[jamemackson]

Feature Request: Access to Platform-Specific Context Objects in Workflow Handlers

Summary

Request for access to platform-specific context objects (like SvelteKit's locals and fetch) within workflow handlers, through a platform-agnostic solution in the underlying serveBase module.

Background

Currently, when using @upstash/workflow with SvelteKit, platform-specific objects like locals and fetch are available in the request handler but are not accessible within the workflow context. This limits the ability to:

• Multitenant platform contextual data and other information stored in locals. (a db connection for instance)
• Use SvelteKit's enhanced fetch function that bypasses the need to call externally for sub-requests.
• Leverage other platform-specific utilities that are very helpful for workflow implementation logic

Current Limitation

Workflow handlers currently have no access to platform-specific context objects, making it more difficult / inefficient to perform workflow operations in the context of a tenant on a platform.

Proposed Solution

Platform-Agnostic Context Extension

Add support for platform-specific context objects through a generic platformContext property in the workflow context. This would be passed through serveBase options and made available in the workflow handler.

Suggested SvelteKit Integration

export const serve = <TInitialPayload = unknown, TResult = unknown>(
	routeFunction: RouteFunction<TInitialPayload, TResult>,
	options: RequireEnv<PublicServeOptions<TInitialPayload>>,
): {
	POST: RequestHandler;
} => {
	const handler: RequestHandler = async ({ request, locals, fetch }) => {
		const { handler: serveHandler } = serveBase<TInitialPayload>(routeFunction, telemetry, {
			...options,
			platformContext: { locals, fetch }, // ← Proposed feature
			useJSONContent: true,
		});
		return await serveHandler(request);
	};
	return { POST: handler };
};

Workflow Handler Usage

// In workflow handler
export async function myWorkflow(context: WorkflowContext<MyPayload>) {
  // Access platform-specific objects
  const { locals, fetch } = context.platformContext;
  
  // Use SvelteKit's enhanced fetch
  const response = await fetch('/api/some-endpoint');
  
  // Access platform tenant context from locals
  const siteId = locals.site?.id;
  const activeDomain = locals.domain;
  
  // ... rest of workflow logic
}

Suggested Implementation in serveBase

interface ServeOptions {
  // ... existing options
  platformContext?: Record<string, any>;
}

// In serveBase implementation
const context: WorkflowContext = {
  // ... existing context properties
  platformContext: options.platformContext || {},
};

Platform-Specific Implementations

Each platform wrapper would populate platformContext with relevant objects:

SvelteKit:

serveBase(routeFunction, telemetry, {
  ...options,
  platformContext: { locals, fetch },
});

Next.js:

serveBase(routeFunction, telemetry, {
  ...options,
  platformContext: { req, res, cookies },
});

Express:

serveBase(routeFunction, telemetry, {
  ...options,
  platformContext: { req, res, session },
});

Benefits

1. Platform Agnostic: The solution works across all supported frameworks
2. Backward Compatible: Existing workflows continue to work unchanged
3. Flexible: Each platform can expose relevant context objects
4. Type Safe: Can be properly typed for each platform implementation
5. Consistent: Provides a unified way to access platform-specific features

Use Cases

• Authentication: Access user session data stored in locals
• Server-Side Requests: Use framework-enhanced fetch functions
• Database Connections: Access connection pools stored in platform context
• Configuration: Access environment-specific settings
• Middleware Data: Use data populated by framework middleware

This enhancement would significantly improve the developer experience when building complex workflows that need to interact with platform-specific features and data.

I would be happy to work up a PR if this would be considered by the project maintainers.

[CahidArda]

Hi @jamemackson,

Thanks for the suggestion. I think this is a very good idea. We experimented with something similar in Astro, where platform specific parameters are passed after context in the route function. But passing the fields is not a very good idea. Putting them under context is more convenient.

I liked the the API you proposed. A PR would be much appreciated. Some things you can keep in mind:

• This option should probably be only available in serveBase. serve implementation of platforms probably shouldn't allow this. You can exclude this from platform specific serve methods by updating the PublicServeOptions type.
• We will probably need to add another generic to the context.
• Make sure that you pass the platforms specific parameters (and the new generic) everywhere WorkflowContext is initialized.

[jamemackson]

thanks @CahidArda, i appreciate your feedback and suggestions. i’ll work on a PR in the next week.