Skip to content

README.md

Latest commit

 

History

History
128 lines (97 loc) · 3.16 KB

README.md

File metadata and controls

128 lines (97 loc) · 3.16 KB

@objectstack/plugin-hono-server

HTTP Server adapter for ObjectStack using Hono.

Features

  • Standard Runtime: Uses the unified HttpDispatcher and standard Hono adapter via @objectstack/hono.
  • Fast: Built on Hono, a high-performance web framework.
  • Full Protocol Support: Automatically provides all ObjectStack Runtime endpoints (Auth, Data, Metadata, etc.).
  • Middleware: Supports standard Hono middleware.
  • Wildcard CORS: Supports wildcard patterns in CORS origins (compatible with better-auth).

Usage

import { ObjectKernel } from '@objectstack/runtime';
import { HonoServerPlugin } from '@objectstack/plugin-hono-server';

const kernel = new ObjectKernel();

// Register the server plugin
kernel.use(new HonoServerPlugin({
  port: 3000,
  restConfig: {
      api: {
          apiPath: '/api/v1' // Customize API prefix
      }
  }
}));

await kernel.start();

CORS Configuration

The Hono server plugin supports flexible CORS configuration with wildcard pattern matching.

Basic CORS

kernel.use(new HonoServerPlugin({
  port: 3000,
  cors: {
    origins: ['https://app.example.com'],
    credentials: true
  }
}));

Wildcard Patterns (better-auth compatible)

// Subdomain wildcards
kernel.use(new HonoServerPlugin({
  cors: {
    origins: ['https://*.objectui.org', 'https://*.objectstack.ai'],
    credentials: true
  }
}));

// Port wildcards (useful for development)
kernel.use(new HonoServerPlugin({
  cors: {
    origins: 'http://localhost:*'
  }
}));

// Comma-separated patterns
kernel.use(new HonoServerPlugin({
  cors: {
    origins: 'https://*.objectui.org,https://*.objectstack.ai,http://localhost:*'
  }
}));

Environment Variables

CORS can also be configured via environment variables:

# Single origin
CORS_ORIGIN=https://app.example.com

# Wildcard patterns (comma-separated)
CORS_ORIGIN=https://*.objectui.org,https://*.objectstack.ai

# Disable CORS
CORS_ENABLED=false

# Additional options
CORS_CREDENTIALS=true
CORS_MAX_AGE=86400

Disable CORS

kernel.use(new HonoServerPlugin({
  cors: false  // Completely disable CORS
}));

Bearer token auth (set-auth-token)

The CORS middleware always includes set-auth-token in Access-Control-Expose-Headers so that @objectstack/plugin-auth's bearer() plugin can deliver rotated session tokens to cross-origin and mobile clients. Authorization is included in Access-Control-Allow-Headers by default so Authorization: Bearer <token> requests succeed preflight.

You can contribute additional exposed / allowed headers — exposeHeaders entries you supply are merged with the set-auth-token default:

kernel.use(new HonoServerPlugin({
  cors: {
    origins: ['https://app.example.com'],
    credentials: true,
    exposeHeaders: ['X-Request-Id'],           // in addition to set-auth-token
    allowHeaders: ['Content-Type', 'Authorization', 'X-Tenant-Id'],
  },
}));

Architecture

This plugin wraps @objectstack/hono to provide a turnkey HTTP server solution for the Runtime. It binds the standard HttpDispatcher to a Hono application and starts listening on the configured port.