@breadstone/archipel-mcp 0.0.15 → 0.0.16

package/data/guides/blob-storage.md

@@ -0,0 +1,268 @@
+---
+title: Blob Storage
+description: Upload, download, and manage files with multi-provider blob storage using Vercel, Azure, AWS S3, or custom providers.
+order: 7
+---
+
+# Blob Storage
+
+This guide covers file storage with `platform-blob-storage`: choosing a provider, uploading and downloading files, generating signed URLs, and optionally tracking file metadata with persistence ports.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-blob-storage
+```
+
+---
+
+## Choose a Provider
+
+`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the provider at module registration time. Supported providers:
+
+| Provider   | Kind constant              | When to use                                 |
+| ---------- | -------------------------- | ------------------------------------------- |
+| **Vercel** | `BlobProviderKinds.Vercel` | Vercel-hosted apps with Vercel Blob storage |
+| **Azure**  | `BlobProviderKinds.Azure`  | Azure Blob Storage accounts                 |
+| **AWS S3** | `BlobProviderKinds.AwsS3`  | Amazon S3 or S3-compatible providers        |
+| **Custom** | `BlobProviderKinds.Custom` | Your own storage backend                    |
+
+---
+
+## Module Registration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { BlobModule, BlobProviderKinds } from '@breadstone/archipel-platform-blob-storage';
+
+@Module({
+  imports: [
+    BlobModule.forRoot({
+      provider: {
+        kind: BlobProviderKinds.AwsS3,
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Each provider reads its credentials from environment variables via the `ConfigModule`. Set the variables for your chosen provider:
+
+### AWS S3
+
+```env
+BLOB_AWS_REGION=eu-central-1
+BLOB_AWS_BUCKET=my-app-uploads
+BLOB_AWS_ACCESS_KEY_ID=AKIA...
+BLOB_AWS_SECRET_ACCESS_KEY=secret...
+```
+
+> **Note:** `accessKeyId` and `secretAccessKey` must be provided **together**. Omit both to use the default AWS credential chain (e.g., IAM roles, instance profiles).
+
+### Azure Blob Storage
+
+You can authenticate with either a **connection string** or **DefaultAzureCredential** (via managed identity):
+
+```env
+# Option 1: Connection string
+BLOB_AZURE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+BLOB_AZURE_CONTAINER=uploads
+
+# Option 2: DefaultAzureCredential (no connection string needed)
+BLOB_AZURE_ACCOUNT_NAME=mystorageaccount
+BLOB_AZURE_CONTAINER=uploads
+```
+
+When using `accountName` without a `connectionString`, the provider authenticates via `DefaultAzureCredential` from `@azure/identity`. This supports managed identities, environment credentials, and other Azure credential sources without storing secrets.
+
+> **Peer dependency:** Install `@azure/identity` when using DefaultAzureCredential: `yarn add @azure/identity`
+
+### Vercel Blob
+
+```env
+BLOB_VERCEL_TOKEN=your-vercel-blob-token
+```
+
+---
+
+## Uploading Files
+
+Inject `BlobService` to upload files. It returns metadata about the stored blob.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { BlobService } from '@breadstone/archipel-platform-blob-storage';
+
+@Injectable()
+export class AvatarService {
+  private readonly _blobService: BlobService;
+
+  constructor(blobService: BlobService) {
+    this._blobService = blobService;
+  }
+
+  public async uploadAvatar(userId: string, file: Buffer, mimeType: string): Promise<string> {
+    const result = await this._blobService.upload({
+      key: `avatars/${userId}`,
+      body: file,
+      contentType: mimeType,
+    });
+
+    return result.url;
+  }
+}
+```
+
+### Handling Multipart Uploads in Controllers
+
+For HTTP file uploads, use the `@UploadedFile()` decorator with Multer:
+
+```typescript
+import { Controller, Post, UploadedFile, UseGuards, UseInterceptors } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { JwtAuthGuard, User, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
+
+@Controller('avatars')
+export class AvatarController {
+  private readonly _avatarService: AvatarService;
+
+  constructor(avatarService: AvatarService) {
+    this._avatarService = avatarService;
+  }
+
+  @Post()
+  @UseGuards(JwtAuthGuard)
+  @UseInterceptors(FileInterceptor('file'))
+  public async upload(@User() user: IAuthSubject, @UploadedFile() file: Express.Multer.File): Promise<{ url: string }> {
+    const url = await this._avatarService.uploadAvatar(user.id, file.buffer, file.mimetype);
+    return { url };
+  }
+}
+```
+
+---
+
+## Downloading and Signed URLs
+
+```typescript
+// Download a blob
+const content = await this._blobService.download('avatars/user-123');
+
+// Generate a time-limited signed URL for direct client access
+const signedUrl = await this._blobService.getSignedUrl('avatars/user-123', {
+  expiresIn: 3600, // seconds
+});
+```
+
+Signed URLs are useful for serving private files directly to the client without proxying through your server.
+
+---
+
+## Deleting Files
+
+```typescript
+await this._blobService.delete('avatars/user-123');
+```
+
+---
+
+## Tracking Metadata (Optional Ports)
+
+By default, `BlobService` performs storage operations without persisting metadata to your database. If you need to track uploaded files (for listing, auditing, or cleanup), implement the optional persistence ports.
+
+### BlobObjectPersistencePort
+
+Tracks blob metadata after upload and deletion:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { BlobObjectPersistencePort } from '@breadstone/archipel-platform-blob-storage';
+import { PrismaService } from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class PrismaBlobObjectAdapter extends BlobObjectPersistencePort {
+  private readonly _prisma: PrismaService;
+
+  constructor(prisma: PrismaService) {
+    super();
+    this._prisma = prisma;
+  }
+
+  public async onUploaded(key: string, url: string, contentType: string, size: number): Promise<void> {
+    await this._prisma.blobObject.upsert({
+      where: { key },
+      create: { key, url, contentType, size },
+      update: { url, contentType, size },
+    });
+  }
+
+  public async onDeleted(key: string): Promise<void> {
+    await this._prisma.blobObject.deleteMany({ where: { key } });
+  }
+}
+```
+
+### BlobVariantPersistencePort
+
+Tracks image variants (thumbnails, resized versions):
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { BlobVariantPersistencePort } from '@breadstone/archipel-platform-blob-storage';
+import { PrismaService } from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class PrismaBlobVariantAdapter extends BlobVariantPersistencePort {
+  private readonly _prisma: PrismaService;
+
+  constructor(prisma: PrismaService) {
+    super();
+    this._prisma = prisma;
+  }
+
+  public async onVariantCreated(originalKey: string, variantKey: string, width: number, height: number): Promise<void> {
+    await this._prisma.blobVariant.create({
+      data: { originalKey, variantKey, width, height },
+    });
+  }
+}
+```
+
+### Register with Persistence
+
+```typescript
+BlobModule.forRoot({
+  provider: { kind: BlobProviderKinds.AwsS3 },
+  objectPersistence: PrismaBlobObjectAdapter,
+  variantPersistence: PrismaBlobVariantAdapter,
+}),
+```
+
+---
+
+## Security
+
+All built-in blob providers (AWS S3, Azure, Vercel) apply automatic key normalization via the internal `normalizeKey` method before any storage operation. This includes:
+
+- **Path traversal prevention** — segments such as `..` and `.` are removed so callers cannot escape the intended directory.
+- **Backslash normalization** — backslashes (`\`) are converted to forward slashes before processing.
+- **Leading-slash stripping** — a leading `/` is removed to produce clean, relative keys.
+- **Control-character rejection** — keys containing characters in the `\x00`–`\x1f` range cause an immediate `Error` to be thrown.
+
+These checks run transparently on every `uploadObject`, `downloadObject`, `deleteObject`, and `getSignedUrl` call. No additional configuration is required.
+
+---
+
+## Health Checks
+
+`platform-blob-storage` registers a health indicator automatically. It verifies connectivity to the configured provider. The result is included in your `/health` endpoint if you use `platform-core`'s health module.
+
+---
+
+## Next Steps
+
+- See the [Implementing Ports](/guides/implementing-ports) guide for the general port/adapter pattern
+- Browse the [platform-blob-storage API reference](/packages/platform-blob-storage/api/) for all method signatures

package/data/guides/caching.md

@@ -0,0 +1,255 @@
+---
+title: Caching
+description: Add layered caching to your NestJS application with in-memory LRU and Redis-backed implementations, TTL expiration, stale-while-revalidate, and metrics.
+order: 16
+---
+
+# Caching
+
+This guide covers layered caching with `platform-caching`: choosing between in-memory and Redis backends, configuring TTL and LRU eviction, using stale-while-revalidate for low-latency reads, and integrating cache metrics with your observability stack.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-caching
+```
+
+For Redis-backed caching, also install `ioredis`:
+
+```bash
+yarn add ioredis
+```
+
+---
+
+## Concepts
+
+`platform-caching` provides a generic `ILayeredCache<TKey, TValue>` interface with two implementations:
+
+| Implementation       | Backend   | Sync support | Best for                                 |
+| -------------------- | --------- | ------------ | ---------------------------------------- |
+| `MemoryLayeredCache` | In-memory | Yes          | Single-instance apps, fast local lookups |
+| `RedisLayeredCache`  | Redis     | No (async)   | Multi-instance deployments, shared state |
+
+Both implementations use a **loader function** pattern: when a cache miss occurs, the cache automatically calls a user-provided async function to load the value, stores it, and returns it. This eliminates repetitive "check cache → miss → load → store" boilerplate.
+
+---
+
+## In-Memory Cache
+
+### Basic Setup
+
+Create a `MemoryLayeredCache` with a loader function that fetches the value on cache misses:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { MemoryLayeredCache } from '@breadstone/archipel-platform-caching';
+
+@Injectable()
+export class ProductCacheService {
+  private readonly _cache: MemoryLayeredCache<string, IProduct>;
+
+  constructor(productRepository: ProductRepository) {
+    this._cache = new MemoryLayeredCache<string, IProduct>(async (productId: string) =>
+      productRepository.findById(productId),
+    );
+  }
+
+  public async getProduct(productId: string): Promise<IProduct | undefined> {
+    return this._cache.getAsync(productId);
+  }
+
+  public invalidateProduct(productId: string): void {
+    this._cache.invalidate(productId);
+  }
+}
+```
+
+### TTL Expiration
+
+Set a time-to-live so entries automatically expire:
+
+```typescript
+this._cache = new MemoryLayeredCache<string, IProduct>(
+  async (id) => productRepository.findById(id),
+  { ttlMs: 60_000 }, // entries expire after 60 seconds
+);
+```
+
+### LRU Eviction
+
+Limit the number of entries to prevent unbounded memory growth. The oldest entry (least recently used) is evicted first:
+
+```typescript
+this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
+  ttlMs: 300_000, // 5-minute TTL
+  maxEntries: 1000, // keep at most 1000 entries
+});
+```
+
+### Stale-While-Revalidate
+
+Serve expired entries immediately while refreshing in the background. This keeps latency low for frequently accessed data:
+
+```typescript
+this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
+  ttlMs: 30_000,
+  staleWhileRevalidate: true, // return stale value, refresh async
+});
+```
+
+> **When to use:** Quasi-static reference data (categories, feature flags, configuration). Avoid for personalized or rapidly changing data where freshness is critical.
+
+### Synchronous Access
+
+`MemoryLayeredCache` supports synchronous `get()` and `set()` for cases where you've pre-warmed the cache or need zero-await lookups:
+
+```typescript
+// Pre-warm on startup
+await this._cache.warm('featured-product');
+
+// Later: synchronous read (no await needed)
+const product = this._cache.get('featured-product');
+```
+
+---
+
+## Redis Cache
+
+### Basic Setup
+
+`RedisLayeredCache` provides the same `ILayeredCache` interface but stores entries in Redis. Synchronous methods (`get`, `set`, `invalidate`) throw — use the async variants.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';
+
+@Injectable()
+export class SessionCacheService {
+  private readonly _cache: RedisLayeredCache<string, ISessionData>;
+
+  constructor(sessionRepository: SessionRepository) {
+    this._cache = new RedisLayeredCache<string, ISessionData>(
+      async (sessionId) => sessionRepository.findById(sessionId),
+      {
+        url: process.env['REDIS_URL'] ?? 'redis://localhost:6379',
+        keyPrefix: 'session:',
+        ttlSeconds: 3600, // 1-hour TTL
+      },
+    );
+  }
+
+  public async getSession(sessionId: string): Promise<ISessionData | undefined> {
+    return this._cache.getAsync(sessionId);
+  }
+
+  public async invalidateSession(sessionId: string): Promise<void> {
+    await this._cache.invalidateAsync(sessionId);
+  }
+}
+```
+
+### Custom Serialization
+
+By default, values are serialized with `JSON.stringify` and deserialized with `JSON.parse`. Override this for custom formats:
+
+```typescript
+this._cache = new RedisLayeredCache<string, ISessionData>(async (id) => sessionRepository.findById(id), {
+  url: 'redis://localhost:6379',
+  keyPrefix: 'session:',
+  serialize: (value) => msgpack.encode(value).toString('base64'),
+  deserialize: (raw) => msgpack.decode(Buffer.from(raw, 'base64')) as ISessionData,
+});
+```
+
+### Graceful Shutdown
+
+`RedisLayeredCache` implements `OnModuleDestroy` and automatically disconnects the Redis client when the NestJS module is destroyed. No manual cleanup is needed.
+
+---
+
+## Cache Metrics
+
+Both implementations accept an optional `ICacheMetricsRecorder` to forward cache statistics to your observability backend.
+
+### Implementing a Metrics Recorder
+
+```typescript
+import type { ICacheMetricsRecorder } from '@breadstone/archipel-platform-caching';
+import { TelemetryFacade } from '@breadstone/archipel-platform-telemetry';
+
+export class TelemetryCacheMetricsRecorder implements ICacheMetricsRecorder {
+  private readonly _telemetry: TelemetryFacade;
+
+  constructor(telemetry: TelemetryFacade) {
+    this._telemetry = telemetry;
+  }
+
+  public recordHit(cache: string): void {
+    this._telemetry.recordCounter('cache_hits_total', 1, { cache });
+  }
+
+  public recordMiss(cache: string): void {
+    this._telemetry.recordCounter('cache_misses_total', 1, { cache });
+  }
+
+  public recordLoadSuccess(cache: string): void {
+    this._telemetry.recordCounter('cache_load_success_total', 1, { cache });
+  }
+
+  public recordLoadError(cache: string): void {
+    this._telemetry.recordCounter('cache_load_error_total', 1, { cache });
+  }
+
+  public recordEviction(cache: string): void {
+    this._telemetry.recordCounter('cache_evictions_total', 1, { cache });
+  }
+}
+```
+
+### Wiring It Up
+
+Pass the recorder when creating the cache:
+
+```typescript
+this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
+  ttlMs: 60_000,
+  maxEntries: 500,
+  metricsRecorder: new TelemetryCacheMetricsRecorder(telemetry),
+  cacheName: 'products',
+});
+```
+
+When no metrics recorder is provided, a `NoopCacheMetricsRecorder` is used automatically — no setup needed.
+
+---
+
+## Cache Statistics
+
+Both implementations expose a `stats()` method returning a snapshot of cache performance:
+
+```typescript
+const stats = this._cache.stats();
+console.log(stats.hits); // total cache hits
+console.log(stats.misses); // total cache misses
+console.log(stats.loads); // successful loader invocations
+console.log(stats.loadErrors); // failed loader invocations
+console.log(stats.evictions); // LRU evictions (MemoryLayeredCache only)
+```
+
+Use this for health checks or debug endpoints.
+
+---
+
+## Best Practices
+
+| Practice                                  | Why                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------ |
+| Set `maxEntries` for in-memory caches     | Prevents unbounded memory growth in long-running processes         |
+| Use `staleWhileRevalidate` for read-heavy | Keeps p99 latency low for popular keys                             |
+| Invalidate on writes                      | Call `invalidate(key)` after mutations to avoid serving stale data |
+| Use `cacheName` labels                    | Makes metrics dashboards filterable by cache instance              |
+| Keep TTLs short for user-specific data    | Personalized data should not be stale for extended periods         |
+| Use Redis for multi-instance deployments  | In-memory caches are not shared across application instances       |