@iskra-bun/web-kit 0.1.0

package/src/features/request-id.ts

@@ -0,0 +1,45 @@
+import type { Feature, RequestIdConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+
+// Extend Hono's context with requestId
+declare module "hono" {
+    interface ContextVariableMap {
+        requestId: string;
+    }
+}
+
+export class RequestIdFeature implements Feature {
+    name = "request-id";
+
+    private config: Required<RequestIdConfig>;
+
+    constructor(config: RequestIdConfig = {}) {
+        this.config = {
+            headerName: config.headerName || "X-Request-ID",
+            generator: config.generator || this.defaultGenerator,
+        };
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        const app = kernel.getApp();
+
+        app.use("*", async (c: Context, next: Next) => {
+            let requestId = c.req.header(this.config.headerName);
+
+            if (!requestId) {
+                requestId = this.config.generator();
+            }
+
+            c.set("requestId", requestId);
+            await next();
+            c.res.headers.set(this.config.headerName, requestId);
+        });
+
+        console.log("✅ Request ID feature initialized");
+    }
+
+    private defaultGenerator(): string {
+        return crypto.randomUUID();
+    }
+}

package/src/features/session.ts

@@ -0,0 +1,322 @@
+import type { Feature, SessionConfig } from "../types";
+import type { Kernel } from "../kernel";
+import type { Context, Next } from "hono";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+import { createHmac } from "crypto";
+import { sql, eq } from "drizzle-orm";
+import { pgTable, text as pgText, bigint as pgBigint } from "drizzle-orm/pg-core";
+import { mysqlTable, varchar as myVarchar, text as myText, bigint as myBigint } from "drizzle-orm/mysql-core";
+import { sqliteTable, text as sqliteText, integer as sqliteInteger } from "drizzle-orm/sqlite-core";
+
+// ─── Session Store Interface ─────────────────────────────────────────────────
+
+interface SessionStore {
+    get(id: string): Promise<Record<string, any> | null>;
+    set(id: string, data: Record<string, any>, ttl: number): Promise<void>;
+    destroy(id: string): Promise<void>;
+}
+
+// ─── Memory Store ────────────────────────────────────────────────────────────
+
+class MemorySessionStore implements SessionStore {
+    private store = new Map<string, { data: Record<string, any>; expiresAt: number }>();
+    private cleanupInterval: ReturnType<typeof setInterval>;
+
+    constructor() {
+        this.cleanupInterval = setInterval(() => this.cleanup(), 300_000);
+    }
+
+    async get(id: string) {
+        const entry = this.store.get(id);
+        if (!entry) return null;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(id);
+            return null;
+        }
+        return entry.data;
+    }
+
+    async set(id: string, data: Record<string, any>, ttl: number) {
+        this.store.set(id, { data, expiresAt: Date.now() + ttl * 1000 });
+    }
+
+    async destroy(id: string) {
+        this.store.delete(id);
+    }
+
+    private cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.store.entries()) {
+            if (now > entry.expiresAt) this.store.delete(key);
+        }
+    }
+
+    dispose() {
+        clearInterval(this.cleanupInterval);
+    }
+}
+
+// ─── Cache Store ─────────────────────────────────────────────────────────────
+
+class CacheSessionStore implements SessionStore {
+    constructor(private cache: any) { }
+
+    async get(id: string) {
+        const data = await this.cache.get(`session:${id}`);
+        return data || null;
+    }
+
+    async set(id: string, data: Record<string, any>, ttl: number) {
+        await this.cache.set(`session:${id}`, data, ttl);
+    }
+
+    async destroy(id: string) {
+        await this.cache.delete(`session:${id}`);
+    }
+}
+
+// ─── DB Store ────────────────────────────────────────────────────────────────
+
+type SessionDialect = "postgres" | "mysql" | "sqlite";
+
+// One table definition per dialect (column types differ). The Drizzle query
+// builder parameterizes every value, so user data in a session can never break
+// out of a SQL string.
+const sessionTables = {
+    postgres: pgTable("sessions", {
+        id: pgText("id").primaryKey(),
+        data: pgText("data").notNull(),
+        expiresAt: pgBigint("expires_at", { mode: "number" }).notNull(),
+    }),
+    mysql: mysqlTable("sessions", {
+        id: myVarchar("id", { length: 255 }).primaryKey(),
+        data: myText("data").notNull(),
+        expiresAt: myBigint("expires_at", { mode: "number" }).notNull(),
+    }),
+    sqlite: sqliteTable("sessions", {
+        id: sqliteText("id").primaryKey(),
+        data: sqliteText("data").notNull(),
+        expiresAt: sqliteInteger("expires_at").notNull(),
+    }),
+} as const;
+
+const createTableDdl: Record<SessionDialect, string> = {
+    postgres: "CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, data TEXT NOT NULL, expires_at BIGINT NOT NULL)",
+    mysql: "CREATE TABLE IF NOT EXISTS sessions (id VARCHAR(255) PRIMARY KEY, data TEXT NOT NULL, expires_at BIGINT NOT NULL)",
+    sqlite: "CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, data TEXT NOT NULL, expires_at INTEGER NOT NULL)",
+};
+
+class DbSessionStore implements SessionStore {
+    private initialized = false;
+    private dialect: SessionDialect;
+    private table: (typeof sessionTables)[SessionDialect];
+
+    constructor(private db: any, dialect: SessionDialect = "sqlite") {
+        this.dialect = sessionTables[dialect] ? dialect : "sqlite";
+        this.table = sessionTables[this.dialect];
+    }
+
+    private async ensureTable() {
+        if (this.initialized) return;
+        try {
+            const ddl = sql.raw(createTableDdl[this.dialect]);
+            // sqlite drivers expose run(); postgres/mysql expose execute().
+            if (this.dialect === "sqlite") {
+                await this.db.run(ddl);
+            } else {
+                await this.db.execute(ddl);
+            }
+        } catch (err) {
+            console.error("[session] Failed to ensure sessions table:", err);
+        }
+        this.initialized = true;
+    }
+
+    async get(id: string) {
+        await this.ensureTable();
+        try {
+            const rows = await this.db
+                .select()
+                .from(this.table)
+                .where(eq(this.table.id, id))
+                .limit(1);
+
+            const row = rows?.[0];
+            if (!row) return null;
+
+            if (Date.now() > Number(row.expiresAt)) {
+                await this.destroy(id);
+                return null;
+            }
+            return JSON.parse(row.data);
+        } catch (err) {
+            console.error("[session] Failed to read session:", err);
+            return null;
+        }
+    }
+
+    async set(id: string, data: Record<string, any>, ttl: number) {
+        await this.ensureTable();
+        const row = { id, data: JSON.stringify(data), expiresAt: Date.now() + ttl * 1000 };
+
+        try {
+            // Portable upsert: delete-then-insert works identically across all
+            // three dialects without per-dialect ON CONFLICT / ON DUPLICATE syntax.
+            await this.db.delete(this.table).where(eq(this.table.id, id));
+            await this.db.insert(this.table).values(row);
+        } catch (err) {
+            console.error("[session] Failed to write session:", err);
+        }
+    }
+
+    async destroy(id: string) {
+        try {
+            await this.db.delete(this.table).where(eq(this.table.id, id));
+        } catch (err) {
+            console.error("[session] Failed to destroy session:", err);
+        }
+    }
+}
+
+// ─── Cookie Signing ──────────────────────────────────────────────────────────
+
+function signValue(value: string, secret: string): string {
+    const signature = createHmac("sha256", secret).update(value).digest("base64url");
+    return `${value}.${signature}`;
+}
+
+function verifySignedValue(signed: string, secret: string): string | null {
+    const lastDot = signed.lastIndexOf(".");
+    if (lastDot === -1) return null;
+
+    const value = signed.substring(0, lastDot);
+    const signature = signed.substring(lastDot + 1);
+    const expected = createHmac("sha256", secret).update(value).digest("base64url");
+
+    if (signature !== expected) return null;
+    return value;
+}
+
+// ─── Session Feature ─────────────────────────────────────────────────────────
+
+declare module "hono" {
+    interface ContextVariableMap {
+        session: Record<string, any>;
+        sessionId: string;
+        destroySession: () => Promise<void>;
+    }
+}
+
+export class SessionFeature implements Feature {
+    name = "session";
+    dependencies?: string[];
+
+    private store?: SessionStore;
+    private ttl: number;
+    private cookieName: string;
+
+    constructor(private config: SessionConfig) {
+        this.ttl = config.ttl || 86400; // 24 hours default
+        this.cookieName = config.cookieName || "sid";
+
+        // Set dependencies based on store type
+        if (config.store === "cache") {
+            this.dependencies = ["cache"];
+        } else if (config.store === "db") {
+            this.dependencies = ["db"];
+        }
+    }
+
+    async initialize(kernel: Kernel): Promise<void> {
+        console.log(`⚙️ Initializing Session: store=${this.config.store}`);
+
+        switch (this.config.store) {
+            case "memory":
+                this.store = new MemorySessionStore();
+                break;
+            case "cache": {
+                const cacheFeature = kernel.getFeature("cache") as any;
+                if (!cacheFeature?.client) {
+                    console.warn("⚠️ Cache feature not available, falling back to memory session store");
+                    this.store = new MemorySessionStore();
+                } else {
+                    this.store = new CacheSessionStore(cacheFeature.client);
+                }
+                break;
+            }
+            case "db": {
+                const dbFeature = kernel.getFeature("db") as any;
+                if (!dbFeature?.db) {
+                    console.warn("⚠️ DB feature not available, falling back to memory session store");
+                    this.store = new MemorySessionStore();
+                } else {
+                    this.store = new DbSessionStore(dbFeature.db, dbFeature.adapter);
+                }
+                break;
+            }
+        }
+
+        const app = kernel.getApp();
+        app.use("*", async (c: Context, next: Next) => {
+            const signedCookie = getCookie(c, this.cookieName);
+            let sessionId: string | null = null;
+            let session: Record<string, any> = {};
+
+            if (signedCookie) {
+                sessionId = verifySignedValue(signedCookie, this.config.secret);
+                if (sessionId) {
+                    const data = await this.store!.get(sessionId);
+                    if (data) {
+                        session = data;
+                    } else {
+                        sessionId = null; // Session expired or not found
+                    }
+                }
+            }
+
+            if (!sessionId) {
+                sessionId = crypto.randomUUID();
+            }
+
+            let destroyed = false;
+
+            c.set("session", session);
+            c.set("sessionId", sessionId);
+            c.set("destroySession", async () => {
+                destroyed = true;
+                await this.store!.destroy(sessionId!);
+                deleteCookie(c, this.cookieName);
+            });
+
+            await next();
+
+            // A destroyed session must not be re-persisted (otherwise the save
+            // block below would immediately recreate it and override deleteCookie).
+            if (destroyed) return;
+
+            // Save session after response
+            const currentSession = c.get("session");
+            if (currentSession && Object.keys(currentSession).length > 0) {
+                await this.store!.set(sessionId, currentSession, this.ttl);
+                const signed = signValue(sessionId, this.config.secret);
+                const opts = this.config.cookieOptions || {};
+                setCookie(c, this.cookieName, signed, {
+                    httpOnly: true,
+                    sameSite: opts.sameSite || "Lax",
+                    secure: opts.secure ?? false,
+                    domain: opts.domain,
+                    path: opts.path || "/",
+                    maxAge: this.ttl,
+                });
+            }
+        });
+
+        console.log("✅ Session initialized");
+    }
+
+    async shutdown(): Promise<void> {
+        if (this.store instanceof MemorySessionStore) {
+            (this.store as any).dispose?.();
+        }
+    }
+}

package/src/features/storage/adapters/local.ts

@@ -0,0 +1,133 @@
+import { BaseStorageAdapter, type PutOptions, type StorageConfig, type StorageFile } from "../base";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+export class LocalStorageAdapter extends BaseStorageAdapter {
+    private basePath: string;
+
+    constructor(config: StorageConfig) {
+        super();
+        this.basePath = config.basePath || "./storage";
+    }
+
+    async connect(): Promise<void> {
+        await fs.mkdir(this.basePath, { recursive: true });
+        this.connected = true;
+        console.log(`✅ Local storage connected at: ${this.basePath}`);
+    }
+
+    async disconnect(): Promise<void> {
+        this.connected = false;
+    }
+
+    async put(filePath: string, data: Uint8Array | Buffer, options?: PutOptions): Promise<StorageFile> {
+        this.ensureConnected();
+
+        const sanitizedPath = this.sanitizePath(filePath);
+        const fullPath = path.join(this.basePath, sanitizedPath);
+
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, data);
+
+        const stat = await fs.stat(fullPath);
+
+        return {
+            name: path.basename(sanitizedPath),
+            path: sanitizedPath,
+            size: stat.size,
+            mimeType: options?.contentType || this.getMimeType(sanitizedPath),
+            lastModified: stat.mtime,
+            url: await this.url(sanitizedPath),
+        };
+    }
+
+    async get(filePath: string): Promise<Uint8Array | null> {
+        this.ensureConnected();
+        const sanitizedPath = this.sanitizePath(filePath);
+        const fullPath = path.join(this.basePath, sanitizedPath);
+
+        try {
+            return await fs.readFile(fullPath);
+        } catch (error: any) {
+            if (error.code === 'ENOENT') return null;
+            throw error;
+        }
+    }
+
+    async delete(filePath: string): Promise<void> {
+        this.ensureConnected();
+        const sanitizedPath = this.sanitizePath(filePath);
+        const fullPath = path.join(this.basePath, sanitizedPath);
+
+        try {
+            await fs.unlink(fullPath);
+        } catch (error: any) {
+            if (error.code !== 'ENOENT') throw error;
+        }
+    }
+
+    async exists(filePath: string): Promise<boolean> {
+        this.ensureConnected();
+        const sanitizedPath = this.sanitizePath(filePath);
+        const fullPath = path.join(this.basePath, sanitizedPath);
+        try {
+            await fs.access(fullPath);
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    async isDirectory(filePath: string): Promise<boolean> {
+        this.ensureConnected();
+        const sanitizedPath = this.sanitizePath(filePath);
+        const fullPath = path.join(this.basePath, sanitizedPath);
+        try {
+            const stat = await fs.stat(fullPath);
+            return stat.isDirectory();
+        } catch {
+            return false;
+        }
+    }
+
+    async list(prefix?: string): Promise<StorageFile[]> {
+        this.ensureConnected();
+        const searchPath = prefix ? path.join(this.basePath, this.sanitizePath(prefix)) : this.basePath;
+        const files: StorageFile[] = [];
+
+        // Simple recursive walk
+        const walk = async (dir: string) => {
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    if (entry.isDirectory()) {
+                        await walk(fullPath);
+                    } else {
+                        const relativePath = path.relative(this.basePath, fullPath);
+                        const stat = await fs.stat(fullPath);
+                        files.push({
+                            name: entry.name,
+                            path: this.sanitizePath(relativePath),
+                            size: stat.size,
+                            mimeType: this.getMimeType(entry.name),
+                            lastModified: stat.mtime,
+                            url: await this.url(this.sanitizePath(relativePath))
+                        });
+                    }
+                }
+            } catch (e: any) {
+                if (e.code !== 'ENOENT') throw e;
+            }
+        };
+
+        await walk(searchPath);
+        return files;
+    }
+
+    async url(filePath: string, _expiresIn?: number): Promise<string> {
+        const sanitizedPath = this.sanitizePath(filePath);
+        return `/storage/${sanitizedPath}`;
+    }
+}

package/src/features/storage/adapters/s3.ts

@@ -0,0 +1,193 @@
+import { BaseStorageAdapter } from "../base";
+import type { StorageConfig, StorageFile, PutOptions } from "../base";
+import {
+    S3Client,
+    PutObjectCommand,
+    GetObjectCommand,
+    DeleteObjectCommand,
+    HeadObjectCommand,
+    HeadBucketCommand,
+    ListObjectsV2Command,
+    CopyObjectCommand,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+export class S3StorageAdapter extends BaseStorageAdapter {
+    private client: S3Client;
+    private bucket: string;
+
+    constructor(private config: StorageConfig) {
+        super();
+        const conn = config.connection || {};
+
+        this.bucket = conn.bucket || "iskra-storage";
+
+        this.client = new S3Client({
+            endpoint: conn.endpoint,
+            region: conn.region || "us-east-1",
+            credentials: conn.accessKey && conn.secretKey
+                ? { accessKeyId: conn.accessKey, secretAccessKey: conn.secretKey }
+                : undefined,
+            forcePathStyle: !!conn.endpoint, // true for MinIO
+        });
+    }
+
+    async connect(): Promise<void> {
+        try {
+            await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+            this.connected = true;
+        } catch (err: any) {
+            throw new Error(`Failed to connect to S3 bucket "${this.bucket}": ${err.message}`);
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        this.client.destroy();
+        this.connected = false;
+    }
+
+    async put(path: string, data: Uint8Array | Buffer | ReadableStream, options?: PutOptions): Promise<StorageFile> {
+        this.ensureConnected();
+        const key = this.sanitizePath(path);
+
+        let body: Uint8Array | Buffer;
+        if (data instanceof ReadableStream) {
+            const response = new Response(data);
+            body = new Uint8Array(await response.arrayBuffer());
+        } else {
+            body = data;
+        }
+
+        await this.client.send(new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            Body: body,
+            ContentType: options?.contentType || this.getMimeType(key),
+            Metadata: options?.metadata,
+        }));
+
+        return {
+            name: key.split("/").pop() || key,
+            path: key,
+            size: body.length,
+            mimeType: options?.contentType || this.getMimeType(key),
+            lastModified: new Date(),
+        };
+    }
+
+    async get(path: string): Promise<Uint8Array | null> {
+        this.ensureConnected();
+        const key = this.sanitizePath(path);
+
+        try {
+            const response = await this.client.send(new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+            }));
+
+            if (!response.Body) return null;
+            return new Uint8Array(await response.Body.transformToByteArray());
+        } catch (err: any) {
+            if (err.name === "NoSuchKey" || err.$metadata?.httpStatusCode === 404) {
+                return null;
+            }
+            throw err;
+        }
+    }
+
+    async delete(path: string): Promise<void> {
+        this.ensureConnected();
+        const key = this.sanitizePath(path);
+
+        await this.client.send(new DeleteObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+        }));
+    }
+
+    async exists(path: string): Promise<boolean> {
+        this.ensureConnected();
+        const key = this.sanitizePath(path);
+
+        try {
+            await this.client.send(new HeadObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+            }));
+            return true;
+        } catch (err: any) {
+            if (err.name === "NotFound" || err.$metadata?.httpStatusCode === 404) {
+                return false;
+            }
+            throw err;
+        }
+    }
+
+    async list(prefix?: string): Promise<StorageFile[]> {
+        this.ensureConnected();
+        const files: StorageFile[] = [];
+        let continuationToken: string | undefined;
+
+        do {
+            const response = await this.client.send(new ListObjectsV2Command({
+                Bucket: this.bucket,
+                Prefix: prefix ? this.sanitizePath(prefix) : undefined,
+                ContinuationToken: continuationToken,
+            }));
+
+            if (response.Contents) {
+                for (const obj of response.Contents) {
+                    if (!obj.Key) continue;
+                    files.push({
+                        name: obj.Key.split("/").pop() || obj.Key,
+                        path: obj.Key,
+                        size: obj.Size || 0,
+                        mimeType: this.getMimeType(obj.Key),
+                        lastModified: obj.LastModified,
+                    });
+                }
+            }
+
+            continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+        } while (continuationToken);
+
+        return files;
+    }
+
+    async url(path: string, expiresIn: number = 3600): Promise<string> {
+        this.ensureConnected();
+        const key = this.sanitizePath(path);
+
+        const command = new GetObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+        });
+
+        return await getSignedUrl(this.client, command, { expiresIn });
+    }
+
+    async copy(from: string, to: string): Promise<void> {
+        this.ensureConnected();
+        const sourceKey = this.sanitizePath(from);
+        const destKey = this.sanitizePath(to);
+
+        await this.client.send(new CopyObjectCommand({
+            Bucket: this.bucket,
+            CopySource: `${this.bucket}/${sourceKey}`,
+            Key: destKey,
+        }));
+    }
+
+    async isDirectory(path: string): Promise<boolean> {
+        this.ensureConnected();
+        const prefix = this.sanitizePath(path).replace(/\/?$/, "/");
+
+        const response = await this.client.send(new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            MaxKeys: 1,
+        }));
+
+        return (response.Contents?.length || 0) > 0;
+    }
+}