@podosoft/podokit 0.17.4 → 1.0.2

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.module.ts

@@ -1,65 +1,85 @@
-import { Injectable, Module } from "@nestjs/common";
-import { APP_GUARD, Reflector } from "@nestjs/core";
-import {
-  InjectThrottlerOptions,
-  InjectThrottlerStorage,
-  ThrottlerGuard,
-  ThrottlerModule,
-  type ThrottlerLimitDetail,
-  type ThrottlerModuleOptions,
-  type ThrottlerRequest,
-  type ThrottlerStorage,
-} from "@nestjs/throttler";
-import { ThrottlerStorageRedisService } from "@nest-lab/throttler-storage-redis";
-import type { Request } from "express";
-import { ApiKeyVerifier } from "../api-key/api-key-verifier";
+import type { RedisClient } from "bun";
 import { AppException } from "../common/app-exception";
-import { RedisModule } from "../redis/redis.module";
-import { RedisService } from "../redis/redis.service";
-import { rateLimitConfig } from "./rate-limit.config";
+import { API_KEY_VERIFIER } from "../api-key/api-key.module";
+import {
+  REQUEST_GUARDS,
+  type PodokitModule,
+  type RequestGuardContext,
+  type ServiceKey,
+} from "../core/services";
+import { REDIS } from "../redis/redis.module";
+import { rateLimitConfig, type RateLimitConfig } from "./rate-limit.config";
 import { RateLimitIdentity } from "./rate-limit.identity";
 
-const config = rateLimitConfig();
-const unthrottledHealthPaths = new Set(["/health", "/health/ready"]);
+export interface RateLimitIncrement {
+  count: number;
+  retryAfterSeconds: number;
+}
 
-@Injectable()
-export class ProxyAwareThrottlerGuard extends ThrottlerGuard {
-  constructor(
-    @InjectThrottlerOptions() options: ThrottlerModuleOptions,
-    @InjectThrottlerStorage() storage: ThrottlerStorage,
-    reflector: Reflector,
-    private readonly identity: RateLimitIdentity,
-  ) {
-    super(options, storage, reflector);
+export interface RateLimitStorage {
+  increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement>;
+}
+
+const INCREMENT_SCRIPT = `
+local count = redis.call('INCR', KEYS[1])
+if count == 1 then redis.call('EXPIRE', KEYS[1], ARGV[1]) end
+local ttl = redis.call('TTL', KEYS[1])
+return { count, ttl }
+`;
+
+function resultNumber(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
   }
+  return undefined;
+}
 
-  protected override async handleRequest(
-    requestProps: ThrottlerRequest,
-  ): Promise<boolean> {
-    const { req, res } = this.getRequestResponse(requestProps.context);
-    const method = typeof req.method === "string" ? req.method : "";
-    const path = typeof req.path === "string" ? req.path : "";
-    if (method === "GET" && unthrottledHealthPaths.has(path)) return true;
+export class RedisRateLimitStorage implements RateLimitStorage {
+  constructor(private readonly client: RedisClient) {}
 
-    let effective = requestProps;
-    if (path === "/api/auth" || path.startsWith("/api/auth/")) {
-      effective = {
-        ...requestProps,
-        limit: config.authLimit,
-        ttl: config.authTtlSeconds * 1000,
-        blockDuration: config.authTtlSeconds * 1000,
-      };
-    } else if (method === "GET" && path === "/site/settings") {
-      effective = { ...requestProps, limit: config.runtimeLimit };
+  async increment(key: string, ttlSeconds: number): Promise<RateLimitIncrement> {
+    const result = await this.client.send("EVAL", [
+      INCREMENT_SCRIPT,
+      "1",
+      key,
+      String(ttlSeconds),
+    ]);
+    if (!Array.isArray(result)) throw new Error("Redis returned an invalid rate-limit result");
+    const count = resultNumber(result[0]);
+    const retryAfterSeconds = resultNumber(result[1]);
+    if (count === undefined || retryAfterSeconds === undefined) {
+      throw new Error("Redis returned an invalid rate-limit counter");
     }
+    return { count, retryAfterSeconds: Math.max(1, retryAfterSeconds) };
+  }
+}
+
+type LimitProfile = { name: string; ttlSeconds: number; limit: number };
+
+export class RateLimiter {
+  constructor(
+    private readonly config: RateLimitConfig,
+    private readonly identity: RateLimitIdentity,
+    private readonly storage: RateLimitStorage,
+  ) {}
+
+  async enforce(context: RequestGuardContext): Promise<void> {
+    const { request } = context;
+    const path = new URL(request.url).pathname;
+    if (
+      request.method === "GET" &&
+      ["/health", "/health/ready", "/api-docs", "/api-docs-json", "/api-docs-elysia-json"].includes(path)
+    ) return;
 
     try {
-      return await this.withStorageTimeout(super.handleRequest(effective));
+      const profile = this.profile(request.method, path);
+      const tracker = await this.identity.resolve(request, context.remoteAddress, this.config);
+      await this.enforceCustom(profile.name, tracker, profile.ttlSeconds, profile.limit, context.setHeader);
     } catch (error) {
       if (error instanceof AppException) throw error;
-      if (typeof res.header === "function") {
-        res.header("Retry-After", config.unavailableRetryAfterSeconds);
-      }
+      context.setHeader("Retry-After", String(this.config.unavailableRetryAfterSeconds));
       throw new AppException(
         "RATE_LIMIT_UNAVAILABLE",
         "Request limiting is temporarily unavailable.",
@@ -68,57 +88,73 @@ export class ProxyAwareThrottlerGuard extends ThrottlerGuard {
     }
   }
 
-  protected override getTracker(request: Record<string, unknown>): Promise<string> {
-    return this.identity.resolve(request as unknown as Request, config);
+  async enforceCustom(
+    name: string,
+    tracker: string,
+    ttlSeconds: number,
+    limit: number,
+    setHeader: (name: string, value: string) => void,
+  ): Promise<void> {
+    try {
+      const result = await this.withTimeout(
+        this.storage.increment(`${this.config.keyPrefix}:${name}:${tracker}`, ttlSeconds),
+      );
+      setHeader("RateLimit-Limit", String(limit));
+      setHeader("RateLimit-Remaining", String(Math.max(0, limit - result.count)));
+      if (result.count > limit) {
+        setHeader("Retry-After", String(result.retryAfterSeconds));
+        throw new AppException("RATE_LIMIT_EXCEEDED", "Too many requests.", 429);
+      }
+    } catch (error) {
+      if (error instanceof AppException) throw error;
+      setHeader("Retry-After", String(this.config.unavailableRetryAfterSeconds));
+      throw new AppException(
+        "RATE_LIMIT_UNAVAILABLE",
+        "Request limiting is temporarily unavailable.",
+        503,
+      );
+    }
   }
 
-  protected override async throwThrottlingException(
-    _context: Parameters<ThrottlerGuard["canActivate"]>[0],
-    _detail: ThrottlerLimitDetail,
-  ): Promise<void> {
-    throw new AppException(
-      "RATE_LIMIT_EXCEEDED",
-      "Too many requests.",
-      429,
-    );
+  private profile(method: string, path: string): LimitProfile {
+    if (path === "/api/auth" || path.startsWith("/api/auth/")) {
+      return { name: "auth", ttlSeconds: this.config.authTtlSeconds, limit: this.config.authLimit };
+    }
+    if (method === "GET" && path === "/site/settings") {
+      return { name: "runtime", ttlSeconds: this.config.ttlSeconds, limit: this.config.runtimeLimit };
+    }
+    return { name: "general", ttlSeconds: this.config.ttlSeconds, limit: this.config.limit };
   }
 
-  private async withStorageTimeout(operation: Promise<boolean>): Promise<boolean> {
-    let timeout: NodeJS.Timeout | undefined;
+  private async withTimeout(operation: Promise<RateLimitIncrement>): Promise<RateLimitIncrement> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
     try {
       return await Promise.race([
         operation,
         new Promise<never>((_resolve, reject) => {
-          timeout = setTimeout(
+          timer = setTimeout(
             () => reject(new Error("Rate limit storage timeout")),
-            config.storageTimeoutMs,
+            this.config.storageTimeoutMs,
           );
         }),
       ]);
     } finally {
-      if (timeout) clearTimeout(timeout);
+      if (timer !== undefined) clearTimeout(timer);
     }
   }
 }
 
-@Module({
-  imports: [
-    RedisModule,
-    ThrottlerModule.forRootAsync({
-      imports: [RedisModule],
-      inject: [RedisService],
-      useFactory: (redis: RedisService) => ({
-        throttlers: [{ ttl: config.ttlSeconds * 1000, limit: config.limit }],
-        storage: new ThrottlerStorageRedisService(redis.client),
-      }),
-    }),
-  ],
-  providers: [
-    ApiKeyVerifier,
-    RateLimitIdentity,
-    ProxyAwareThrottlerGuard,
-    { provide: APP_GUARD, useExisting: ProxyAwareThrottlerGuard },
-  ],
-  exports: [RateLimitIdentity],
-})
-export class RateLimitModule {}
+export const RATE_LIMITER = Symbol("rate-limiter") as ServiceKey<RateLimiter>;
+
+export const rateLimitModule: PodokitModule = {
+  name: "rate-limit",
+  configure: (_env, services): void => {
+    const limiter = new RateLimiter(
+      rateLimitConfig(),
+      new RateLimitIdentity(services.resolve(API_KEY_VERIFIER), services),
+      new RedisRateLimitStorage(services.resolve(REDIS).client),
+    );
+    services.register(RATE_LIMITER, limiter);
+    services.resolve(REQUEST_GUARDS).register((context) => limiter.enforce(context));
+  },
+};

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -13,10 +13,26 @@ const origin = { origin: base };
 // to the module default and allow a little headroom.
 const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 
+async function session(
+  playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
+) {
+  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+  const signup = await ctx.post("/api/auth/sign-up/email", {
+    data: {
+      email,
+      password: "Podokit3e-Str0ng!pw",
+      name: "Rate Limit",
+    },
+  });
+  expect(signup.ok()).toBeTruthy();
+  return ctx;
+}
+
 test("rate limit: health probes stay available while ordinary routes return 429 @smoke", async ({
   playwright,
 }) => {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+  const ctx = await session(playwright);
   for (const path of ["/api/health", "/api/health/ready"]) {
     for (let i = 0; i < limit + 5; i++) {
       const response = await ctx.get(path);

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,24 +1,21 @@
 {
   "name": "rate-limit",
-  "description": "Distributed request limiting by authenticated user, validated API key, or trusted-proxy client address. Uses Redis across API replicas and returns stable 429/503 errors.",
+  "description": "Distributed Elysia request limiting by authenticated user, validated API key, or trusted-proxy client address. Uses Bun Redis across replicas and returns stable 429/503 errors.",
   "requires": ["redis", "api-key-auth"],
   "targetApp": "api",
   "managedGlobs": [
     "apps/api/src/rate-limit/**",
     "tests/api/rate-limit.api.spec.ts"
   ],
-  "dependencies": {
-    "@nestjs/throttler": "^6.5.0",
-    "@nest-lab/throttler-storage-redis": "^1.2.0"
-  },
   "env": [
     "# rate limit (window in seconds, max requests per identity)",
+    "RATE_LIMIT_KEY_PREFIX=podokit:rate-limit",
     "RATE_LIMIT_TTL=60",
     "RATE_LIMIT_MAX=300",
     "# stricter authentication endpoint ceiling",
     "RATE_LIMIT_AUTH_TTL=60",
     "RATE_LIMIT_AUTH_MAX=20",
-    "# higher ceiling for SSR runtime settings reads (maintenance, sign-up, branding)",
+    "# higher ceiling for SSR runtime settings reads",
     "RATE_LIMIT_RUNTIME_MAX=1000",
     "# trust no proxy hop by default; set the exact production proxy depth",
     "RATE_LIMIT_TRUSTED_PROXY_HOPS=0",
@@ -27,17 +24,26 @@
     "RATE_LIMIT_UNAVAILABLE_RETRY_AFTER=1"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RateLimitModule } from \"./rate-limit/rate-limit.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "RateLimitModule," }
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:imports",
+      "text": "import { rateLimitModule } from \"./rate-limit/rate-limit.module\";"
+    },
+    {
+      "file": "apps/api/src/app.ts",
+      "marker": "// podokit:end:modules",
+      "text": "rateLimitModule,"
+    }
   ],
   "instructions": [
-    "Ensure Redis is running:  docker compose -f infra/docker/docker-compose.yml up -d",
+    "Ensure Redis is running: docker compose -f infra/docker/docker-compose.yml up -d",
     "Tune the general, authentication, and runtime limits in .env.",
+    "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
     "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
     "Authenticated users and validated X-API-Key clients receive independent opaque counters; other traffic uses the trusted client address.",
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Redis failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
-    "Provide RateLimitIdentityExtension from app.extensions.ts when an application has another validated machine-key source; keep the single managed RateLimitModule import.",
+    "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
-    "The limit is shared across API replicas because it is stored in Redis."
+    "The atomic counter is shared across API replicas in Redis."
   ]
 }

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.module.ts

@@ -1,12 +1,43 @@
-import { Global, Module } from "@nestjs/common";
-import { CacheController } from "./cache.controller";
+import { Elysia, t } from "elysia";
+import {
+  type AppPlugin,
+  type PodokitModule,
+  READINESS,
+  type ServiceKey,
+} from "../core/services";
 import { RedisService } from "./redis.service";
 
-// Global so any module can inject RedisService (cache, pub/sub, etc.).
-@Global()
-@Module({
-  controllers: [CacheController],
-  providers: [RedisService],
-  exports: [RedisService],
-})
-export class RedisModule {}
+export const REDIS = Symbol("redis") as ServiceKey<RedisService>;
+
+const cachePlugin: AppPlugin = ({ services }) => {
+  const redis = services.resolve(REDIS);
+  return new Elysia({ name: "podokit.redis" })
+    .put("/cache/:key", async ({ params, body }) => {
+      await redis.set(params.key, body.value, body.ttl);
+      return { key: params.key };
+    }, {
+      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      body: t.Object({
+        value: t.String(),
+        ttl: t.Optional(t.Integer({ minimum: 1 })),
+      }),
+      detail: { tags: ["cache"], summary: "Store a cache value" },
+    })
+    .get("/cache/:key", async ({ params }) => ({
+      key: params.key,
+      value: await redis.get(params.key),
+    }), {
+      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      detail: { tags: ["cache"], summary: "Read a cache value" },
+    });
+};
+
+export const redisModule: PodokitModule = {
+  name: "redis",
+  configure: (_env, services): void => {
+    const redis = new RedisService(services.resolve(READINESS));
+    services.register(REDIS, redis, () => redis.close());
+    services.onStart(() => redis.connect());
+  },
+  plugin: cachePlugin,
+};

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "@jest/globals";
+import { describe, expect, it } from "bun:test";
 import { ReadinessService } from "../health/readiness.service";
 import { RedisService } from "./redis.service";
 
@@ -14,13 +14,13 @@ describe("RedisService integration", () => {
     const key = `podokit:test:${Date.now()}:${Math.random().toString(36).slice(2)}`;
 
     try {
-      await service.onModuleInit();
+      await service.connect();
       await service.set(key, "value", 10);
       await expect(service.get(key)).resolves.toBe("value");
       await expect(readiness.run()).resolves.toEqual({ redis: "up" });
       await service.del(key);
     } finally {
-      await service.onModuleDestroy();
+      service.close();
       if (previousUrl === undefined) delete process.env.REDIS_URL;
       else process.env.REDIS_URL = previousUrl;
     }

package/dist/templates/modules/redis/files/apps/api/src/redis/redis.service.ts

@@ -1,32 +1,24 @@
-import {
-  Injectable,
-  Optional,
-  type OnModuleDestroy,
-  type OnModuleInit,
-} from "@nestjs/common";
-import Redis from "ioredis";
-import { redisConnectionOptions } from "../config/redis.connection";
+import { RedisClient } from "bun";
+import { redisConnectionUrl } from "../config/redis.connection";
 import { ReadinessService } from "../health/readiness.service";
 
-@Injectable()
-export class RedisService implements OnModuleInit, OnModuleDestroy {
-  readonly client = new Redis(redisConnectionOptions(process.env, {
-    lazyConnect: true,
-    enableReadyCheck: true,
-    enableOfflineQueue: false,
-    maxRetriesPerRequest: 1,
-    connectTimeout: 5_000,
-    commandTimeout: 5_000,
-  }));
-  private readonly subscribers: Redis[] = [];
+export class RedisService {
+  readonly client: RedisClient;
+  private readonly subscribers: RedisClient[] = [];
   private unregisterReadiness?: () => void;
 
-  constructor(@Optional() private readonly readiness?: ReadinessService) {}
+  constructor(private readonly readiness?: ReadinessService) {
+    this.client = new RedisClient(redisConnectionUrl(), {
+      connectionTimeout: 5_000,
+      enableOfflineQueue: false,
+      maxRetries: 1,
+    });
+  }
 
-  async onModuleInit(): Promise<void> {
-    await this.client.connect();
+  async connect(): Promise<void> {
+    if (!this.client.connected) await this.client.connect();
     await this.client.ping();
-    this.unregisterReadiness = this.readiness?.register("redis", async () => {
+    this.unregisterReadiness ??= this.readiness?.register("redis", async () => {
       await this.client.ping();
     });
   }
@@ -36,8 +28,8 @@ export class RedisService implements OnModuleInit, OnModuleDestroy {
   }
 
   async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
-    if (ttlSeconds) await this.client.set(key, value, "EX", ttlSeconds);
-    else await this.client.set(key, value);
+    await this.client.set(key, value);
+    if (ttlSeconds !== undefined) await this.client.expire(key, ttlSeconds);
   }
 
   del(key: string): Promise<number> {
@@ -48,37 +40,23 @@ export class RedisService implements OnModuleInit, OnModuleDestroy {
     return this.client.publish(channel, message);
   }
 
-  async subscribe(
-    channel: string,
-    handler: (message: string) => void,
-  ): Promise<() => Promise<void>> {
-    const sub = new Redis(redisConnectionOptions(process.env, {
-      lazyConnect: true,
-      enableReadyCheck: true,
-      maxRetriesPerRequest: null,
-      connectTimeout: 5_000,
-    }));
-    try {
-      await sub.connect();
-      await sub.subscribe(channel);
-    } catch (error) {
-      await sub.quit().catch(() => undefined);
-      throw error;
-    }
-    this.subscribers.push(sub);
-    sub.on("message", (ch, message) => {
-      if (ch === channel) handler(message);
-    });
+  async subscribe(channel: string, handler: (message: string) => void): Promise<() => Promise<void>> {
+    const subscriber = await this.client.duplicate();
+    await subscriber.connect();
+    const listener = (message: string): void => handler(message);
+    await subscriber.subscribe(channel, listener);
+    this.subscribers.push(subscriber);
     return async () => {
-      const index = this.subscribers.indexOf(sub);
+      const index = this.subscribers.indexOf(subscriber);
       if (index >= 0) this.subscribers.splice(index, 1);
-      await sub.unsubscribe(channel);
-      await sub.quit();
+      await subscriber.unsubscribe(channel, listener);
+      subscriber.close();
     };
   }
 
-  async onModuleDestroy(): Promise<void> {
+  close(): void {
     this.unregisterReadiness?.();
-    await Promise.allSettled([this.client.quit(), ...this.subscribers.map((s) => s.quit())]);
+    for (const subscriber of this.subscribers) subscriber.close();
+    this.client.close();
   }
 }

package/dist/templates/modules/redis/module.manifest.json

@@ -1,31 +1,22 @@
 {
   "name": "redis",
-  "description": "Redis client (ioredis) with get/set/del and publish/subscribe, plus demo cache endpoints.",
+  "description": "Bun native Redis client with get/set/del and publish/subscribe, plus demo cache endpoints.",
   "requires": [],
   "requiredProjectFiles": [
     "apps/api/src/config/redis.connection.ts",
     "apps/api/src/health/readiness.service.ts"
   ],
-  "requiredProjectContents": {
-    "apps/api/src/config/redis.connection.ts": [
-      "connectTimeout?: number;",
-      "commandTimeout?: number;"
-    ]
-  },
   "managedGlobs": [
     "apps/api/src/redis/**",
     "tests/api/redis.api.spec.ts"
   ],
   "targetApp": "api",
-  "dependencies": {
-    "ioredis": "^5.4.1"
-  },
   "env": [
     "# redis uses REDIS_URL or the REDIS_HOST / REDIS_PORT / REDIS_USERNAME / REDIS_PASSWORD / REDIS_DB settings defined above"
   ],
   "inject": [
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:imports", "text": "import { RedisModule } from \"./redis/redis.module\";" },
-    { "file": "apps/api/src/app.module.ts", "marker": "// podokit:end:module-imports", "text": "RedisModule," }
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { redisModule } from \"./redis/redis.module\";" },
+    { "file": "apps/api/src/app.ts", "marker": "// podokit:end:modules", "text": "redisModule," }
   ],
   "instructions": [
     "Start Redis:  docker compose -f infra/docker/docker-compose.yml up -d",

package/dist/templates/modules/sse/files/apps/api/src/events/events.module.ts

@@ -1,19 +1,48 @@
-import { Global, Module } from "@nestjs/common";
-import { EventsController } from "./events.controller";
-import { EVENTS_TRANSPORT, EventsService } from "./events.service";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia, sse, t } from "elysia";
+import {
+  type AppPlugin,
+  type PodokitModule,
+  READINESS,
+  type ServiceKey,
+} from "../core/services";
+import { EventsService } from "./events.service";
 import { createEventsTransport } from "./events.transport";
 
-// Global so any module can inject EventsService to broadcast updates.
-@Global()
-@Module({
-  controllers: [EventsController],
-  providers: [
-    {
-      provide: EVENTS_TRANSPORT,
-      useFactory: () => createEventsTransport(),
-    },
-    EventsService,
-  ],
-  exports: [EventsService],
-})
-export class EventsModule {}
+export const EVENTS = Symbol("events") as ServiceKey<EventsService>;
+
+const eventsPlugin: AppPlugin = ({ services }) => {
+  const events = services.resolve(EVENTS);
+  return new Elysia({ name: "podokit.events" })
+    .get("/events/stream", async function* ({ request }) {
+      for await (const data of events.stream(request.signal)) yield sse({ data });
+    }, {
+      detail: { tags: ["events"], summary: "Stream server-sent events" },
+    })
+    .post("/events", async ({ body, set }) => {
+      try {
+        await events.publishAsync({ type: "message", message: body.message });
+      } catch {
+        throw new AppException(
+          "EVENTS_TRANSPORT_UNAVAILABLE",
+          "Event transport is unavailable",
+          503,
+        );
+      }
+      set.status = 201;
+      return { ok: true as const };
+    }, {
+      body: t.Object({ message: t.String() }),
+      detail: { tags: ["events"], summary: "Publish an event" },
+    });
+};
+
+export const eventsModule: PodokitModule = {
+  name: "sse",
+  configure: (_env, services): void => {
+    const events = new EventsService(createEventsTransport(), services.resolve(READINESS));
+    services.register(EVENTS, events, () => events.close());
+    services.onStart(() => events.connect());
+  },
+  plugin: eventsPlugin,
+};