arcway 0.1.0

package/README.md

@@ -0,0 +1,711 @@
+# Arcway
+
+A convention-based TypeScript framework for building modular monoliths with strict domain boundaries.
+
+Arcway uses file-system conventions to discover routes, services, jobs, events, and middleware — no manual wiring required. Each domain is isolated with its own database scope, event emitter, queue, cache, and file storage.
+
+## Quick Start
+
+```bash
+npm install arcway
+```
+
+Create a project:
+
+```
+my-app/
+├── arcway.config.ts
+├── domains/
+│   └── users/
+│       ├── config.ts
+│       └── api/
+│           └── index.ts
+└── db/
+    └── migrations/
+```
+
+**arcway.config.ts**
+
+```typescript
+import type { FrameworkConfig } from 'arcway';
+
+export default {
+  database: {
+    client: 'sqlite',
+    connection: './dev.db',
+  },
+} satisfies FrameworkConfig;
+```
+
+**domains/users/config.ts**
+
+```typescript
+import type { DomainConfig } from 'arcway';
+
+export default {
+  name: 'users',
+  tables: ['users'],
+} satisfies DomainConfig;
+```
+
+**domains/users/api/index.ts**
+
+```typescript
+import type { RouteMethodConfig } from 'arcway';
+
+export const GET: RouteMethodConfig = {
+  handler: async (ctx) => {
+    const users = await ctx.db('users').select('*');
+    return { data: users };
+  },
+};
+
+export const POST: RouteMethodConfig = {
+  handler: async (ctx) => {
+    const [id] = await ctx.db('users').insert(ctx.body);
+    return { status: 201, data: { id } };
+  },
+};
+```
+
+Start the dev server:
+
+```bash
+npx arcway dev
+```
+
+This boots the full stack: database, migrations, route discovery, event bus, job runner, and HTTP server.
+
+## CLI Commands
+
+| Command                         | Description                                                        |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `arcway dev`                      | Start development server (console logging, CORS enabled)           |
+| `arcway start`                    | Start production server (JSON logging, health check at `/health`)  |
+| `arcway build [outDir]`           | Compile TypeScript to production bundle (default: `dist`)          |
+| `arcway seed`                     | Run database seed files from `db/seeds/`                           |
+| `arcway docs [outFile]`           | Generate OpenAPI spec from route schemas (default: `openapi.json`) |
+| `arcway test [--watch] [pattern]` | Run domain tests (`domains/*/tests/**/*.test.ts`)                  |
+| `arcway lint`                     | Check for domain boundary violations                               |
+
+## Project Structure
+
+```
+project-root/
+├── arcway.config.ts              # Framework configuration
+├── domains/
+│   ├── users/
+│   │   ├── config.ts                # Domain name, owned tables, events, hooks
+│   │   ├── services/index.ts        # Exported service functions
+│   │   ├── api/                     # HTTP route handlers
+│   │   │   ├── index.ts             # GET /users, POST /users
+│   │   │   ├── [id].ts             # GET /users/:id, PUT /users/:id
+│   │   │   ├── [id]/projects.ts    # GET /users/:id/projects
+│   │   │   ├── admin/settings.ts   # GET /users/admin/settings
+│   │   │   ├── _middleware.ts       # Middleware for all /users/* routes
+│   │   │   └── admin/
+│   │   │       └── _middleware.ts   # Middleware for /users/admin/* only
+│   │   ├── jobs/                    # Background job definitions
+│   │   │   └── send-welcome.ts
+│   │   ├── listeners/               # Event subscribers
+│   │   │   └── on-signup.ts
+│   │   └── tests/                   # Domain unit tests
+│   │       └── users.test.ts
+│   └── billing/
+│       ├── config.ts
+│       ├── services/index.ts
+│       └── listeners/
+│           └── on-user-created.ts
+└── db/
+    ├── migrations/              # Knex migration files
+    │   └── 001_create_tables.js
+    └── seeds/                   # Database seed files
+        └── 001_users.ts
+```
+
+Files starting with `_` (except `_middleware.ts`) are excluded from route/job/listener discovery.
+
+## Configuration
+
+### Framework Config
+
+```typescript
+import type { FrameworkConfig } from 'arcway';
+
+export default {
+  server: {
+    port: 3000,
+    shutdownTimeoutMs: 10_000,
+    maxBodySize: 1_048_576, // 1 MB
+  },
+  api: {
+    cors: {
+      // Or true/false
+      origin: ['https://app.com'],
+      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization'],
+      exposedHeaders: ['X-Request-Id'],
+      credentials: true,
+      maxAge: 86400,
+    },
+  },
+  database: {
+    client: 'postgres',
+    connection: 'postgres://user:pass@localhost/mydb',
+  },
+  queue: {
+    driver: 'redis', // 'knex' (default) or 'redis'
+    lockCooldownMs: 300_000,
+    redis: { url: 'redis://localhost:6379' },
+  },
+  cache: {
+    driver: 'redis',
+    defaultTtlMs: 60_000,
+    redis: { url: 'redis://localhost:6379' },
+  },
+  events: {
+    driver: 'redis', // 'memory' (default) or 'redis'
+    redis: { url: 'redis://localhost:6379' },
+  },
+  files: {
+    driver: 's3', // 'local' (default) or 's3'
+    s3: {
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+    },
+  },
+} satisfies FrameworkConfig;
+```
+
+### CORS
+
+CORS behavior by default:
+
+- **Development** (`arcway dev`): Permissive — all origins allowed.
+- **Production** (`arcway start`): Disabled — no CORS headers unless configured.
+
+Configure with `api.cors`:
+
+- `true` — enable permissive CORS in any mode.
+- `false` — disable CORS entirely.
+- `CorsConfig` object — use specific settings.
+
+### Domain Config
+
+```typescript
+import type { DomainConfig } from 'arcway';
+import { z } from 'zod';
+
+export default {
+  name: 'users',
+  tables: ['users', 'sessions'],
+  events: [
+    { name: 'users/created', schema: z.object({ userId: z.number() }) },
+    { name: 'users/deleted' },
+  ],
+  hooks: {
+    onInit: async (ctx) => {
+      /* Before server starts */
+    },
+    onReady: async (ctx) => {
+      /* After server is listening */
+    },
+    onShutdown: async (ctx) => {
+      /* Graceful shutdown */
+    },
+  },
+} satisfies DomainConfig;
+```
+
+## Routes
+
+Route files live in `domains/<name>/api/` and map to URL patterns by file path:
+
+| File                    | URL Pattern                |
+| ----------------------- | -------------------------- |
+| `api/index.ts`          | `/<domain>`                |
+| `api/[id].ts`           | `/<domain>/:id`            |
+| `api/[id]/projects.ts`  | `/<domain>/:id/projects`   |
+| `api/admin/settings.ts` | `/<domain>/admin/settings` |
+
+Export named constants for each HTTP method:
+
+```typescript
+import { z } from 'zod';
+import type { RouteMethodConfig } from 'arcway';
+
+export const GET: RouteMethodConfig = {
+  schema: {
+    query: z.object({ page: z.coerce.number().default(1) }),
+  },
+  meta: {
+    summary: 'List users',
+    tags: ['users'],
+  },
+  handler: async (ctx) => {
+    const users = await ctx
+      .db('users')
+      .select('*')
+      .limit(20)
+      .offset((ctx.query.page - 1) * 20);
+    return { data: users };
+  },
+};
+
+export const POST: RouteMethodConfig = {
+  schema: {
+    body: z.object({
+      name: z.string().min(1),
+      email: z.string().email(),
+    }),
+  },
+  handler: async (ctx) => {
+    const { name, email } = ctx.body as { name: string; email: string };
+    const [id] = await ctx.db('users').insert({ name, email });
+    await ctx.events.emit('users/created', { userId: id });
+    return { status: 201, data: { id } };
+  },
+};
+```
+
+### Route Context
+
+Every handler receives a `RouteContext`:
+
+```typescript
+interface RouteContext {
+  domain: string; // Domain name
+  db: Knex; // Scoped database connection
+  services: ServicesProxy; // Cross-domain service calls
+  events: DomainEvents; // Event emission
+  queue: DomainQueue; // Persistent queue
+  cache: DomainCache; // Key-value cache
+  files: DomainFiles; // File storage
+  params: Record<string, string>; // URL parameters (:id)
+  query: Record<string, string>; // Query string (?key=value)
+  body: unknown; // Parsed request body
+  headers: Record<string, string>; // Request headers
+}
+```
+
+### Route Response
+
+```typescript
+interface RouteResponse {
+  status?: number; // Default: 200 (or 400 if error)
+  data?: unknown; // Wrapped in { data: ... }
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  headers?: Record<string, string>;
+}
+```
+
+## Middleware
+
+Place `_middleware.ts` files in `api/` directories. Middleware applies to all routes at that level and below.
+
+```typescript
+// domains/users/api/_middleware.ts — applies to all /users/* routes
+import type { MiddlewareFn } from 'arcway';
+
+const logger: MiddlewareFn = async (ctx, next) => {
+  const start = Date.now();
+  const response = await next();
+  console.log(`${ctx.headers['method']} took ${Date.now() - start}ms`);
+  return response;
+};
+
+export default logger;
+```
+
+```typescript
+// domains/users/api/admin/_middleware.ts — applies to /users/admin/* only
+import type { MiddlewareFn } from 'arcway';
+
+const auth: MiddlewareFn = async (ctx, next) => {
+  if (ctx.headers['authorization'] !== 'Bearer valid-token') {
+    return {
+      status: 401,
+      error: { code: 'UNAUTHORIZED', message: 'Invalid token' },
+    };
+  }
+  return next();
+};
+
+export default auth;
+```
+
+Middleware can also export an array of functions:
+
+```typescript
+export default [loggerMiddleware, authMiddleware];
+```
+
+Middleware chains execute outermost-first. A request to `/users/admin/settings` runs:
+
+1. `/users/api/_middleware.ts` (root)
+2. `/users/api/admin/_middleware.ts` (admin)
+3. Route handler
+
+Return without calling `next()` to short-circuit (e.g., return 401).
+
+## Services
+
+Services enable cross-domain function calls with automatic context injection.
+
+```typescript
+// domains/users/services/index.ts
+import type { DomainContext } from 'arcway';
+
+export default {
+  getById: async (ctx: DomainContext, id: string) => {
+    return ctx.db('users').where({ id }).first();
+  },
+  list: async (ctx: DomainContext) => {
+    return ctx.db('users').select('*');
+  },
+};
+```
+
+Call from another domain — `ctx` is injected automatically:
+
+```typescript
+// In a billing route handler
+const user = await ctx.services.users.getById(userId);
+```
+
+## Events
+
+Domains declare events they can emit in `config.ts`:
+
+```typescript
+events: [
+  { name: 'users/created', schema: z.object({ userId: z.number() }) },
+],
+```
+
+Emit from any handler, service, or job:
+
+```typescript
+const results = await ctx.events.emit('users/created', { userId: 42 });
+```
+
+Always `await` the emit call — immediate handlers run in-process during emit and their results are returned as an array of `EventResult`.
+
+### Listeners
+
+Listeners define how they handle events via two handler functions:
+
+- **`handler`** — dispatched via the event bus (eventually consistent, fire-and-forget)
+- **`handlerImmediate`** — runs in-process during `emit()`, before bus dispatch
+
+At least one must be defined. Both can be defined on the same listener.
+
+```typescript
+// domains/billing/listeners/on-user-created.ts (async — via bus)
+import type { ListenerDefinition } from 'arcway';
+
+export default {
+  event: 'users/created',
+  handler: async (ctx, payload) => {
+    const { userId } = payload as { userId: number };
+    await ctx.db('billing_accounts').insert({ user_id: userId, balance: 0 });
+  },
+} satisfies ListenerDefinition;
+```
+
+```typescript
+// domains/orgs/listeners/on-user-created.ts (immediate — in-process)
+import type { ListenerDefinition } from 'arcway';
+
+export default {
+  event: 'users/created',
+  handlerImmediate: async (ctx, payload) => {
+    const { userId } = payload as { userId: number };
+    const [org] = await ctx.db('orgs').insert({ owner_id: userId, name: 'My Org' });
+    if (!org) {
+      return { error: { code: 'ORG_CREATE_FAILED', message: 'Failed to create org' } };
+    }
+  },
+} satisfies ListenerDefinition;
+```
+
+Event patterns support wildcards: `'users/*'` matches all events from the users domain.
+
+## Jobs
+
+Background jobs support one-off queuing and cron scheduling.
+
+```typescript
+// domains/billing/jobs/generate-invoice.ts
+import { z } from 'zod';
+import type { JobDefinition } from 'arcway';
+
+export default {
+  name: 'generate-invoice',
+  schema: z.object({ userId: z.number(), month: z.string() }),
+  retries: 3,
+  schedule: '0 0 1 * *', // First of each month
+  handler: async (ctx, payload) => {
+    const { userId, month } = payload as { userId: number; month: string };
+    // Generate invoice...
+  },
+} satisfies JobDefinition;
+```
+
+Queue a job from any handler:
+
+```typescript
+await ctx.queue.push('generate-invoice', { userId: 42, month: '2025-01' });
+```
+
+Failed jobs retry with exponential backoff (1s, 2s, 4s, 8s...).
+
+## Queue
+
+Domain-scoped persistent queue for background processing:
+
+```typescript
+// Push work
+await ctx.queue.push('email-send', { to: 'user@example.com', body: '...' });
+
+// Pop and process (typically in a job handler)
+const items = await ctx.queue.pop('email-send', 10);
+for (const item of items) {
+  await sendEmail(item.data);
+  await ctx.queue.remove([item.id]);
+}
+```
+
+Drivers: `knex` (default, database-backed) or `redis`.
+
+## Cache
+
+Domain-scoped key-value cache with TTL support:
+
+```typescript
+// Set with TTL
+await ctx.cache.set('user:42', userData, 60_000);
+
+// Get
+const cached = await ctx.cache.get('user:42');
+
+// Cache-aside pattern
+const user = await ctx.cache.wrap(
+  'user:42',
+  async () => {
+    return ctx.db('users').where({ id: 42 }).first();
+  },
+  60_000,
+);
+
+// Delete
+await ctx.cache.delete('user:42');
+```
+
+Drivers: `knex` (default) or `redis`.
+
+## File Storage
+
+Domain-scoped file operations:
+
+```typescript
+// Write
+await ctx.files.write('avatars/user-42.png', imageBuffer);
+
+// Read
+const data = await ctx.files.read('avatars/user-42.png');
+
+// List
+const files = await ctx.files.list('avatars/');
+
+// Check existence
+const exists = await ctx.files.exists('avatars/user-42.png');
+
+// Delete
+await ctx.files.delete('avatars/user-42.png');
+```
+
+Drivers: `local` (default, filesystem) or `s3`.
+
+## Rate Limiting
+
+Rate limiting is available as a middleware factory with pluggable backends:
+
+```typescript
+// domains/api-gateway/api/_middleware.ts
+import { createRateLimitMiddleware, MemoryRateLimitStore } from 'arcway';
+
+const store = new MemoryRateLimitStore();
+
+export default createRateLimitMiddleware(
+  {
+    max: 100, // 100 requests
+    windowMs: 60_000, // per minute
+    // keyFn: (ctx) => ctx.headers['x-api-key'] ?? 'anonymous',
+    // message: 'Rate limit exceeded',
+  },
+  store,
+);
+```
+
+The middleware uses a sliding window algorithm. By default, it keys on the client IP from `X-Forwarded-For` or `X-Real-IP` headers.
+
+Response headers are added automatically:
+
+- `X-RateLimit-Limit` — configured maximum
+- `X-RateLimit-Remaining` — remaining requests in window
+- `X-RateLimit-Reset` — Unix timestamp when window resets
+- `Retry-After` — seconds until retry (on 429 responses only)
+
+Implement `RateLimitStore` for custom backends (Redis, etc.):
+
+```typescript
+interface RateLimitStore {
+  check(key: string, max: number, windowMs: number): Promise<RateLimitResult>;
+  destroy(): void;
+}
+```
+
+## Database Access Control
+
+Domains can only write to tables listed in their `config.ts`. Attempting to write to another domain's table throws `DomainAccessViolation`:
+
+```typescript
+// In users domain (tables: ['users', 'sessions'])
+await ctx.db('users').insert({ name: 'Alice' }); // OK
+await ctx.db('billing').insert({ amount: 100 }); // Throws DomainAccessViolation
+```
+
+Read access is unrestricted. Cross-domain writes go through services.
+
+## Domain Boundary Linting
+
+`arcway lint` statically checks for illegal imports between domains:
+
+```bash
+$ arcway lint
+Checking domain boundaries...
+  Domains: users, billing, projects
+  Files scanned: 24
+
+1 violation(s) found:
+
+  domains/billing/services/index.ts:3
+    Domain 'billing' imports directly from domain 'users'
+    Import: ../../users/services/index.ts
+```
+
+Domains must communicate through `ctx.services`, `ctx.events`, or `ctx.queue` — never by importing each other's files directly.
+
+## Testing
+
+Arcway provides test utilities that create isolated domain contexts with in-memory SQLite:
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createTestContext, type TestContext } from 'arcway';
+
+describe('users service', () => {
+  let t: TestContext;
+
+  beforeAll(async () => {
+    t = await createTestContext({
+      domain: 'users',
+      tables: ['users'],
+      migrationsDir: 'db/migrations',
+    });
+  });
+
+  afterAll(() => t.cleanup());
+
+  it('creates a user', async () => {
+    const [id] = await t.ctx.db('users').insert({ name: 'Alice' });
+    const user = await t.ctx.db('users').where({ id }).first();
+    expect(user.name).toBe('Alice');
+  });
+});
+```
+
+The test context stubs all infrastructure (events, queue, cache, files) so tests run fast and in isolation.
+
+## Seeds
+
+Seed files live in `db/seeds/` and run in alphabetical order:
+
+```typescript
+// db/seeds/001_users.ts
+import type { Knex } from 'knex';
+
+export default async function seed(db: Knex): Promise<void> {
+  await db('users')
+    .insert([
+      { id: 1, name: 'Alice', email: 'alice@test.com' },
+      { id: 2, name: 'Bob', email: 'bob@test.com' },
+    ])
+    .onConflict('id')
+    .merge();
+}
+```
+
+Run with `arcway seed`. Migrations execute first to ensure the schema is current.
+
+## OpenAPI Generation
+
+`arcway docs` generates an OpenAPI 3.0 spec from route schemas:
+
+```bash
+arcway docs openapi.json
+```
+
+Routes with `meta` and `schema` fields produce documented endpoints:
+
+```typescript
+export const GET: RouteMethodConfig = {
+  schema: {
+    params: z.object({ id: z.string() }),
+    query: z.object({ fields: z.string().optional() }),
+  },
+  meta: {
+    summary: 'Get user by ID',
+    description: 'Returns a single user record.',
+    tags: ['users'],
+  },
+  handler: async (ctx) => {
+    /* ... */
+  },
+};
+```
+
+## Production Build
+
+```bash
+arcway build           # Compile to dist/
+cd dist && arcway start
+```
+
+The build step compiles TypeScript with esbuild, copies non-TS files (migrations, JSON), and preserves the directory structure. The production server uses native `import()` — no tsx required at runtime.
+
+## Boot Sequence
+
+When `arcway dev` or `arcway start` runs, the framework:
+
+1. Loads `arcway.config.ts`
+2. Discovers all domains in `domains/`
+3. Connects to the database and runs migrations
+4. Initializes queue, cache, and file drivers
+5. Creates scoped domain contexts
+6. Discovers services and wires cross-domain proxies
+7. Creates event bus and registers listeners
+8. Discovers and registers jobs
+9. Runs `onInit` hooks
+10. Discovers routes and middleware
+11. Resolves CORS configuration
+12. Creates and starts HTTP server
+13. Runs `onReady` hooks
+14. Starts job runner (cron scheduler)
+
+Graceful shutdown reverses the process: stops the job runner, runs `onShutdown` hooks, drains connections, and closes the server.