@bleedingdev/modern-js-plugin-bff-extensions 3.8.3-ultramodern.2

package/src/client-generator/built-entry.ts

@@ -0,0 +1,70 @@
+import { fs, upath as path } from '@modern-js/utils';
+
+import { resolveEffectEntryFile } from './paths';
+
+const BUILT_ENTRY_EXT = /\.(?:[cm]?ts|tsx|jsx)$/u;
+
+export function resolveBuiltEffectEntry(
+  appDirectory: string,
+  distDirectory: string,
+  sourceEntry: string | undefined,
+): string | undefined {
+  if (sourceEntry === undefined || sourceEntry.length === 0) {
+    return undefined;
+  }
+  const relativeEntry = path.relative(appDirectory, sourceEntry);
+  if (relativeEntry === '..' || relativeEntry.startsWith(`..${path.sep}`)) {
+    throw new Error(
+      `Effect BFF entry must be inside the application directory: ${sourceEntry}`,
+    );
+  }
+  const builtEntry = path
+    .resolve(distDirectory, relativeEntry)
+    .replace(BUILT_ENTRY_EXT, '.js');
+  return fs.existsSync(builtEntry) ? builtEntry : undefined;
+}
+
+export async function bundleBuiltEffectEntryForNode(options: {
+  appDir: string;
+  apiDir: string;
+  distDir: string;
+  effectEntry?: string;
+  format: 'cjs' | 'esm';
+}) {
+  const { appDir, apiDir, distDir, effectEntry, format } = options;
+  const sourceEntry = resolveEffectEntryFile({ appDir, apiDir, effectEntry });
+  const builtEntry = resolveBuiltEffectEntry(appDir, distDir, sourceEntry);
+  if (builtEntry === undefined || builtEntry.length === 0) {
+    throw new Error(
+      `Effect BFF entry was not emitted into ${distDir}: ${
+        sourceEntry ?? path.resolve(apiDir, 'index')
+      }`,
+    );
+  }
+  const { bundleEffectEntryForNode } = await import(
+    '../effect-source-loader/loader'
+  );
+  return bundleEffectEntryForNode({
+    appDir,
+    entryPath: builtEntry,
+    format,
+  });
+}
+
+export function resolveEffectEntryPaths(options: {
+  appDir: string;
+  apiDir: string;
+  effectEntry?: string;
+}): { sourceEffectEntry: string | undefined; relativeEffectEntry: string } {
+  const { appDir, apiDir, effectEntry } = options;
+  const sourceEffectEntry = resolveEffectEntryFile({
+    appDir,
+    apiDir,
+    effectEntry,
+  });
+  const relativeEffectEntry =
+    sourceEffectEntry !== undefined && sourceEffectEntry.length > 0
+      ? path.relative(appDir, sourceEffectEntry).replace(BUILT_ENTRY_EXT, '.js')
+      : '';
+  return { sourceEffectEntry, relativeEffectEntry };
+}

package/src/client-generator/generator.ts

@@ -0,0 +1,52 @@
+import { collectEffectEndpoints } from '@modern-js/bff-effect/effect';
+import { logger } from '@modern-js/utils';
+import {
+  createEffectClientGeneration,
+  renderEffectClientCode,
+  renderEffectClientDeclaration,
+} from './rendering';
+import { getHttpApiRuntime, loadEffectApi } from './runtime';
+import type {
+  EffectClientCodegenOptions,
+  GeneratedEffectClientArtifacts,
+} from './types';
+
+export function generateEffectClient(
+  options: EffectClientCodegenOptions,
+): Promise<GeneratedEffectClientArtifacts | null> {
+  return loadEffectApi({
+    appDir: options.appDir,
+    resourcePath: options.resourcePath,
+    onDependency: options.onDependency,
+  }).then(api => {
+    if (api === null) {
+      logger.warn(
+        `[BFF][Effect] Failed to generate client for ${options.resourcePath}: unable to resolve exported HttpApi.`,
+      );
+      return null;
+    }
+
+    return getHttpApiRuntime().then(httpApiRuntime => {
+      const endpoints = collectEffectEndpoints(
+        httpApiRuntime.reflect,
+        api,
+        options.prefix,
+      );
+      const generation = createEffectClientGeneration(endpoints, options);
+      return {
+        code: renderEffectClientCode(generation),
+        declaration: renderEffectClientDeclaration(endpoints),
+        endpoints,
+        operationContracts: generation.operationContracts,
+        operationVersion: generation.operationVersion,
+        requestId: generation.requestId,
+      };
+    });
+  });
+}
+
+export function generateEffectClientCode(options: EffectClientCodegenOptions) {
+  return generateEffectClient(options).then(artifacts =>
+    artifacts === null ? null : artifacts.code,
+  );
+}

package/src/client-generator/index.ts

@@ -0,0 +1,10 @@
+export {
+  bundleBuiltEffectEntryForNode,
+  resolveEffectEntryPaths,
+} from './built-entry';
+export { generateEffectClient, generateEffectClientCode } from './generator';
+export { resolveEffectEntryFile } from './paths';
+export type {
+  EffectClientCodegenOptions,
+  GeneratedEffectClientArtifacts,
+} from './types';

package/src/client-generator/paths.ts

@@ -0,0 +1,40 @@
+import { findExists, fs, upath as path } from '@modern-js/utils';
+
+const JS_OR_TS_EXTS = [
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.mts',
+  '.cjs',
+  '.cts',
+] as const;
+
+export function resolveEffectEntryFile(options: {
+  appDir: string;
+  apiDir: string;
+  effectEntry?: string;
+}): string | undefined {
+  const { appDir, apiDir, effectEntry } = options;
+
+  const resolveEntry = (entryWithoutExt: string) => {
+    if (path.extname(entryWithoutExt) !== '') {
+      return fs.existsSync(entryWithoutExt) ? entryWithoutExt : undefined;
+    }
+
+    return (
+      findExists(JS_OR_TS_EXTS.map(ext => `${entryWithoutExt}${ext}`)) ||
+      undefined
+    );
+  };
+
+  if (effectEntry !== undefined && effectEntry !== '') {
+    const entryWithoutExt = path.isAbsolute(effectEntry)
+      ? effectEntry
+      : path.resolve(appDir, effectEntry);
+    return resolveEntry(entryWithoutExt);
+  }
+
+  return resolveEntry(path.resolve(apiDir, 'index'));
+}

package/src/client-generator/rendering.ts

@@ -0,0 +1,307 @@
+import {
+  buildOperationContractMap,
+  deriveOperationVersion,
+  type OperationContractMap,
+} from '@modern-js/bff-core';
+import {
+  createEffectEndpointContractHash,
+  type EffectEndpointMeta,
+  ensureLeadingSlash,
+  normalizeEffectPrefix,
+  toOperationContractSources,
+} from '@modern-js/bff-effect/effect';
+import { fs, upath as path } from '@modern-js/utils';
+import type { EffectClientCodegenOptions } from './types';
+
+const DEFAULT_REQUEST_CREATOR = '@modern-js/plugin-bff/client';
+const EFFECT_CLIENT_RUNTIME_IMPORT =
+  '@modern-js/plugin-bff/effect-client-runtime';
+
+function isAbsoluteUrl(value: string) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBatchEndpoint(prefix: string, endpoint: string | undefined) {
+  const value =
+    endpoint === undefined || endpoint === '' ? '/_data/batch' : endpoint;
+  if (isAbsoluteUrl(value)) {
+    return value;
+  }
+
+  const normalizedPrefix = normalizeEffectPrefix(prefix);
+  const normalizedEndpoint = ensureLeadingSlash(value);
+  if (normalizedPrefix === '') {
+    return normalizedEndpoint;
+  }
+
+  if (
+    normalizedEndpoint === normalizedPrefix ||
+    normalizedEndpoint.startsWith(`${normalizedPrefix}/`)
+  ) {
+    return normalizedEndpoint;
+  }
+
+  return `${normalizedPrefix}${normalizedEndpoint === '/' ? '' : normalizedEndpoint}`;
+}
+
+function getPackageInfo(
+  resourcePath: string,
+  appDir: string,
+  onDependency?: (dependency: string) => void,
+): { name?: string; version?: string } {
+  for (const startDir of [path.dirname(resourcePath), appDir]) {
+    let current = path.resolve(startDir);
+    for (let depth = 0; depth < 32; depth += 1) {
+      const packageJsonPath = path.join(current, 'package.json');
+      if (fs.existsSync(packageJsonPath)) {
+        onDependency?.(packageJsonPath);
+        try {
+          const packageJson = fs.readJSONSync(packageJsonPath) as {
+            name?: string;
+            version?: string;
+          };
+          return { name: packageJson.name, version: packageJson.version };
+        } catch {
+          return {};
+        }
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return {};
+}
+
+export type EffectClientGeneration = {
+  config: Record<string, unknown>;
+  manifest: {
+    endpoints: Array<{
+      apiId: string;
+      group: string;
+      endpoint: string;
+      method: string;
+      routePath: string;
+      schemaHash: string;
+      operationVersion: number;
+    }>;
+  };
+  operationContracts: OperationContractMap;
+  operationVersion: number;
+  requestCreator: string;
+  requestId: string;
+};
+
+export function renderEffectClientCode(generation: EffectClientGeneration) {
+  const { config, manifest } = generation;
+  return `import * as __requestRuntime from ${JSON.stringify(
+    generation.requestCreator,
+  )};
+import { createGeneratedEffectClient } from ${JSON.stringify(
+    EFFECT_CLIENT_RUNTIME_IMPORT,
+  )};
+
+const __manifest = ${JSON.stringify(manifest, null, 2)};
+
+const __config = ${JSON.stringify(config, null, 2)};
+
+const __generated = createGeneratedEffectClient(__manifest, __config, __requestRuntime);
+
+const client = __generated.client;
+const operationManifest = __generated.operationManifest;
+const createEffectRequestContext = __generated.createEffectRequestContext;
+const apiModule = {
+  client,
+  operationManifest,
+  createEffectRequestContext,
+};
+
+export { client, createEffectRequestContext, operationManifest };
+export default apiModule;
+`;
+}
+
+export function createEffectClientGeneration(
+  endpoints: EffectEndpointMeta[],
+  options: EffectClientCodegenOptions,
+): EffectClientGeneration {
+  const requestCreator = options.requestCreator || DEFAULT_REQUEST_CREATOR;
+  const httpMethodDecider = options.httpMethodDecider || 'functionName';
+  const packageInfo = getPackageInfo(
+    options.resourcePath,
+    options.appDir,
+    options.onDependency,
+  );
+  const packageName = packageInfo.name;
+  const dataPlatformAppNamespace =
+    packageName === undefined || packageName === ''
+      ? 'unknown-app'
+      : packageName;
+  const requestId =
+    options.target === 'bundle'
+      ? options.requestId !== undefined && options.requestId.trim() !== ''
+        ? options.requestId.trim()
+        : packageName !== undefined && packageName !== ''
+          ? packageName
+          : undefined
+      : undefined;
+  const normalizedRequestId =
+    requestId === undefined || requestId === '' ? 'default' : requestId;
+  const operationVersion = deriveOperationVersion(packageInfo.version);
+  const batchConfig = options.dataPlatformBatch;
+  const batchEndpoint = resolveBatchEndpoint(
+    options.prefix,
+    batchConfig?.endpoint,
+  );
+
+  const manifest = {
+    endpoints: endpoints.map(endpoint => ({
+      apiId: endpoint.apiId,
+      group: endpoint.groupName,
+      endpoint: endpoint.endpointName,
+      method: endpoint.method,
+      routePath: endpoint.routePath,
+      schemaHash: createEffectEndpointContractHash(
+        endpoint,
+        normalizedRequestId,
+      ),
+      operationVersion,
+    })),
+  };
+
+  const config = {
+    appNamespace: dataPlatformAppNamespace,
+    ...(requestId !== undefined && requestId !== '' ? { requestId } : {}),
+    port: options.port,
+    useEnvPort: options.target === 'server',
+    defaultOrigin: `http://localhost:${String(options.port)}`,
+    httpMethodDecider,
+    batch: {
+      enabled: batchConfig?.enabled ?? true,
+      endpoint: batchEndpoint,
+      flushIntervalMs: batchConfig?.flushIntervalMs ?? 8,
+      maxBatchSize: batchConfig?.maxBatchSize ?? 16,
+      maxBatchBytes: batchConfig?.maxBatchBytes ?? 64 * 1024,
+      requestTimeoutMs: batchConfig?.requestTimeoutMs ?? 10_000,
+      allowedMethods:
+        batchConfig?.allowedMethods !== undefined &&
+        batchConfig.allowedMethods.length > 0
+          ? batchConfig.allowedMethods
+          : ['GET'],
+    },
+  };
+
+  return {
+    config,
+    manifest,
+    operationContracts: buildOperationContractMap({
+      handlers: toOperationContractSources(endpoints),
+      requestId: normalizedRequestId,
+      operationVersion,
+    }),
+    operationVersion,
+    requestCreator,
+    requestId: normalizedRequestId,
+  };
+}
+
+function renderClientShape(
+  endpoints: EffectEndpointMeta[],
+  valueType: string,
+): string {
+  if (endpoints.length === 0) {
+    return `Record<string, Record<string, ${valueType}>>`;
+  }
+  const groups = new Map<string, string[]>();
+  for (const endpoint of endpoints) {
+    const group = groups.get(endpoint.groupName) || [];
+    group.push(endpoint.endpointName);
+    groups.set(endpoint.groupName, group);
+  }
+  const groupEntries = [...groups.entries()].map(([groupName, names]) => {
+    const endpointEntries = names
+      .map(name => `    ${JSON.stringify(name)}: ${valueType};`)
+      .join('\n');
+    return `  ${JSON.stringify(groupName)}: {\n${endpointEntries}\n  };`;
+  });
+  return `{\n${groupEntries.join('\n')}\n}`;
+}
+
+export function renderEffectClientDeclaration(
+  endpoints: EffectEndpointMeta[] = [],
+) {
+  return `export type EffectClientOperation = (
+  request?: unknown,
+) => Promise<unknown>;
+export type EffectClientGroup = Record<string, EffectClientOperation>;
+export type EffectClient = Record<string, EffectClientGroup>;
+export type EffectOperationDescriptor = {
+  appNamespace: string;
+  apiId: string;
+  group: string;
+  endpoint: string;
+  operationId: string;
+  routePath: string;
+  method: string;
+  operationVersion: number;
+  schemaHash: string;
+  version: number;
+};
+export type EffectOperationManifest = Record<
+  string,
+  Record<string, EffectOperationDescriptor>
+>;
+export type EffectOperationContext = {
+  requestId?: string;
+  operationId?: string;
+  routePath?: string;
+  method?: string;
+  schemaHash?: string;
+  operationVersion?: number;
+  locale?: string;
+  traceparent?: string;
+  traceId?: string;
+  spanId?: string;
+  source?: string;
+  scope?: Record<string, unknown>;
+  sessionClaims?: Record<string, unknown>;
+  attributes?: Record<string, unknown>;
+};
+export type EffectRequestContext = {
+  headers?: Record<string, string>;
+  locale?: string;
+  operationContext?: EffectOperationContext;
+  traceparent?: string;
+  traceId?: string;
+  spanId?: string;
+};
+export type GeneratedEffectClient = ${renderClientShape(
+    endpoints,
+    'EffectClientOperation',
+  )};
+export type GeneratedEffectOperationManifest = ${renderClientShape(
+    endpoints,
+    'EffectOperationDescriptor',
+  )};
+
+export declare const client: GeneratedEffectClient;
+export declare const createEffectRequestContext: (
+  requestContext: Record<string, unknown>,
+) => EffectRequestContext;
+export declare const operationManifest: GeneratedEffectOperationManifest;
+declare const apiModule: {
+  client: GeneratedEffectClient;
+  createEffectRequestContext: typeof createEffectRequestContext;
+  operationManifest: GeneratedEffectOperationManifest;
+};
+
+export default apiModule;
+`;
+}

package/src/client-generator/runtime.ts

@@ -0,0 +1,69 @@
+import {
+  extractHttpApiFromModule,
+  type HttpApiLike,
+  type HttpApiReflect,
+} from '@modern-js/bff-effect/effect';
+import { compatibleRequire, upath as path } from '@modern-js/utils';
+import { loadEffectSourceModule } from '../effect-source-loader/loader';
+
+type HttpApiRuntime = {
+  isHttpApi: (value: unknown) => boolean;
+  reflect: HttpApiReflect;
+};
+
+let httpApiRuntimePromise: Promise<HttpApiRuntime> | undefined;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isHttpApiRuntime(value: unknown): value is HttpApiRuntime {
+  return (
+    isRecord(value) &&
+    typeof value.isHttpApi === 'function' &&
+    typeof value.reflect === 'function'
+  );
+}
+
+export function getHttpApiRuntime(): Promise<HttpApiRuntime> {
+  if (httpApiRuntimePromise === undefined) {
+    httpApiRuntimePromise = compatibleRequire('effect/unstable/httpapi', false)
+      .catch(error => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes("Cannot find module 'effect/unstable/httpapi'")) {
+          throw error;
+        }
+        const effectPackageJson = require.resolve('effect/package.json');
+        const effectHttpApiRuntimePath = path.join(
+          path.dirname(effectPackageJson),
+          'dist',
+          'unstable',
+          'httpapi',
+          'index.js',
+        );
+        return compatibleRequire(effectHttpApiRuntimePath, false);
+      })
+      .then(mod => {
+        if (isRecord(mod) && isHttpApiRuntime(mod.HttpApi)) {
+          return mod.HttpApi;
+        }
+        throw new Error(
+          '[BFF][Effect] Unable to resolve HttpApi runtime from effect/unstable/httpapi.',
+        );
+      });
+  }
+
+  return httpApiRuntimePromise;
+}
+
+export function loadEffectApi(options: {
+  appDir: string;
+  resourcePath: string;
+  onDependency?: (dependency: string) => void;
+}): Promise<HttpApiLike | null> {
+  return getHttpApiRuntime().then(httpApiRuntime =>
+    loadEffectSourceModule(options).then(mod =>
+      extractHttpApiFromModule(mod, httpApiRuntime.isHttpApi),
+    ),
+  );
+}

package/src/client-generator/types.ts

@@ -0,0 +1,35 @@
+import type { OperationContractMap } from '@modern-js/bff-core';
+import type { EffectEndpointMeta } from '@modern-js/bff-effect/effect';
+import type { HttpMethodDecider } from '@modern-js/types';
+
+export type EffectClientCodegenOptions = {
+  appDir: string;
+  apiDir: string;
+  resourcePath: string;
+  prefix: string;
+  port: number;
+  target?: string;
+  /** Producer identity used by cross-project clients and server contracts. */
+  requestId?: string;
+  requestCreator?: string;
+  httpMethodDecider?: HttpMethodDecider;
+  onDependency?: (dependency: string) => void;
+  dataPlatformBatch?: {
+    enabled?: boolean;
+    endpoint?: string;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxBatchBytes?: number;
+    requestTimeoutMs?: number;
+    allowedMethods?: string[];
+  };
+};
+
+export type GeneratedEffectClientArtifacts = {
+  code: string;
+  declaration: string;
+  endpoints: EffectEndpointMeta[];
+  operationContracts: OperationContractMap;
+  operationVersion: number;
+  requestId: string;
+};

package/src/cross-project-generation/index.ts

@@ -0,0 +1 @@
+export { renderProducerRuntimeDefaults } from './render';

package/src/cross-project-generation/render.ts

@@ -0,0 +1,14 @@
+export const renderProducerRuntimeDefaults = (requestIdValue: string) => `{
+      requestId: ${requestIdValue},
+      requireEnvelope: true,
+      identityBinding: {
+        enabled: true,
+        strict: true,
+      },
+      operationContract: {
+        enabled: true,
+        strict: true,
+        requireSchemaHash: true,
+        requireOperationVersion: true,
+      },
+    }`;

package/src/cross-project-policy/evaluation.ts

@@ -0,0 +1,70 @@
+import {
+  type CrossProjectRequestObservation,
+  evaluateCrossProjectPolicy,
+  type NormalizedCrossProjectPolicy,
+  resolveCrossProjectRequestObservation,
+} from '@modern-js/bff-core/security/cross-project-policy';
+
+export type ResolvedCrossProjectPolicy = NormalizedCrossProjectPolicy;
+
+const DENIAL_HEADERS = {
+  'content-type': 'application/json; charset=utf-8',
+} as const;
+
+export const checkCrossProjectPolicyResponse = (
+  headers: Record<string, unknown>,
+  policy: ResolvedCrossProjectPolicy | undefined,
+  observedRequest?: CrossProjectRequestObservation,
+): Response | null => {
+  if (!policy?.enabled) {
+    return null;
+  }
+
+  const violation = evaluateCrossProjectPolicy(
+    headers,
+    policy,
+    observedRequest,
+  );
+  if (!violation) {
+    return null;
+  }
+
+  return new Response(
+    JSON.stringify({
+      code: violation.code,
+      reason: violation.reason,
+      message: violation.message,
+    }),
+    {
+      status: violation.status,
+      headers: DENIAL_HEADERS,
+    },
+  );
+};
+
+export const checkCrossProjectPolicyForRequest = (
+  request: Request,
+  policy: ResolvedCrossProjectPolicy | undefined,
+): Response | null => {
+  if (!policy?.enabled) {
+    return null;
+  }
+
+  const requestTarget = {
+    method: request.method,
+    pathname: new URL(request.url).pathname,
+  };
+  const observedRequest = resolveCrossProjectRequestObservation(
+    requestTarget,
+    policy,
+  ) ?? {
+    method: requestTarget.method,
+    routePath: requestTarget.pathname,
+  };
+  const headers: Record<string, string> = {};
+  request.headers.forEach((value, key) => {
+    headers[key] = value;
+  });
+
+  return checkCrossProjectPolicyResponse(headers, policy, observedRequest);
+};

package/src/cross-project-policy/index.ts

@@ -0,0 +1 @@
+export { resolveAdapterCrossProjectPolicy } from './node';