@zyno-io/dk-server-foundation 26.216.430

package/docs/content/index.md

@@ -0,0 +1,147 @@
+---
+layout: home
+
+hero:
+    name: '@zyno-io/dk-server-foundation'
+    text: 'Server Foundation Library'
+    tagline: TypeScript foundation library built on Deepkit for building robust server applications
+    image:
+        src: /images/devconsole/01-dashboard.png
+        alt: DevConsole Dashboard
+    actions:
+        - theme: brand
+          text: Get Started
+          link: /getting-started
+        - theme: alt
+          text: View on GitHub
+          link: https://github.com/zyno-io/dk-server-foundation
+
+features:
+    - icon: 🗄️
+      title: Database ORM
+      details: MySQL/PostgreSQL support with transactions, hooks, session locks, and automatic migrations
+    - icon: 🌐
+      title: HTTP Server
+      details: Custom HTTP kernel with middleware, CORS, file uploads, and OpenAPI documentation
+    - icon: 🔐
+      title: Authentication
+      details: JWT (HS256/EdDSA) and HTTP Basic Auth with entity resolution and password hashing
+    - icon: ⚙️
+      title: Background Workers
+      details: BullMQ-based job processing with decorators, cron scheduling, and leader-elected recording
+    - icon: 🔌
+      title: WebSocket RPC
+      details: Bidirectional SRPC with HMAC auth, ts-proto code generation, and binary streams
+    - icon: 📊
+      title: Telemetry
+      details: OpenTelemetry auto-instrumentation for HTTP, database, Redis, DNS, and BullMQ
+    - icon: 🏥
+      title: Health Checks
+      details: Extensible health check service with automatic database monitoring
+    - icon: 🛠️
+      title: DevConsole
+      details: Built-in web dashboard for development with HTTP inspector, REPL, and more
+    - icon: 📧
+      title: Mail Service
+      details: Email sending via Postmark or SMTP with template system
+    - icon: 🔒
+      title: Distributed Systems
+      details: Leader election and mesh networking for coordinated multi-instance deployments
+    - icon: 🧪
+      title: Testing Utilities
+      details: Test facades with per-test database isolation, fixtures, and request mocking
+    - icon: 📝
+      title: Comprehensive Logging
+      details: Scoped Pino logger with async context tracking and structured data
+---
+
+## Quick Start
+
+```bash
+npm install @zyno-io/dk-server-foundation
+# or
+yarn add @zyno-io/dk-server-foundation
+```
+
+```typescript
+import { createApp, BaseAppConfig, createMySQLDatabase } from '@zyno-io/dk-server-foundation';
+
+class AppConfig extends BaseAppConfig {
+    MY_SETTING!: string;
+}
+
+class MyDB extends createMySQLDatabase({}, [UserEntity]) {}
+
+const app = createApp({
+    config: AppConfig,
+    db: MyDB,
+    cors: config => ({ hosts: ['https://example.com'], credentials: true }),
+    controllers: [UserController],
+    providers: [UserService]
+});
+
+app.run();
+```
+
+## DevConsole Screenshots
+
+The built-in DevConsole provides a comprehensive development dashboard:
+
+### Dashboard
+
+![DevConsole Dashboard](/images/devconsole/01-dashboard.png)
+
+### Routes
+
+![DevConsole Routes](/images/devconsole/02-routes.png)
+
+### OpenAPI Schema
+
+![DevConsole OpenAPI](/images/devconsole/03-openapi.png)
+
+### HTTP Requests
+
+![DevConsole Requests](/images/devconsole/04-requests.png)
+
+### SRPC
+
+![DevConsole SRPC](/images/devconsole/05-srpc.png)
+
+### Database
+
+![DevConsole Database](/images/devconsole/06-database.png)
+
+### Health Checks
+
+![DevConsole Health](/images/devconsole/07-health.png)
+
+### Mutex Monitor
+
+![DevConsole Mutex](/images/devconsole/08-mutex.png)
+
+### Interactive REPL
+
+![DevConsole REPL](/images/devconsole/09-repl.png)
+
+### Workers
+
+![DevConsole Workers](/images/devconsole/10-workers.png)
+
+## Features at a Glance
+
+- **Application Factory**: `createApp()` sets up Deepkit with opinionated defaults
+- **Configuration**: Environment-based config with `@zyno-io/config` integration
+- **Database**: Extends Deepkit ORM with MySQL/PostgreSQL support, transaction hooks, and session locks
+- **HTTP**: Custom kernel with middleware, CORS, uploads, and error handling
+- **Workers**: BullMQ background job processing with `@WorkerJob()` decorator
+- **SRPC**: Bidirectional WebSocket RPC with HMAC authentication
+- **Leader Election**: Redis-based distributed leader election for single-instance tasks
+- **Mesh Networking**: Typed RPC between distributed application instances
+- **Mail**: Email via Postmark or SMTP with template system
+- **Telemetry**: OpenTelemetry and Sentry integration
+- **Testing**: Comprehensive test utilities and fixtures
+- **CLI Tools**: REPL, provider invoke, migration commands, and more
+
+## License
+
+MIT License - see [LICENSE](https://github.com/zyno-io/dk-server-foundation/blob/main/LICENSE) for details.

package/docs/content/leader-service.md

@@ -0,0 +1,98 @@
+# LeaderService
+
+Distributed leader election using Redis. Exactly one instance holds leadership at a time, backed by an atomic lock with TTL-based expiry and periodic renewal.
+
+## Usage
+
+```typescript
+import { LeaderService } from '@zyno-io/dk-server-foundation';
+
+const leader = new LeaderService('my-feature');
+
+leader.setBecameLeaderCallback(async () => {
+    console.log('This instance is now the leader');
+    // Start leader-only work (e.g. scheduled jobs, cleanup tasks)
+});
+
+leader.setLostLeaderCallback(async () => {
+    console.log('Leadership lost');
+    // Stop leader-only work
+});
+
+leader.start();
+
+// Check leadership status at any time
+if (leader.isLeader) {
+    // perform leader-only operation
+}
+
+// Graceful shutdown
+await leader.stop();
+```
+
+## API
+
+### `new LeaderService(key: string, options?: LeaderServiceOptions)`
+
+Creates a new leader election instance.
+
+- **`key`** -- Logical name for the leadership group. All instances using the same key compete for the same lock. The full Redis key is derived as `{prefix}:leader:{key}`.
+- **`options`** -- Optional tuning parameters (see below).
+
+### `LeaderServiceOptions`
+
+| Option              | Type     | Default | Description                                                                                            |
+| ------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `ttlMs`             | `number` | `30000` | Lock TTL in milliseconds. If the leader crashes without releasing, the lock expires after this period. |
+| `renewalIntervalMs` | `number` | `10000` | How often the leader renews its lock. Should be well below `ttlMs` to avoid accidental expiry.         |
+| `retryDelayMs`      | `number` | `5000`  | Delay between acquisition attempts for non-leader instances.                                           |
+
+### Properties
+
+| Property   | Type      | Description                                            |
+| ---------- | --------- | ------------------------------------------------------ |
+| `isLeader` | `boolean` | Whether this instance currently holds the leader lock. |
+
+### Methods
+
+#### `setBecameLeaderCallback(callback: () => void | Promise<void>): void`
+
+Register a callback invoked when this instance acquires leadership. Errors thrown by the callback are logged but do not affect leader status.
+
+#### `setLostLeaderCallback(callback: () => void | Promise<void>): void`
+
+Register a callback invoked when this instance loses leadership (e.g. renewal failure, network partition). Errors are logged and do not prevent re-election attempts.
+
+#### `start(): void`
+
+Begin participating in leader election. Throws if already running. Acquisition is asynchronous -- the instance may not be leader immediately after `start()` returns.
+
+#### `stop(): Promise<void>`
+
+Stop participating and release the lock if currently leader. Safe to call multiple times.
+
+## How It Works
+
+1. **Acquisition**: Each instance attempts to set a Redis key with `NX` (set-if-not-exists) semantics and a TTL via a Lua script. If the key doesn't exist, the caller becomes leader.
+2. **Renewal**: The leader periodically refreshes the TTL on its lock. If the key's value no longer matches (another instance took over), leadership is considered lost.
+3. **Release**: On `stop()`, the leader deletes its key (only if the value still matches), allowing immediate failover.
+4. **Retry**: Non-leaders retry acquisition on a timer. If the leader crashes, the lock expires after `ttlMs` and another instance acquires it.
+
+All Redis operations use Lua scripts for atomicity:
+
+- **ACQUIRE** -- `SET key value PX ttl` only if the key doesn't exist
+- **RENEW** -- `PEXPIRE key ttl` only if the value matches
+- **RELEASE** -- `DEL key` only if the value matches
+
+## Configuration
+
+The Redis connection is configured via environment variables with the `MUTEX_REDIS_` prefix (falls back to `REDIS_`):
+
+| Variable                    | Description                                                  |
+| --------------------------- | ------------------------------------------------------------ |
+| `MUTEX_REDIS_HOST`          | Redis host                                                   |
+| `MUTEX_REDIS_PORT`          | Redis port                                                   |
+| `MUTEX_REDIS_PREFIX`        | Key prefix (falls back to `REDIS_PREFIX`, then package name) |
+| `MUTEX_REDIS_SENTINEL_HOST` | Sentinel host (optional)                                     |
+| `MUTEX_REDIS_SENTINEL_PORT` | Sentinel port (optional)                                     |
+| `MUTEX_REDIS_SENTINEL_NAME` | Sentinel master name (optional)                              |

package/docs/content/logging.md

@@ -0,0 +1,150 @@
+# Logging
+
+Scoped Pino logger with async context tracking, structured data, and error reporting integration.
+
+## Creating Loggers
+
+```typescript
+import { createLogger } from '@zyno-io/dk-server-foundation';
+
+// From a class instance (uses class name as scope)
+class OrderService {
+    private logger = createLogger(this);
+
+    async process() {
+        this.logger.info('Processing order');
+    }
+}
+
+// From a string
+const logger = createLogger('PaymentWorker');
+
+// With default data attached to every log
+const logger = createLogger(this, { region: 'us-east-1' });
+```
+
+## Log Levels
+
+```typescript
+logger.debug('Debug message');
+logger.info('Info message');
+logger.warning('Warning message');
+logger.error('Error message');
+logger.alert('Alert message');
+```
+
+## Structured Data
+
+```typescript
+// Attach data to a log entry
+logger.info('Order created', { orderId: 123, total: 99.99 });
+
+// Error with context
+logger.error('Payment failed', error, { orderId: 123, provider: 'stripe' });
+```
+
+## Scoped Loggers
+
+Create child loggers with a scope prefix and optional persistent data:
+
+```typescript
+const logger = createLogger(this);
+
+// Child logger with scope
+const paymentLogger = logger.scoped('payment');
+paymentLogger.info('Processing');
+// Output: [OrderService:payment] Processing
+
+// Child logger with persistent data
+const orderLogger = logger.scoped('order', { orderId: 123 });
+orderLogger.info('Created');
+// Every log includes { orderId: 123 }
+```
+
+### `setScopeData(data?)`
+
+Update the persistent data attached to a scoped logger:
+
+```typescript
+const logger = createLogger(this);
+logger.setScopeData({ userId: 456 });
+logger.info('Action');
+// Includes { userId: 456 }
+```
+
+## Async Context
+
+Logger automatically includes async context properties in log entries. This means request IDs, trace IDs, and other context set via `setContextProp()` or `withContextData()` flow into logs automatically.
+
+```typescript
+import { withContextData } from '@zyno-io/dk-server-foundation';
+
+await withContextData({ reqId: 'abc-123' }, async () => {
+    logger.info('Handling request');
+    // Log includes reqId: 'abc-123'
+});
+```
+
+### `withLoggerContext(data, fn)`
+
+Add additional logger context for the duration of a function:
+
+```typescript
+import { withLoggerContext } from '@zyno-io/dk-server-foundation';
+
+await withLoggerContext({ jobId: 'job-456' }, async () => {
+    logger.info('Processing job');
+    // Log includes jobId: 'job-456'
+});
+```
+
+## Error Handling
+
+When logging errors, the logger automatically:
+
+1. Extracts the error message and stack trace
+2. Includes any `cause` chain
+3. Reports to the global error reporter (Sentry, Slack) for `error` and `alert` levels
+
+```typescript
+try {
+    await riskyOperation();
+} catch (err) {
+    logger.error('Operation failed', err);
+    // Error reported to Sentry, details logged to Pino
+}
+```
+
+## ExtendedLogger
+
+`ExtendedLogger` replaces Deepkit's default `Logger` in the DI container. It extends `Logger` with:
+
+- Pino as the underlying transport
+- Scoped child loggers
+- Async context integration
+- Error reporting to Sentry and Slack
+
+All injected `Logger` instances are `ExtendedLogger` instances.
+
+## Pino Instance
+
+Access the raw Pino logger:
+
+```typescript
+import { pinoLogger } from '@zyno-io/dk-server-foundation';
+
+pinoLogger.info({ custom: 'data' }, 'Raw pino log');
+```
+
+## HTTP Request Logging
+
+Request logging is handled by the HTTP kernel and configured via `HTTP_REQUEST_LOGGING_MODE`:
+
+| Mode     | Description                  |
+| -------- | ---------------------------- |
+| `e2e`    | Log at request start and end |
+| `finish` | Log only at request end      |
+| `errors` | Log only errors              |
+| `none`   | No request logging           |
+
+Health check logging is disabled by default. Enable with `HEALTHZ_ENABLE_REQUEST_LOGGING=true`.

package/docs/content/mail.md

@@ -0,0 +1,161 @@
+# Mail
+
+Email sending via Postmark or SMTP with a template system.
+
+## Setup
+
+`MailService` is automatically registered by `createApp()`. Configure via environment variables:
+
+```bash
+# Provider selection
+MAIL_PROVIDER=smtp   # or 'postmark'
+MAIL_FROM=noreply@example.com
+MAIL_FROM_NAME="My App"
+
+# SMTP
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USER=apikey
+SMTP_PASSWORD_SECRET=secret
+SMTP_TLS=true
+
+# Postmark
+POSTMARK_SECRET=your-api-token
+```
+
+## Sending Emails
+
+### Direct Send
+
+```typescript
+import { MailService } from '@zyno-io/dk-server-foundation';
+
+class OrderService {
+    constructor(private mail: MailService) {}
+
+    async sendConfirmation(order: Order) {
+        await this.mail.send({
+            to: { address: order.email, name: order.name },
+            subject: 'Order Confirmation',
+            message: `<h1>Your order #${order.id} has been placed.</h1>`,
+            plainMessage: `Your order #${order.id} has been placed.`
+        });
+    }
+}
+```
+
+### Template Send
+
+```typescript
+await this.mail.sendFromTemplate({
+    to: { address: 'user@example.com' },
+    template: WelcomeEmail,
+    data: { name: 'Alice' }
+});
+```
+
+### Prepared Messages
+
+Prepare a message without sending (useful for previews or queuing):
+
+```typescript
+const prepared = await this.mail.prepare({
+    to: { address: 'user@example.com' },
+    subject: 'Hello',
+    message: '<h1>Hello</h1>'
+});
+
+const preparedFromTemplate = await this.mail.prepareFromTemplate({
+    to: { address: 'user@example.com' },
+    template: WelcomeEmail,
+    data: { name: 'Alice' }
+});
+```
+
+## Templates
+
+Create email templates by extending `MailTemplate`:
+
+```typescript
+import { MailTemplate } from '@zyno-io/dk-server-foundation';
+
+class WelcomeEmail extends MailTemplate<{ name: string; loginUrl: string }> {
+    subject = 'Welcome to Our App!';
+
+    generateHtml() {
+        return `
+            <h1>Welcome, ${this.data.name}!</h1>
+            <p>Get started by <a href="${this.data.loginUrl}">logging in</a>.</p>
+        `;
+    }
+
+    generateText() {
+        return `Welcome, ${this.data.name}! Log in at: ${this.data.loginUrl}`;
+    }
+}
+```
+
+### `MailTemplate<T>`
+
+| Property / Method | Type             | Description                          |
+| ----------------- | ---------------- | ------------------------------------ |
+| `subject`         | `string`         | Email subject line (abstract)        |
+| `data`            | `T`              | Template data (set by the framework) |
+| `generateHtml()`  | `string`         | HTML body (abstract)                 |
+| `generateText()`  | `string \| void` | Plain text body (optional)           |
+
+## Message Properties
+
+### `MessageProperties`
+
+| Property       | Type                                     | Required | Description                      |
+| -------------- | ---------------------------------------- | -------- | -------------------------------- |
+| `to`           | `{ address: string; name?: string }`     | Yes      | Recipient                        |
+| `from`         | `{ address: string; name?: string }`     | No       | Sender (defaults to `MAIL_FROM`) |
+| `replyTo`      | `{ address: string; name?: string }`     | No       | Reply-to address                 |
+| `subject`      | `string`                                 | Yes      | Subject line                     |
+| `message`      | `string`                                 | Yes      | HTML body                        |
+| `plainMessage` | `string`                                 | No       | Plain text body                  |
+| `attachments`  | `{ name, content, contentType, cid? }[]` | No       | File attachments                 |
+
+### `TemplateMessageProperties<T>`
+
+| Property   | Type                                 | Required | Description    |
+| ---------- | ------------------------------------ | -------- | -------------- |
+| `to`       | `{ address: string; name?: string }` | Yes      | Recipient      |
+| `template` | `ClassType<MailTemplate<T>>`         | Yes      | Template class |
+| `data`     | `T`                                  | Yes      | Template data  |
+
+## Providers
+
+### SMTP
+
+Uses nodemailer. Configured via `SMTP_*` environment variables.
+
+### Postmark
+
+Uses the Postmark API. Configured via `POSTMARK_SECRET`.
+
+Both providers implement the `MailProvider` interface:
+
+```typescript
+interface MailProvider {
+    send(message: PreparedMessageProperties): Promise<string>;
+}
+```
+
+The return value is a provider-specific message ID.
+
+## Configuration
+
+| Variable               | Type      | Default     | Description                    |
+| ---------------------- | --------- | ----------- | ------------------------------ |
+| `MAIL_PROVIDER`        | `string`  | `smtp`      | Provider: `smtp` or `postmark` |
+| `MAIL_FROM`            | `string`  | —           | Default sender address         |
+| `MAIL_FROM_NAME`       | `string`  | —           | Default sender name            |
+| `SMTP_HOST`            | `string`  | `127.0.0.1` | SMTP host                      |
+| `SMTP_PORT`            | `number`  | `1025`      | SMTP port                      |
+| `SMTP_USER`            | `string`  | —           | SMTP username                  |
+| `SMTP_PASSWORD_SECRET` | `string`  | —           | SMTP password                  |
+| `SMTP_TLS`             | `boolean` | `false`     | Enable TLS                     |
+| `POSTMARK_SECRET`      | `string`  | —           | Postmark API token             |