stacktape 3.5.8 → 3.6.0-beta.0

package/ai-docs/recipe/background-jobs.md

@@ -0,0 +1,183 @@
+---
+docType: recipe
+title: Background Jobs
+tags:
+  - background
+  - jobs
+  - recipe
+source: docs/_curated-docs/recipes/background-jobs.mdx
+priority: 1
+---
+
+# Background Job Processing
+
+Process jobs asynchronously using SQS queues and Lambda functions.
+
+## Configuration
+
+```typescript
+import { defineConfig, LambdaFunction, SqsQueue, HttpApiGateway } from 'stacktape';
+
+export default defineConfig(() => {
+  // Job queue
+  const jobQueue = new SqsQueue({
+    visibilityTimeoutSeconds: 300, // 5 minutes to process
+    messageRetentionPeriodSeconds: 1209600 // Keep for 14 days
+  });
+
+  // Job processor
+  const jobProcessor = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/processor.ts'
+      }
+    },
+    timeout: 300, // 5 minute timeout
+    memory: 1024,
+    events: [
+      {
+        type: 'sqs',
+        properties: {
+          sqsQueueName: 'jobQueue',
+          batchSize: 10
+        }
+      }
+    ]
+  });
+
+  // API to enqueue jobs
+  const api = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/api.ts'
+      }
+    },
+    connectTo: [jobQueue]
+  });
+
+  const gateway = new HttpApiGateway({
+    routes: [{ path: '/jobs', method: 'POST', integration: { type: 'function', properties: { function: api } } }]
+  });
+
+  return {
+    resources: { jobQueue, jobProcessor, api, gateway }
+  };
+});
+```
+
+## API Handler (Enqueue Jobs)
+
+```typescript
+// src/api.ts
+import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
+import { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+
+const sqs = new SQSClient({});
+
+export const handler: APIGatewayProxyHandlerV2 = async (event) => {
+  const body = JSON.parse(event.body || '{}');
+
+  await sqs.send(
+    new SendMessageCommand({
+      QueueUrl: process.env.STP_JOBQUEUE_QUEUE_URL,
+      MessageBody: JSON.stringify({
+        type: body.type,
+        payload: body.payload,
+        createdAt: new Date().toISOString()
+      })
+    })
+  );
+
+  return {
+    statusCode: 202,
+    body: JSON.stringify({ message: 'Job queued' })
+  };
+};
+```
+
+## Job Processor
+
+```typescript
+// src/processor.ts
+import { SQSHandler } from 'aws-lambda';
+
+export const handler: SQSHandler = async (event) => {
+  for (const record of event.Records) {
+    const job = JSON.parse(record.body);
+
+    console.log(`Processing job: ${job.type}`);
+
+    switch (job.type) {
+      case 'email':
+        await sendEmail(job.payload);
+        break;
+      case 'resize-image':
+        await resizeImage(job.payload);
+        break;
+      case 'generate-report':
+        await generateReport(job.payload);
+        break;
+      default:
+        console.warn(`Unknown job type: ${job.type}`);
+    }
+  }
+};
+
+async function sendEmail(payload: any) {
+  // Email sending logic
+}
+
+async function resizeImage(payload: any) {
+  // Image processing logic
+}
+
+async function generateReport(payload: any) {
+  // Report generation logic
+}
+```
+
+## Dead Letter Queue
+
+Handle failed jobs:
+
+```typescript
+// Failed jobs go here after 3 retries
+const deadLetterQueue = new SqsQueue({
+  messageRetentionPeriodSeconds: 1209600
+});
+
+const jobQueue = new SqsQueue({
+  visibilityTimeoutSeconds: 300,
+  redrivePolicy: {
+    targetSqsQueueName: 'deadLetterQueue',
+    maxReceiveCount: 3 // Retry 3 times before DLQ
+  }
+});
+
+// Alert on DLQ messages
+const dlqProcessor = new LambdaFunction({
+  packaging: {
+    type: 'stacktape-lambda-buildpack',
+    properties: {
+      entryfilePath: './src/dlq-alert.ts'
+    }
+  },
+  events: [
+    {
+      type: 'sqs',
+      properties: { sqsQueueName: 'deadLetterQueue' }
+    }
+  ]
+});
+```
+
+## Usage
+
+```bash
+# Enqueue a job
+curl -X POST https://your-api.execute-api.us-east-1.amazonaws.com/jobs \
+  -H "Content-Type: application/json" \
+  -d '{"type": "email", "payload": {"to": "user@example.com", "subject": "Hello"}}'
+```

package/ai-docs/recipe/database-migrations.md

@@ -0,0 +1,240 @@
+---
+docType: recipe
+title: Database Migrations
+tags:
+  - database
+  - migrations
+  - recipe
+source: docs/_curated-docs/recipes/database-migrations.mdx
+priority: 1
+---
+
+# Database Migrations
+
+Run database migrations automatically during deployment.
+
+## Using Prisma
+
+### Configuration
+
+```typescript
+import {
+  defineConfig,
+  LambdaFunction,
+  RelationalDatabase,
+  RdsEnginePostgres,
+  HttpApiGateway,
+  $Secret,
+  $ResourceParam
+} from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  const api = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/handler.ts'
+      }
+    },
+    connectTo: [database]
+  });
+
+  const gateway = new HttpApiGateway({
+    routes: [{ path: '/{proxy+}', method: '*', integration: { type: 'function', properties: { function: api } } }]
+  });
+
+  return {
+    hooks: {
+      afterDeploy: [{ scriptName: 'migrate' }]
+    },
+    scripts: {
+      migrate: {
+        executeCommand: 'npx prisma migrate deploy',
+        environment: {
+          DATABASE_URL: $ResourceParam('database', 'connectionString')
+        }
+      },
+      // Optional: seed script for development
+      seed: {
+        executeCommand: 'npx prisma db seed',
+        environment: {
+          DATABASE_URL: $ResourceParam('database', 'connectionString')
+        }
+      }
+    },
+    resources: { database, api, gateway }
+  };
+});
+```
+
+### Prisma Schema
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  posts     Post[]
+  createdAt DateTime @default(now())
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  content   String?
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  Int
+  createdAt DateTime @default(now())
+}
+```
+
+### Creating Migrations
+
+```bash
+# Development: create a new migration
+npx prisma migrate dev --name add_users_table
+
+# This creates: prisma/migrations/20240115_add_users_table/migration.sql
+```
+
+## Using Drizzle
+
+### Configuration
+
+```typescript
+export default defineConfig(({ stage }) => {
+  // ... resources ...
+
+  return {
+    hooks: {
+      afterDeploy: [{ scriptName: 'migrate' }]
+    },
+    scripts: {
+      migrate: {
+        executeCommand: 'npx drizzle-kit push',
+        environment: {
+          DATABASE_URL: $ResourceParam('database', 'connectionString')
+        }
+      }
+    },
+    resources: { database, api, gateway }
+  };
+});
+```
+
+## Using Raw SQL
+
+### Migration Script
+
+```typescript
+// scripts/migrate.ts
+import { Pool } from 'pg';
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL
+});
+
+async function migrate() {
+  // Create migrations table if not exists
+  await pool.query(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      id SERIAL PRIMARY KEY,
+      name VARCHAR(255) NOT NULL UNIQUE,
+      applied_at TIMESTAMP DEFAULT NOW()
+    )
+  `);
+
+  // Get applied migrations
+  const { rows: applied } = await pool.query('SELECT name FROM _migrations');
+  const appliedNames = new Set(applied.map((r) => r.name));
+
+  // Get migration files
+  const migrationsDir = join(__dirname, '../migrations');
+  const files = await readdir(migrationsDir);
+  const pending = files
+    .filter((f) => f.endsWith('.sql'))
+    .filter((f) => !appliedNames.has(f))
+    .sort();
+
+  // Apply pending migrations
+  for (const file of pending) {
+    console.log(`Applying: ${file}`);
+    const sql = await readFile(join(migrationsDir, file), 'utf-8');
+
+    await pool.query('BEGIN');
+    try {
+      await pool.query(sql);
+      await pool.query('INSERT INTO _migrations (name) VALUES ($1)', [file]);
+      await pool.query('COMMIT');
+      console.log(`Applied: ${file}`);
+    } catch (error) {
+      await pool.query('ROLLBACK');
+      throw error;
+    }
+  }
+
+  console.log('Migrations complete');
+}
+
+migrate()
+  .catch(console.error)
+  .finally(() => pool.end());
+```
+
+### Stacktape Script
+
+```typescript
+scripts: {
+  migrate: {
+    executeCommand: 'npx ts-node scripts/migrate.ts',
+    environment: {
+      DATABASE_URL: $ResourceParam('database', 'connectionString')
+    }
+  }
+}
+```
+
+## Migration Best Practices
+
+1. **Always test migrations locally first**
+
+   ```bash
+   stacktape dev --stage dev --region us-east-1
+   # Then run migrations against local emulated database
+   ```
+
+2. **Make migrations idempotent when possible**
+
+   ```sql
+   CREATE TABLE IF NOT EXISTS users (...);
+   CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+   ```
+
+3. **Use transactions for safety**
+   - Prisma and Drizzle handle this automatically
+   - For raw SQL, wrap in BEGIN/COMMIT
+
+4. **Back up production before migrating**
+   ```bash
+   # Create a snapshot before deploying
+   aws rds create-db-snapshot --db-instance-identifier my-db --db-snapshot-identifier pre-migration-backup
+   ```

package/ai-docs/recipe/graphql-api.md

@@ -0,0 +1,211 @@
+---
+docType: recipe
+title: GraphQL API
+tags:
+  - graphql
+  - api
+  - recipe
+source: docs/_curated-docs/recipes/graphql-api.mdx
+priority: 1
+---
+
+# GraphQL API
+
+Deploy a GraphQL API using Apollo Server.
+
+## Lambda-based (Serverless)
+
+```typescript
+import {
+  defineConfig,
+  LambdaFunction,
+  RelationalDatabase,
+  RdsEnginePostgres,
+  HttpApiGateway,
+  $Secret
+} from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  const graphql = new LambdaFunction({
+    packaging: {
+      type: 'stacktape-lambda-buildpack',
+      properties: {
+        entryfilePath: './src/graphql.ts'
+      }
+    },
+    timeout: 30,
+    memory: 1024,
+    connectTo: [database]
+  });
+
+  const gateway = new HttpApiGateway({
+    routes: [{ path: '/graphql', method: '*', integration: { type: 'function', properties: { function: graphql } } }]
+  });
+
+  return {
+    resources: { database, graphql, gateway }
+  };
+});
+```
+
+## Apollo Server Handler
+
+```typescript
+// src/graphql.ts
+import { ApolloServer } from '@apollo/server';
+import { startServerAndCreateLambdaHandler, handlers } from '@as-integrations/aws-lambda';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+const typeDefs = `#graphql
+  type User {
+    id: ID!
+    email: String!
+    name: String
+    posts: [Post!]!
+  }
+
+  type Post {
+    id: ID!
+    title: String!
+    content: String
+    author: User!
+  }
+
+  type Query {
+    users: [User!]!
+    user(id: ID!): User
+    posts: [Post!]!
+  }
+
+  type Mutation {
+    createUser(email: String!, name: String): User!
+    createPost(title: String!, content: String, authorId: ID!): Post!
+  }
+`;
+
+const resolvers = {
+  Query: {
+    users: () => prisma.user.findMany(),
+    user: (_: any, { id }: { id: string }) => prisma.user.findUnique({ where: { id: parseInt(id) } }),
+    posts: () => prisma.post.findMany()
+  },
+  Mutation: {
+    createUser: (_: any, { email, name }: { email: string; name?: string }) =>
+      prisma.user.create({ data: { email, name } }),
+    createPost: (_: any, { title, content, authorId }: { title: string; content?: string; authorId: string }) =>
+      prisma.post.create({ data: { title, content, authorId: parseInt(authorId) } })
+  },
+  User: {
+    posts: (user: any) => prisma.post.findMany({ where: { authorId: user.id } })
+  },
+  Post: {
+    author: (post: any) => prisma.user.findUnique({ where: { id: post.authorId } })
+  }
+};
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  introspection: process.env.NODE_ENV !== 'production'
+});
+
+export const handler = startServerAndCreateLambdaHandler(server, handlers.createAPIGatewayProxyEventV2RequestHandler());
+```
+
+## Container-based (For Complex APIs)
+
+```typescript
+import { defineConfig, WebService, RelationalDatabase, RdsEnginePostgres, $Secret } from 'stacktape';
+
+export default defineConfig(({ stage }) => {
+  const database = new RelationalDatabase({
+    engine: new RdsEnginePostgres({ version: '16' }),
+    credentials: {
+      masterUserPassword: $Secret(`db-password-${stage}`)
+    }
+  });
+
+  const graphql = new WebService({
+    packaging: {
+      type: 'stacktape-image-buildpack',
+      properties: {
+        entryfilePath: './src/server.ts'
+      }
+    },
+    resources: {
+      cpu: 0.5,
+      memory: 1024
+    },
+    connectTo: [database],
+    scaling: {
+      minInstances: 1,
+      maxInstances: 10
+    }
+  });
+
+  return {
+    resources: { database, graphql }
+  };
+});
+```
+
+## Container Server
+
+```typescript
+// src/server.ts
+import { ApolloServer } from '@apollo/server';
+import { expressMiddleware } from '@apollo/server/express4';
+import express from 'express';
+import cors from 'cors';
+
+const app = express();
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers
+});
+
+await server.start();
+
+app.use('/graphql', cors(), express.json(), expressMiddleware(server));
+
+app.listen(process.env.PORT || 80, () => {
+  console.log('GraphQL server running');
+});
+```
+
+## Dependencies
+
+```json
+{
+  "dependencies": {
+    "@apollo/server": "^4.0.0",
+    "@as-integrations/aws-lambda": "^3.0.0",
+    "@prisma/client": "^5.0.0",
+    "graphql": "^16.0.0"
+  }
+}
+```
+
+## Testing
+
+```bash
+# Query
+curl -X POST https://your-api.execute-api.us-east-1.amazonaws.com/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ users { id email name } }"}'
+
+# Mutation
+curl -X POST https://your-api.execute-api.us-east-1.amazonaws.com/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "mutation { createUser(email: \"test@example.com\", name: \"Test\") { id } }"}'
+```