@strav/http 0.1.0

package/src/session/session.ts

@@ -0,0 +1,308 @@
+import type Context from '../http/context.ts'
+import { clearCookie } from '../http/cookie.ts'
+import { randomHex } from '@stravigor/kernel/helpers/crypto'
+import { extractUserId } from '@stravigor/database/helpers/identity'
+import SessionManager from './session_manager.ts'
+
+const FLASH_KEY = '_flash'
+const FLASH_OLD_KEY = '_flash_old'
+
+/**
+ * Unified server-side session backed by a database row and an HTTP-only cookie.
+ *
+ * Serves both anonymous visitors and authenticated users. Stores arbitrary
+ * key-value data in a JSONB column and supports flash data (available only
+ * on the next request).
+ *
+ * @example
+ * // Read / write data (anonymous or authenticated)
+ * const session = ctx.get<Session>('session')
+ * session.set('cart', [item])
+ * session.flash('success', 'Item added!')
+ *
+ * // Login
+ * session.authenticate(user)
+ * await session.regenerate()
+ *
+ * // Logout
+ * return Session.destroy(ctx, ctx.redirect('/login'))
+ */
+export default class Session {
+  private _id: string
+  private _userId: string | null
+  private _csrfToken: string
+  private _data: Record<string, unknown>
+  private _dirty = false
+
+  constructor(
+    id: string,
+    userId: string | null,
+    csrfToken: string,
+    data: Record<string, unknown>,
+    readonly ipAddress: string | null,
+    readonly userAgent: string | null,
+    readonly lastActivity: Date,
+    readonly createdAt: Date
+  ) {
+    this._id = id
+    this._userId = userId
+    this._csrfToken = csrfToken
+    this._data = data
+  }
+
+  // ---------------------------------------------------------------------------
+  // Getters
+  // ---------------------------------------------------------------------------
+
+  get id(): string {
+    return this._id
+  }
+
+  get userId(): string | null {
+    return this._userId
+  }
+
+  get csrfToken(): string {
+    return this._csrfToken
+  }
+
+  get isAuthenticated(): boolean {
+    return this._userId !== null
+  }
+
+  get isDirty(): boolean {
+    return this._dirty
+  }
+
+  // ---------------------------------------------------------------------------
+  // Data bag
+  // ---------------------------------------------------------------------------
+
+  /** Get a value from the session data. */
+  get<T = unknown>(key: string, defaultValue?: T): T {
+    return (this._data[key] as T) ?? (defaultValue as T)
+  }
+
+  /** Set a persistent session value. */
+  set(key: string, value: unknown): void {
+    this._data[key] = value
+    this._dirty = true
+  }
+
+  /** Check whether a key exists in the session data. */
+  has(key: string): boolean {
+    return key in this._data && !key.startsWith('_flash')
+  }
+
+  /** Remove a key from the session data. */
+  forget(key: string): void {
+    delete this._data[key]
+    this._dirty = true
+  }
+
+  /** Remove all session data (keeps the session row alive). */
+  flush(): void {
+    this._data = {}
+    this._dirty = true
+  }
+
+  /** Return all user-facing session data (excludes flash internals). */
+  all(): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(this._data)) {
+      if (!key.startsWith('_flash')) {
+        result[key] = value
+      }
+    }
+    return result
+  }
+
+  // ---------------------------------------------------------------------------
+  // Flash data
+  // ---------------------------------------------------------------------------
+
+  /** Set flash data that will be available only on the next request. */
+  flash(key: string, value: unknown): void {
+    const bag = (this._data[FLASH_KEY] ?? {}) as Record<string, unknown>
+    bag[key] = value
+    this._data[FLASH_KEY] = bag
+    this._dirty = true
+  }
+
+  /** Get flash data set by the previous request. */
+  getFlash<T = unknown>(key: string): T | undefined {
+    const old = this._data[FLASH_OLD_KEY] as Record<string, unknown> | undefined
+    return old?.[key] as T | undefined
+  }
+
+  /** Check if there is flash data for the given key (from previous request). */
+  hasFlash(key: string): boolean {
+    const old = this._data[FLASH_OLD_KEY] as Record<string, unknown> | undefined
+    return old !== undefined && key in old
+  }
+
+  /**
+   * Rotate flash data for the next request cycle. Called once per request
+   * by the session middleware before the handler runs.
+   *
+   * Moves `_flash` → `_flash_old` (readable this request), then clears `_flash`.
+   * Only marks dirty if there was actually flash data to rotate.
+   */
+  ageFlash(): void {
+    const current = this._data[FLASH_KEY]
+    const old = this._data[FLASH_OLD_KEY]
+
+    if (current !== undefined || old !== undefined) {
+      this._data[FLASH_OLD_KEY] = current ?? {}
+      delete this._data[FLASH_KEY]
+      this._dirty = true
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Authentication
+  // ---------------------------------------------------------------------------
+
+  /** Associate this session with a user (login). */
+  authenticate(user: unknown): void {
+    this._userId = extractUserId(user)
+    this._dirty = true
+  }
+
+  /** Disassociate the user from this session. */
+  clearUser(): void {
+    this._userId = null
+    this._dirty = true
+  }
+
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /** Whether this session has exceeded its configured lifetime. */
+  isExpired(): boolean {
+    const lifetimeMs = SessionManager.config.lifetime * 60_000
+    return Date.now() - this.lastActivity.getTime() > lifetimeMs
+  }
+
+  /** Update the last_activity timestamp to keep the session alive. */
+  async touch(): Promise<void> {
+    await SessionManager.db.sql`
+      UPDATE "_strav_sessions"
+      SET "last_activity" = NOW()
+      WHERE "id" = ${this._id}
+    `
+  }
+
+  /**
+   * Regenerate the session ID and CSRF token. Use after login to
+   * prevent session fixation attacks.
+   */
+  async regenerate(): Promise<void> {
+    const oldId = this._id
+    this._id = crypto.randomUUID()
+    this._csrfToken = randomHex(32)
+    this._dirty = true
+
+    await this.save()
+    await SessionManager.db.sql`
+      DELETE FROM "_strav_sessions" WHERE "id" = ${oldId}
+    `
+  }
+
+  /**
+   * Persist session data to the database. Uses an upsert so both new
+   * and existing sessions go through the same code path.
+   * No-op if the session has not been modified.
+   */
+  async save(): Promise<void> {
+    if (!this._dirty) return
+
+    const dataToSave = { ...this._data }
+    delete dataToSave[FLASH_OLD_KEY]
+
+    await SessionManager.db.sql`
+      INSERT INTO "_strav_sessions"
+        ("id", "user_id", "csrf_token", "data", "ip_address", "user_agent", "last_activity")
+      VALUES
+        (${this._id}, ${this._userId}, ${this._csrfToken},
+         ${JSON.stringify(dataToSave)}::jsonb, ${this.ipAddress}, ${this.userAgent}, NOW())
+      ON CONFLICT ("id") DO UPDATE SET
+        "user_id"       = EXCLUDED."user_id",
+        "csrf_token"    = EXCLUDED."csrf_token",
+        "data"          = EXCLUDED."data",
+        "last_activity" = NOW()
+    `
+    this._dirty = false
+  }
+
+  // ---------------------------------------------------------------------------
+  // Static API
+  // ---------------------------------------------------------------------------
+
+  /** Create a new anonymous session (not yet persisted — call save() or let the middleware handle it). */
+  static create(ctx: Context): Session {
+    const id = crypto.randomUUID()
+    const csrfToken = randomHex(32)
+    const ipAddress = ctx.header('x-forwarded-for') ?? null
+    const userAgent = ctx.header('user-agent') ?? null
+    const now = new Date()
+
+    const session = new Session(id, null, csrfToken, {}, ipAddress, userAgent, now, now)
+    session._dirty = true
+    return session
+  }
+
+  /** Look up a session by ID. Returns null if not found. */
+  static async find(id: string): Promise<Session | null> {
+    const rows = await SessionManager.db.sql`
+      SELECT * FROM "_strav_sessions" WHERE "id" = ${id} LIMIT 1
+    `
+    if (rows.length === 0) return null
+    return Session.hydrate(rows[0] as Record<string, unknown>)
+  }
+
+  /** Read the session cookie from the request and look up the session. */
+  static async fromRequest(ctx: Context): Promise<Session | null> {
+    const sessionId = ctx.cookie(SessionManager.config.cookie)
+    if (!sessionId) return null
+    return Session.find(sessionId)
+  }
+
+  /** Delete the session from the database and clear the cookie on the response. */
+  static async destroy(ctx: Context, response: Response): Promise<Response> {
+    const cfg = SessionManager.config
+    const sessionId = ctx.cookie(cfg.cookie)
+
+    if (sessionId) {
+      await SessionManager.db.sql`
+        DELETE FROM "_strav_sessions" WHERE "id" = ${sessionId}
+      `
+    }
+
+    return clearCookie(response, cfg.cookie, { path: '/' })
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private static hydrate(row: Record<string, unknown>): Session {
+    const rawData = row.data
+    const data: Record<string, unknown> =
+      typeof rawData === 'string'
+        ? JSON.parse(rawData)
+        : ((rawData as Record<string, unknown>) ?? {})
+
+    return new Session(
+      row.id as string,
+      (row.user_id as string) ?? null,
+      row.csrf_token as string,
+      data,
+      (row.ip_address as string) ?? null,
+      (row.user_agent as string) ?? null,
+      row.last_activity as Date,
+      row.created_at as Date
+    )
+  }
+}

package/src/session/session_manager.ts

@@ -0,0 +1,83 @@
+import { inject } from '@stravigor/kernel/core/inject'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+import Configuration from '@stravigor/kernel/config/configuration'
+import Database from '@stravigor/database/database/database'
+
+export interface SessionConfig {
+  cookie: string
+  lifetime: number
+  httpOnly: boolean
+  secure: boolean
+  sameSite: 'strict' | 'lax' | 'none'
+}
+
+/**
+ * Central session configuration hub.
+ *
+ * Resolved once via the DI container — stores the database reference
+ * and parsed config for Session and the session middleware.
+ *
+ * @example
+ * app.singleton(SessionManager)
+ * app.resolve(SessionManager)
+ * await SessionManager.ensureTable()
+ */
+@inject
+export default class SessionManager {
+  private static _db: Database
+  private static _config: SessionConfig
+
+  constructor(db: Database, config: Configuration) {
+    SessionManager._db = db
+    SessionManager._config = {
+      cookie: 'strav_session',
+      lifetime: 120,
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      ...(config.get('session', {}) as object),
+    }
+  }
+
+  static get db(): Database {
+    if (!SessionManager._db) {
+      throw new ConfigurationError(
+        'SessionManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SessionManager._db
+  }
+
+  static get config(): SessionConfig {
+    return SessionManager._config
+  }
+
+  /** Create the sessions table if it does not exist. */
+  static async ensureTable(): Promise<void> {
+    await SessionManager.db.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_sessions" (
+        "id"            UUID PRIMARY KEY,
+        "user_id"       VARCHAR(255),
+        "csrf_token"    VARCHAR(64) NOT NULL,
+        "data"          JSONB NOT NULL DEFAULT '{}',
+        "ip_address"    VARCHAR(45),
+        "user_agent"    TEXT,
+        "last_activity" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "created_at"    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+  }
+
+  /** Delete all expired sessions. Call periodically for housekeeping. */
+  static async gc(): Promise<number> {
+    const lifetimeMs = SessionManager.config.lifetime * 60_000
+    const cutoff = new Date(Date.now() - lifetimeMs)
+
+    const rows = await SessionManager.db.sql`
+      DELETE FROM "_strav_sessions"
+      WHERE "last_activity" < ${cutoff}
+      RETURNING "id"
+    `
+    return rows.length
+  }
+}

package/src/validation/index.ts

@@ -0,0 +1,18 @@
+export { validate } from './validate.ts'
+export {
+  required,
+  string,
+  integer,
+  number,
+  boolean,
+  min,
+  max,
+  email,
+  url,
+  regex,
+  enumOf,
+  oneOf,
+  array,
+} from './rules.ts'
+export type { Rule } from './rules.ts'
+export type { RuleSet, ValidationResult } from './validate.ts'

package/src/validation/rules.ts

@@ -0,0 +1,170 @@
+import { t } from '@stravigor/kernel/i18n/helpers'
+
+export interface Rule {
+  name: string
+  validate(value: unknown): string | null
+}
+
+export function required(): Rule {
+  return {
+    name: 'required',
+    validate(value) {
+      if (value === undefined || value === null || value === '') {
+        return t('validation.required')
+      }
+      return null
+    },
+  }
+}
+
+export function string(): Rule {
+  return {
+    name: 'string',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'string') return t('validation.string')
+      return null
+    },
+  }
+}
+
+export function integer(): Rule {
+  return {
+    name: 'integer',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'number' || !Number.isInteger(value)) return t('validation.integer')
+      return null
+    },
+  }
+}
+
+export function number(): Rule {
+  return {
+    name: 'number',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'number' || isNaN(value)) return t('validation.number')
+      return null
+    },
+  }
+}
+
+export function boolean(): Rule {
+  return {
+    name: 'boolean',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'boolean') return t('validation.boolean')
+      return null
+    },
+  }
+}
+
+export function min(n: number): Rule {
+  return {
+    name: 'min',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value === 'number') {
+        if (value < n) return t('validation.min.number', { min: n })
+      } else if (typeof value === 'string') {
+        if (value.length < n) return t('validation.min.string', { min: n })
+      }
+      return null
+    },
+  }
+}
+
+export function max(n: number): Rule {
+  return {
+    name: 'max',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value === 'number') {
+        if (value > n) return t('validation.max.number', { max: n })
+      } else if (typeof value === 'string') {
+        if (value.length > n) return t('validation.max.string', { max: n })
+      }
+      return null
+    },
+  }
+}
+
+export function email(): Rule {
+  return {
+    name: 'email',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'string') return t('validation.string')
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return t('validation.email')
+      return null
+    },
+  }
+}
+
+export function url(): Rule {
+  return {
+    name: 'url',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'string') return t('validation.string')
+      try {
+        new URL(value)
+        return null
+      } catch {
+        return t('validation.url')
+      }
+    },
+  }
+}
+
+export function regex(pattern: RegExp): Rule {
+  return {
+    name: 'regex',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (typeof value !== 'string') return t('validation.string')
+      if (!pattern.test(value)) return t('validation.regex')
+      return null
+    },
+  }
+}
+
+export function enumOf(enumObj: Record<string, string | number>): Rule {
+  const values = Object.values(enumObj)
+  return {
+    name: 'enumOf',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (!values.includes(value as any)) {
+        return t('validation.enum', { values: values.join(', ') })
+      }
+      return null
+    },
+  }
+}
+
+export function oneOf(values: readonly (string | number | boolean)[]): Rule {
+  return {
+    name: 'oneOf',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (!values.includes(value as any)) {
+        return t('validation.enum', { values: values.join(', ') })
+      }
+      return null
+    },
+  }
+}
+
+export function array(): Rule {
+  return {
+    name: 'array',
+    validate(value) {
+      if (value === undefined || value === null) return null
+      if (!Array.isArray(value)) return t('validation.array')
+      return null
+    },
+  }
+}

package/src/validation/validate.ts

@@ -0,0 +1,41 @@
+import type { Rule } from './rules.ts'
+
+export type RuleSet = Record<string, Rule[]>
+
+export interface ValidationResult<T = Record<string, unknown>> {
+  data: T
+  errors: Record<string, string[]> | null
+}
+
+export function validate<T = Record<string, unknown>>(
+  input: unknown,
+  rules: RuleSet
+): ValidationResult<T> {
+  const record = (typeof input === 'object' && input !== null ? input : {}) as Record<
+    string,
+    unknown
+  >
+  const data: Record<string, unknown> = {}
+  const errors: Record<string, string[]> = {}
+  let hasErrors = false
+
+  for (const [field, fieldRules] of Object.entries(rules)) {
+    const value = record[field]
+    if (value !== undefined) data[field] = value
+
+    for (const rule of fieldRules) {
+      const error = rule.validate(value)
+      if (error) {
+        if (!errors[field]) errors[field] = []
+        errors[field]!.push(error)
+        hasErrors = true
+        break // stop at first error per field
+      }
+    }
+  }
+
+  return {
+    data: data as T,
+    errors: hasErrors ? errors : null,
+  }
+}

package/src/view/cache.ts

@@ -0,0 +1,47 @@
+export interface RenderResult {
+  output: string
+  blocks: Record<string, string>
+}
+
+export type RenderFunction = (
+  data: Record<string, unknown>,
+  includeFn: IncludeFn
+) => Promise<RenderResult>
+
+export type IncludeFn = (name: string, data: Record<string, unknown>) => Promise<string>
+
+export interface CacheEntry {
+  fn: RenderFunction
+  layout?: string
+  mtime: number
+  filePath: string
+}
+
+export default class TemplateCache {
+  private entries = new Map<string, CacheEntry>()
+
+  get(name: string): CacheEntry | undefined {
+    return this.entries.get(name)
+  }
+
+  set(name: string, entry: CacheEntry): void {
+    this.entries.set(name, entry)
+  }
+
+  async isStale(name: string): Promise<boolean> {
+    const entry = this.entries.get(name)
+    if (!entry) return true
+    const file = Bun.file(entry.filePath)
+    const exists = await file.exists()
+    if (!exists) return true
+    return file.lastModified > entry.mtime
+  }
+
+  delete(name: string): void {
+    this.entries.delete(name)
+  }
+
+  clear(): void {
+    this.entries.clear()
+  }
+}