alepha 0.14.4 → 0.15.1

package/src/server/auth/primitives/$authCredentials.ts

@@ -1,5 +1,5 @@
 import { AlephaError } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type CredentialsFn,
@@ -13,7 +13,7 @@ import {
  * Uses username and password to authenticate users.
  */
 export const $authCredentials = (
-  realm: RealmPrimitive & WithLoginFn,
+  realm: IssuerPrimitive & WithLoginFn,
   options: Partial<CredentialsOptions> = {},
 ) => {
   const name = "credentials";
@@ -29,7 +29,7 @@ export const $authCredentials = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     credentials: {
       account,

package/src/server/auth/primitives/$authGithub.ts

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import type { OAuth2Profile } from "../providers/ServerAuthProvider.ts";
 import {
   $auth,
@@ -19,7 +19,7 @@ import {
  * - `GITHUB_CLIENT_SECRET`: The client secret obtained from the GitHub Developer Settings.
  */
 export const $authGithub = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -45,7 +45,7 @@ export const $authGithub = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oauth: {
       clientId: env.GITHUB_CLIENT_ID!,

package/src/server/auth/primitives/$authGoogle.ts

@@ -1,5 +1,5 @@
 import { $context, AlephaError, t } from "alepha";
-import type { RealmPrimitive } from "alepha/security";
+import type { IssuerPrimitive } from "alepha/security";
 import {
   $auth,
   type LinkAccountFn,
@@ -18,7 +18,7 @@ import {
  * - `GOOGLE_CLIENT_SECRET`: The client secret obtained from the Google Developer Console.
  */
 export const $authGoogle = (
-  realm: RealmPrimitive & WithLinkFn,
+  realm: IssuerPrimitive & WithLinkFn,
   options: Partial<OidcOptions> = {},
 ) => {
   const { alepha } = $context();
@@ -44,7 +44,7 @@ export const $authGoogle = (
   }
 
   return $auth({
-    realm,
+    issuer: realm,
     name,
     oidc: {
       issuer: "https://accounts.google.com",

package/src/server/auth/providers/ServerAuthProvider.ts

@@ -71,8 +71,8 @@ export class ServerAuthProvider {
 
     for (const identity of this.identities) {
       if (filters.realmName) {
-        const realm = "realm" in identity.options && identity.options.realm;
-        if (!realm || realm.name !== filters.realmName) {
+        const issuer = identity.issuer;
+        if (!issuer || issuer.name !== filters.realmName) {
           continue;
         }
       }
@@ -145,7 +145,7 @@ export class ServerAuthProvider {
       // [feature] support for auth providers with fallback
       if (!request.headers.authorization) {
         for (const provider of this.identities) {
-          if (!("realm" in provider.options) && !!provider.options.fallback) {
+          if ("fallback" in provider.options && !!provider.options.fallback) {
             const token = await provider.options.fallback();
             if (token) {
               request.headers.authorization = `Bearer ${token}`;
@@ -340,8 +340,8 @@ export class ServerAuthProvider {
         realm: query.realm,
       });
 
-      const realm = "realm" in provider.options && provider.options.realm;
-      if (!realm) {
+      const issuer = provider.issuer;
+      if (!issuer) {
         throw new SecurityError(
           `Auth provider '${query.provider}' does not support password grant`,
         );
@@ -373,7 +373,7 @@ export class ServerAuthProvider {
 
       const tokens = {
         provider: query.provider,
-        ...(await realm.createToken(user)),
+        ...(await issuer.createToken(user)),
       };
 
       // for web applications, we store tokens in cookies
@@ -519,10 +519,10 @@ export class ServerAuthProvider {
 
       this.authorizationCode.del({ cookies });
 
-      const realm = "realm" in provider.options && provider.options.realm;
+      const issuer = provider.issuer;
 
       // external, full OIDC System (e.g. Keycloak, Auth0)
-      if (!realm) {
+      if (!issuer) {
         this.setTokens(externalTokens, cookies);
         reply.redirect(redirectUri);
         return;
@@ -531,7 +531,7 @@ export class ServerAuthProvider {
       // internal, we need to create our own tokens
 
       const user = await provider.user(externalTokens);
-      const tokens = await realm.createToken(user);
+      const tokens = await issuer.createToken(user);
 
       this.setTokens(
         {
@@ -570,9 +570,9 @@ export class ServerAuthProvider {
       this.tokens.del({ cookies });
 
       // for internal providers, we can delete the session - if available
-      if ("realm" in provider.options && tokens.refresh_token) {
+      if (provider.issuer && tokens.refresh_token) {
         const onDeleteSession =
-          provider.options.realm.options.settings?.onDeleteSession;
+          provider.issuer.options.settings?.onDeleteSession;
         if (onDeleteSession) {
           try {
             await onDeleteSession(tokens.refresh_token);
@@ -635,8 +635,8 @@ export class ServerAuthProvider {
         return false;
       }
 
-      // If realm filter is specified, match against provider's realm
-      if (realmName && identity.realm?.name !== realmName) {
+      // If realm filter is specified, match against provider's issuer
+      if (realmName && identity.issuer?.name !== realmName) {
         return false;
       }
 

package/src/server/cache/providers/ServerCacheProvider.ts

@@ -204,7 +204,7 @@ export class ServerCacheProvider {
 
   protected readonly onSend = $hook({
     on: "server:onSend",
-    handler: async ({ route, request }) => {
+    handler: ({ route, request }) => {
       // before sending the response, check if the ETag matches
       // and if so, return a 304 Not Modified response
       // -> this is only relevant for etag-only routes, not cached routes <-

package/src/server/cookies/providers/ServerCookiesProvider.ts

@@ -48,7 +48,7 @@ export class ServerCookiesProvider {
 
   public readonly onRequest = $hook({
     on: "server:onRequest",
-    handler: async ({ request }) => {
+    handler: ({ request }) => {
       request.cookies = {
         req: this.cookieParser.parseRequestCookies(
           request.headers.cookie ?? "",
@@ -60,7 +60,7 @@ export class ServerCookiesProvider {
 
   public readonly onAction = $hook({
     on: "action:onRequest",
-    handler: async ({ request }) => {
+    handler: ({ request }) => {
       request.cookies = {
         req: this.cookieParser.parseRequestCookies(
           request.headers.cookie ?? "",
@@ -72,7 +72,7 @@ export class ServerCookiesProvider {
 
   public readonly onSend = $hook({
     on: "server:onSend",
-    handler: async ({ request }) => {
+    handler: ({ request }) => {
       if (request.cookies && Object.keys(request.cookies.res).length > 0) {
         const setCookieHeaders = this.cookieParser.serializeResponseCookies(
           request.cookies.res,

package/src/server/core/index.ts

@@ -141,7 +141,7 @@ export const AlephaServer = $module({
     ServerRouterProvider,
   ],
   register: (alepha: Alepha) => {
-    if (!alepha.isServerless() && !alepha.isViteDev()) {
+    if (!alepha.isServerless()) {
       if (alepha.isBun()) {
         alepha.with({
           optional: true,

package/src/server/core/providers/BunHttpServerProvider.ts

@@ -107,7 +107,7 @@ export class BunHttpServerProvider extends ServerProvider {
         },
       });
 
-      this.log.info(`Server listening on ${this.hostname}`);
+      this.log.info(`Server listening on ${this.hostname}/`);
     } catch (err) {
       this.log.error("Failed to start Bun server", err);
       throw err;

package/src/server/core/providers/NodeHttpServerProvider.spec.ts

@@ -0,0 +1,125 @@
+import { Alepha } from "alepha";
+import { afterEach, describe, expect, test } from "vitest";
+import { NodeHttpServerProvider } from "./NodeHttpServerProvider.ts";
+
+describe("NodeHttpServerProvider", () => {
+  describe("graceful shutdown", () => {
+    let alepha: Alepha;
+    let server: NodeHttpServerProvider;
+
+    afterEach(async () => {
+      await alepha?.stop().catch(() => {});
+    });
+
+    test("dev mode: destroys connections immediately on close", async () => {
+      alepha = Alepha.create({ env: { NODE_ENV: "development" } });
+      alepha.with(NodeHttpServerProvider);
+
+      await alepha.start();
+      server = alepha.inject(NodeHttpServerProvider);
+
+      // Make a request to establish connection
+      await fetch(`${server.hostname}/`);
+
+      const startTime = Date.now();
+      await alepha.stop();
+      const elapsed = Date.now() - startTime;
+
+      // Should close instantly (under 100ms)
+      expect(elapsed).toBeLessThan(100);
+      expect(server.getConnectionsCount()).toBe(0);
+    });
+
+    test("production mode: waits for connections then closes", async () => {
+      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha.with(NodeHttpServerProvider);
+
+      await alepha.start();
+      server = alepha.inject(NodeHttpServerProvider);
+      server.options.shutdownTimeout = 500;
+
+      // Make a request to establish keep-alive connection
+      await fetch(`${server.hostname}/`);
+
+      const startTime = Date.now();
+      await alepha.stop();
+      const elapsed = Date.now() - startTime;
+
+      // In production, should not be instant (waits for graceful close or timeout)
+      // But should complete within timeout
+      expect(elapsed).toBeLessThan(server.options.shutdownTimeout + 100);
+      expect(server.getConnectionsCount()).toBe(0);
+    });
+
+    test("production mode: forces close after timeout", async () => {
+      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha.with(NodeHttpServerProvider);
+
+      await alepha.start();
+      server = alepha.inject(NodeHttpServerProvider);
+      server.options.shutdownTimeout = 50;
+
+      // Make a request to establish connection
+      await fetch(`${server.hostname}/`);
+
+      const startTime = Date.now();
+      await alepha.stop();
+      const elapsed = Date.now() - startTime;
+
+      // Should close around timeout
+      expect(elapsed).toBeLessThan(200);
+      expect(server.getConnectionsCount()).toBe(0);
+    });
+
+    test("connections are tracked and cleared", async () => {
+      alepha = Alepha.create({ env: { NODE_ENV: "development" } });
+      alepha.with(NodeHttpServerProvider);
+
+      await alepha.start();
+      server = alepha.inject(NodeHttpServerProvider);
+
+      // Make multiple requests
+      await fetch(`${server.hostname}/`);
+      await fetch(`${server.hostname}/`);
+
+      await alepha.stop();
+
+      // All connections cleared after stop
+      expect(server.getConnectionsCount()).toBe(0);
+    });
+
+    test("rejects new requests during shutdown", async () => {
+      alepha = Alepha.create({ env: { NODE_ENV: "production" } });
+      alepha.with(NodeHttpServerProvider);
+
+      await alepha.start();
+      server = alepha.inject(NodeHttpServerProvider);
+      server.options.shutdownTimeout = 500;
+
+      // Establish a connection to keep server busy
+      await fetch(`${server.hostname}/`);
+
+      // Start shutdown (don't await yet)
+      const stopPromise = alepha.stop();
+
+      // Give server.close() time to be called
+      await new Promise((r) => setTimeout(r, 10));
+
+      // New request should fail (server no longer accepting connections)
+      let error: Error | null = null;
+      try {
+        await fetch(`${server.hostname}/`, {
+          signal: AbortSignal.timeout(100),
+        });
+      } catch (e) {
+        error = e as Error;
+      }
+
+      // Should get a connection error (ECONNREFUSED or similar)
+      expect(error).not.toBeNull();
+
+      // Wait for shutdown to complete
+      await stopPromise;
+    });
+  });
+});

package/src/server/core/providers/NodeHttpServerProvider.ts

@@ -4,6 +4,7 @@ import {
   type Server,
   type ServerResponse,
 } from "node:http";
+import type { Socket } from "node:net";
 import { $env, $hook, $inject, Alepha, type Static, t } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -34,6 +35,24 @@ export class NodeHttpServerProvider extends ServerProvider {
   protected readonly env = $env(envSchema);
   protected readonly router = $inject(ServerRouterProvider);
 
+  /** Track active connections for fast shutdown */
+  protected readonly connections = new Set<Socket>();
+
+  /** Get number of active connections */
+  public getConnectionsCount(): number {
+    return this.connections.size;
+  }
+
+  /** Server options */
+  public readonly options = {
+    /**
+     * Graceful shutdown timeout in ms.
+     * After this, remaining connections are forcefully closed.
+     * @default 30000
+     */
+    shutdownTimeout: 10000,
+  };
+
   public get hostname(): string {
     if (this.server.listening) {
       const address = this.server.address();
@@ -44,13 +63,29 @@ export class NodeHttpServerProvider extends ServerProvider {
     return `http://${this.env.SERVER_HOST}:${this.env.SERVER_PORT}`;
   }
 
+  // Pre-bound error handler to avoid function allocation per request
+  protected readonly handleRequestError = (res: ServerResponse, err: Error) => {
+    this.log.error("Error handling request", err);
+    res.statusCode = 500;
+    res.end("Internal Server Error");
+  };
+
+  // P3: Pre-allocated event object to avoid { req, res } allocation per request
+  // Safe because handleNodeRequest completes before the next request reuses this object
+  protected readonly nodeRequestEvent = {
+    req: null as unknown as IncomingMessage,
+    res: null as unknown as ServerResponse,
+  };
+
   public readonly server = this.createHttpServer((req, res) => {
-    this.log.trace(`Incoming Node.js message -> ${req.url}`);
-    this.handleNodeRequest({ req, res }).catch((err) => {
-      this.log.error("Error handling request", err);
-      res.statusCode = 500;
-      res.end("Internal Server Error");
-    });
+    // Reuse pre-allocated event object instead of creating { req, res } per request
+    const ev = this.nodeRequestEvent;
+    ev.req = req;
+    ev.res = res;
+    // Note: handleNodeRequest returns a promise that resolves after response is sent
+    this.handleNodeRequest(ev).catch((err) =>
+      this.handleRequestError(res, err),
+    );
   });
 
   public readonly start = $hook({
@@ -64,25 +99,27 @@ export class NodeHttpServerProvider extends ServerProvider {
   protected createHttpServer(
     func: (req: IncomingMessage, res: ServerResponse) => void,
   ): Server {
-    return createServer(
+    const server = createServer(
       {
         // nov 25 - keep connections alive for better performance, cuz we http/1.1 by default
         keepAlive: this.alepha.isProduction(),
       },
       func,
     );
+
+    // Track connections for fast shutdown
+    server.on("connection", (socket) => {
+      this.connections.add(socket);
+      socket.on("close", () => this.connections.delete(socket));
+    });
+
+    return server;
   }
 
   protected readonly stop = $hook({
     on: "stop",
     handler: async () => {
-      if (this.alepha.isProduction()) {
-        await this.close();
-        return;
-      }
-
-      // do not await in development & test
-      this.close().catch(() => {});
+      await this.close();
     },
   });
 
@@ -96,7 +133,7 @@ export class NodeHttpServerProvider extends ServerProvider {
 
     await new Promise<void>((resolve, reject) => {
       this.server?.listen(port, this.env.SERVER_HOST, () => {
-        this.log.info(`Server listening on ${this.hostname}`);
+        this.log.info(`Server listening on ${this.hostname}/`);
         resolve();
       });
 
@@ -107,18 +144,49 @@ export class NodeHttpServerProvider extends ServerProvider {
   }
 
   protected async close() {
-    const promise = new Promise<void>((resolve, reject) => {
-      this.server?.close((err) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve();
-        }
-      });
+    // Dev/Test: instant shutdown (destroy connections immediately)
+    // Production: graceful shutdown (wait for requests to complete, then close)
+    if (!this.alepha.isProduction()) {
+      this.destroyAllConnections();
+    }
+
+    // Stop accepting new connections
+    const closePromise = new Promise<void>((resolve, reject) => {
+      this.server?.close((err) => (err ? reject(err) : resolve()));
     });
 
-    await Promise.race([this.dateTimeProvider.wait(2000), promise]);
+    if (this.alepha.isProduction() && this.connections.size > 0) {
+      // In production, wait for connections with timeout
+      const timeout = this.options.shutdownTimeout;
+
+      // Set up timeout to force-close connections
+      const timeoutId = setTimeout(() => {
+        if (this.connections.size > 0) {
+          this.log.warn(
+            `Shutdown timeout (${timeout}ms) reached, forcing ${this.connections.size} connections to close`,
+          );
+          // Destroy sockets - this triggers 'close' events which eventually resolves closePromise
+          for (const socket of this.connections) {
+            socket.destroy();
+          }
+        }
+      }, timeout);
+
+      // Wait for server to fully close (all connections closed)
+      await closePromise;
+      clearTimeout(timeoutId);
+      this.connections.clear();
+    } else {
+      await closePromise;
+    }
 
     this.log.info("Server closed");
   }
+
+  protected destroyAllConnections() {
+    for (const socket of this.connections) {
+      socket.destroy();
+    }
+    this.connections.clear();
+  }
 }

package/src/server/core/providers/ServerBodyParserProvider.ts

@@ -24,7 +24,7 @@ export class ServerBodyParserProvider {
 
   public readonly onRequest = $hook({
     on: "server:onRequest",
-    handler: async ({ route, request }) => {
+    handler: ({ route, request }) => {
       if (request.body) {
         return; // already parsed
       }
@@ -46,28 +46,24 @@ export class ServerBodyParserProvider {
       }
 
       if (route.schema?.body) {
-        try {
-          const body = await this.parse(
-            stream,
-            request.headers,
-            route.schema.body,
-          );
-          if (body) {
-            request.body = body;
-          }
-        } catch (error) {
-          if (error instanceof HttpError) {
-            throw error;
-          }
-
-          throw new HttpError(
-            {
-              status: 400,
-              message: "Failed to parse request body",
-            },
-            error,
-          );
-        }
+        return this.parse(stream, request.headers, route.schema.body)
+          .then((body) => {
+            if (body) {
+              request.body = body;
+            }
+          })
+          .catch((error) => {
+            if (error instanceof HttpError) {
+              throw error;
+            }
+            throw new HttpError(
+              {
+                status: 400,
+                message: "Failed to parse request body",
+              },
+              error,
+            );
+          });
       }
     },
   });

package/src/server/core/providers/ServerLoggerProvider.ts

@@ -9,24 +9,26 @@ export class ServerLoggerProvider {
     on: "server:onRequest",
     priority: "first",
     handler: ({ route, request }) => {
-      if (!route.silent) {
-        request.metadata.now = Date.now();
-
-        const data: Record<string, string> = {
-          method: request.method,
-          path: request.url.pathname,
-        };
-
-        if (this.alepha.isProduction()) {
-          data.agent = request.headers["user-agent"];
-          const ip = request.ip;
-          if (ip) {
-            data.ip = ip;
-          }
-        }
+      if (route.silent || request.metadata.vite) {
+        return;
+      }
+
+      request.metadata.now = Date.now();
+
+      const data: Record<string, string> = {
+        method: request.method,
+        path: request.url.pathname,
+      };
 
-        this.log.info("Incoming request", data);
+      if (this.alepha.isProduction()) {
+        data.agent = request.headers["user-agent"];
+        const ip = request.ip;
+        if (ip) {
+          data.ip = ip;
+        }
       }
+
+      this.log.info("Incoming request", data);
     },
   });
 
@@ -42,10 +44,12 @@ export class ServerLoggerProvider {
     on: "server:onResponse",
     priority: "last",
     handler: ({ route, request, response }) => {
-      if (!route.silent) {
-        const ms = Date.now() - request.metadata.now;
-        this.log.info("Request completed", { status: response.status, ms });
+      if (route.silent || request.metadata.vite) {
+        return;
       }
+
+      const ms = Date.now() - request.metadata.now;
+      this.log.info("Request completed", { status: response.status, ms });
     },
   });
 }