cfw-graphql-bootstrap 1.0.0

package/README.md

@@ -0,0 +1,278 @@
+# cfw-graphql-bootstrap
+
+Enterprise-grade GraphQL server framework for Cloudflare Workers with built-in security, caching, and observability.
+
+## Features
+
+- 🚀 **Optimized for Cloudflare Workers** - Built specifically for edge runtime with minimal bundle size
+- 🔒 **Enterprise Security** - HMAC signature verification, CORS, rate limiting, and security headers
+- 💾 **Multi-tier Caching** - Support for Cloudflare KV and Redis with cache-aside pattern
+- 📊 **Observability** - Distributed tracing, structured logging with Pino, and health checks
+- 🛡️ **Type Safety** - Full TypeScript support with proper type exports
+- ⚡ **High Performance** - Lightweight environment parsing, efficient middleware chain
+- 🔧 **Developer Experience** - Easy setup, extensible context, and modular architecture
+
+## Installation
+
+```bash
+npm install cfw-graphql-bootstrap
+# or
+bun add cfw-graphql-bootstrap
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```json
+{
+  "@apollo/server": "^5.0.0",
+  "@cloudflare/workers-types": "^4.0.0",
+  "hono": "^4.0.0",
+  "typescript": "^5.0.0"
+}
+```
+
+## Quick Start
+
+```typescript
+import {
+  createGraphQLServer,
+  createSchemaModule,
+  gql,
+} from 'cfw-graphql-bootstrap';
+
+// Define your schema
+const schema = createSchemaModule({
+  typeDefs: gql`
+    type Query {
+      hello(name: String!): String
+    }
+  `,
+  resolvers: {
+    Query: {
+      hello: (_, {name}) => `Hello ${name}!`,
+    },
+  },
+});
+
+// Create the server
+const server = createGraphQLServer({
+  name: 'my-graphql-api',
+  version: '1.0.0',
+  config: {
+    apollo: {
+      schema: schema.schema,
+    },
+    datasources: (cache, context) => ({}),
+  },
+});
+
+// Export for Cloudflare Workers
+export default server.configure();
+```
+
+## Advanced Usage
+
+### Custom Context
+
+Extend the base context with your own properties:
+
+```typescript
+import {createGraphQLServer, type BaseContext} from 'cfw-graphql-bootstrap';
+
+interface MyContext extends BaseContext {
+  dataSources: {
+    userAPI: UserAPI;
+  };
+}
+
+const server = createGraphQLServer<any, MyContext>({
+  name: 'my-api',
+  version: '1.0.0',
+  config: {
+    apollo: {schema},
+    datasources: (cache, context) => ({
+      userAPI: new UserAPI(context),
+    }),
+    extendContext: async (baseContext, honoContext) => ({
+      ...baseContext,
+      // Add custom context properties
+    }),
+  },
+});
+```
+
+### Caching
+
+Enable KV caching by binding a KV namespace:
+
+```toml
+# wrangler.toml
+[[kv_namespaces]]
+binding = "CACHE_KV"
+id = "your-kv-namespace-id"
+```
+
+Use the cache decorator in resolvers:
+
+```typescript
+import {cached} from 'cfw-graphql-bootstrap';
+
+class UserResolver {
+  @cached({ttl: 300}) // Cache for 5 minutes
+  async getUser(_, {id}, context) {
+    return fetchUserFromDB(id);
+  }
+}
+```
+
+### Environment Configuration
+
+The framework automatically validates and parses environment variables:
+
+```typescript
+// Available in context.env
+interface EnvConfig {
+  NODE_ENV: 'development' | 'test' | 'production';
+  PORT: number;
+  GATEWAY_SECRET?: string;
+  ALLOWED_ORIGINS: string[];
+  LOG_LEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  RATE_LIMIT_WINDOW_MS: number;
+  RATE_LIMIT_MAX: number;
+  // ... and more
+}
+```
+
+### Middleware
+
+Add custom middleware or configure built-in ones:
+
+```typescript
+import {
+  createRateLimitMiddleware,
+  createValidationMiddleware,
+  createTracingMiddleware,
+  configureHealthChecks,
+} from 'cfw-graphql-bootstrap';
+
+// All middleware is automatically configured
+// Customize if needed in your server setup
+```
+
+### Logging
+
+Structured logging with Pino, optimized for Cloudflare Workers:
+
+```typescript
+import {logger} from 'cfw-graphql-bootstrap';
+
+logger.info({userId: '123'}, 'User action');
+logger.error({err: error}, 'Operation failed');
+```
+
+### Security
+
+Built-in security features:
+
+- HMAC signature verification for gateway communication
+- Rate limiting with Cloudflare KV
+- CORS configuration
+- Security headers (CSP, HSTS, etc.)
+- Request validation
+
+## API Reference
+
+### Core Exports
+
+- `createGraphQLServer(options)` - Create a new GraphQL server
+- `ServerBuilder` - Low-level server builder class
+- `createContextFunction(extendFn?)` - Create context factory
+
+### Context & Types
+
+- `BaseContext` - Base context interface
+- `ContextUser` - User context type
+- `ContextExtendFunction` - Context extension function type
+
+### Environment
+
+- `envLoader` - Environment configuration loader
+- `EnvConfig` - Environment configuration type
+
+### Cache
+
+- `createCache(env)` - Create cache instance
+- `KVCache` - Cloudflare KV cache implementation
+- `RedisCache` - Redis cache implementation
+- `@cached(options)` - Cache decorator
+
+### Middleware
+
+- `createRateLimitMiddleware(options)`
+- `createValidationMiddleware(options)`
+- `createTracingMiddleware()`
+- `configureHealthChecks(app, options)`
+
+### Utilities
+
+- `createSchemaModule(config)` - Create GraphQL schema
+- `gql` - GraphQL template literal tag
+- `AppError` - Application error class
+- `logger` - Pino logger instance
+
+## Deployment
+
+### Wrangler Configuration
+
+```toml
+# wrangler.toml
+name = "my-graphql-api"
+main = "dist/index.js"
+compatibility_date = "2024-01-01"
+
+[env.production]
+vars = {
+  NODE_ENV = "production",
+  ALLOWED_ORIGINS = "https://myapp.com",
+  RATE_LIMIT_MAX = "100"
+}
+
+[[kv_namespaces]]
+binding = "CACHE_KV"
+id = "your-kv-namespace-id"
+
+[[kv_namespaces]]
+binding = "RATE_LIMIT_KV"
+id = "your-rate-limit-kv-id"
+```
+
+### Deploy
+
+```bash
+# Development
+wrangler dev
+
+# Production
+wrangler deploy --env production
+```
+
+## Performance
+
+- **Bundle Size**: ~30KB (ESM, before compression)
+- **Cold Start**: < 10ms typical
+- **Request Overhead**: < 2ms for middleware chain
+- **Memory Usage**: Optimized for Workers' 128MB limit
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, please use the [GitHub issue tracker](https://github.com/yourusername/cfw-graphql-bootstrap/issues).

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+import { BaseContext as BaseContext$1, ApolloServerOptions, ApolloServerPlugin } from '@apollo/server';
+import { KVNamespace, ExecutionContext } from '@cloudflare/workers-types';
+import { CloudflareContextFunctionArgument } from '@as-integrations/cloudflare-workers';
+import { GraphQLSchema, GraphQLError, DocumentNode } from 'graphql';
+import { Hono, MiddlewareHandler } from 'hono';
+import { ApolloServerErrorCode } from '@apollo/server/errors';
+export { gql } from 'graphql-tag';
+
+declare const logger: any;
+declare global {
+    var logshipper: {
+        log: (data: any) => void;
+    };
+    var requestContext: {
+        traceId?: string;
+        spanId?: string;
+        userId?: string;
+    };
+}
+
+interface ContextUser {
+    id: string;
+    email?: string;
+    roles?: string[];
+    permissions?: string[];
+}
+
+/**
+ * KV Cache implementation for Cloudflare Workers
+ * Provides caching capabilities for GraphQL resolvers using Cloudflare KV
+ */
+
+interface CacheOptions {
+    ttl?: number;
+    cacheKey?: string;
+}
+declare class KVCache {
+    private kv;
+    constructor(kv: KVNamespace);
+    /**
+     * Get a value from cache
+     */
+    get<T = any>(key: string): Promise<T | null>;
+    /**
+     * Set a value in cache
+     */
+    set(key: string, value: any, options?: CacheOptions): Promise<void>;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a key exists in cache
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clear multiple keys matching a prefix
+     */
+    clearPrefix(prefix: string): Promise<void>;
+    /**
+     * Get or set a value with a factory function
+     * Useful for cache-aside pattern
+     */
+    getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+}
+
+/**
+ * Redis Cache implementation for Cloudflare Workers
+ * Alternative to KV for more advanced caching needs
+ */
+
+declare class RedisCache {
+    private redis;
+    constructor(config?: {
+        url?: string;
+        token?: string;
+    });
+    private initUpstash;
+    private createMockRedis;
+    get<T = any>(key: string): Promise<T | null>;
+    set(key: string, value: any, options?: CacheOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    clearPrefix(prefix: string): Promise<void>;
+    getOrSet<T>(key: string, factory: () => Promise<T>, options?: CacheOptions): Promise<T>;
+    increment(key: string, by?: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number>;
+}
+
+/**
+ * Cache module for GraphQL resolvers
+ * Provides unified caching interface with multiple backends
+ */
+
+/**
+ * Cache factory - creates appropriate cache based on environment
+ */
+declare function createCache(env: any): KVCache | RedisCache | null;
+/**
+ * Decorator for caching resolver results
+ */
+declare function cached(options?: CacheOptions & {
+    keyGenerator?: (...args: any[]) => string;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * GraphQL DataLoader integration for batching and caching
+ */
+declare class CachedDataLoader<K, V> {
+    private options;
+    private loader;
+    private cache;
+    constructor(batchFn: (keys: K[]) => Promise<V[]>, cache: KVCache | RedisCache, options?: CacheOptions);
+    load(key: K): Promise<V>;
+    loadMany(keys: K[]): Promise<V[]>;
+    clear(key: K): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+/**
+ * Environment configuration type
+ */
+interface EnvConfig {
+    NODE_ENV: 'development' | 'test' | 'production';
+    PORT: number;
+    GATEWAY_SECRET?: string;
+    ALLOWED_ORIGINS: string[];
+    LOG_LEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    RATE_LIMIT_WINDOW_MS: number;
+    RATE_LIMIT_MAX: number;
+    ENABLE_METRICS: boolean;
+    ENABLE_TRACING: boolean;
+    MAX_QUERY_DEPTH: number;
+    MAX_QUERY_COMPLEXITY: number;
+    INTROSPECTION_ENABLED: boolean;
+    REDIS_URL?: string;
+    REDIS_TOKEN?: string;
+    LOG_SERVICE_URL?: string;
+    LOG_SERVICE_TOKEN?: string;
+}
+/**
+ * Environment loader for Cloudflare Workers
+ */
+declare class EnvironmentLoader {
+    private config;
+    /**
+     * Load environment from Cloudflare Workers env object
+     */
+    load(env: Record<string, any>): EnvConfig;
+    /**
+     * Get current configuration
+     */
+    getConfig(): EnvConfig;
+    /**
+     * Helper getters for common checks
+     */
+    get isDev(): boolean;
+    get isTest(): boolean;
+    get isProd(): boolean;
+}
+declare const envLoader: EnvironmentLoader;
+
+interface JaegerContext {
+    rootSpan?: {
+        getBaggageItem: (key: string) => string | undefined;
+    };
+}
+interface BaseContext extends JaegerContext, BaseContext$1 {
+    user?: ContextUser;
+    logger: typeof logger;
+    executionCtx: ExecutionContext;
+    cache?: KVCache;
+    env: EnvConfig;
+    /** @deprecated should not be used directly */
+    authorization: string;
+    clientId: string;
+}
+type ContextExtendFunction<T extends BaseContext> = (ctx: BaseContext, honoContext: CloudflareContextFunctionArgument<unknown>) => T | Promise<T>;
+declare function createContextFunction<T extends BaseContext>(extendContext?: ContextExtendFunction<T>): (honoContext: CloudflareContextFunctionArgument<unknown>) => Promise<BaseContext>;
+
+type Runner = {
+    fetch: typeof Hono.prototype.fetch;
+    port?: number;
+};
+type ServerConfig<TDatasource, TContext extends BaseContext> = {
+    path?: string;
+    apollo: Partial<ApolloServerOptions<BaseContext>>;
+    datasources: (cache: any, context: TContext) => TDatasource;
+    extendContext?: ContextExtendFunction<TContext>;
+};
+declare class ServerBuilder<TDatasource, TContext extends BaseContext> {
+    readonly config: ServerConfig<TDatasource, TContext>;
+    readonly app: Hono;
+    readonly schema: GraphQLSchema;
+    readonly plugins: ApolloServerPlugin<BaseContext>[];
+    constructor(config: ServerConfig<TDatasource, TContext>);
+    configure(): Runner;
+    assert(): void;
+}
+
+type BaseServerOptions = {
+    /**
+     * The version of the server
+     *
+     * @type {string}
+     */
+    version: string;
+    /**
+     * The name of the server
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * The port to listen on
+     *
+     * @type {number}
+     */
+    port?: number;
+    /**
+     * The hostname to listen on
+     *
+     * @type {string}
+     */
+    hostname?: string;
+};
+type ServerOptions<TDatasource, TContext extends BaseContext> = BaseServerOptions & {
+    config: ServerConfig<TDatasource, TContext>;
+};
+declare function createGraphQLServer<TDatasource, TContext extends BaseContext>(options: ServerOptions<TDatasource, TContext>): ServerBuilder<TDatasource, TContext>;
+
+declare function createApolloLoggingPlugin(): ApolloServerPlugin<BaseContext>;
+
+interface RateLimitOptions {
+    windowMs?: number;
+    max?: number;
+    keyGenerator?: (c: any) => string;
+}
+declare function createRateLimitMiddleware(options?: RateLimitOptions): MiddlewareHandler;
+
+interface ValidationOptions {
+    maxQueryDepth?: number;
+    maxQueryComplexity?: number;
+    maxAliasCount?: number;
+}
+declare function createValidationMiddleware(options?: ValidationOptions): MiddlewareHandler;
+
+declare function createTracingMiddleware(): MiddlewareHandler;
+
+interface HealthCheckOptions {
+    checks?: {
+        [key: string]: () => Promise<boolean>;
+    };
+}
+declare function configureHealthChecks(app: Hono, options?: HealthCheckOptions): void;
+
+declare enum ErrorCode {
+    UNAUTHENTICATED = "UNAUTHENTICATED",
+    FORBIDDEN = "FORBIDDEN",
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    RATE_LIMITED = "RATE_LIMITED",
+    EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR",
+    NOT_FOUND = "NOT_FOUND",
+    CONFLICT = "CONFLICT"
+}
+declare class AppError extends GraphQLError {
+    constructor(message: string, code: ErrorCode | ApolloServerErrorCode, extensions?: Record<string, any>);
+}
+
+declare const createSchemaModule: (typeDefs: DocumentNode, resolvers?: any) => {
+    typeDefs: DocumentNode;
+    resolvers: any;
+};
+type SchemaModule = ReturnType<typeof createSchemaModule>;
+
+declare const getNonUserInputErrors: (errors: readonly GraphQLError[]) => GraphQLError[];
+
+export { AppError, type BaseContext, type BaseServerOptions, type CacheOptions, CachedDataLoader, type ContextExtendFunction, type ContextUser, type EnvConfig, ErrorCode, KVCache, RedisCache, type Runner, type SchemaModule, ServerBuilder, type ServerConfig, type ServerOptions, cached, configureHealthChecks, createApolloLoggingPlugin, createCache, createContextFunction, createGraphQLServer, createRateLimitMiddleware, createSchemaModule, createTracingMiddleware, createValidationMiddleware, envLoader, getNonUserInputErrors, logger };