alepha 0.11.4 → 0.11.6

package/server/links.d.ts

@@ -1 +1,322 @@
-export * from '@alepha/server-links';
+import { ServerRouteSecure } from "alepha/server/security";
+import * as _alepha_core2 from "alepha";
+import { Alepha, Descriptor, KIND, Static } from "alepha";
+import * as _alepha_server0 from "alepha/server";
+import { ActionDescriptor, ClientRequestEntry, ClientRequestOptions, ClientRequestResponse, FetchResponse, HttpClient, RequestConfigSchema, ServerHandler, ServerRequestConfigEntry, ServerTimingProvider } from "alepha/server";
+import * as _alepha_logger0 from "alepha/logger";
+import * as _alepha_retry0 from "alepha/retry";
+import { ProxyDescriptorOptions, ServerProxyProvider } from "alepha/server/proxy";
+import { ServiceAccountDescriptor, UserAccountToken } from "alepha/security";
+import * as typebox18 from "typebox";
+
+//#region src/schemas/apiLinksResponseSchema.d.ts
+declare const apiLinkSchema: typebox18.TObject<{
+  name: typebox18.TString;
+  group: typebox18.TOptional<typebox18.TString>;
+  path: typebox18.TString;
+  method: typebox18.TOptional<typebox18.TString>;
+  requestBodyType: typebox18.TOptional<typebox18.TString>;
+  service: typebox18.TOptional<typebox18.TString>;
+}>;
+declare const apiLinksResponseSchema: typebox18.TObject<{
+  prefix: typebox18.TOptional<typebox18.TString>;
+  links: typebox18.TArray<typebox18.TObject<{
+    name: typebox18.TString;
+    group: typebox18.TOptional<typebox18.TString>;
+    path: typebox18.TString;
+    method: typebox18.TOptional<typebox18.TString>;
+    requestBodyType: typebox18.TOptional<typebox18.TString>;
+    service: typebox18.TOptional<typebox18.TString>;
+  }>>;
+}>;
+type ApiLinksResponse = Static<typeof apiLinksResponseSchema>;
+type ApiLink = Static<typeof apiLinkSchema>;
+//#endregion
+//#region src/providers/LinkProvider.d.ts
+/**
+ * Browser, SSR friendly, service to handle links.
+ */
+declare class LinkProvider {
+  static path: {
+    apiLinks: string;
+    apiSchema: string;
+  };
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly alepha: Alepha;
+  protected readonly httpClient: HttpClient;
+  protected serverLinks: Array<HttpClientLink>;
+  /**
+   * Get applicative links registered on the server.
+   * This does not include lazy-loaded remote links.
+   */
+  getServerLinks(): HttpClientLink[];
+  /**
+   * Register a new link for the application.
+   */
+  registerLink(link: HttpClientLink): void;
+  get links(): HttpClientLink[];
+  /**
+   * Force browser to refresh links from the server.
+   */
+  fetchLinks(): Promise<HttpClientLink[]>;
+  /**
+   * Create a virtual client that can be used to call actions.
+   *
+   * Use js Proxy under the hood.
+   */
+  client<T extends object>(scope?: ClientScope): HttpVirtualClient<T>;
+  /**
+   * Check if a link with the given name exists.
+   * @param name
+   */
+  can(name: string): boolean;
+  /**
+   * Resolve a link by its name and call it.
+   * - If link is local, it will call the local handler.
+   * - If link is remote, it will make a fetch request to the remote server.
+   */
+  follow(name: string, config?: Partial<ServerRequestConfigEntry>, options?: ClientRequestOptions & ClientScope): Promise<any>;
+  protected createVirtualAction<T extends RequestConfigSchema>(name: string, scope?: ClientScope): VirtualAction<T>;
+  protected followRemote(link: HttpClientLink, config?: Partial<ServerRequestConfigEntry>, options?: ClientRequestOptions): Promise<FetchResponse>;
+  protected getLinkByName(name: string, options?: ClientScope): Promise<HttpClientLink>;
+}
+interface HttpClientLink extends ApiLink {
+  secured?: boolean | ServerRouteSecure;
+  prefix?: string;
+  host?: string;
+  service?: string;
+  schema?: RequestConfigSchema;
+  handler?: ServerHandler;
+}
+interface ClientScope {
+  group?: string;
+  service?: string;
+  hostname?: string;
+}
+type HttpVirtualClient<T> = { [K in keyof T as T[K] extends ActionDescriptor<RequestConfigSchema> ? K : never]: T[K] extends ActionDescriptor<infer Schema> ? VirtualAction<Schema> : never };
+interface VirtualAction<T extends RequestConfigSchema> extends Pick<ActionDescriptor<T>, "name" | "run" | "fetch"> {
+  (config?: ClientRequestEntry<T>, opts?: ClientRequestOptions): Promise<ClientRequestResponse<T>>;
+  can: () => boolean;
+}
+//#endregion
+//#region src/descriptors/$client.d.ts
+/**
+ * Create a new client.
+ */
+declare const $client: {
+  <T extends object>(scope?: ClientScope): HttpVirtualClient<T>;
+  [KIND]: string;
+};
+//#endregion
+//#region src/descriptors/$remote.d.ts
+/**
+ * $remote is a descriptor that allows you to define remote service access.
+ *
+ * Use it only when you have 2 or more services that need to communicate with each other.
+ *
+ * All remote services can be exposed as actions, ... or not.
+ *
+ * You can add a service account if you want to use a security layer.
+ */
+declare const $remote: {
+  (options: RemoteDescriptorOptions): RemoteDescriptor;
+  [KIND]: typeof RemoteDescriptor;
+};
+interface RemoteDescriptorOptions {
+  /**
+   * The URL of the remote service.
+   * You can use a function to generate the URL dynamically.
+   * You probably should use $env(env) to get the URL from the environment.
+   *
+   * @example
+   * ```ts
+   * import { $remote } from "alepha/server";
+   * import { $inject, t } from "alepha";
+   *
+   * class App {
+   *   env = $env(t.object({
+   *     REMOTE_URL: t.text({default: "http://localhost:3000"}),
+   *   }));
+   *   remote = $remote({
+   *     url: this.env.REMOTE_URL,
+   *   });
+   * }
+   * ```
+   */
+  url: string | (() => string);
+  /**
+   * The name of the remote service.
+   *
+   * @default Member of the class containing the remote service.
+   */
+  name?: string;
+  /**
+   * If true, all methods of the remote service will be exposed as actions in this context.
+   * > Note: Proxy will never use the service account, it just... proxies the request.
+   */
+  proxy?: boolean | Partial<ProxyDescriptorOptions & {
+    /**
+     * If true, the remote service won't be available internally, only through the proxy.
+     */
+    noInternal: boolean;
+  }>;
+  /**
+   * For communication between the server and the remote service with a security layer.
+   * This will be used for internal communication and will not be exposed to the client.
+   */
+  serviceAccount?: ServiceAccountDescriptor;
+}
+declare class RemoteDescriptor extends Descriptor<RemoteDescriptorOptions> {
+  get name(): string;
+}
+//#endregion
+//#region src/providers/RemoteDescriptorProvider.d.ts
+declare class RemoteDescriptorProvider {
+  protected readonly env: {
+    SERVER_API_PREFIX: string;
+  };
+  protected readonly alepha: Alepha;
+  protected readonly proxyProvider: ServerProxyProvider;
+  protected readonly linkProvider: LinkProvider;
+  protected readonly remotes: Array<ServerRemote>;
+  protected readonly log: _alepha_logger0.Logger;
+  getRemotes(): ServerRemote[];
+  readonly configure: _alepha_core2.HookDescriptor<"configure">;
+  readonly start: _alepha_core2.HookDescriptor<"start">;
+  registerRemote(value: RemoteDescriptor): Promise<void>;
+  protected readonly fetchLinks: _alepha_retry0.RetryDescriptorFn<(opts: FetchLinksOptions) => Promise<ApiLinksResponse>>;
+}
+interface FetchLinksOptions {
+  /**
+   * Name of the remote service.
+   */
+  service: string;
+  /**
+   * URL to fetch links from.
+   */
+  url: string;
+  /**
+   * Authorization header containing access token.
+   */
+  authorization?: string;
+}
+interface ServerRemote {
+  /**
+   * URL of the remote service.
+   */
+  url: string;
+  /**
+   * Name of the remote service.
+   */
+  name: string;
+  /**
+   * Expose links as endpoint. It's not only internal.
+   */
+  proxy: boolean;
+  /**
+   * It's only used inside the application.
+   */
+  internal: boolean;
+  /**
+   * Links fetcher.
+   */
+  links: (args: {
+    authorization?: string;
+  }) => Promise<ApiLinksResponse>;
+  /**
+   * Fetches schema for the remote service.
+   */
+  schema: (args: {
+    name: string;
+    authorization?: string;
+  }) => Promise<any>;
+  /**
+   * Force a default access token provider when not provided.
+   */
+  serviceAccount?: ServiceAccountDescriptor;
+  /**
+   * Prefix for the remote service links.
+   */
+  prefix: string;
+}
+//#endregion
+//#region src/providers/ServerLinksProvider.d.ts
+declare class ServerLinksProvider {
+  protected readonly env: {
+    SERVER_API_PREFIX: string;
+  };
+  protected readonly alepha: Alepha;
+  protected readonly linkProvider: LinkProvider;
+  protected readonly remoteProvider: RemoteDescriptorProvider;
+  protected readonly serverTimingProvider: ServerTimingProvider;
+  get prefix(): string;
+  readonly onRoute: _alepha_core2.HookDescriptor<"configure">;
+  /**
+   * First API - Get all API links for the user.
+   *
+   * This is based on the user's permissions.
+   */
+  readonly links: _alepha_server0.RouteDescriptor<{
+    response: typebox18.TObject<{
+      prefix: typebox18.TOptional<typebox18.TString>;
+      links: typebox18.TArray<typebox18.TObject<{
+        name: typebox18.TString;
+        group: typebox18.TOptional<typebox18.TString>;
+        path: typebox18.TString;
+        method: typebox18.TOptional<typebox18.TString>;
+        requestBodyType: typebox18.TOptional<typebox18.TString>;
+        service: typebox18.TOptional<typebox18.TString>;
+      }>>;
+    }>;
+  }>;
+  /**
+   * Second API - Get schema for a specific API link.
+   *
+   * Note: Body/Response schema are not included in `links` API because it's TOO BIG.
+   * I mean for 150+ links, you got 50ms of serialization time.
+   */
+  readonly schema: _alepha_server0.RouteDescriptor<{
+    params: typebox18.TObject<{
+      name: typebox18.TString;
+    }>;
+    response: typebox18.TRecord<string, typebox18.TAny>;
+  }>;
+  getSchemaByName(name: string, options?: GetApiLinksOptions): Promise<RequestConfigSchema>;
+  /**
+   * Retrieves API links for the user based on their permissions.
+   * Will check on local links and remote links.
+   */
+  getUserApiLinks(options: GetApiLinksOptions): Promise<ApiLinksResponse>;
+}
+interface GetApiLinksOptions {
+  user?: UserAccountToken;
+  authorization?: string;
+}
+//#endregion
+//#region src/index.d.ts
+declare module "alepha" {
+  interface State {
+    /**
+     * API links attached to the server request state.
+     *
+     * @see {@link ApiLinksResponse}
+     * @internal
+     */
+    "alepha.server.request.apiLinks"?: ApiLinksResponse;
+  }
+}
+/**
+ * Provides server-side link management and remote capabilities for client-server interactions.
+ *
+ * The server-links module enables declarative link definitions using `$remote` and `$client` descriptors,
+ * facilitating seamless API endpoint management and client-server communication. It integrates with server
+ * security features to ensure safe and controlled access to resources.
+ *
+ * @see {@link $remote}
+ * @see {@link $client}
+ * @module alepha.server.links
+ */
+declare const AlephaServerLinks: _alepha_core2.Service<_alepha_core2.Module>;
+//#endregion
+export { $client, $remote, AlephaServerLinks, ApiLink, ApiLinksResponse, ClientScope, FetchLinksOptions, GetApiLinksOptions, HttpClientLink, HttpVirtualClient, LinkProvider, RemoteDescriptor, RemoteDescriptorOptions, RemoteDescriptorProvider, ServerLinksProvider, ServerRemote, VirtualAction, apiLinkSchema, apiLinksResponseSchema };
+//# sourceMappingURL=index.d.ts.map

package/server/metrics.d.ts

@@ -1 +1,35 @@
-export * from '@alepha/server-metrics';
+import * as _alepha_core1 from "alepha";
+import { Alepha } from "alepha";
+import * as _alepha_server0 from "alepha/server";
+import { Histogram, Registry } from "prom-client";
+
+//#region src/providers/ServerMetricsProvider.d.ts
+declare class ServerMetricsProvider {
+  protected readonly register: Registry;
+  protected readonly alepha: Alepha;
+  protected httpRequestDuration?: Histogram<string>;
+  readonly options: ServerMetricsProviderOptions;
+  readonly metrics: _alepha_server0.RouteDescriptor<_alepha_server0.RequestConfigSchema>;
+  protected readonly onStart: _alepha_core1.HookDescriptor<"start">;
+  protected readonly onRequest: _alepha_core1.HookDescriptor<"server:onRequest">;
+  protected readonly onResponse: _alepha_core1.HookDescriptor<"server:onResponse">;
+}
+interface ServerMetricsProviderOptions {
+  prefix?: string;
+  gcDurationBuckets?: number[];
+  eventLoopMonitoringPrecision?: number;
+  labels?: object;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * This module provides prometheus metrics for the Alepha server.
+ * Metrics are exposed at the `/metrics` endpoint.
+ *
+ * @see {@link ServerMetricsProvider}
+ * @module alepha.server.metrics
+ */
+declare const AlephaServerMetrics: _alepha_core1.Service<_alepha_core1.Module>;
+//#endregion
+export { AlephaServerMetrics, ServerMetricsProvider, ServerMetricsProviderOptions };
+//# sourceMappingURL=index.d.ts.map

package/server/multipart.d.ts

@@ -1 +1,42 @@
-export * from '@alepha/server-multipart';
+import * as _alepha_core0 from "alepha";
+import { Alepha, FileLike, HookDescriptor } from "alepha";
+import { ServerRoute } from "alepha/server";
+import { IncomingMessage } from "node:http";
+import { BusboyConfig } from "@fastify/busboy";
+
+//#region src/providers/ServerMultipartProvider.d.ts
+declare class ServerMultipartProvider {
+  protected readonly alepha: Alepha;
+  readonly onRequest: HookDescriptor<"server:onRequest">;
+  readonly onSend: HookDescriptor<"server:onResponse">;
+  handleMultipartBodyFromNode(route: ServerRoute, stream: IncomingMessage): Promise<{
+    body: Record<string, unknown>;
+    cleanup: () => Promise<void>;
+  }>;
+  parseMultipart(req: IncomingMessage, config?: Omit<BusboyConfig, "headers">): Promise<MultipartResult>;
+}
+interface MultipartResult {
+  fields: Record<string, string | string[]>;
+  files: Record<string, HybridFile>;
+}
+interface HybridFile extends FileLike {
+  cleanup(): Promise<void>;
+  _state: {
+    cleanup: boolean;
+    size: number;
+    tmpPath: string;
+  };
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * This module provides support for handling multipart/form-data requests.
+ * It allows to parse body data containing t.file().
+ *
+ * @see {@link ServerMultipartProvider}
+ * @module alepha.server.multipart
+ */
+declare const AlephaServerMultipart: _alepha_core0.Service<_alepha_core0.Module>;
+//#endregion
+export { AlephaServerMultipart, ServerMultipartProvider };
+//# sourceMappingURL=index.d.ts.map

package/server/proxy.d.ts

@@ -1 +1,234 @@
-export * from '@alepha/server-proxy';
+import * as _alepha_core1 from "alepha";
+import { Alepha, Async, Descriptor, KIND } from "alepha";
+import { ServerHandler, ServerRequest, ServerRouterProvider } from "alepha/server";
+import * as _alepha_logger0 from "alepha/logger";
+
+//#region src/descriptors/$proxy.d.ts
+
+/**
+ * Creates a proxy descriptor to forward requests to another server.
+ *
+ * This descriptor enables you to create reverse proxy functionality, allowing your Alepha server
+ * to forward requests to other services while maintaining a unified API surface. It's particularly
+ * useful for microservice architectures, API gateways, or when you need to aggregate multiple
+ * services behind a single endpoint.
+ *
+ * **Key Features**
+ *
+ * - **Path-based routing**: Match specific paths or patterns to proxy
+ * - **Dynamic targets**: Support both static and dynamic target resolution
+ * - **Request/Response hooks**: Modify requests before forwarding and responses after receiving
+ * - **URL rewriting**: Transform URLs before forwarding to the target
+ * - **Conditional proxying**: Enable/disable proxies based on environment or conditions
+ *
+ * @example
+ * **Basic proxy setup:**
+ * ```ts
+ * import { $proxy } from "alepha/server-proxy";
+ *
+ * class ApiGateway {
+ *   // Forward all /api/* requests to external service
+ *   api = $proxy({
+ *     path: "/api/*",
+ *     target: "https://api.example.com"
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Dynamic target with environment-based routing:**
+ * ```ts
+ * class ApiGateway {
+ *   // Route to different environments based on configuration
+ *   api = $proxy({
+ *     path: "/api/*",
+ *     target: () => process.env.NODE_ENV === "production"
+ *       ? "https://api.prod.example.com"
+ *       : "https://api.dev.example.com"
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Advanced proxy with request/response modification:**
+ * ```ts
+ * class SecureProxy {
+ *   secure = $proxy({
+ *     path: "/secure/*",
+ *     target: "https://secure-api.example.com",
+ *     beforeRequest: async (request, proxyRequest) => {
+ *       // Add authentication headers
+ *       proxyRequest.headers = {
+ *         ...proxyRequest.headers,
+ *         'Authorization': `Bearer ${await getServiceToken()}`,
+ *         'X-Forwarded-For': request.headers['x-forwarded-for'] || request.ip
+ *       };
+ *     },
+ *     afterResponse: async (request, proxyResponse) => {
+ *       // Log response for monitoring
+ *       console.log(`Proxied ${request.url} -> ${proxyResponse.status}`);
+ *     },
+ *     rewrite: (url) => {
+ *       // Remove /secure prefix when forwarding
+ *       url.pathname = url.pathname.replace('/secure', '');
+ *     }
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * **Conditional proxy based on feature flags:**
+ * ```ts
+ * class FeatureProxy {
+ *   newApi = $proxy({
+ *     path: "/v2/*",
+ *     target: "https://new-api.example.com",
+ *     disabled: !process.env.ENABLE_V2_API // Disable if feature flag is off
+ *   });
+ * }
+ * ```
+ */
+declare const $proxy: {
+  (options: ProxyDescriptorOptions): ProxyDescriptor;
+  [KIND]: typeof ProxyDescriptor;
+};
+type ProxyDescriptorOptions = {
+  /**
+   * Path pattern to match for proxying requests.
+   *
+   * Supports wildcards and path parameters:
+   * - `/api/*` - Matches all paths starting with `/api/`
+   * - `/api/v1/*` - Matches all paths starting with `/api/v1/`
+   * - `/users/:id` - Matches `/users/123`, `/users/abc`, etc.
+   *
+   * @example "/api/*"
+   * @example "/secure/admin/*"
+   * @example "/users/:id/posts"
+   */
+  path: string;
+  /**
+   * Target URL to which matching requests should be forwarded.
+   *
+   * Can be either:
+   * - **Static string**: A fixed URL like `"https://api.example.com"`
+   * - **Dynamic function**: A function that returns the URL, enabling runtime target resolution
+   *
+   * The target URL will be combined with the remaining path from the original request.
+   *
+   * @example "https://api.example.com"
+   * @example () => process.env.API_URL || "http://localhost:3001"
+   */
+  target: string | (() => string);
+  /**
+   * Whether this proxy is disabled.
+   *
+   * When `true`, requests matching the path will not be proxied and will be handled
+   * by other routes or return 404. Useful for feature toggles or conditional proxying.
+   *
+   * @default false
+   * @example !process.env.ENABLE_PROXY
+   */
+  disabled?: boolean;
+  /**
+   * Hook called before forwarding the request to the target server.
+   *
+   * Use this to:
+   * - Add authentication headers
+   * - Modify request headers or body
+   * - Add request tracking/logging
+   * - Transform the request before forwarding
+   *
+   * @param request - The original incoming server request
+   * @param proxyRequest - The request that will be sent to the target (modifiable)
+   *
+   * @example
+   * ```ts
+   * beforeRequest: async (request, proxyRequest) => {
+   *   proxyRequest.headers = {
+   *     ...proxyRequest.headers,
+   *     'Authorization': `Bearer ${await getToken()}`,
+   *     'X-Request-ID': generateRequestId()
+   *   };
+   * }
+   * ```
+   */
+  beforeRequest?: (request: ServerRequest, proxyRequest: RequestInit) => Async<void>;
+  /**
+   * Hook called after receiving the response from the target server.
+   *
+   * Use this to:
+   * - Log response details for monitoring
+   * - Add custom headers to the response
+   * - Transform response data
+   * - Handle error responses
+   *
+   * @param request - The original incoming server request
+   * @param proxyResponse - The response received from the target server
+   *
+   * @example
+   * ```ts
+   * afterResponse: async (request, proxyResponse) => {
+   *   console.log(`Proxy ${request.method} ${request.url} -> ${proxyResponse.status}`);
+   *
+   *   if (!proxyResponse.ok) {
+   *     await logError(`Proxy error: ${proxyResponse.status}`, { request, response: proxyResponse });
+   *   }
+   * }
+   * ```
+   */
+  afterResponse?: (request: ServerRequest, proxyResponse: Response) => Async<void>;
+  /**
+   * Function to rewrite the URL before sending to the target server.
+   *
+   * Use this to:
+   * - Remove or add path prefixes
+   * - Transform path parameters
+   * - Modify query parameters
+   * - Change the URL structure entirely
+   *
+   * The function receives a mutable URL object and should modify it in-place.
+   *
+   * @param url - The URL object to modify (mutable)
+   *
+   * @example
+   * ```ts
+   * // Remove /api prefix when forwarding
+   * rewrite: (url) => {
+   *   url.pathname = url.pathname.replace('/api', '');
+   * }
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Add version prefix
+   * rewrite: (url) => {
+   *   url.pathname = `/v2${url.pathname}`;
+   * }
+   * ```
+   */
+  rewrite?: (url: URL) => void;
+};
+declare class ProxyDescriptor extends Descriptor<ProxyDescriptorOptions> {}
+//#endregion
+//#region src/providers/ServerProxyProvider.d.ts
+declare class ServerProxyProvider {
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly routerProvider: ServerRouterProvider;
+  protected readonly alepha: Alepha;
+  protected readonly configure: _alepha_core1.HookDescriptor<"configure">;
+  createProxy(options: ProxyDescriptorOptions): void;
+  createProxyHandler(target: string, options: Omit<ProxyDescriptorOptions, "path">): ServerHandler;
+  private getRawRequestBody;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Plugin for Alepha that provides a proxy server functionality.
+ *
+ * @see {@link $proxy}
+ * @module alepha.server.proxy
+ */
+declare const AlephaServerProxy: _alepha_core1.Service<_alepha_core1.Module>;
+//#endregion
+export { $proxy, AlephaServerProxy, ProxyDescriptor, ProxyDescriptorOptions, ServerProxyProvider };
+//# sourceMappingURL=index.d.ts.map