@sap-ux/backend-proxy-middleware-cf 0.0.99 → 0.1.0

package/README.md

@@ -2,70 +2,42 @@
 
 # [`@sap-ux/backend-proxy-middleware-cf`](https://github.com/SAP/open-ux-tools/tree/main/packages/backend-proxy-middleware-cf)
 
-The `@sap-ux/backend-proxy-middleware-cf` is a [Custom UI5 Server Middleware](https://sap.github.io/ui5-tooling/pages/extensibility/CustomServerMiddleware) for proxying requests to Cloud Foundry destinations with OAuth2 authentication. It supports proxying multiple OData source paths to a single destination URL with automatic OAuth token management.
+UI5 server middleware that uses `@sap/approuter` to make destinations configured in SAP Business Technology Platform (BTP) available for local development. Requests to destination routes are proxied to a local approuter instance via `http-proxy-middleware`.
 
 > **⚠️ Experimental**: This middleware is currently experimental and may be subject to breaking changes or even removal in future versions. Use with caution and be prepared to update your configuration or migrate to alternative solutions if needed.
 
-It can be used either with the `ui5 serve` or the `fiori run` commands.
+## [Prerequisites](#prerequisites)
 
-## [Configuration Options](#configuration-options)
+- [@ui5/cli](https://ui5.github.io/cli/) 4.0 or later (specVersion 4.0 and later in `ui5.yaml`)
 
-| Option              | Value Type | Requirement Type | Default Value | Description                                                                                                      |
-| ------------------- | ---------- | ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `url`               | `string`   | **required**     | `undefined`   | Destination URL to proxy requests to.                                                                           |
-| `paths`             | `string[]` | **required**     | `[]`          | Array of OData source paths to proxy to this destination. Each path represents an OData service that should be proxied. Requests matching these paths will have the path prefix removed before forwarding. |
-| `pathRewrite`       | `string`   | optional         | `undefined`   | Optional path rewriting. When specified, the matched path prefix will be replaced with this value before forwarding to the backend. If not specified, the matched path is simply removed. Example: path `/resources/lib/api` with pathRewrite `/api` transforms `/resources/lib/api/v1/Service` to `/api/v1/Service`. |
-| `credentials`       | object     | optional         | `undefined`    | Manual OAuth credentials. If not provided, middleware attempts to auto-detect from Cloud Foundry ADP project.   |
-| `credentials.clientId` | `string` | mandatory (if credentials provided) | `undefined` | OAuth2 client ID.                                                                                                |
-| `credentials.clientSecret` | `string` | mandatory (if credentials provided) | `undefined` | OAuth2 client secret.                                                                                            |
-| `credentials.url`    | `string`   | mandatory (if credentials provided) | `undefined` | Base URL for the OAuth service. The token endpoint will be constructed as `{url}/oauth/token`.                   |
-| `debug`             | `boolean`  | optional         | `false`        | Enable debug logging for troubleshooting.                                                                        |
+## [Install](#install)
 
-## [Usage](#usage)
-
-### [Basic Configuration](#basic-configuration)
-
-```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-          - url: https://your-backend-service
-            paths:
-              - /odata/v4/visitorservice
-              - /odata
+```bash
+pnpm add -D @sap-ux/backend-proxy-middleware-cf
 ```
 
-### [Automatic Detection (Recommended)](#automatic-detection-recommended)
-
-For Cloud Foundry adaptation projects, the middleware automatically detects the project configuration from `ui5.yaml` and extracts OAuth credentials from service keys. You only need to provide the `url` and `paths`:
+## [Configuration (ui5.yaml)](#configuration-ui5yaml)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Verbose logging |
+| `port` | `number` | `5000` | Port for the local approuter |
+| `xsappJsonPath` | `string` | `"./xs-app.json"` | Path to the CF-style approuter config (e.g. `xs-app.json`). Destination route sources should match the pattern `/[^/]*\/(.*\/)?[^/]*/` (e.g. `"^/backend/(.*)$"`). |
+| `envOptionsPath` | `string` | — | Path (relative to project root) to a JSON file. Each top-level key is set on `process.env` (objects/arrays are JSON-stringified) so the approuter can read credentials and services. |
+| `destinations` | `array` or `string` | `[]` | List of `{ name, url }` destinations (names must match routes in `xs-app.json`). |
+| `allowServices` | `boolean` | `false` | Allow BTP services referenced in `xs-app.json` (requires authenticated BTP session). |
+| `authenticationMethod` | `"none"` \| `"route"` | `"none"` | Authentication for routes |
+| `allowLocalDir` | `boolean` | `false` | Allow approuter to serve static assets (usually ui5-server serves them). |
+| `rewriteContent` | `boolean` | `true` | Replace proxied URLs in response body with the server URL |
+| `rewriteContentTypes` | `string[]` | `["text/html", "application/json", "application/atom+xml", "application/xml"]` | Content types to rewrite when `rewriteContent` is true |
+| `extensions` | `array` | `[]` | Approuter extensions: `{ module: string, parameters?: Record<string, string> }`. Parameters are passed as the 4th argument to extension handlers. |
+| `appendAuthRoute` | `boolean` | `false` | Add a route for HTML pages to trigger XSUAA login when `authenticationMethod` is not `"none"`. |
+| `disableWelcomeFile` | `boolean` | `false` | Disable welcome file handling from `xs-app.json`. |
+| `disableUi5ServerRoutes` | `boolean` | `false` | Disable automatic injection of the `ui5-server` HTML auth route for `/test/*` and `/local/*` pages. |
 
-```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-          - url: https://your-backend-service
-            paths:
-              - /odata/v4/visitorservice
-              - /odata
-```
-
-The middleware will:
-
-1. Read the `app-variant-bundler-build` custom task from `ui5.yaml`
-2. Extract `serviceInstanceName` and `serviceInstanceGuid`
-3. Retrieve service keys using `@sap-ux/adp-tooling`
-4. Extract UAA credentials and construct the token endpoint
-5. Automatically add Bearer tokens to proxied requests
-
-### [Manual Credentials](#manual-credentials)
+## [Usage](#usage)
 
-For custom setups or when auto-detection is not available, you can provide OAuth credentials manually:
+1. Add the middleware in `ui5.yaml`:
 
 ```yaml
 server:
@@ -73,140 +45,56 @@ server:
     - name: backend-proxy-middleware-cf
       afterMiddleware: compression
       configuration:
-        backends: 
-          - url: https://your-backend-service
-            paths:
-              - /odata/v4/visitorservice
-              - /odata
-            credentials:
-              clientId: "sb-your-service-instance!b123|your-app!b456"
-              clientSecret: "your-client-secret"
-              url: "https://example.authentication"
-            debug: true
+        authenticationMethod: "none"
+        debug: true
+        port: 5000
+        xsappJsonPath: "./xs-app.json"
+        destinations:
+          - name: "backend"
+            url: "https://your-backend.example/path"
 ```
 
-The `credentials.url` should be the base URL of the UAA service (without `/oauth/token`). The middleware will automatically construct the full token endpoint.
-
-### Multiple OData Sources
+2. Point your path to the location of xs-app.json.
 
-You can proxy multiple OData paths to the same destination:
-
-```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-          - url: https://your-backend-service
-            paths:
-              - /odata/v4/service1
-              - /odata/v4/service2
-              - /odata/v2/legacy
-```
+### [Env options file (VCAP_SERVICES, credentials)](#env-options-file-vcap_services-credentials)
 
-### Path Rewriting with pathRewrite
+To run the approuter with BTP-style credentials (e.g. XSUAA, destinations), point `envOptionsPath` to a JSON file. Each top-level key is applied to `process.env` so the approuter can find them; object and array values are stored as JSON strings. The key `destinations` in the file is ignored so that the middleware's `destinations` from ui5.yaml are used.
 
-When your application requests resources with a specific path prefix (e.g., from a UI5 library), but the backend API expects a different path structure, use `pathRewrite`:
+Example shape (minimal):
 
-```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-          - url: https://my-backend.example.com
-            paths:
-              - /resources/my/app/ui/api/example
-            pathRewrite: /api/example
+```json
+{
+  "VCAP_SERVICES": {
+    "xsuaa": [{ "label": "xsuaa", "credentials": { "clientid": "...", "clientsecret": "...", "url": "..." } }],
+    "destination": [{ "label": "destination", "credentials": { ... } }]
+  }
+}
 ```
 
-**How it works:**
-- **Request from app:** `/resources/my/app/ui/api/example/v1/ExampleService/$metadata`
-- **Matched path:** `/resources/my/app/ui/api/example`
-- **Path rewriting:** `/api/example`
-- **Forwarded to backend:** `/api/example/v1/ExampleService/$metadata`
+You can export a real `VCAP_SERVICES` (and optionally other keys) from your BTP app and save it to a file (e.g. `./default-env.json`); do not commit secrets. In ui5.yaml set `envOptionsPath: "./default-env.json"`.
+
+## [How it works](#how-it-works)
 
-Without `pathRewrite`, the matched path prefix is simply removed:
-- **Request:** `/odata/v4/service/EntitySet`
-- **Matched path:** `/odata`
-- **Forwarded:** `/v4/service/EntitySet`
+The middleware starts a local `@sap/approuter` process with your `xs-app.json` and destinations. The UI5 server proxies requests that match approuter routes (e.g. login callback, welcome file, destination routes) to `http://localhost:<port>`. Response content can be rewritten so that backend URLs in the body are replaced with the server URL for the relevant content types.
 
-### Multiple Backend Services
+## [Extensions](#extensions)
 
-You can proxy multiple backend services:
+You can plug in approuter extensions and pass parameters:
 
 ```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-          - url: https://your-backend-service1
-            paths:
-              - /odata/v4/service1
-              - /odata/v4/service2
-              - /odata/v2/legacy
-          - url: https://your-backend-service2
-            paths:
-              - /odata/v4/service1
-              - /odata/v4/service2
-              - /odata/v2/legacy
+configuration:
+  extensions:
+    - module: ./approuter-local-ext.js
+      parameters:
+        userId: "user@example.com"
 ```
 
-### With Debug Logging
-
-Enable debug logging to troubleshoot issues:
+In the extension, parameters are available as the 4th argument: `function (req, res, next, params)`.
 
-```yaml
-server:
-  customMiddleware:
-    - name: backend-proxy-middleware-cf
-      afterMiddleware: compression
-      configuration:
-        backends:
-        - url: https://your-backend-service.cfapps.eu12.hana.ondemand.com
-          paths:
-            - /odata
-          debug: true
-```
+## [Keywords](#keywords)
 
-## How It Works
-
-1. **Proxy Setup**: Creates HTTP proxy middleware for each configured path, proxying to the destination URL.
-2. **Path Rewriting**: Removes the matched path prefix before forwarding requests (e.g., `/odata/v4/service` → `/service`).
-3. **OAuth Detection**: For automatic mode, checks if the project is a CF ADP project by reading `ui5.yaml` and looking for the `app-variant-bundler-build` custom task.
-4. **Credentials**: Extracts `serviceInstanceName` and `serviceInstanceGuid` from the custom task configuration.
-5. **Service Keys**: Retrieves service keys using `@sap-ux/adp-tooling`, which communicates with Cloud Foundry CLI.
-6. **Token Endpoint**: Constructs the token endpoint from the UAA base URL as `{url}/oauth/token`.
-7. **Token Management**: Requests OAuth tokens using client credentials flow.
-8. **Caching**: Caches tokens in memory and refreshes them automatically 60 seconds before expiry.
-9. **Request Proxying**: Adds `Authorization: Bearer <token>` header to proxied requests before forwarding.
-
-## Error Handling
-
-- If `url` is not provided, the middleware will be inactive and log a warning.
-- If no paths are configured, the middleware will be inactive and log a warning.
-- If auto-detection fails and no manual credentials are provided, the middleware will proxy requests without OAuth tokens (may fail if backend requires authentication).
-- If token request fails, an error is logged but the request may still proceed (depending on the backend's authentication requirements).
-- All errors are logged for debugging purposes.
-
-## Security Considerations
-
-- Credentials are never logged in production mode.
-- Tokens are cached in memory only and never persisted to disk.
-- Token refresh happens automatically 60 seconds before expiry to avoid using expired tokens.
-- Service keys are obtained securely through Cloud Foundry CLI.
-- The middleware only proxies requests matching any of the configured path prefixes.
-- If no paths are configured, the middleware will be inactive and log a warning.
-
-## Keywords
-
-- OAuth2 Middleware
-- Cloud Foundry ADP
-- Bearer Token
-- Fiori tools
-- SAP UI5
-- Proxy Middleware
+- UI5 middleware
+- Cloud Foundry
+- Approuter
+- Destination proxy
+- SAP BTP

package/dist/approuter/approuter.d.ts

@@ -0,0 +1,27 @@
+import createApprouter from '@sap/approuter';
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { XsappConfig } from '../types';
+/**
+ * Options for starting the approuter.
+ */
+interface StartApprouterOptions {
+    /** Port to run the approuter on. */
+    port: number;
+    /** Parsed xs-app.json configuration. */
+    xsappConfig: XsappConfig;
+    /** Project root path (working directory for approuter). */
+    rootPath: string;
+    /** Approuter extension modules. */
+    modules: unknown[];
+    /** Logger instance. */
+    logger: ToolsLogger;
+}
+/**
+ * Start the approuter and register it globally for cleanup.
+ *
+ * @param options - Approuter start options.
+ * @returns The started approuter instance.
+ */
+export declare function startApprouter(options: StartApprouterOptions): ReturnType<typeof createApprouter>;
+export {};
+//# sourceMappingURL=approuter.d.ts.map

package/dist/approuter/approuter.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startApprouter = startApprouter;
+const approuter_1 = __importDefault(require("@sap/approuter"));
+/**
+ * Start the approuter and register it globally for cleanup.
+ *
+ * @param options - Approuter start options.
+ * @returns The started approuter instance.
+ */
+function startApprouter(options) {
+    const { port, xsappConfig, rootPath, modules, logger } = options;
+    const approuter = (0, approuter_1.default)();
+    try {
+        approuter.start({
+            port,
+            xsappConfig,
+            workingDir: rootPath,
+            extensions: modules
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to start approuter on port ${port}: ${message}`);
+    }
+    logger.debug(`Approuter started on port ${port}`);
+    // Register approuter globally for cleanup
+    const globalKey = 'backend-proxy-middleware-cf';
+    const g = globalThis;
+    if (typeof g[globalKey]?.approuters === 'object') {
+        g[globalKey].approuters?.push(approuter);
+    }
+    return approuter;
+}
+//# sourceMappingURL=approuter.js.map

package/dist/approuter/extensions.d.ts

@@ -0,0 +1,29 @@
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { ApprouterExtension, ExtensionModule, LoadedExtensions } from '../types';
+/**
+ * Load and prepare extension modules for the approuter.
+ *
+ * @param rootPath - Project root path for resolving module paths.
+ * @param extensions - Extension configs from effectiveOptions.
+ * @param logger - Logger instance.
+ * @returns Loaded extension modules and list of extension routes (paths) they register.
+ */
+export declare function loadExtensions(rootPath: string, extensions: ApprouterExtension[] | undefined, logger: ToolsLogger): LoadedExtensions;
+/**
+ * Collect route paths registered by an extension module via insertMiddleware.
+ *
+ * @param extensionModule - The extension module to inspect.
+ * @returns Array of path strings from insertMiddleware entries that define a path.
+ */
+export declare function getExtensionRoutes(extensionModule: ExtensionModule): string[];
+/**
+ * Convert an extension config to a loaded extension module with parameter-injected handlers.
+ * Does not mutate any shared state; use getExtensionRoutes to obtain paths from the returned module.
+ *
+ * @param extension - The extension to convert.
+ * @param rootPath - The root path of the project for resolving the module.
+ * @param logger - The logger to use.
+ * @returns The extension module, or undefined if the module cannot be resolved.
+ */
+export declare function toExtensionModule(extension: ApprouterExtension, rootPath: string, logger: ToolsLogger): ExtensionModule | undefined;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/approuter/extensions.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadExtensions = loadExtensions;
+exports.getExtensionRoutes = getExtensionRoutes;
+exports.toExtensionModule = toExtensionModule;
+/**
+ * Create a wrapper that injects parameters as 4th argument for approuter extension handlers.
+ *
+ * @param middleware - Original handler (req, res, next, params).
+ * @param params - Parameters to inject (from extension config).
+ * @returns Wrapper function with ≤3 args so approuter invokes it.
+ */
+function createParametersInjector(middleware, params) {
+    return function injectParameters(req, res, next) {
+        req['backend-proxy-middleware-cf'] = { parameters: params };
+        middleware.apply(this, [req, res, next, params]);
+    };
+}
+/**
+ * Load and prepare extension modules for the approuter.
+ *
+ * @param rootPath - Project root path for resolving module paths.
+ * @param extensions - Extension configs from effectiveOptions.
+ * @param logger - Logger instance.
+ * @returns Loaded extension modules and list of extension routes (paths) they register.
+ */
+function loadExtensions(rootPath, extensions, logger) {
+    const modules = (extensions ?? [])
+        .map((extension) => toExtensionModule(extension, rootPath, logger))
+        .filter((e) => e != null);
+    const routes = modules.flatMap(getExtensionRoutes);
+    return { modules, routes };
+}
+/**
+ * Collect route paths registered by an extension module via insertMiddleware.
+ *
+ * @param extensionModule - The extension module to inspect.
+ * @returns Array of path strings from insertMiddleware entries that define a path.
+ */
+function getExtensionRoutes(extensionModule) {
+    const insertMiddleware = extensionModule.insertMiddleware;
+    if (!insertMiddleware) {
+        return [];
+    }
+    const paths = [];
+    for (const type of Object.keys(insertMiddleware)) {
+        for (const entry of insertMiddleware[type]) {
+            if (typeof entry !== 'function' && entry.path) {
+                paths.push(entry.path);
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Convert an extension config to a loaded extension module with parameter-injected handlers.
+ * Does not mutate any shared state; use getExtensionRoutes to obtain paths from the returned module.
+ *
+ * @param extension - The extension to convert.
+ * @param rootPath - The root path of the project for resolving the module.
+ * @param logger - The logger to use.
+ * @returns The extension module, or undefined if the module cannot be resolved.
+ */
+function toExtensionModule(extension, rootPath, logger) {
+    try {
+        const extensionModulePath = require.resolve(extension.module, { paths: [rootPath] });
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- dynamic user extension path
+        const originalModule = require(extensionModulePath);
+        const insertMiddleware = originalModule?.insertMiddleware;
+        if (!insertMiddleware) {
+            return originalModule;
+        }
+        // Shallow-copy to avoid mutating the require'd module cache
+        const wrappedMiddleware = {};
+        for (const type of Object.keys(insertMiddleware)) {
+            wrappedMiddleware[type] = insertMiddleware[type].map((module) => {
+                if (typeof module === 'function') {
+                    return createParametersInjector(module, extension.parameters);
+                }
+                return { ...module, handler: createParametersInjector(module.handler, extension.parameters) };
+            });
+        }
+        return { ...originalModule, insertMiddleware: wrappedMiddleware };
+    }
+    catch {
+        logger.warn(`Failed to resolve extension "${extension.module}". Extension will be ignored.`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=extensions.js.map

package/dist/config/config.d.ts

@@ -0,0 +1,10 @@
+import type { BackendProxyMiddlewareCfConfig, EffectiveOptions } from '../types';
+export declare const DEFAULT_REWRITE_CONTENT_TYPES: string[];
+/**
+ * Merge user configuration with defaults.
+ *
+ * @param configuration - Configuration from ui5.yaml.
+ * @returns Effective options with all defaults applied.
+ */
+export declare function mergeEffectiveOptions(configuration: BackendProxyMiddlewareCfConfig): EffectiveOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/config/config.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REWRITE_CONTENT_TYPES = void 0;
+exports.mergeEffectiveOptions = mergeEffectiveOptions;
+exports.DEFAULT_REWRITE_CONTENT_TYPES = [
+    'text/html',
+    'application/json',
+    'application/atom+xml',
+    'application/xml'
+];
+/**
+ * Merge user configuration with defaults.
+ *
+ * @param configuration - Configuration from ui5.yaml.
+ * @returns Effective options with all defaults applied.
+ */
+function mergeEffectiveOptions(configuration) {
+    return {
+        debug: false,
+        port: 5000,
+        xsappJsonPath: './xs-app.json',
+        destinations: [],
+        allowServices: false,
+        authenticationMethod: 'none',
+        allowLocalDir: false,
+        rewriteContent: true,
+        rewriteContentTypes: [...exports.DEFAULT_REWRITE_CONTENT_TYPES],
+        appendAuthRoute: false,
+        disableWelcomeFile: false,
+        disableUi5ServerRoutes: false,
+        extensions: [],
+        ...configuration
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Destination name for the local UI5 server (used in xs-app.json routes and env config).
+ */
+export declare const UI5_SERVER_DESTINATION = "ui5-server";
+/**
+ * Header set by the proxy on requests forwarded to the approuter.
+ * Used to detect approuter loop-back requests and prevent infinite loops.
+ */
+export declare const PROXY_MARKER_HEADER = "x-backend-proxy-middleware-cf";
+//# sourceMappingURL=constants.d.ts.map

package/dist/config/constants.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXY_MARKER_HEADER = exports.UI5_SERVER_DESTINATION = void 0;
+/**
+ * Destination name for the local UI5 server (used in xs-app.json routes and env config).
+ */
+exports.UI5_SERVER_DESTINATION = 'ui5-server';
+/**
+ * Header set by the proxy on requests forwarded to the approuter.
+ * Used to detect approuter loop-back requests and prevent infinite loops.
+ */
+exports.PROXY_MARKER_HEADER = 'x-backend-proxy-middleware-cf';
+//# sourceMappingURL=constants.js.map

package/dist/config/env.d.ts

@@ -0,0 +1,32 @@
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { EffectiveOptions } from '../types';
+/**
+ * Load env options from file or CF, apply to process.env, and add destinations from effectiveOptions.
+ *
+ * When effectiveOptions.envOptionsPath is set, loads that JSON file. When null, loads mta.yaml one level
+ * above rootPath and fetches VCAP_SERVICES from CF. effectiveOptions.destinations is applied so
+ * middleware config takes precedence over file/env.
+ *
+ * @param rootPath - Project root path.
+ * @param effectiveOptions - Merged config; envOptionsPath and destinations are used.
+ * @param logger - Logger for CF path.
+ * @returns Promise resolving when env options are loaded and applied.
+ */
+export declare function loadAndApplyEnvOptions(rootPath: string, effectiveOptions: EffectiveOptions, logger: ToolsLogger): Promise<void>;
+/**
+ * Ensure the ui5-server destination exists and has the correct URL.
+ * If ui5-server doesn't exist in configuration, it will be auto-created.
+ * If it exists but has a different port, it will be updated.
+ * In BAS, the external URL is used instead of localhost so the approuter
+ * builds correct redirect URIs.
+ *
+ * This enables multi-instance support and removes the need to manually
+ * configure ui5-server in ui5.yaml - it's auto-configured based on the actual port.
+ *
+ * @param effectiveOptions - Merged options containing destinations.
+ * @param actualPort - The actual port detected from the incoming request.
+ * @param basExternalUrl - Optional BAS external URL; when set, used as the destination URL.
+ * @returns True if destination was created or updated, false if no change needed.
+ */
+export declare function updateUi5ServerDestinationPort(effectiveOptions: EffectiveOptions, actualPort: number, basExternalUrl?: URL): boolean;
+//# sourceMappingURL=env.d.ts.map