Deduplicate provider adapter host/basePath/validation methods in shared adapter factory (#3210)

* Initial plan

* refactor: share common provider adapter methods

* docs: document participatesInValidation adapter option

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

containers/api-proxy/providers/ADDING-A-PROVIDER.md

@@ -17,13 +17,28 @@ Create `providers/<name>.js`. The adapter is a plain JS object (no class syntax
 ```js
 'use strict';
 
-const { normalizeApiTarget, normalizeBasePath } = require('../proxy-utils');
+const { createBaseAdapterConfig, createAdapterMethods } = require('../proxy-utils');
 
 function createMyProviderAdapter(env, deps = {}) {
   // Read credentials and config from env at construction time
-  const apiKey   = (env.MY_PROVIDER_API_KEY || '').trim() || undefined;
-  const target   = normalizeApiTarget(env.MY_PROVIDER_API_TARGET) || 'api.myprovider.com';
-  const basePath = normalizeBasePath(env.MY_PROVIDER_API_BASE_PATH);
+  const { apiKey, rawTarget: target, basePath } = createBaseAdapterConfig(env, {
+    keyEnvVar: 'MY_PROVIDER_API_KEY',
+    targetEnvVar: 'MY_PROVIDER_API_TARGET',
+    basePathEnvVar: 'MY_PROVIDER_API_BASE_PATH',
+    defaultTarget: 'api.myprovider.com',
+  });
+  const adapterMethods = createAdapterMethods({
+    apiKey,
+    rawTarget: target,
+    basePath,
+    provider: 'my-provider',
+    port: 10005,
+    defaultTarget: 'api.myprovider.com',
+    validationPath: '/v1/models',
+    validationHeaders: () => ({ 'Authorization': `Bearer ${apiKey}` }),
+    modelsPath: '/v1/models',
+    modelsFetchHeaders: () => ({ 'Authorization': `Bearer ${apiKey}` }),
+  });
 
   const bodyTransform = deps.bodyTransform || null;   // model-alias rewriting etc.
 
@@ -34,12 +49,9 @@ function createMyProviderAdapter(env, deps = {}) {
 
     isManagementPort: false,   // true only for port 10000 (OpenAI)
     alwaysBind: false,         // set true to start a 503-stub when not configured
-    get participatesInValidation() { return this.isEnabled(); },
-
     // ── Credentials ──────────────────────────────────────────────────────────
     isEnabled()       { return !!apiKey; },
-    getTargetHost()   { return target; },
-    getBasePath()     { return basePath; },
+    ...adapterMethods,
 
     // ── Per-request auth headers ──────────────────────────────────────────────
     // `req` is the incoming http.IncomingMessage — inspect it for request-specific logic.
@@ -55,41 +67,13 @@ function createMyProviderAdapter(env, deps = {}) {
     // Return a function (body: Buffer) => Buffer|null, or null for no transform.
     getBodyTransform() { return bodyTransform; },
 
-    // ── Startup: credential validation ───────────────────────────────────────
-    // Return a probe config, a skip config, or null if validation is not applicable.
-    getValidationProbe() {
-      if (!apiKey) return null;
-      if (target !== 'api.myprovider.com') {
-        return { skip: true, reason: `Custom target ${target}; validation skipped` };
-      }
-      return {
-        url: `https://${target}/v1/models`,
-        opts: { method: 'GET', headers: { 'Authorization': `Bearer ${apiKey}` } },
-      };
-    },
-
-    // ── Startup: model listing ────────────────────────────────────────────────
-    // Return null to opt out of model fetching.
-    getModelsFetchConfig() {
-      if (!apiKey) return null;
-      return {
-        url:      `https://${target}/v1/models`,
-        opts:     { method: 'GET', headers: { 'Authorization': `Bearer ${apiKey}` } },
-        cacheKey: 'my-provider',   // key in cachedModels; must match name
-      };
-    },
-
-    // ── /reflect endpoint metadata ────────────────────────────────────────────
-    getReflectionInfo() {
-      return {
-        provider:        'my-provider',
-        port:            10005,
-        base_url:        'http://api-proxy:10005',
-        configured:      !!apiKey,
-        models_cache_key: 'my-provider',   // null when models are not fetched
-        models_url:       'http://api-proxy:10005/v1/models',
-      };
-    },
+    // createAdapterMethods provides:
+    // - participatesInValidation (defaults to !!apiKey)
+    // - getTargetHost()
+    // - getBasePath()
+    // - getValidationProbe()
+    // - getModelsFetchConfig()
+    // - getReflectionInfo()
   };
 }
 

containers/api-proxy/providers/anthropic.js

@@ -107,11 +107,7 @@ function createAnthropicAdapter(env, deps = {}) {
      * The stub server does NOT count toward the startup validation latch —
      * only the fully-configured server (when ANTHROPIC_API_KEY is set) does.
      */
-    get participatesInValidation() { return this.isEnabled(); },
-
     isEnabled() { return !!apiKey; },
-    getTargetHost() { return rawTarget; },
-    getBasePath() { return basePath; },
 
     /**
      * Build Anthropic auth headers for this request.

containers/api-proxy/providers/copilot.js

@@ -335,11 +335,7 @@ function createCopilotAdapter(env, deps = {}) {
      * The stub server does NOT count toward the startup validation latch —
      * only the fully-configured server (when credentials are present) does.
      */
-    get participatesInValidation() { return this.isEnabled(); },
-
     isEnabled() { return !!authToken; },
-    getTargetHost() { return rawTarget; },
-    getBasePath() { return basePath; },
 
     /**
      * Build Copilot auth headers for this request.

containers/api-proxy/providers/gemini.js

@@ -59,11 +59,7 @@ function createGeminiAdapter(env, deps = {}) {
      * The 503-fallback server does NOT count toward the startup validation latch —
      * only the fully-configured server (when GEMINI_API_KEY is set) does.
      */
-    get participatesInValidation() { return this.isEnabled(); },
-
     isEnabled() { return !!apiKey; },
-    getTargetHost() { return rawTarget; },
-    getBasePath() { return basePath; },
 
     getAuthHeaders() {
       return { 'x-goog-api-key': apiKey };

containers/api-proxy/providers/openai.js

@@ -126,12 +126,7 @@ function createOpenAIAdapter(env, deps = {}) {
      */
     alwaysBind: true,
 
-    /** Port 10000 always counts toward the startup validation latch. */
-    participatesInValidation: true,
-
     isEnabled() { return !!apiKey || !!oidcProvider?.isReady() || !!awsOidcProvider?.isReady(); },
-    getTargetHost() { return rawTarget; },
-    getBasePath() { return basePath; },
 
     /**
      * Get the OIDC token provider (Azure or GCP — Bearer-token compatible).
@@ -167,6 +162,9 @@ function createOpenAIAdapter(env, deps = {}) {
     getBodyTransform() { return bodyTransform; },
     ...adapterMethods,
 
+    /** Port 10000 always counts toward the startup validation latch. */
+    participatesInValidation: true,
+
     /** Response returned when port 10000 receives a proxy request but no key is set. */
     getUnconfiguredResponse() {
       if (oidcConfigured) {

containers/api-proxy/providers/opencode.js

@@ -117,6 +117,10 @@ function createOpenCodeAdapter(env, { candidateAdapters = [] } = {}) {
      */
     alwaysBind: true,
 
+    // OpenCode is a routing layer over the base providers; those providers
+    // handle their own startup validation and model fetching.
+    ...adapterMethods,
+
     /**
      * The stub server does NOT count toward the startup validation latch —
      * only the fully-configured server (when enabled and a candidate is active) does.
@@ -171,10 +175,6 @@ function createOpenCodeAdapter(env, { candidateAdapters = [] } = {}) {
       return resolveActiveAdapter()?.getBodyTransform() || null;
     },
 
-    // OpenCode is a routing layer over the base providers; those providers
-    // handle their own startup validation and model fetching.
-    ...adapterMethods,
-
     /** Response returned for all requests when OpenCode is not configured. */
     getUnconfiguredResponse() {
       if (!enabled) {

containers/api-proxy/proxy-utils.js

@@ -234,13 +234,17 @@ function createBaseAdapterConfig(env, { keyEnvVar, targetEnvVar, basePathEnvVar,
  * @param {() => boolean} [opts.skipModelsFetch]
  * @param {Record<string,string>|(() => Record<string,string>)} [opts.modelsFetchHeaders]
  * @param {string|null} [opts.modelsCacheKey]
+ * @param {boolean} [opts.participatesInValidation]
  * @param {boolean} [opts.reflectionConfigured]
  * @param {string|null} [opts.reflectionModelsPath]
  * @param {Record<string, unknown>|(() => Record<string, unknown>)} [opts.reflectionExtra]
  * @param {() => ({ url: string, opts: object }|{ skip: true, reason: string }|null)} [opts.getValidationProbe]
  * @param {() => ({ url: string, opts: object, cacheKey: string }|null)} [opts.getModelsFetchConfig]
  * @param {() => object} [opts.getReflectionInfo]
  * @returns {{
+ *   getTargetHost: (req?: import('http').IncomingMessage) => string,
+ *   getBasePath: (req?: import('http').IncomingMessage) => string,
+ *   participatesInValidation: boolean,
  *   getValidationProbe: () => ({ url: string, opts: object }|{ skip: true, reason: string }|null),
  *   getModelsFetchConfig: () => ({ url: string, opts: object, cacheKey: string }|null),
  *   getReflectionInfo: () => object
@@ -263,6 +267,7 @@ function createAdapterMethods(opts) {
     skipModelsFetch,
     modelsFetchHeaders = validationHeaders,
     modelsCacheKey = provider,
+    participatesInValidation = !!apiKey,
     reflectionConfigured = !!apiKey,
     reflectionModelsPath = modelsPath,
     reflectionExtra = {},
@@ -316,6 +321,9 @@ function createAdapterMethods(opts) {
   }));
 
   return {
+    getTargetHost() { return rawTarget; },
+    getBasePath() { return basePath; },
+    participatesInValidation,
     getValidationProbe: builtValidationProbe,
     getModelsFetchConfig: builtModelsFetchConfig,
     getReflectionInfo: builtReflectionInfo,

containers/api-proxy/server.routing.test.js

@@ -85,6 +85,25 @@ describe('createAdapterMethods', () => {
       models_cache_key: 'example',
       models_url: 'http://api-proxy:12345/v1/models',
     });
+    expect(methods.getTargetHost()).toBe('api.example.com');
+    expect(methods.getBasePath()).toBe('/api/v1');
+  });
+
+  it('defaults participatesInValidation from apiKey presence', () => {
+    const methods = createAdapterMethods({
+      rawTarget: 'api.example.com',
+      provider: 'example',
+      port: 12345,
+    });
+    const enabledMethods = createAdapterMethods({
+      apiKey: 'sk-test',
+      rawTarget: 'api.example.com',
+      provider: 'example',
+      port: 12345,
+    });
+
+    expect(methods.participatesInValidation).toBe(false);
+    expect(enabledMethods.participatesInValidation).toBe(true);
   });
 
   it('does not double-slash model fetch URL when basePath is root', () => {