feat: Change backend-proxy-middleware-cf to use approuter instead of token exchange (#4160)

* feat: add approuter support

* refactor: code improvements

* refactor: interfaces and jsdocs

* refactor: code and split methods

* refactor: move types

* chore: add cset

* refactor: move types

* refactor: set default env options in process

* refactor: code improvements

* refactor: middleware options

* test: add test suites

* test: add test suites

* fix: sonar issues

* refactor: improve code quality and tests

* test: add test case

* fix: sonar issue with regxp

* feat: add service cred retrieval for approuter env options

* test: add new tooling tests

* test: add missing test cases

* fix: sonar issues

* fix: dest merging from env path

* fix: review comments

* feat: add approuter lazy loading, dynamic port allocation, loop prevention mechanism

* fix: sonar issue

* refactor: move interfaces

* refactor: code improvements

* feat: add needed configurations for bas

* refactor: clear text

* feat: update xsuaa service runtime

* fix: incorrect credentials object return for vcap services

* fix: add error handling for approuter start

* Linting auto fix commit

* fix: add wait flag for cf cli when updating service

* test: fix failing test

* chore: update cset

* chore: update cset

* feat: add default path for xsapp.json

* fix: test noise and missing api call mock

* fix: remove unused var from test

* refactor: change folder structure in the middleware

* fix: forward error if approuter instantiation fails

* fix: use object assign for process env vars

* refactor: routes, emit warning when route is skipped

* fix: escape regex metacharacters in custom route path filter

* chore: update readme with title links

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: nikmace

.changeset/modern-canyons-wear.md

@@ -0,0 +1,6 @@
+---
+'@sap-ux/backend-proxy-middleware-cf': minor
+'@sap-ux/adp-tooling': patch
+---
+
+feat: Change `backend-proxy-middleware-cf` to use `approuter` instead of token exchange

.vscode/launch.json

@@ -25,6 +25,7 @@
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/abap-deploy-config-sub-generator",
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/abap-deploy-config-inquirer",
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/deploy-config-sub-generator",
+                "--extensionDevelopmentPath=${workspaceFolder}/packages/backend-proxy-middleware-cf",
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/ui5-application-inquirer",
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/ui5-info",
                 "--extensionDevelopmentPath=${workspaceFolder}/packages/ui5-config"
@@ -39,6 +40,7 @@
                 "${workspaceRoot}/packages/abap-deploy-config-sub-generator/generators/**/*.js",
                 "${workspaceRoot}/packages/abap-deploy-config-inquirer/dist/**/*.js",
                 "${workspaceRoot}/packages/deploy-config-sub-generator/generators/**/*.js",
+                "${workspaceRoot}/packages/backend-proxy-middleware-cf/dist/**/*.js",
                 "${workspaceRoot}/packages/ui5-application-inquirer/dist/**/*.js",
                 "${workspaceRoot}/packages/ui5-info/dist/**/*.js",
                 "${workspaceRoot}/packages/ui5-config/dist/**/*.js"

packages/adp-tooling/src/base/helper.ts

@@ -3,6 +3,7 @@ import type { ReaderCollection } from '@ui5/fs'; // eslint-disable-line sonarjs/
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, isAbsolute, relative, basename, dirname } from 'node:path';
 
+import type { ToolsLogger } from '@sap-ux/logger';
 import type { UI5Config } from '@sap-ux/ui5-config';
 import { type InboundContent, type Inbound, AdaptationProjectType } from '@sap-ux/axios-extension';
 import {
@@ -113,6 +114,24 @@ export function extractCfBuildTask(ui5Conf: UI5Config): UI5YamlCustomTaskConfigu
     return buildTask;
 }
 
+/**
+ * Read space GUID from ui5.yaml customTasks app-variant-bundler-build.space.
+ *
+ * @param {string} rootPath - Project root (where ui5.yaml lives).
+ * @param {ToolsLogger} logger - Optional logger.
+ * @returns {Promise<string | undefined>} Space GUID or undefined if not found.
+ */
+export async function getSpaceGuidFromUi5Yaml(rootPath: string, logger?: ToolsLogger): Promise<string | undefined> {
+    try {
+        const ui5Config = await readUi5Config(rootPath, 'ui5.yaml');
+        const buildTask = extractCfBuildTask(ui5Config);
+        return buildTask?.space;
+    } catch {
+        logger?.warn('Could not read space from ui5.yaml (app-variant-bundler-build).');
+        return undefined;
+    }
+}
+
 /**
  * Read the manifest from the build output folder.
  *

packages/adp-tooling/src/cf/project/index.ts

@@ -1,3 +1,3 @@
+export * from './mta';
 export * from './yaml';
 export * from './yaml-loader';
-export * from './mta';

packages/adp-tooling/src/cf/project/mta.ts

@@ -3,10 +3,54 @@ import * as path from 'node:path';
 import type { ToolsLogger } from '@sap-ux/logger';
 
 import { t } from '../../i18n';
+import type { CfServiceOffering, CfAPIResponse, BusinessServiceResource, AppRouterType, MtaYaml } from '../../types';
+import { getServiceKeyCredentialsWithTags } from '../services/api';
+import { requestCfApi } from '../services/cli';
 import { getRouterType } from './yaml';
 import { getYamlContent } from './yaml-loader';
-import { requestCfApi } from '../services/cli';
-import type { CfServiceOffering, CfAPIResponse, BusinessServiceResource, AppRouterType } from '../../types';
+
+const EXCLUDED_SERVICES_VCAP = new Set(['html5-apps-repo', 'portal']);
+
+/**
+ * Builds VCAP_SERVICES by resolving MTA resources to service key credentials.
+ *
+ * @param {MtaYaml['resources']} resources - MTA YAML resources.
+ * @param {string} spaceGuid - The space GUID.
+ * @param {ToolsLogger} logger - Optional logger.
+ * @returns {Promise<Record<string, unknown>>} VCAP_SERVICES keyed by service name.
+ */
+export async function buildVcapServicesFromResources(
+    resources: MtaYaml['resources'],
+    spaceGuid: string,
+    logger?: ToolsLogger
+): Promise<Record<string, unknown>> {
+    const vcapServices: Record<string, unknown> = {};
+    for (const resource of resources ?? []) {
+        const serviceName = resource.parameters?.service;
+        const serviceInstanceName = resource.parameters?.['service-name'];
+        const servicePlan = resource.parameters?.['service-plan'];
+
+        if (!serviceName || !serviceInstanceName || EXCLUDED_SERVICES_VCAP.has(serviceName)) {
+            continue;
+        }
+
+        const data = await getServiceKeyCredentialsWithTags(
+            spaceGuid,
+            serviceName,
+            serviceInstanceName,
+            servicePlan ?? '',
+            logger
+        );
+
+        if (!data?.credentials) {
+            throw new Error(`Credentials and tags for service '${serviceName}' ('${serviceInstanceName}') not found`);
+        }
+
+        vcapServices[serviceName] = [data];
+    }
+
+    return vcapServices;
+}
 
 /**
  * Get the approuter type.

packages/adp-tooling/src/cf/services/api.ts

@@ -20,7 +20,8 @@ import type {
     CfServiceInstance,
     MtaYaml,
     ServiceInfo,
-    CfUi5AppInfo
+    CfUi5AppInfo,
+    ServiceKeyCredentialsWithTags
 } from '../../types';
 import { t } from '../../i18n';
 import { getProjectNameForXsSecurity } from '../project';
@@ -437,3 +438,65 @@ export async function getOrCreateServiceKeys(
         throw new Error(t('error.failedToGetOrCreateServiceKeys', { serviceInstanceName, error: e.message }));
     }
 }
+
+/**
+ * Gets service tags for a given service name.
+ *
+ * @param {string} spaceGuid - The space GUID.
+ * @param {string} serviceName - The service name (e.g., 'xsuaa', 'hana').
+ * @returns {Promise<string[]>} The service tags.
+ */
+export async function getServiceTags(spaceGuid: string, serviceName: string): Promise<string[]> {
+    const json: CfAPIResponse<CfServiceOffering> = await requestCfApi<CfAPIResponse<CfServiceOffering>>(
+        `/v3/service_offerings?per_page=1000&space_guids=${spaceGuid}&names=${serviceName}`
+    );
+    const serviceOffering = json?.resources?.find((resource: CfServiceOffering) => resource.name === serviceName);
+    return serviceOffering?.tags ?? [];
+}
+
+/**
+ * Fetches service tags and credentials for a single app-router resource (xsuaa/destination).
+ *
+ * @param {string} spaceGuid - The space GUID.
+ * @param {string} serviceName - The service name (e.g. 'xsuaa', 'destination').
+ * @param {string} serviceInstanceName - The service instance name.
+ * @param {string} plan - The service plan.
+ * @param {ToolsLogger} logger - Optional logger.
+ * @returns {Promise<ServiceKeyCredentialsWithTags | null>} Service key credentials with tags returned by the CF API.
+ */
+export async function getServiceKeyCredentialsWithTags(
+    spaceGuid: string,
+    serviceName: string,
+    serviceInstanceName: string,
+    plan: string,
+    logger?: ToolsLogger
+): Promise<ServiceKeyCredentialsWithTags | null> {
+    try {
+        const tags = await getServiceTags(spaceGuid, serviceName);
+
+        const serviceInstances = await getServiceInstance({
+            names: [serviceInstanceName],
+            spaceGuids: [spaceGuid]
+        });
+
+        if (serviceInstances.length === 0) {
+            logger?.error(`Service instance '${serviceInstanceName}' not found, skipping`);
+            return null;
+        }
+
+        const credentials = await getOrCreateServiceKeys(serviceInstances[0], logger);
+
+        return {
+            label: serviceName,
+            name: serviceInstanceName,
+            tags,
+            plan,
+            credentials: credentials?.[0].credentials
+        };
+    } catch (e) {
+        logger?.error(
+            `Failed to get credentials and tags for service '${serviceName}' (instance: '${serviceInstanceName}'): ${e.message}`
+        );
+        return null;
+    }
+}

packages/adp-tooling/src/cf/services/cli.ts

@@ -106,6 +106,26 @@ export async function createServiceKey(serviceInstanceName: string, serviceKeyNa
     }
 }
 
+/**
+ * Updates a Cloud Foundry service instance with the given parameters.
+ *
+ * @param {string} serviceInstanceName - The service instance name.
+ * @param {object} parameters - The configuration parameters to update.
+ */
+export async function updateServiceInstance(serviceInstanceName: string, parameters: object): Promise<void> {
+    try {
+        const cliResult = await Cli.execute(
+            ['update-service', serviceInstanceName, '-c', JSON.stringify(parameters), '--wait'],
+            ENV
+        );
+        if (cliResult.exitCode !== 0) {
+            throw new Error(cliResult.stderr);
+        }
+    } catch (e) {
+        throw new Error(t('error.failedToUpdateServiceInstance', { serviceInstanceName, error: e.message }));
+    }
+}
+
 /**
  * Request CF API.
  *

packages/adp-tooling/src/translations/adp-tooling.i18n.json

@@ -103,6 +103,7 @@
         "emptyCFAPIResponse": "Empty response from CF API. Please verify your CF login status with 'cf target' and re-authenticate if needed with 'cf login'.",
         "xsSecurityJsonCouldNotBeParsed": "The xs-security.json file could not be parsed. Ensure the xs-security.json file exists and try again.",
         "failedToCreateServiceInstance": "Failed to create the service instance: '{{serviceInstanceName}}'. Error: {{error}}",
+        "failedToUpdateServiceInstance": "Failed to update the service instance: '{{serviceInstanceName}}'. Error: {{error}}",
         "failedToGetFDCApps": "Retrieving FDC apps failed: {{error}}",
         "failedToGetFDCInbounds": "Retrieving inbounds from the UI5 Flexibility Design and Configuration service failed: {{error}}", 
         "failedToConnectToFDCService": "Failed to connect to the FDC service: '{{status}}'",

packages/adp-tooling/src/types.ts

@@ -932,6 +932,22 @@ export interface ServiceInstance {
     guid: string;
 }
 
+/**
+ * Service key credentials with tags returned by the CF API.
+ */
+export interface ServiceKeyCredentialsWithTags {
+    label: string;
+    name: string;
+    tags: string[];
+    plan: string;
+    credentials: ServiceKeys['credentials'] | undefined;
+}
+
+export interface AppRouterEnvOptions {
+    'VCAP_SERVICES'?: Record<string, unknown>;
+    destinations?: { name: string; url: string }[];
+}
+
 export interface GetServiceInstanceParams {
     spaceGuids?: string[];
     planNames?: string[];

packages/adp-tooling/test/unit/base/helper.test.ts

@@ -18,6 +18,7 @@ import {
     filterAndMapInboundsToManifest,
     readUi5Config,
     extractCfBuildTask,
+    getSpaceGuidFromUi5Yaml,
     readManifestFromBuildPath,
     loadAppVariant,
     getBaseAppId,
@@ -338,6 +339,37 @@ describe('helper', () => {
         });
     });
 
+    describe('getSpaceGuidFromUi5Yaml', () => {
+        const rootPath = join(__dirname, '../../fixtures', 'adaptation-project');
+
+        beforeEach(() => {
+            jest.clearAllMocks();
+        });
+
+        test('returns space GUID when ui5.yaml has app-variant-bundler-build space', async () => {
+            const spaceGuid = 'my-space-guid-123';
+            const mockBuildTask = { space: spaceGuid };
+            readUi5YamlMock.mockResolvedValue({
+                findCustomTask: jest.fn().mockReturnValue({ configuration: mockBuildTask })
+            } as unknown as UI5Config);
+
+            const result = await getSpaceGuidFromUi5Yaml(rootPath);
+
+            expect(readUi5YamlMock).toHaveBeenCalledWith(rootPath, 'ui5.yaml');
+            expect(result).toBe(spaceGuid);
+        });
+
+        test('returns undefined and calls logger.warn when space cannot be read', async () => {
+            readUi5YamlMock.mockRejectedValue(new Error('File not found'));
+            const logger = { warn: jest.fn() };
+
+            const result = await getSpaceGuidFromUi5Yaml(rootPath, logger as never);
+
+            expect(result).toBeUndefined();
+            expect(logger.warn).toHaveBeenCalledWith('Could not read space from ui5.yaml (app-variant-bundler-build).');
+        });
+    });
+
     describe('extractCfBuildTask', () => {
         beforeEach(() => {
             jest.clearAllMocks();