@loutrejs/loutre 0.4.1 → 0.6.0

package/README.md

@@ -1,8 +1,8 @@
 # @loutrejs/loutre
 
-LoutreのCore packageです。Application Definition、Contract、DI、Pipeline、Task、Trigger、Environment、Arguments、Runtime bindingなど、Loutre Applicationを構成するpublic APIを提供します。
+LoutreのApplication Graph Kernelです。Application Definition / Model、Module、DI、Environment、Arguments、Lifecycle、Runtime Capability、generic Layer、Kernel bootstrapを提供します。
 
-> Loutreは現在v0.xです。Public APIには破壊的変更が入る可能性があります。
+HTTP、Task、MessagePort、WebSocketは同じpackageのsubpathからExecution Extensionとして提供します。
 
 ## Install
 
@@ -10,53 +10,84 @@ LoutreのCore packageです。Application Definition、Contract、DI、Pipeline
 npm install @loutrejs/loutre
 ```
 
-新しいApplicationを始める場合はinitializerも利用できます。
+新しいApplicationはinitializerから作成できます。
 
 ```sh
 npm create loutre@latest my-app
 ```
 
-## Application model
+## Application Model
 
-LoutreはHTTP endpointだけを中心にせず、Applicationが実行する処理を同じmodelへ載せます。
+Applicationの構成は`defineApplication()`でcanonical `Application Model`へcompileされます。
 
-- **Contract / Implementation** — protocolごとのinterfaceと実装
-- **Module / DI** — dependencyとApplication構成
-- **Pipeline / Layer** — requestやexecution contextの処理
-- **Task / Trigger / Queue** — 明示実行、schedule、queue consumer
-- **Environment / Arguments** — Hostから渡されるtyped input
-- **Application Graph** — Application構造をRuntimeとToolingで共有
+```ts
+import { defineApplication, defineModule } from '@loutrejs/loutre'
+import { http } from '@loutrejs/loutre/http'
+import { z } from 'zod'
+
+const HealthContract = http.contract({
+  health: {
+    method: 'GET',
+    path: '/health',
+    responses: {
+      ok: { status: 200, body: z.string() },
+    },
+  },
+})
+
+const HealthHttp = http.implementation({
+  name: 'HealthHttp',
+  contract: HealthContract,
+  factory: () => ({
+    health: (ctx) => ctx.response.ok({ body: 'ok' }),
+  }),
+})
+
+const AppModule = defineModule(() => ({
+  executions: [HealthHttp],
+}))
+
+export default defineApplication({ modules: [AppModule()] })
+```
 
-## Example
+## Kernel bootstrap
+
+portableなApplicationはroot packageから起動できます。
 
 ```ts
-import { defineApplication, task } from '@loutrejs/loutre'
+import { bootstrapApplication } from '@loutrejs/loutre'
+import { bindHttpServer } from '@loutrejs/loutre/http'
 
-export const hello = task<void, string>({
-  name: 'hello',
-  factory: () => () => 'Hello, Loutre!',
+const app = await bootstrapApplication({
+  application,
+  capabilities: [bindHttpServer({ runtime: 'test' })],
 })
 
-export default defineApplication({
-  modules: [],
-  tasks: [hello],
-})
+const response = await app.http.fetch(new Request('http://localhost/health'))
 ```
 
+ExtensionがApplication Modelに存在するときだけ、そのExtensionのHost APIがApplicationへ合成されます。
+
 ## Entry points
 
-主なsubpath exportは次のとおりです。
-
-| Entry point                     | Role                     |
-| ------------------------------- | ------------------------ |
-| `@loutrejs/loutre/http`         | HTTP Contract / Pipeline |
-| `@loutrejs/loutre/host`         | Application bootstrap    |
-| `@loutrejs/loutre/binding`      | Host / Queue binding     |
-| `@loutrejs/loutre/runtime`      | Runtime capability       |
-| `@loutrejs/loutre/graph`        | Application Graph        |
-| `@loutrejs/loutre/openapi`      | OpenAPI generation       |
-| `@loutrejs/loutre/presentation` | startup presentation     |
-| `@loutrejs/loutre/message-port` | MessagePort protocol     |
+| Entry point                     | Role                                          |
+| ------------------------------- | --------------------------------------------- |
+| `@loutrejs/loutre`              | Application Graph Kernel / Kernel bootstrap   |
+| `@loutrejs/loutre/http`         | HTTP Execution Extension                      |
+| `@loutrejs/loutre/tasks`        | Task / Trigger / Queue Execution Extension    |
+| `@loutrejs/loutre/message-port` | MessagePort Execution Extension               |
+| `@loutrejs/loutre/websocket`    | WebSocket Execution Extension                 |
+| `@loutrejs/loutre/graph`        | Application Model graph projection            |
+| `@loutrejs/loutre/runtime`      | Runtime capability / Kernel runtime primitive |
+| `@loutrejs/loutre/http/openapi` | OpenAPI projection                            |
+| `@loutrejs/loutre/presentation` | startup presentation                          |
+| `@loutrejs/loutre/runtime/*`    | portable Runtime adapter                      |
+
+Node.js listener ownership is provided by `@loutrejs/node`.
+
+## Architecture invariant
+
+Core never interprets HTTP, Task, MessagePort, or WebSocket identity. Execution Extensions compile their definitions into the single Application Model and own their runtime semantics, Host API, and Graph projection.
 
 ## Documentation
 

package/dist/adapters/aws-lambda.d.ts

@@ -1,9 +1,11 @@
-import { type ApplicationDefinition, type BootstrapArguments, type HasHttp } from '../application/index.js';
-type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
-type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
+import { type ApplicationDefinition, type BootstrapArguments, type RequireApplicationExtension } from '../application/index.js';
+import type { RuntimeCapabilityBinding } from '../core/index.js';
+import { httpExecutionExtension } from '../http/index.js';
+type HttpApplication<TDefinition extends ApplicationDefinition> = RequireApplicationExtension<TDefinition, typeof httpExecutionExtension>;
 export type AwsLambdaBindBaseOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
     readonly environment?: unknown;
+    readonly capabilities?: readonly RuntimeCapabilityBinding[];
 } & BootstrapArguments<TDefinition>;
 export type AwsLambdaBindOptions<TDefinition extends ApplicationDefinition> = AwsLambdaBindBaseOptions<TDefinition> & {
     readonly response?: 'buffered';

package/dist/adapters/aws-lambda.js

@@ -1,4 +1,6 @@
-import { binding, } from '../application/index.js';
+import { createKernelApplication, } from '../application/index.js';
+import { bindApplicationCapability } from '../application/kernel-internal.js';
+import { httpExecutionExtension } from '../http/index.js';
 import { assertRuntimeEngine } from '../runtime/engine.js';
 export const awsLambdaRuntime = {
     runtime: 'aws-lambda',
@@ -14,18 +16,27 @@ export const awsLambdaRuntime = {
 };
 function bind(options) {
     assertRuntimeEngine('aws-lambda');
-    const invocation = binding.invocation({
+    if (options.application.model.extensions.get(httpExecutionExtension) ===
+        undefined) {
+        throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: awsLambdaRuntime.bind() requires the HTTP Execution Extension.');
+    }
+    const application = createKernelApplication({
+        ...options,
         application: options.application,
+        capabilities: [
+            bindApplicationCapability(options.application.model, 'http.server', {
+                runtime: 'aws-lambda',
+            }),
+            ...(options.capabilities ?? []),
+        ],
         environment: 'environment' in options ? options.environment : process.env,
-        ...('arguments' in options ? { arguments: options.arguments } : {}),
     });
-    const http = 'http' in invocation
-        ? invocation.http
-        : undefined;
-    if (!http) {
-        void invocation.application.close();
-        throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: awsLambdaRuntime.bind() requires an HTTP-capable Application.');
-    }
+    const http = {
+        initialize: async () => {
+            await application.init();
+        },
+        fetch: (request) => application.http.fetch(request),
+    };
     if (options.response === 'streaming') {
         const handler = createAwsLambdaStreamingHttpDriver(http);
         const aws = awsLambdaGlobal();
@@ -36,9 +47,9 @@ function bind(options) {
 function createAwsLambdaHttpDriver(application) {
     let initialization;
     return async (event) => {
-        initialization ??= application.initialize();
+        initialization ??= application.initialize?.() ?? Promise.resolve();
         await initialization;
-        const response = await application.handle(toRequest(event));
+        const response = await application.fetch(toRequest(event));
         const metadata = responseMetadata(response);
         return {
             statusCode: response.status,
@@ -51,9 +62,9 @@ function createAwsLambdaHttpDriver(application) {
 function createAwsLambdaStreamingHttpDriver(application) {
     let initialization;
     return async (event, output) => {
-        initialization ??= application.initialize();
+        initialization ??= application.initialize?.() ?? Promise.resolve();
         await initialization;
-        const response = await application.handle(toRequest(event));
+        const response = await application.fetch(toRequest(event));
         const metadata = responseMetadata(response);
         const aws = awsLambdaGlobal();
         const outputMetadata = {
@@ -73,15 +84,34 @@ function createAwsLambdaStreamingHttpDriver(application) {
             });
         }
         const reader = response.body?.getReader();
-        if (reader) {
-            while (true) {
-                const chunk = await reader.read();
-                if (chunk.done)
-                    break;
-                if (!stream.write(chunk.value) && stream.once) {
-                    await new Promise((resolve) => {
-                        stream.once?.('drain', resolve);
-                    });
+        let completed = false;
+        let failure;
+        try {
+            if (reader) {
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    if (!stream.write(chunk.value) && stream.once) {
+                        await new Promise((resolve) => {
+                            stream.once?.('drain', resolve);
+                        });
+                    }
+                }
+            }
+            completed = true;
+        }
+        catch (error) {
+            failure = error;
+            throw error;
+        }
+        finally {
+            if (reader && !completed) {
+                try {
+                    await reader.cancel(failure);
+                }
+                catch {
+                    // cancel失敗でresponse pumpの元errorを上書きしない。
                 }
             }
         }

package/dist/adapters/bun.d.ts

@@ -1,9 +1,12 @@
-import { type ApplicationDefinition, type BootstrapArguments, type HasHttp, type HostBindingApplication } from '../application/index.js';
-type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
-type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
+import { type ApplicationDefinition, type BootstrapArguments, type KernelHostedApplication, type RequireApplicationExtension } from '../application/index.js';
+import type { RuntimeCapabilityBinding } from '../core/index.js';
+import { httpExecutionExtension } from '../http/index.js';
+type HttpApplication<TDefinition extends ApplicationDefinition> = RequireApplicationExtension<TDefinition, typeof httpExecutionExtension>;
 export type BunCreateOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
     readonly environment?: unknown;
+    readonly capabilities?: readonly RuntimeCapabilityBinding[];
+    readonly forceShutdownTimeoutMs?: number;
 } & BootstrapArguments<TDefinition>;
 export interface BunServeOptions {
     readonly port?: number;
@@ -13,7 +16,7 @@ export interface BunServeOptions {
 export interface BunListenerHandle {
     readonly port: number;
 }
-export type BunRuntimeApplication<TDefinition extends ApplicationDefinition = ApplicationDefinition> = HostBindingApplication<TDefinition> & {
+export type BunRuntimeApplication<TDefinition extends ApplicationDefinition = ApplicationDefinition> = KernelHostedApplication<TDefinition> & {
     serve(options?: BunServeOptions): Promise<BunListenerHandle>;
 };
 export declare const bunRuntime: {

package/dist/adapters/bun.js

@@ -1,7 +1,10 @@
-import { binding, } from '../application/index.js';
+import { createKernelApplication, } from '../application/index.js';
+import { bindApplicationCapability } from '../application/kernel-internal.js';
+import { httpExecutionExtension } from '../http/index.js';
 import { LOUTRE_VERSION, detectPresentationTerminal, startStartupPresentation, } from '../presentation.js';
 import { assertRuntimeEngine } from '../runtime/engine.js';
 import { serverUrl } from '../runtime/server-url.js';
+import { canRetryOnNextPort, initialServerPort, } from '../runtime/server-port.js';
 export const bunRuntime = {
     runtime: 'bun',
     capabilities: new Set([
@@ -26,46 +29,64 @@ async function create(options) {
         terminal: detectPresentationTerminal(process.stdout, environment),
         write: (value) => console.log(value),
     });
-    const host = binding.host({
+    if (options.application.model.extensions.get(httpExecutionExtension) ===
+        undefined) {
+        throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: bunRuntime.create() requires the HTTP Execution Extension.');
+    }
+    const hosted = createKernelApplication({
+        ...options,
         application: options.application,
+        capabilities: [
+            bindApplicationCapability(options.application.model, 'http.server', {
+                runtime: 'bun',
+            }),
+            ...(options.capabilities ?? []),
+        ],
         environment: 'environment' in options ? options.environment : environment,
-        ...('arguments' in options ? { arguments: options.arguments } : {}),
     });
-    const http = 'http' in host ? host.http : undefined;
-    if (!http) {
-        await host.application.close();
-        throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: bunRuntime.create() requires an HTTP-capable Application.');
-    }
-    await host.application.init();
-    const application = host.application;
-    const closeApplication = host.application.close.bind(host.application);
+    await hosted.init();
+    const application = hosted;
+    const http = hosted
+        .http;
+    const closeApplication = application.close.bind(application);
     let server;
     let removeShutdownHooks;
     let serving = false;
     let closed = false;
-    const close = async (signal) => {
+    let closingPromise;
+    const close = (signal) => {
         if (closed)
-            return;
-        closed = true;
-        removeShutdownHooks?.();
-        removeShutdownHooks = undefined;
-        const errors = [];
-        if (server) {
+            return Promise.resolve();
+        if (closingPromise)
+            return closingPromise;
+        closingPromise = (async () => {
+            removeShutdownHooks?.();
+            removeShutdownHooks = undefined;
+            const errors = [];
+            if (server) {
+                try {
+                    await server.stop(true);
+                    server = undefined;
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
             try {
-                await server.stop(true);
+                await closeApplication(signal);
             }
             catch (error) {
                 errors.push(error);
             }
-        }
-        try {
-            await closeApplication(signal);
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, 'Bun runtime shutdown failed');
+            if (errors.length > 0) {
+                throw new AggregateError(errors, 'Bun runtime shutdown failed');
+            }
+            closed = true;
+        })().catch((error) => {
+            closingPromise = undefined;
+            throw error;
+        });
+        return closingPromise;
     };
     const serve = async (serveOptions = {}) => {
         if (closed) {
@@ -80,10 +101,8 @@ async function create(options) {
         }
         serving = true;
         try {
-            if ('triggers' in application)
-                await application.triggers.start();
             const requestedPort = serveOptions.port;
-            let port = requestedPort ?? 3000;
+            let port = initialServerPort(requestedPort);
             while (true) {
                 try {
                     server = bun.serve({
@@ -139,21 +158,12 @@ function registerBunShutdownHooks(close) {
     }
     return remove;
 }
-function canRetryOnNextPort(error, port) {
-    return port < 65_535 && isAddressInUseError(error);
-}
-function isAddressInUseError(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        error.code === 'EADDRINUSE');
-}
 function createBunFetchDriver(application) {
     let initialization;
     return async (request) => {
-        initialization ??= application.initialize();
+        initialization ??= application.initialize?.() ?? Promise.resolve();
         await initialization;
-        return application.handle(request);
+        return application.fetch(request);
     };
 }
 function bunGlobal() {

package/dist/adapters/cloudflare-workers.d.ts

@@ -1,8 +1,10 @@
-import { type ApplicationDefinition, type BootstrapArguments, type HasHttp } from '../application/index.js';
-type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
-type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
+import { type ApplicationDefinition, type BootstrapArguments, type RequireApplicationExtension } from '../application/index.js';
+import type { RuntimeCapabilityBinding } from '../core/index.js';
+import { httpExecutionExtension } from '../http/index.js';
+type HttpApplication<TDefinition extends ApplicationDefinition> = RequireApplicationExtension<TDefinition, typeof httpExecutionExtension>;
 export type CloudflareWorkersBindOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
+    readonly capabilities?: readonly RuntimeCapabilityBinding[];
 } & BootstrapArguments<TDefinition>;
 export interface CloudflareWorkersBinding {
     fetch(request: Request, environment?: unknown, executionContext?: unknown): Promise<Response>;

package/dist/adapters/cloudflare-workers.js

@@ -1,4 +1,6 @@
-import { binding, } from '../application/index.js';
+import { createKernelApplication, } from '../application/index.js';
+import { bindApplicationCapability } from '../application/kernel-internal.js';
+import { httpExecutionExtension } from '../http/index.js';
 import { assertRuntimeEngine } from '../runtime/engine.js';
 export const cloudflareWorkersRuntime = {
     runtime: 'cloudflare-workers',
@@ -17,41 +19,34 @@ export const cloudflareWorkersRuntime = {
 };
 function bind(options) {
     assertRuntimeEngine('cloudflare-workers');
-    let invocation;
-    let fetch;
-    const resolve = (environment) => {
-        if (invocation && fetch)
-            return { invocation, fetch };
-        invocation = binding.invocation({
+    if (options.application.model.extensions.get(httpExecutionExtension) ===
+        undefined) {
+        throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: cloudflareWorkersRuntime.bind() requires the HTTP Execution Extension.');
+    }
+    let application;
+    let initialization;
+    const resolve = async (environment) => {
+        application ??= createKernelApplication({
+            ...options,
             application: options.application,
+            capabilities: [
+                bindApplicationCapability(options.application.model, 'http.server', {
+                    runtime: 'cloudflare-workers',
+                }),
+                ...(options.capabilities ?? []),
+            ],
             environment,
-            ...('arguments' in options ? { arguments: options.arguments } : {}),
         });
-        const http = 'http' in invocation
-            ? invocation.http
-            : undefined;
-        if (!http) {
-            void invocation.application.close();
-            throw new Error('LUTRE_RUNTIME_HTTP_REQUIRED: cloudflareWorkersRuntime.bind() requires an HTTP-capable Application.');
-        }
-        fetch = createCloudflareWorkersFetchDriver(http);
-        return { invocation, fetch };
+        initialization ??= application.init();
+        await initialization;
+        return application.http;
     };
     return {
         async fetch(request, environment) {
-            const resolved = resolve(environment);
-            return resolved.fetch(request);
+            return (await resolve(environment)).fetch(request);
         },
         async close(signal) {
-            await invocation?.application.close(signal);
+            await application?.close(signal);
         },
     };
 }
-function createCloudflareWorkersFetchDriver(application) {
-    let initialization;
-    return async (request) => {
-        initialization ??= application.initialize();
-        await initialization;
-        return application.handle(request);
-    };
-}

package/dist/adapters/deno.d.ts

@@ -1,9 +1,12 @@
-import { type ApplicationDefinition, type BootstrapArguments, type HasHttp, type HostBindingApplication } from '../application/index.js';
-type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
-type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
+import { type ApplicationDefinition, type BootstrapArguments, type KernelHostedApplication, type RequireApplicationExtension } from '../application/index.js';
+import type { RuntimeCapabilityBinding } from '../core/index.js';
+import { httpExecutionExtension } from '../http/index.js';
+type HttpApplication<TDefinition extends ApplicationDefinition> = RequireApplicationExtension<TDefinition, typeof httpExecutionExtension>;
 export type DenoRuntimeOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
     readonly environment?: unknown;
+    readonly capabilities?: readonly RuntimeCapabilityBinding[];
+    readonly forceShutdownTimeoutMs?: number;
 } & BootstrapArguments<TDefinition>;
 export type DenoCreateOptions<TDefinition extends ApplicationDefinition> = DenoRuntimeOptions<TDefinition>;
 export interface DenoServeOptions {
@@ -18,7 +21,7 @@ export interface DenoBinding {
 export interface DenoListenerHandle {
     readonly port: number;
 }
-export type DenoRuntimeApplication<TDefinition extends ApplicationDefinition = ApplicationDefinition> = HostBindingApplication<TDefinition> & {
+export type DenoRuntimeApplication<TDefinition extends ApplicationDefinition = ApplicationDefinition> = KernelHostedApplication<TDefinition> & {
     serve(options?: DenoServeOptions): Promise<DenoListenerHandle>;
 };
 export declare const denoRuntime: {