@rip-lang/api 0.5.1 → 0.7.0

package/README.md

@@ -8,8 +8,8 @@
 
 `@rip-lang/api` is a complete API framework written entirely in Rip. It provides Hono-compatible routing, middleware composition, and powerful validation — all with no external dependencies.
 
-- **`api.rip`** (~565 lines) — Core framework: routing, validation, `read()`, `session`, server
-- **`middleware.rip`** (~395 lines) — Optional middleware: cors, logger, compress, cookies, sessions, etc.
+- **`api.rip`** (~595 lines) — Core framework: routing, validation, `read()`, `session`, server
+- **`middleware.rip`** (~390 lines) — Optional middleware: cors, logger, compress, sessions, etc.
 
 **Core Philosophy**: API development should be intuitive, safe, and beautiful. Every function eliminates boilerplate, prevents common errors, and makes your intent crystal clear.
 
@@ -19,7 +19,7 @@
 - **Sinatra-Style Handlers** — Return data directly, no ceremony
 - **Magic `@` Access** — Use `@req`, `@json()`, `@session`, `@silent` like Sinatra
 - **Powerful Validation** — 37 built-in validators with elegant `read()` function
-- **Before/After Filters** — Sinatra-style request lifecycle hooks
+- **Lifecycle Filters** — `raw` → `before` → handler → `after` hooks
 - **AsyncLocalStorage** — Safe, race-condition-free request context
 - **Hono-Compatible API** — Easy migration from existing Hono apps
 
@@ -27,15 +27,32 @@
 
 ## Try it Now
 
-Run the included example to see everything working:
+Create `app.rip`:
 
-```bash
-# Clone the repo (if you haven't)
-git clone https://github.com/shreeve/rip-lang.git
-cd rip-lang
+```coffee
+import { get, post, read, session, start, use, before } from '@rip-lang/api'
+import { sessions } from '@rip-lang/api/middleware'
+
+use sessions()  # Add secret: 'your-secret' for production
+
+before ->
+  session.views ?= 0
+  session.views += 1
+
+get '/', -> 'Hello, World!'
+get '/json', -> { message: 'It works!', timestamp: Date.now() }
+get '/users/:id', -> { user: { id: read('id', 'id!') } }
+get '/session', -> { views: session.views, loggedIn: session.userId? }
+get '/login', -> session.userId = 123; { loggedIn: true, userId: 123 }
+get '/logout', -> delete session.userId; { loggedOut: true }
 
-# Run the example server
-bun packages/api/test/example.rip
+start port: 3000
+```
+
+Run it:
+
+```bash
+rip app.rip
 ```
 
 **Test the endpoints:**
@@ -317,7 +334,7 @@ Import from `@rip-lang/api/middleware`:
 
 ```coffee
 import { use } from '@rip-lang/api'
-import { cors, logger, compress, cookies, sessions, secureHeaders, timeout, bodyLimit } from '@rip-lang/api/middleware'
+import { cors, logger, compress, sessions, secureHeaders, timeout, bodyLimit } from '@rip-lang/api/middleware'
 
 # Logging
 use logger()
@@ -335,10 +352,6 @@ use cors credentials: true, maxAge: 86400
 use compress()
 use compress threshold: 1024             # Min bytes to compress
 
-# Cookies
-use cookies()
-use cookies secret: 'my-secret', secure: true, httpOnly: true
-
 # Security headers
 use secureHeaders()
 use secureHeaders hsts: true, contentSecurityPolicy: "default-src 'self'"
@@ -353,11 +366,10 @@ use bodyLimit maxSize: 1024 * 1024       # 1MB max body
 | Middleware | Options |
 |------------|---------|
 | `logger()` | `format`, `skip`, `stream` |
-| `cors()` | `origin`, `methods`, `headers`, `credentials`, `maxAge` |
+| `cors()` | `origin`, `methods`, `headers`, `credentials`, `maxAge`, `exposeHeaders`, `preflight` |
 | `compress()` | `threshold`, `encodings` |
-| `cookies()` | `secure`, `httpOnly`, `sameSite`, `maxAge`, `path` |
-| `sessions()` | `name`, `maxAge`, `secure`, `httpOnly`, `sameSite` |
-| `secureHeaders()` | `hsts`, `hstsMaxAge`, `contentSecurityPolicy`, `frameOptions` |
+| `sessions()` | `secret`, `name`, `maxAge`, `secure`, `httpOnly`, `sameSite` |
+| `secureHeaders()` | `hsts`, `hstsMaxAge`, `contentSecurityPolicy`, `frameOptions`, `referrerPolicy` |
 | `timeout()` | `ms`, `message`, `status` |
 | `bodyLimit()` | `maxSize`, `message` |
 
@@ -365,10 +377,10 @@ use bodyLimit maxSize: 1024 * 1024       # 1MB max body
 
 ```coffee
 import { get, use, before, session } from '@rip-lang/api'
-import { cookies, sessions } from '@rip-lang/api/middleware'
+import { sessions } from '@rip-lang/api/middleware'
 
-use cookies()
-use sessions()
+# Sessions parses cookies directly from request headers
+use sessions secret: process.env.SESSION_SECRET
 
 before ->
   session.views ?= 0
@@ -388,25 +400,18 @@ get '/logout', ->
 
 The `session` import works anywhere via AsyncLocalStorage — no `@` needed, works in helpers and nested callbacks.
 
-### Cookie Usage (low-level)
-
-```coffee
-import { get, use } from '@rip-lang/api'
-import { cookies } from '@rip-lang/api/middleware'
+**Security note:** Without `secret`, sessions use plain base64 (dev only). With `secret`, sessions are HMAC-SHA256 signed (tamper-proof). Always set `secret` in production.
 
-use cookies()
+### CORS with Preflight
 
-get '/set-cookie', ->
-  @cookie 'theme', 'dark', maxAge: 3600
-  { success: true }
+For APIs that need to handle OPTIONS preflight requests before route matching:
 
-get '/get-cookie', ->
-  theme = @cookie 'theme'
-  { theme }
+```coffee
+import { use } from '@rip-lang/api'
+import { cors } from '@rip-lang/api/middleware'
 
-get '/logout', ->
-  @clearCookie 'theme'
-  { cleared: true }
+# Handle OPTIONS early (before routes are matched)
+use cors origin: 'https://myapp.com', preflight: true
 ```
 
 ### Custom Middleware
@@ -438,16 +443,22 @@ use (c, next) ->
   console.log 'After handler'
 ```
 
-### Before/After Filters (Sinatra-style)
+### Request Lifecycle Filters
 
-For simpler cases, use `before` and `after` filters. Use `@` to access context:
+Three filters run at different stages: `raw` → `before` → handler → `after`
 
 ```coffee
-import { before, after, get } from '@rip-lang/api'
+import { raw, before, after, get } from '@rip-lang/api'
+
+# Runs first — modify raw request before body parsing
+raw (req) ->
+  # Fix content-type for specific clients
+  if req.headers.get('X-Raw-SQL') is 'true'
+    req.headers.set 'content-type', 'text/plain'
 
 skipPaths = ['/favicon.ico', '/ping', '/health']
 
-# Runs before every request
+# Runs before handler (after body parsing)
 before ->
   @start = Date.now()
   @silent = @req.path in skipPaths
@@ -455,12 +466,14 @@ before ->
   unless @req.header 'Authorization'
     return @json { error: 'Unauthorized' }, 401
 
-# Runs after every request
+# Runs after handler
 after ->
   return if @silent
   console.log "#{@req.method} #{@req.path} - #{Date.now() - @start}ms"
 ```
 
+**Note:** `raw` receives the native `Request` object (before parsing). `before` and `after` use `@` to access the context.
+
 **How `@` works:** Handlers are called with `this` bound to the context, so `@foo` is `this.foo`. This gives you Sinatra-like magic access to:
 - `@req` — Request object
 - `@json()`, `@text()`, `@html()`, `@redirect()` — Response helpers
@@ -612,6 +625,41 @@ export default App ->
   post '/echo', -> read()
 ```
 
+## Context Utilities
+
+### ctx()
+
+Get the current request context from anywhere (via AsyncLocalStorage):
+
+```coffee
+import { ctx } from '@rip-lang/api'
+
+# In a helper function
+logRequest = ->
+  c = ctx()
+  console.log "#{c.req.method} #{c.req.path}" if c
+
+# Works in callbacks, helpers, anywhere during request
+get '/demo', ->
+  logRequest()
+  { ok: true }
+```
+
+### resetGlobals()
+
+Reset all global state (routes, middleware, filters). Useful for testing:
+
+```coffee
+import { resetGlobals, get, start } from '@rip-lang/api'
+
+# In test setup
+beforeEach ->
+  resetGlobals()
+
+# Now define fresh routes for this test
+get '/test', -> { test: true }
+```
+
 ## Utility Functions
 
 ### isBlank
@@ -759,7 +807,7 @@ start port: 3000
 
 ## Performance
 
-- **Minimal footprint** — Core is ~565 lines, optional middleware ~395 lines
+- **Minimal footprint** — Core is ~595 lines, optional middleware ~390 lines
 - **Zero dependencies** — No external packages to load
 - **Compiled patterns** — Route regexes compiled once at startup
 - **Smart response wrapping** — Minimal overhead for return-value handlers

package/api.rip

@@ -8,13 +8,12 @@
 # Public exports:
 #   DSL:        get, post, put, patch, del, all, use, prefix
 #   Server:     start, startHandler, fetch, App
-#   Filters:    before, after
+#   Filters:    raw, before, after
 #   Handlers:   onError, notFound
 #   Validation: read, validators, registerValidator, getValidator
 #   Context:    ctx, session, env
 #   Utilities:  isBlank, toName, toPhone
 #   Dev:        resetGlobals
-#
 # ==============================================================================
 
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -26,20 +25,27 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 _                = null  # Match capture holder for Rip's =~
 _errorHandler    = null  # Custom error handler
 _notFoundHandler = null  # Custom 404 handler
+_rawFilter       = null  # Raw request filter (before body parsing)
 _beforeFilters   = []    # Before request filters
 _afterFilters    = []    # After request filters
 _routes          = []    # Route definitions
 _middlewares     = []    # Global middleware functions
 _prefix          = ''    # Current route prefix for grouping
+_corsPreflight   = false # Enable early OPTIONS handling (set by cors middleware)
 
 export resetGlobals = ->
   _errorHandler    = null
   _notFoundHandler = null
+  _rawFilter       = null
   _beforeFilters   = []
   _afterFilters    = []
   _routes          = []
   _middlewares     = []
   _prefix          = ''
+  _corsPreflight   = false
+
+# Enable early OPTIONS handling (called by cors middleware with preflight: true)
+export enableCorsPreflight = -> _corsPreflight = true
 
 # AsyncLocalStorage for request context (enables sync read() in handlers)
 export requestContext = new AsyncLocalStorage()
@@ -237,6 +243,7 @@ export prefix = (base, fn) ->
 export onError = (handler) -> _errorHandler = handler
 export notFound = (handler) -> _notFoundHandler = handler
 
+export raw = (fn) -> _rawFilter = fn
 export before = (fn) -> _beforeFilters.push fn
 export after = (fn) -> _afterFilters.push fn
 
@@ -253,6 +260,18 @@ export fetch = (req) ->
     res = fetch!(new Request(req.url, { method: 'GET', headers: req.headers }))
     return new Response(null, { status: res.status, headers: res.headers })
 
+  # Handle CORS preflight (OPTIONS) requests early, before route matching
+  # Enabled when cors middleware is used with preflight: true
+  if method is 'OPTIONS' and _corsPreflight
+    return new Response null,
+      status: 204
+      headers:
+        'Access-Control-Allow-Origin': req.headers.get('origin') or '*'
+        'Access-Control-Allow-Credentials': 'true'
+        'Access-Control-Allow-Methods': 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
+        'Access-Control-Allow-Headers': req.headers.get('access-control-request-headers') or 'Content-Type,Authorization'
+        'Access-Control-Max-Age': '86400'
+
   match = matchRoute(method, pathname)
 
   unless match
@@ -263,6 +282,9 @@ export fetch = (req) ->
 
   c = createContext(req, match.params)
 
+  # Run raw filter before body parsing (e.g., fix content-type)
+  _rawFilter?(req) if method in ['POST', 'PUT', 'PATCH']
+
   # Pre-parse body and query for sync read() — baked in, zero ceremony
   data = {}
   try
@@ -272,6 +294,8 @@ export fetch = (req) ->
         data = c.req.json!
       else if ct =~ /x-www-form-urlencoded|form-data/i
         data = c.req.parseBody!
+      else if ct =~ /text\//i
+        data = { body: c.req.text! }
   catch
     data = {}
   merged = { ...data, ...c.req.query(), ...match.params }
@@ -300,10 +324,14 @@ runHandler = (c, handler) ->
 export startHandler = -> fetch
 
 export start = (opts = {}) ->
-  # Skip if running under rip-server (worker sets these env vars)
-  return if process.env.WORKER_ID? or process.env.SOCKET_PATH?
-
   handler = startHandler()
+
+  # If running under rip-server, set global handler and return
+  if process.env.WORKER_ID? or process.env.SOCKET_PATH?
+    globalThis.__ripHandler = handler
+    return handler
+
+  # Otherwise start standalone server
   host = opts.host or '0.0.0.0'
   port = opts.port or 3000
   server = Bun.serve { hostname: host, port: port, fetch: handler }

package/middleware.rip

@@ -3,13 +3,12 @@
 # ==============================================================================
 #
 # Usage:
-#   import { cors, logger, compress, cookies, sessions } from '@rip-lang/api/middleware'
+#   import { cors, logger, compress, sessions } from '@rip-lang/api/middleware'
 #   import { session } from '@rip-lang/api'
 #
 #   use logger()
 #   use cors origin: 'https://myapp.com'
 #   use compress()
-#   use cookies()
 #   use sessions()
 #
 #   before ->
@@ -30,8 +29,11 @@
 #   credentials: boolean
 #   maxAge: number (seconds)
 #   exposeHeaders: string | string[]
+#   preflight: boolean — handle OPTIONS before route matching (default: false)
 #
 
+import { enableCorsPreflight } from '@rip-lang/api'
+
 export cors = (opts = {}) ->
   origin = opts.origin or '*'
   methods = opts.methods or 'GET,POST,PUT,PATCH,DELETE,OPTIONS'
@@ -45,6 +47,9 @@ export cors = (opts = {}) ->
   headers = headers.join(',') if Array.isArray(headers)
   exposeHeaders = exposeHeaders.join(',') if Array.isArray(exposeHeaders)
 
+  # Enable early OPTIONS handling if preflight option is set
+  enableCorsPreflight() if opts.preflight
+
   (c, next) ->
     requestOrigin = c.req.header('Origin')
 
@@ -188,73 +193,11 @@ export compress = (opts = {}) ->
       return
 
 # ==============================================================================
-# cookies — Cookie Parsing and Setting
-# ==============================================================================
-#
-# Options:
-#   secret: string (for signed cookies)
-#   secure: boolean (HTTPS only, default false)
-#   httpOnly: boolean (default true)
-#   sameSite: 'Strict' | 'Lax' | 'None' (default 'Lax')
-#   maxAge: number (seconds)
-#   path: string (default '/')
-#
-# Adds to context:
-#   c.cookie(name) — get cookie value
-#   c.cookie(name, value, opts) — set cookie
-#   c.clearCookie(name) — delete cookie
-#
-
-export cookies = (opts = {}) ->
-  defaults =
-    secure: opts.secure or false
-    httpOnly: opts.httpOnly ? true
-    sameSite: opts.sameSite or 'Lax'
-    path: opts.path or '/'
-    maxAge: opts.maxAge
-
-  (c, next) ->
-    # Parse cookies from header
-    cookieHeader = c.req.header('Cookie') or ''
-    parsed = {}
-    for pair in cookieHeader.split(';')
-      [key, val] = pair.trim().split('=')
-      parsed[key] = decodeURIComponent(val) if key and val
-
-    # Store pending Set-Cookie headers
-    setCookies = []
-
-    # Get cookie value
-    c.cookie = (name, value, cookieOpts) ->
-      if value is undefined
-        # Getter
-        return parsed[name]
-
-      # Setter
-      cookieOpts = { ...defaults, ...cookieOpts }
-      parts = ["#{encodeURIComponent(name)}=#{encodeURIComponent(value)}"]
-      parts.push "Path=#{cookieOpts.path}" if cookieOpts.path
-      parts.push "Max-Age=#{cookieOpts.maxAge}" if cookieOpts.maxAge?
-      parts.push "HttpOnly" if cookieOpts.httpOnly
-      parts.push "Secure" if cookieOpts.secure
-      parts.push "SameSite=#{cookieOpts.sameSite}" if cookieOpts.sameSite
-      setCookies.push parts.join('; ')
-
-    # Clear cookie
-    c.clearCookie = (name, cookieOpts = {}) ->
-      c.cookie name, '', { ...cookieOpts, maxAge: 0 }
-
-    await next()
-
-    # Apply Set-Cookie headers
-    for cookie in setCookies
-      c.header 'Set-Cookie', cookie, append: true
-
-# ==============================================================================
-# session — Session Management (requires cookies middleware)
+# sessions — Session Management
 # ==============================================================================
 #
 # Options:
+#   secret: string (REQUIRED for production — signs cookie to prevent tampering)
 #   name: string (cookie name, default 'session')
 #   maxAge: number (seconds, default 86400 = 24 hours)
 #   secure: boolean (HTTPS only)
@@ -263,6 +206,9 @@ export cookies = (opts = {}) ->
 #
 # Usage:
 #   import { session } from '@rip-lang/api'
+#   import { sessions } from '@rip-lang/api/middleware'
+#
+#   use sessions secret: process.env.SESSION_SECRET
 #
 #   before ->
 #     session.userId = 123
@@ -270,21 +216,73 @@ export cookies = (opts = {}) ->
 #   get '/profile', ->
 #     { userId: session.userId }
 #
+# Security:
+#   Without `secret`, sessions use plain base64 (INSECURE — dev only).
+#   With `secret`, sessions are HMAC-SHA256 signed (tamper-proof).
+#
+# Note: Self-contained — parses cookies directly from request headers.
+#
+
+# HMAC-SHA256 signing helpers
+hmacSign = (data, secret) ->
+  encoder = new TextEncoder()
+  key = crypto.subtle.importKey! 'raw', encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
+  signature = crypto.subtle.sign! 'HMAC', key, encoder.encode(data)
+  Array.from(new Uint8Array(signature)).map((b) -> b.toString(16).padStart(2, '0')).join('')
+
+hmacVerify = (data, signature, secret) ->
+  expected = hmacSign! data, secret
+  # Constant-time comparison to prevent timing attacks
+  return false if expected.length isnt signature.length
+  result = 0
+  for i in [0...expected.length]
+    result |= expected.charCodeAt(i) ^ signature.charCodeAt(i)
+  result is 0
+
+encodeSession = (data, secret) ->
+  json = JSON.stringify(data)
+  payload = btoa(unescape(encodeURIComponent(json)))
+  return payload unless secret
+  signature = hmacSign! payload, secret
+  "#{payload}--#{signature}"
+
+decodeSession = (cookie, secret) ->
+  return {} unless cookie
+  try
+    if secret
+      [payload, signature] = cookie.split('--')
+      return {} unless payload and signature
+      return {} unless hmacVerify! payload, signature, secret
+      JSON.parse(decodeURIComponent(escape(atob(payload))))
+    else
+      JSON.parse(decodeURIComponent(escape(atob(cookie))))
+  catch
+    {}
 
 export sessions = (opts = {}) ->
+  secret = opts.secret
   cookieName = opts.name or 'session'
   maxAge = opts.maxAge or 86400
   secure = opts.secure or false
   httpOnly = opts.httpOnly ? true
   sameSite = opts.sameSite or 'Lax'
 
+  # Warn if no secret in production
+  if not secret and process.env.NODE_ENV is 'production'
+    console.warn 'WARNING: sessions() without secret is insecure. Set secret option for production.'
+
   (c, next) ->
-    # Parse existing session from cookie
-    raw = c.cookie?(cookieName)
-    try
-      c.session = if raw then JSON.parse(atob(raw)) else {}
-    catch
-      c.session = {}
+    # Parse cookie header
+    cookieHeader = c.req.header('Cookie') or ''
+    cookies = {}
+    for pair in cookieHeader.split(';')
+      [key, val] = pair.trim().split('=')
+      cookies[key] = decodeURIComponent(val) if key and val
+
+    # Decode existing session
+    raw = cookies[cookieName]
+    c.session = decodeSession raw, secret
 
     # Track original for change detection
     original = JSON.stringify(c.session)
@@ -294,8 +292,8 @@ export sessions = (opts = {}) ->
     # Save session if changed
     current = JSON.stringify(c.session)
     if current isnt original and c._response?
-      encoded = btoa(current)
-      parts = ["#{cookieName}=#{encoded}"]
+      encoded = encodeSession c.session, secret
+      parts = ["#{cookieName}=#{encodeURIComponent(encoded)}"]
       parts.push "Path=/"
       parts.push "Max-Age=#{maxAge}"
       parts.push "HttpOnly" if httpOnly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rip-lang/api",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Pure Rip API framework — elegant, fast, zero dependencies",
   "type": "module",
   "main": "api.rip",
@@ -32,9 +32,6 @@
   },
   "author": "Steve Shreeve <steve.shreeve@gmail.com>",
   "license": "MIT",
-  "peerDependencies": {
-    "rip-lang": "^2.0.0"
-  },
   "files": [
     "api.rip",
     "middleware.rip",