alepha 0.18.2 → 0.18.3

package/src/server/links/index.browser.ts

@@ -5,7 +5,6 @@ import { $client } from "./primitives/$client.ts";
 import { $remote } from "./primitives/$remote.ts";
 import { LinkProvider } from "./providers/LinkProvider.ts";
 import { BatchCollector } from "./services/BatchCollector.ts";
-import { DefinitionsPool } from "./services/DefinitionsPool.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -16,7 +15,6 @@ export * from "./primitives/$remote.ts";
 export * from "./providers/LinkProvider.ts";
 export * from "./schemas/apiLinksResponseSchema.ts";
 export * from "./services/BatchCollector.ts";
-export * from "./services/DefinitionsPool.ts";
 
 // ---------------------------------------------------------------- -----------------------------------------------------
 
@@ -24,5 +22,5 @@ export const AlephaServerLinks = $module({
   name: "alepha.server.links",
   atoms: [apiLinksAtom, linkOptionsAtom],
   primitives: [$remote, $client],
-  services: [LinkProvider, BatchCollector, DefinitionsPool],
+  services: [LinkProvider, BatchCollector],
 });

package/src/server/links/index.ts

@@ -9,7 +9,6 @@ import { RemotePrimitiveProvider } from "./providers/RemotePrimitiveProvider.ts"
 import { ServerLinksProvider } from "./providers/ServerLinksProvider.ts";
 import type { ApiRegistryResponse } from "./schemas/apiLinksResponseSchema.ts";
 import { BatchCollector } from "./services/BatchCollector.ts";
-import { DefinitionsPool } from "./services/DefinitionsPool.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -22,7 +21,6 @@ export * from "./providers/RemotePrimitiveProvider.ts";
 export * from "./providers/ServerLinksProvider.ts";
 export * from "./schemas/apiLinksResponseSchema.ts";
 export * from "./services/BatchCollector.ts";
-export * from "./services/DefinitionsPool.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -69,6 +67,5 @@ export const AlephaServerLinks = $module({
     RemotePrimitiveProvider,
     LinkProvider,
     BatchCollector,
-    DefinitionsPool,
   ],
 });

package/src/server/links/providers/LinkProvider.spec.ts

@@ -40,13 +40,9 @@ describe("LinkProvider", () => {
 
     expect(data).toStrictEqual({
       prefix: "/api",
-      definitions: {
-        $0: '{"type":"object","required":["pong"],"properties":{"pong":{"type":"boolean"}},"additionalProperties":false}',
-      },
       actions: {
         ping: {
           path: "/ping",
-          response: "$0",
         },
       },
     });
@@ -114,13 +110,13 @@ describe("LinkProvider", () => {
     expect(data.actions.createUser.method).toBe("POST");
   });
 
-  it("should deduplicate schemas in definitions pool", async ({ expect }) => {
-    const responseSchema = t.object({ id: t.integer(), name: t.text() });
-
-    class DedupeApp {
+  it("should not include definitions or schema refs in registry", async ({
+    expect,
+  }) => {
+    class SchemaApp {
       getUser = $action({
         path: "/users/:id",
-        schema: { response: responseSchema },
+        schema: { response: t.object({ id: t.integer(), name: t.text() }) },
         handler: () => ({ id: 1, name: "John" }),
       });
       updateUser = $action({
@@ -128,13 +124,13 @@ describe("LinkProvider", () => {
         path: "/users/:id",
         schema: {
           body: t.object({ name: t.text() }),
-          response: responseSchema,
+          response: t.object({ id: t.integer(), name: t.text() }),
         },
         handler: () => ({ id: 1, name: "John" }),
       });
     }
 
-    const alepha = Alepha.create().with(DedupeApp).with(ServerLinksProvider);
+    const alepha = Alepha.create().with(SchemaApp).with(ServerLinksProvider);
     await alepha.start();
 
     const res = await fetch(
@@ -142,16 +138,11 @@ describe("LinkProvider", () => {
     );
     const data = await res.json();
 
-    // Both actions should reference the same definition for response
-    expect(data.actions.getUser.response).toBe(
-      data.actions.updateUser.response,
-    );
-
-    // The body schema is different, so it gets a separate definition
-    expect(data.actions.updateUser.body).toBeDefined();
-    expect(data.actions.updateUser.body).not.toBe(
-      data.actions.updateUser.response,
-    );
+    expect(data.definitions).toBeUndefined();
+    expect(data.actions.getUser.body).toBeUndefined();
+    expect(data.actions.getUser.response).toBeUndefined();
+    expect(data.actions.updateUser.body).toBeUndefined();
+    expect(data.actions.updateUser.response).toBeUndefined();
   });
 
   it("should not include group or rawSchema in wire format", async ({

package/src/server/links/providers/LinkProvider.ts

@@ -1,12 +1,4 @@
-import {
-  $inject,
-  $use,
-  Alepha,
-  AlephaError,
-  type Async,
-  jsonSchemaToTypeBox,
-  t,
-} from "alepha";
+import { $inject, $use, Alepha, AlephaError, type Async, t } from "alepha";
 import { $logger } from "alepha/logger";
 import type { SecureOptions } from "alepha/security";
 import {
@@ -21,7 +13,11 @@ import {
   type ServerRequest,
   type ServerRequestConfigEntry,
   type ServerResponseBody,
-  type TRequestBody,
+  type SseConfigSchema,
+  type SseEventData,
+  type SsePrimitive,
+  type SseRequestEntry,
+  type SseStream,
   UnauthorizedError,
 } from "alepha/server";
 import { linkOptionsAtom } from "../atoms/linkOptionsAtom.ts";
@@ -49,7 +45,6 @@ export class LinkProvider {
   // Browser/SSR: parsed from the registry response
   protected actionMap = new Map<string, HttpClientLink>();
   protected permissions = new Set<string>();
-  protected definitions: Record<string, string> = {};
   protected lastLoadedRegistry: ApiRegistryResponse | null = null;
 
   // Browser-only: batch collector for coalescing multiple calls
@@ -106,7 +101,6 @@ export class LinkProvider {
    */
   protected loadRegistry(registry: ApiRegistryResponse): void {
     this.lastLoadedRegistry = registry;
-    this.definitions = registry.definitions ?? {};
     this.permissions.clear();
     this.actionMap.clear();
 
@@ -114,12 +108,10 @@ export class LinkProvider {
       this.actionMap.set(name, {
         name,
         path: action.path,
+        kind: action.kind,
         method: action.method,
         contentType: action.contentType,
         service: action.service,
-        // Store definition refs for lazy schema resolution
-        bodyRef: action.body,
-        responseRef: action.response,
       });
     }
 
@@ -320,36 +312,6 @@ export class LinkProvider {
       return this.can(name);
     };
 
-    $.schema = () => {
-      const link = this.links.find((l) => l.name === name);
-      if (!link) {
-        throw new AlephaError(`Link ${name} not found.`);
-      }
-
-      // If schema is already resolved (server-side), return it
-      if (link.schema) {
-        return link.schema as { body: any; response: any };
-      }
-
-      // Lazy resolve from definition refs (browser-side)
-      const resolved: RequestConfigSchema = {};
-      if (link.bodyRef && this.definitions[link.bodyRef]) {
-        resolved.body = jsonSchemaToTypeBox(
-          JSON.parse(this.definitions[link.bodyRef]),
-        ) as TRequestBody;
-      }
-      if (link.responseRef && this.definitions[link.responseRef]) {
-        resolved.response = jsonSchemaToTypeBox(
-          JSON.parse(this.definitions[link.responseRef]),
-        ) as TRequestBody;
-      }
-
-      // Cache for next access
-      link.schema = resolved;
-
-      return resolved as { body: any; response: any };
-    };
-
     return $;
   }
 
@@ -441,6 +403,7 @@ export interface HttpClientLink {
   name: string;
   path: string;
   method?: string;
+  kind?: string;
   contentType?: string;
   service?: string;
   secured?: boolean | SecureOptions;
@@ -453,9 +416,6 @@ export interface HttpClientLink {
     request: ServerRequest,
     options: ClientRequestOptions,
   ) => Async<ServerResponseBody>;
-  // -- browser only (definition refs for lazy schema resolution) --
-  bodyRef?: string;
-  responseRef?: string;
 }
 
 export interface ClientScope {
@@ -469,6 +429,12 @@ export type HttpVirtualClient<T> = {
     : never]: T[K] extends ActionPrimitive<infer Schema>
     ? VirtualAction<Schema>
     : never;
+} & {
+  [K in keyof T as T[K] extends SsePrimitive<SseConfigSchema>
+    ? K
+    : never]: T[K] extends SsePrimitive<infer Schema>
+    ? VirtualSse<Schema>
+    : never;
 };
 
 export interface VirtualAction<T extends RequestConfigSchema>
@@ -478,8 +444,10 @@ export interface VirtualAction<T extends RequestConfigSchema>
     opts?: ClientRequestOptions,
   ): Promise<ClientRequestResponse<T>>;
   can: () => boolean;
-  schema: () => {
-    body: T["body"];
-    response: T["response"];
-  };
+}
+
+export interface VirtualSse<T extends SseConfigSchema> {
+  (config?: SseRequestEntry<T>): Promise<SseStream<SseEventData<T>>>;
+  name: string;
+  can: () => boolean;
 }

package/src/server/links/providers/ServerLinksProvider.spec.ts

@@ -366,6 +366,112 @@ describe("ServerLinksProvider", () => {
     });
   });
 
+  describe("schemas endpoint", () => {
+    it("should return schemas for requested actions", async ({ expect }) => {
+      class App {
+        ping = $action({
+          schema: {
+            body: t.object({ message: t.text() }),
+            response: t.object({ pong: t.boolean() }),
+          },
+          handler: () => ({ pong: true }),
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const res = await fetch(
+        `${alepha.inject(ServerProvider).hostname}/api/_links/schemas`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ actions: ["ping"] }),
+        },
+      );
+
+      const data = await res.json();
+
+      expect(data.ping).toBeDefined();
+      expect(data.ping.body).toBeDefined();
+      expect(data.ping.response).toBeDefined();
+      expect(JSON.parse(data.ping.body).type).toBe("object");
+      expect(JSON.parse(data.ping.response).type).toBe("object");
+    });
+
+    it("should return empty for unknown actions", async ({ expect }) => {
+      class App {
+        ping = $action({
+          schema: { response: t.text() },
+          handler: () => "pong",
+        });
+      }
+
+      const alepha = Alepha.create().with(App).with(ServerLinksProvider);
+      await alepha.start();
+
+      const res = await fetch(
+        `${alepha.inject(ServerProvider).hostname}/api/_links/schemas`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ actions: ["nonexistent"] }),
+        },
+      );
+
+      const data = await res.json();
+
+      expect(data.nonexistent).toBeUndefined();
+    });
+
+    it("should filter based on user permissions", async ({ expect }) => {
+      class App {
+        publicAction = $action({
+          schema: {
+            body: t.object({ name: t.text() }),
+            response: t.text(),
+          },
+          handler: () => "PUBLIC",
+        });
+        securedAction = $action({
+          use: [$secure()],
+          schema: {
+            body: t.object({ secret: t.text() }),
+            response: t.text(),
+          },
+          handler: () => "SECURED",
+        });
+        issuer = $issuer({
+          secret: "test",
+          roles: [{ name: "user", permissions: [{ name: "*" }] }],
+        });
+      }
+
+      const alepha = Alepha.create()
+        .with(App)
+        .with(ServerLinksProvider)
+        .with(AlephaSecurity);
+      await alepha.start();
+
+      // Unauthenticated request — should only get public schema
+      const res = await fetch(
+        `${alepha.inject(ServerProvider).hostname}/api/_links/schemas`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            actions: ["publicAction", "securedAction"],
+          }),
+        },
+      );
+
+      const data = await res.json();
+
+      expect(data.publicAction).toBeDefined();
+      expect(data.securedAction).toBeUndefined();
+    });
+  });
+
   describe("caching and ETag", () => {
     it("should return ETag header on first request", async ({ expect }) => {
       class App {

package/src/server/links/providers/ServerLinksProvider.ts

@@ -5,6 +5,7 @@ import type { SecurityProvider, UserAccountToken } from "alepha/security";
 import {
   $action,
   $route,
+  $sse,
   type ClientRequestEntry,
   type ClientRequestOptions,
   type RequestConfigSchema,
@@ -12,8 +13,7 @@ import {
   serverApiOptions,
 } from "alepha/server";
 import type { ApiRegistryResponse } from "../schemas/apiLinksResponseSchema.ts";
-import { DefinitionsPool } from "../services/DefinitionsPool.ts";
-import { LinkProvider } from "./LinkProvider.ts";
+import { type HttpClientLink, LinkProvider } from "./LinkProvider.ts";
 import { RemotePrimitiveProvider } from "./RemotePrimitiveProvider.ts";
 
 export class ServerLinksProvider {
@@ -68,6 +68,24 @@ export class ServerLinksProvider {
           ) => action.run(config, options),
         });
       }
+
+      // convert all $sse to local links
+      for (const sse of this.alepha.primitives($sse)) {
+        this.linkProvider.registerLink({
+          name: sse.name,
+          group: sse.group,
+          kind: "sse",
+          schema: {
+            body: sse.schema?.body,
+          },
+          method: "POST",
+          prefix: sse.prefix,
+          path: sse.path,
+          handler: async (config) => {
+            return sse.run(config as any) as any;
+          },
+        });
+      }
     },
   });
 
@@ -127,6 +145,51 @@ export class ServerLinksProvider {
     },
   });
 
+  /**
+   * On-demand schemas endpoint — returns JSON Schemas for requested actions.
+   *
+   * Schemas are filtered by the user's permissions (same logic as the registry).
+   */
+  public readonly schemas = $route({
+    method: "POST",
+    path: "/api/_links/schemas",
+    schema: {
+      body: t.object({
+        actions: t.array(t.text()),
+      }),
+      response: t.record(
+        t.text(),
+        t.object({
+          body: t.optional(t.string()),
+          response: t.optional(t.string()),
+        }),
+      ),
+    },
+    handler: async ({ body, user }) => {
+      const result: Record<string, { body?: string; response?: string }> = {};
+
+      for (const name of body.actions) {
+        const link = this.linkProvider
+          .getServerLinks()
+          .find((l) => l.name === name && !l.host);
+
+        if (!link) continue;
+        if (!this.isLinkAccessible(link, user)) continue;
+
+        const entry: { body?: string; response?: string } = {};
+        if (link.schema?.body) {
+          entry.body = JSON.stringify(link.schema.body);
+        }
+        if (link.schema?.response) {
+          entry.response = JSON.stringify(link.schema.response);
+        }
+        result[name] = entry;
+      }
+
+      return result as any;
+    },
+  });
+
   /**
    * Batch endpoint — execute multiple actions in a single HTTP request.
    * Each sub-request is independent: errors in one don't affect others.
@@ -208,7 +271,6 @@ export class ServerLinksProvider {
         ? securityProvider.getPermissions(user)
         : undefined;
 
-    const pool = new DefinitionsPool();
     const actions: Record<string, any> = {};
     const permissions: string[] = [];
 
@@ -228,56 +290,12 @@ export class ServerLinksProvider {
     for (const link of this.linkProvider.getServerLinks()) {
       // SKIP REMOTE LINKS, remote links are handled separately for security
       if (link.host) continue;
-
-      if (securityProvider && link.secured) {
-        // skip secured links if user is not provided
-        if (!user) {
-          continue;
-        }
-
-        if (typeof link.secured === "object") {
-          // issuer check
-          if (
-            link.secured.issuers?.length &&
-            (!user.realm || !link.secured.issuers.includes(user.realm))
-          ) {
-            continue;
-          }
-
-          // role check
-          if (link.secured.roles?.length) {
-            const hasRole = link.secured.roles.some((role: string) =>
-              user.roles?.includes(role),
-            );
-            if (!hasRole) continue;
-          }
-
-          // explicit permission check
-          if (link.secured.permissions?.length) {
-            const perms = link.secured.permissions;
-
-            let allowed = true;
-            for (const perm of perms) {
-              const result = securityProvider.checkPermission(
-                perm,
-                ...(user.roles ?? []),
-              );
-              if (!result.isAuthorized) {
-                allowed = false;
-                break;
-              }
-            }
-            if (!allowed) continue;
-          }
-        }
-        // link.secured === true → auth only, user is already checked above
-      }
+      if (!this.isLinkAccessible(link, user)) continue;
 
       actions[link.name] = {
         path: link.path,
         method: link.method || undefined,
-        body: pool.ref(link.schema?.body),
-        response: pool.ref(link.schema?.response),
+        kind: link.kind,
         contentType: link.contentType,
         service: link.service,
       };
@@ -298,20 +316,6 @@ export class ServerLinksProvider {
     for (const { remote, registry } of remoteResults) {
       const remotePrefix = registry.prefix ?? "/api";
 
-      // Merge remote definitions into our pool
-      const remoteDefMap = new Map<string, string>();
-      if (registry.definitions) {
-        for (const [refKey, jsonString] of Object.entries(
-          registry.definitions,
-        )) {
-          const schema = JSON.parse(jsonString);
-          const newRef = pool.ref(schema);
-          if (newRef) {
-            remoteDefMap.set(refKey, newRef);
-          }
-        }
-      }
-
       // Merge remote actions
       for (const [name, action] of Object.entries(registry.actions)) {
         let path = action.path.replace(remotePrefix, "");
@@ -322,12 +326,6 @@ export class ServerLinksProvider {
         actions[name] = {
           path,
           method: action.method,
-          body: action.body
-            ? (remoteDefMap.get(action.body) ?? action.body)
-            : undefined,
-          response: action.response
-            ? (remoteDefMap.get(action.response) ?? action.response)
-            : undefined,
           contentType: action.contentType,
           service: remote.name,
         };
@@ -341,16 +339,58 @@ export class ServerLinksProvider {
 
     this.serverTimingProvider.endTiming("fetchRemoteLinks");
 
-    const definitions = pool.toJSON();
-
     return {
       prefix: this.serverApi.prefix,
-      definitions:
-        Object.keys(definitions).length > 0 ? definitions : undefined,
       actions,
       permissions: permissions.length > 0 ? permissions : undefined,
     };
   }
+
+  /**
+   * Check if a link is accessible by the given user based on security rules.
+   */
+  protected isLinkAccessible(
+    link: HttpClientLink,
+    user?: UserAccountToken,
+  ): boolean {
+    const { securityProvider } = this;
+
+    if (securityProvider && link.secured) {
+      if (!user) return false;
+
+      if (typeof link.secured === "object") {
+        // issuer check
+        if (
+          link.secured.issuers?.length &&
+          (!user.realm || !link.secured.issuers.includes(user.realm))
+        ) {
+          return false;
+        }
+
+        // role check
+        if (link.secured.roles?.length) {
+          const hasRole = link.secured.roles.some((role: string) =>
+            user.roles?.includes(role),
+          );
+          if (!hasRole) return false;
+        }
+
+        // explicit permission check
+        if (link.secured.permissions?.length) {
+          for (const perm of link.secured.permissions) {
+            const result = securityProvider.checkPermission(
+              perm,
+              ...(user.roles ?? []),
+            );
+            if (!result.isAuthorized) return false;
+          }
+        }
+      }
+      // link.secured === true → auth only, user is already checked above
+    }
+
+    return true;
+  }
 }
 
 export interface GetApiLinksOptions {

package/src/server/links/schemas/apiLinksResponseSchema.ts

@@ -13,24 +13,17 @@ export const apiActionSchema = t.object({
     }),
   ),
 
-  body: t.optional(
-    t.text({
-      description:
-        "Reference to a definitions pool entry (e.g. '$0') for the request body JSON Schema.",
-    }),
-  ),
-
-  response: t.optional(
+  contentType: t.optional(
     t.text({
       description:
-        "Reference to a definitions pool entry (e.g. '$0') for the response JSON Schema.",
+        "Content type for the request body. Only present for non-JSON types (e.g. 'multipart/form-data'). When absent, defaults to application/json.",
     }),
   ),
 
-  contentType: t.optional(
+  kind: t.optional(
     t.text({
       description:
-        "Content type for the request body. Only present for non-JSON types (e.g. 'multipart/form-data'). When absent, defaults to application/json.",
+        "Action kind. Used to distinguish special action types (e.g. 'sse' for Server-Sent Events streams).",
     }),
   ),
 
@@ -45,16 +38,6 @@ export const apiActionSchema = t.object({
 export const apiRegistryResponseSchema = t.object({
   prefix: t.optional(t.text()),
 
-  definitions: t.optional(
-    t.record(
-      t.text(),
-      t.string({
-        description:
-          "Pre-stringified JSON Schema. Values can be 2KB+, so t.string() (no maxLength) is used instead of t.text().",
-      }),
-    ),
-  ),
-
   actions: t.record(t.text(), apiActionSchema),
 
   permissions: t.optional(t.array(t.text())),

package/src/server/links/services/BatchCollector.ts

@@ -1,4 +1,5 @@
 import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
 import { HttpClient, HttpError } from "alepha/server";
 
 /**
@@ -15,6 +16,7 @@ import { HttpClient, HttpError } from "alepha/server";
 export class BatchCollector {
   protected static readonly MAX_BATCH_SIZE = 20;
 
+  protected readonly log = $logger();
   protected readonly httpClient = $inject(HttpClient);
 
   protected pending: PendingBatchEntry[] = [];
@@ -29,10 +31,10 @@ export class BatchCollector {
 
       if (!this.scheduled) {
         this.scheduled = true;
-        queueMicrotask(() => {
+        setTimeout(() => {
           this.scheduled = false;
-          this.flush();
-        });
+          this.flush().catch((err) => this.log.error(err));
+        }, 10);
       }
     });
   }