luca 2.0.0 → 3.0.0

package/src/server.ts

@@ -0,0 +1,229 @@
+import type { NodeContainer } from './node/container.js'
+import { Helper } from './helper.js'
+import { Registry } from './registry.js'
+import { z } from 'zod'
+import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from './schemas/base.js'
+
+export type ServerState = z.infer<typeof ServerStateSchema>
+export type ServerOptions = z.infer<typeof ServerOptionsSchema>
+
+export type StartOptions = {
+  port?: number;
+  host?: string;
+}
+
+export type ServerFactory = <T extends keyof AvailableServers>(
+      key: T,
+      options?: ConstructorParameters<AvailableServers[T]>[0]
+) => NonNullable<InstanceType<AvailableServers[T]>>
+
+export interface ServersInterface {
+  servers: ServersRegistry;
+  server: ServerFactory
+}
+
+export interface AvailableServers {}
+
+export class Server<T extends ServerState = ServerState, K extends ServerOptions = ServerOptions> extends Helper<T, K> {
+    static override stateSchema = ServerStateSchema
+    static override optionsSchema = ServerOptionsSchema
+    static override eventsSchema = ServerEventsSchema
+
+    /** Self-register a Server subclass from a static initialization block. */
+    static register: (SubClass: abstract new (options: any, context: any) => Server, id?: string) => abstract new (options: any, context: any) => Server
+
+    override get initialState() : T {
+      return ({
+        port: this.options.port || 3000,
+        listening: false,
+        configured: false,
+        stopped: false
+      } as unknown) as T
+    }
+
+    override get options() : K {
+      return {
+        port: 3000,
+        host: '0.0.0.0',
+        ...this._options,
+      }
+    }
+
+    static attach(container: NodeContainer & ServersInterface) {
+      container.servers = servers
+
+      Object.assign(container, {
+        server<T extends keyof AvailableServers>(
+          id: T,
+          options?: ConstructorParameters<AvailableServers[T]>[0]
+        ): NonNullable<InstanceType<AvailableServers[T]>> {
+          const BaseClass = servers.lookup(id) as AvailableServers[T]
+
+          return container.createHelperInstance({
+            cache: helperCache,
+            type: 'server',
+            id: String(id),
+            BaseClass,
+            options,
+            fallbackName: String(id),
+          }) as NonNullable<InstanceType<AvailableServers[T]>>
+        }
+      })
+
+      container.registerHelperType('servers', 'server')
+
+      return container
+    }
+
+    override get container() : NodeContainer {
+        return super.container as NodeContainer
+    }
+
+    /** Async functions passed to `.use()` before `start()` — drained in `start()`. */
+    _pendingPlugins: Promise<void>[] = []
+
+    /**
+     * Register a setup function against this server. The function receives the
+     * server instance and can configure it however it likes.
+     *
+     * - If the server hasn't started yet, async return values are queued and
+     *   awaited when `start()` is called.
+     * - If the server is already listening, the function is fire-and-forget.
+     * - Always returns `this` synchronously for chaining.
+     *
+     * @example
+     * ```typescript
+     * server
+     *   .use((s) => s.app.use(cors()))
+     *   .use(async (s) => { await loadRoutes(s) })
+     * await server.start()
+     * ```
+     */
+    use(fn: (server: this) => void | Promise<void>): this {
+      const result = fn(this)
+      if (result && typeof (result as any).then === 'function') {
+        if (!this.isListening) {
+          this._pendingPlugins.push(result as Promise<void>)
+        }
+      }
+      return this
+    }
+
+    /** Drain all pending `.use()` promises. Subclasses should call this at the top of `start()`. */
+    protected async _drainPendingPlugins() {
+      if (this._pendingPlugins.length) {
+        await Promise.all(this._pendingPlugins)
+        this._pendingPlugins = []
+      }
+    }
+
+    get isListening() {
+      return !!this.state.get('listening')
+    }
+
+    get isConfigured() {
+      return !!this.state.get('configured')
+    }
+
+    get isStopped() {
+      return !!this.state.get('stopped')
+    }
+
+    /** The port this server will bind to. Reads from state first (set by start() or configure()), then constructor options, then defaults to 3000. */
+    get port() {
+      return this.state.get('port') || this.options.port || 3000
+    }
+
+    async stop() {
+      if(this.isStopped) {
+        return this
+      }
+
+      this.state.set('stopped', true)
+
+      return this
+    }
+
+    /**
+     * Start the server. Runtime options override constructor options and update state
+     * so that `server.port` always reflects the actual listening port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    async start(options?: StartOptions) {
+      if(this.isListening) {
+        return this
+      }
+
+      await this._drainPendingPlugins()
+
+      if (options?.port) {
+        this.state.set('port', options.port)
+      }
+
+      this.state.set('listening', true)
+
+      return this
+    }
+
+    async configure() {
+      const port = await this.container.networking.findOpenPort(this.port)
+
+      if(port !== this.port) {
+        this.state.set('port', port)
+      }
+
+      this.state.set('configured', true)
+
+      return this
+    }
+}
+
+export class ServersRegistry extends Registry<Server<any>> {
+  override scope = "servers"
+  override baseClass = Server
+}
+
+export const servers = new ServersRegistry()
+
+export const helperCache = new Map()
+
+/**
+ * Self-register a Server subclass from a static initialization block.
+ * IMPORTANT: Place the static block AFTER all static override declarations
+ * so schemas, envVars, and other metadata are set before interceptRegistration fires.
+ *
+ * @example
+ * ```typescript
+ * export class ExpressServer extends Server {
+ *   static override stateSchema = ServerStateSchema
+ *   static override optionsSchema = ExpressServerOptionsSchema
+ *   static { Server.register(this, 'express') }  // must come last
+ * }
+ * ```
+ */
+Server.register = function registerServer(
+  SubClass: abstract new (options: any, context: any) => Server,
+  id?: string,
+) {
+  const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)
+
+  // Auto-set shortcut if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+      (SubClass as any).shortcut === 'unspecified') {
+    ;(SubClass as any).shortcut = `servers.${registryId}` as const
+  }
+
+  // Register in the servers registry (interceptRegistration sees all statics above)
+  servers.register(registryId, SubClass as any)
+
+  // Generate default attach() if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+    ;(SubClass as any).attach = (container: any) => {
+      servers.register(registryId, SubClass as any)
+      return container
+    }
+  }
+
+  return SubClass
+}

package/src/servers/express.ts

@@ -0,0 +1,283 @@
+import express from 'express'
+import type { Express } from 'express'
+import cors from 'cors'
+import { z } from 'zod'
+import { ServerStateSchema, ServerOptionsSchema } from '../schemas/base.js'
+import { type StartOptions, Server, type ServerState } from '../server.js'
+import { Endpoint, type EndpointModule, warnUnknownExports } from '../endpoint.js'
+
+declare module '../server' {
+  interface AvailableServers {
+    express: typeof ExpressServer
+  }
+}
+
+export const ExpressServerOptionsSchema = ServerOptionsSchema.extend({
+  cors: z.boolean().optional().describe('Whether to enable CORS middleware'),
+  static: z.string().optional().describe('Path to serve static files from'),
+  historyFallback: z.boolean().optional().describe('Serve index.html for unmatched routes (SPA history fallback)'),
+  create: z.any().optional().describe('(app: Express, server: Server) => Express'),
+  beforeStart: z.any().optional().describe('(options: StartOptions, server: Server) => Promise<any>'),
+})
+export type ExpressServerOptions = z.infer<typeof ExpressServerOptionsSchema>
+
+const defaultCreate = (app: Express, server: Server) => app
+
+/**
+ * Express.js HTTP server with automatic endpoint mounting, CORS, and SPA history fallback.
+ *
+ * Wraps an Express application with convention-based endpoint discovery. Endpoints
+ * defined as modules are automatically mounted as routes. Supports static file serving,
+ * CORS configuration, and single-page app history fallback out of the box.
+ *
+ * @extends Server
+ *
+ * @example
+ * ```typescript
+ * const server = container.server('express', { cors: true, static: './public' })
+ * await server.start({ port: 3000 })
+ *
+ * // Mount endpoints programmatically
+ * server.mount(myEndpoint)
+ *
+ * // Access the underlying Express app
+ * server.app.get('/health', (req, res) => res.json({ ok: true }))
+ * ```
+ */
+export class ExpressServer<T extends ServerState = ServerState, K extends ExpressServerOptions = ExpressServerOptions> extends Server<T,K> {
+    static override shortcut = 'servers.express' as const
+    static override stateSchema = ServerStateSchema
+    static override optionsSchema = ExpressServerOptionsSchema
+
+    static { Server.register(this, 'express') }
+  
+    _app?: Express
+    _listener?: any
+    _mountedEndpoints: Endpoint[] = []
+
+    get express(): typeof express {
+      return express
+    }
+
+    get hooks(): { create: (app: Express, server: Server) => Express; beforeStart: (options: any, server: Server) => any } {
+      const { create = defaultCreate, beforeStart = () => {} } = this.options  
+      
+      return {
+        create,
+        beforeStart
+      }
+    }
+
+    get app(): Express {
+      if(this._app) {
+        return this._app
+      }
+      
+      const app = express()
+      
+      if (this.options.cors !== false) {
+        app.use(cors())
+      }
+      
+      app.use(express.json({ limit: "500mb" }))
+      app.use(express.urlencoded({ extended: true, limit: "500mb", parameterLimit: 50000 }))
+      
+      if (this.options.static) {
+        app.use(express.static(this.options.static))
+      }
+      
+      // @ts-ignore-next-line
+      const server : Server = this
+      this._app = this.hooks.create(app, server) || app
+
+      return app
+    }
+  
+    /**
+     * Start the Express HTTP server. A runtime `port` overrides the constructor
+     * option and is written to state so `server.port` always reflects reality.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    override async start(options?: StartOptions): Promise<this> {
+      if (this.isListening) {
+        return this
+      }
+
+      await this._drainPendingPlugins()
+
+      // Apply runtime port to state so this.port reflects the override
+      if (options?.port) {
+        this.state.set('port', options.port)
+      }
+
+      const startOptions = {
+        port: this.port,
+        host: options?.host || this.options.host || '0.0.0.0',
+      }
+
+      // @ts-ignore-next-line
+      await this.hooks.beforeStart(startOptions, this)
+
+      // SPA history fallback: serve index.html for unmatched GET routes
+      if (this.options.historyFallback && this.options.static) {
+        const indexPath = `${this.options.static}/index.html`
+        this.app.get('*', (_req: any, res: any) => {
+          res.sendFile(indexPath)
+        })
+      }
+
+      await new Promise((res) => {
+        this._listener = this.app.listen(startOptions.port, startOptions.host, () => {
+          this.state.set('listening', true)
+          res(null)
+        })
+      })
+
+      return this
+    }
+
+    override async stop(): Promise<this> {
+      if (this.isStopped) {
+        return this
+      }
+
+      await Promise.race([
+        new Promise<void>((resolve) => {
+          if (!this._listener) {
+            resolve()
+            return
+          }
+
+          try {
+            this._listener.close(() => {
+              this._listener = undefined
+              resolve()
+            })
+          } catch {
+            this._listener = undefined
+            resolve()
+          }
+        }),
+        new Promise<void>((resolve) => setTimeout(resolve, 500)),
+      ])
+
+      this.state.set('listening', false)
+      this.state.set('stopped', true)
+      return this
+    }
+    
+    override async configure(): Promise<this> {
+      this.state.set('configured', true)
+      return this
+    }
+
+    useEndpoint(endpoint: Endpoint): this {
+      endpoint.mount(this.app)
+      this._mountedEndpoints.push(endpoint)
+      return this
+    }
+
+    async useEndpoints(dir: string): Promise<this> {
+      const { Glob } = globalThis.Bun || (await import('bun'))
+      const glob = new Glob('**/*.ts')
+
+      // Use the helpers feature's VM-aware loader so endpoints can resolve
+      // packages like zod and @soederpop/luca even from the compiled binary
+      const helpers = this.container.feature('helpers') as any
+
+      for await (const file of glob.scan({ cwd: dir, absolute: true })) {
+        try {
+          const mod = await helpers.loadModuleExports(file)
+          const endpointModule: EndpointModule = mod.default || mod
+
+          if (!endpointModule.path) {
+            continue
+          }
+
+          warnUnknownExports(mod, file)
+
+          const endpoint = new Endpoint(
+            { path: endpointModule.path, filePath: file },
+            this.container.context
+          )
+          await endpoint.load(endpointModule)
+          this.useEndpoint(endpoint)
+        } catch (err) {
+          console.error(`Failed to load endpoint from ${file}:`, err)
+        }
+      }
+
+      return this
+    }
+
+    /**
+     * Reload a mounted endpoint by its file path. Re-reads the module through
+     * the helpers VM loader so the next request picks up the new handlers.
+     *
+     * @param filePath - Absolute path to the endpoint file
+     * @returns The reloaded Endpoint, or null if no mounted endpoint matches
+     */
+    async reloadEndpoint(filePath: string): Promise<Endpoint | null> {
+      const endpoint = this._mountedEndpoints.find(ep => (ep.options as any).filePath === filePath)
+      if (!endpoint) return null
+
+      const helpers = this.container.feature('helpers') as any
+      const mod = await helpers.loadModuleExports(filePath, { cacheBust: true })
+      const endpointModule: EndpointModule = mod.default || mod
+      await endpoint.load(endpointModule)
+      return endpoint
+    }
+
+    async useEndpointModules(modules: EndpointModule[]): Promise<this> {
+      for (const mod of modules) {
+        try {
+          const endpointModule: EndpointModule = (mod as any).default || mod
+
+          if (!endpointModule.path) {
+            continue
+          }
+
+          const endpoint = new Endpoint(
+            { path: endpointModule.path },
+            this.container.context
+          )
+          await endpoint.load(endpointModule)
+          this.useEndpoint(endpoint)
+        } catch (err) {
+          console.error(`Failed to load endpoint module (${(mod as any).path || 'unknown'}):`, err)
+        }
+      }
+
+      return this
+    }
+
+    serveOpenAPISpec(options: { title?: string; version?: string; description?: string } = {}): this {
+      const server = this
+      this.app.get('/openapi.json', (_req: any, res: any) => {
+        res.json(server.generateOpenAPISpec(options))
+      })
+      return this
+    }
+
+    generateOpenAPISpec(options: { title?: string; version?: string; description?: string } = {}): Record<string, any> {
+      const paths: Record<string, any> = {}
+
+      for (const ep of this._mountedEndpoints) {
+        paths[ep.path] = ep.toOpenAPIPathItem()
+      }
+
+      return {
+        openapi: '3.1.0',
+        info: {
+          title: options.title || 'Luca API',
+          version: options.version || '1.0.0',
+          description: options.description || 'Auto-generated from Luca endpoints',
+        },
+        servers: [{ url: `http://localhost:${this.port}` }],
+        paths,
+      }
+    }
+}
+
+export default ExpressServer