@swirl-search/backstage-plugin-search-backend-module-swirl 0.1.0

package/dist/engines/SwirlIndexer.cjs.js

@@ -0,0 +1,171 @@
+'use strict';
+
+var pluginSearchBackendNode = require('@backstage/plugin-search-backend-node');
+
+const sleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+class SwirlIndexer extends pluginSearchBackendNode.BatchSearchEngineIndexer {
+  type;
+  client;
+  logger;
+  maxRetries;
+  retryBaseDelayMs;
+  generation;
+  numRecords = 0;
+  settled = false;
+  constructor(options) {
+    super({ batchSize: options.batchSize });
+    this.type = options.type;
+    this.client = options.client;
+    this.logger = options.logger.child({ documentType: options.type });
+    this.maxRetries = options.maxRetries ?? 3;
+    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 250;
+  }
+  async initialize() {
+    const token = await this.client.mintToken();
+    const result = await this.client.request({
+      url: this.client.url(
+        `/swirl/index/${encodeURIComponent(this.type)}/begin/`
+      ),
+      method: "POST",
+      token
+    });
+    if (!result.ok) {
+      throw new Error(
+        `SWIRL refused to open a generation for ${this.type}: ${describe(
+          result
+        )}`
+      );
+    }
+    const generation = result.body?.generation;
+    if (generation === void 0 || generation === null) {
+      throw new Error(
+        `SWIRL opened a generation for ${this.type} but returned no generation id`
+      );
+    }
+    this.generation = String(generation);
+    this.logger.info(
+      `Opened SWIRL index generation ${this.generation} for ${this.type}`
+    );
+  }
+  async index(documents) {
+    const result = await this.postWithRetry(this.generationUrl("docs/"), {
+      documents
+    });
+    if (!result.ok) {
+      throw new Error(
+        `SWIRL rejected a batch of ${documents.length} ${this.type} documents: ${describe(result)}`
+      );
+    }
+    this.numRecords += documents.length;
+  }
+  async finalize() {
+    if (this.numRecords === 0) {
+      this.logger.warn(
+        `Index for ${this.type} was not replaced: indexer received 0 documents`
+      );
+      await this.abort();
+      return;
+    }
+    const token = await this.client.mintToken();
+    const result = await this.client.request({
+      url: this.generationUrl("finalize/"),
+      method: "POST",
+      token
+    });
+    if (!result.ok) {
+      throw new Error(
+        `SWIRL failed to finalize generation ${this.generation} of ${this.type}: ${describe(result)}`
+      );
+    }
+    this.settled = true;
+    this.logger.info(
+      `Finalized SWIRL index generation ${this.generation} for ${this.type} with ${this.numRecords} documents`
+    );
+  }
+  /**
+   * Covers the case where the failure happened elsewhere in the indexing
+   * pipeline, in which case finalize is never called and the open generation
+   * would otherwise block the next run. `BatchSearchEngineIndexer` has no
+   * error hook, so this follows the approach the Postgres engine takes.
+   *
+   * @internal
+   */
+  async _destroy(error, done) {
+    if (!error) {
+      done();
+      return;
+    }
+    await this.abort();
+    done(error);
+  }
+  /** Best effort: an abort that fails is logged, never rethrown. */
+  async abort() {
+    if (this.settled || !this.generation) {
+      return;
+    }
+    this.settled = true;
+    try {
+      const token = await this.client.mintToken();
+      await this.client.request({
+        url: this.generationUrl("abort/"),
+        method: "POST",
+        token
+      });
+      this.logger.info(
+        `Aborted SWIRL index generation ${this.generation} for ${this.type}`
+      );
+    } catch (e) {
+      this.logger.warn(
+        `Could not abort SWIRL index generation ${this.generation} for ${this.type}: ${e}`
+      );
+    }
+  }
+  generationUrl(suffix) {
+    return this.client.url(
+      `/swirl/index/${encodeURIComponent(this.type)}/${encodeURIComponent(
+        this.generation
+      )}/${suffix}`
+    );
+  }
+  async postWithRetry(url, body) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        await sleep(this.retryBaseDelayMs * 2 ** (attempt - 1));
+      }
+      try {
+        const token = await this.client.mintToken();
+        const result = await this.client.request({
+          url,
+          method: "POST",
+          token,
+          body
+        });
+        if (result.status < 500) {
+          return result;
+        }
+        lastError = new Error(describe(result));
+        this.logger.warn(
+          `SWIRL returned ${result.status} for ${this.type}, attempt ${attempt + 1} of ${this.maxRetries + 1}`
+        );
+      } catch (e) {
+        lastError = e;
+        this.logger.warn(
+          `SWIRL request for ${this.type} failed, attempt ${attempt + 1} of ${this.maxRetries + 1}: ${e}`
+        );
+      }
+    }
+    throw new Error(
+      `SWIRL request for ${this.type} failed after ${this.maxRetries + 1} attempts: ${lastError}`
+    );
+  }
+}
+function describe(result) {
+  const detail = typeof result.body === "string" ? result.body : JSON.stringify(result.body ?? {});
+  return `HTTP ${result.status} ${detail}`;
+}
+
+exports.SwirlIndexer = SwirlIndexer;
+//# sourceMappingURL=SwirlIndexer.cjs.js.map

package/dist/engines/SwirlIndexer.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwirlIndexer.cjs.js","sources":["../../src/engines/SwirlIndexer.ts"],"sourcesContent":["/*\n * Copyright 2026 SWIRL AI Connect\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { BatchSearchEngineIndexer } from '@backstage/plugin-search-backend-node';\nimport { IndexableDocument } from '@backstage/plugin-search-common';\nimport { SwirlClient, SwirlRequestResult } from './SwirlClient';\n\n/**\n * Options for {@link SwirlIndexer}.\n *\n * @public\n */\nexport type SwirlIndexerOptions = {\n  type: string;\n  batchSize: number;\n  client: SwirlClient;\n  logger: LoggerService;\n  /** Retries after the first attempt, on 5xx and transport errors. Default 3. */\n  maxRetries?: number;\n  /** First backoff step in ms; doubles per retry. Default 250. */\n  retryBaseDelayMs?: number;\n};\n\nconst sleep = (ms: number) =>\n  new Promise<void>(resolve => {\n    setTimeout(resolve, ms);\n  });\n\n/**\n * Writes one generation of documents of a single type into SWIRL, using the\n * generation lifecycle of the SWIRL ingest API: begin, docs, then finalize or\n * abort. The live generation is only replaced by a successful finalize, so a\n * stream that dies half way through leaves the served index untouched.\n *\n * @public\n */\nexport class SwirlIndexer extends BatchSearchEngineIndexer {\n  private readonly type: string;\n  private readonly client: SwirlClient;\n  private readonly logger: LoggerService;\n  private readonly maxRetries: number;\n  private readonly retryBaseDelayMs: number;\n\n  private generation?: string;\n  private numRecords = 0;\n  private settled = false;\n\n  constructor(options: SwirlIndexerOptions) {\n    super({ batchSize: options.batchSize });\n    this.type = options.type;\n    this.client = options.client;\n    this.logger = options.logger.child({ documentType: options.type });\n    this.maxRetries = options.maxRetries ?? 3;\n    this.retryBaseDelayMs = options.retryBaseDelayMs ?? 250;\n  }\n\n  async initialize(): Promise<void> {\n    const token = await this.client.mintToken();\n    const result = await this.client.request({\n      url: this.client.url(\n        `/swirl/index/${encodeURIComponent(this.type)}/begin/`,\n      ),\n      method: 'POST',\n      token,\n    });\n\n    if (!result.ok) {\n      throw new Error(\n        `SWIRL refused to open a generation for ${this.type}: ${describe(\n          result,\n        )}`,\n      );\n    }\n\n    const generation = result.body?.generation;\n    if (generation === undefined || generation === null) {\n      throw new Error(\n        `SWIRL opened a generation for ${this.type} but returned no generation id`,\n      );\n    }\n\n    this.generation = String(generation);\n    this.logger.info(\n      `Opened SWIRL index generation ${this.generation} for ${this.type}`,\n    );\n  }\n\n  async index(documents: IndexableDocument[]): Promise<void> {\n    const result = await this.postWithRetry(this.generationUrl('docs/'), {\n      documents,\n    });\n\n    if (!result.ok) {\n      throw new Error(\n        `SWIRL rejected a batch of ${documents.length} ${\n          this.type\n        } documents: ${describe(result)}`,\n      );\n    }\n\n    this.numRecords += documents.length;\n  }\n\n  async finalize(): Promise<void> {\n    // Mirror the zero document guard the other engines apply: an empty\n    // collator run must not wipe the index that is currently being served.\n    if (this.numRecords === 0) {\n      this.logger.warn(\n        `Index for ${this.type} was not replaced: indexer received 0 documents`,\n      );\n      await this.abort();\n      return;\n    }\n\n    const token = await this.client.mintToken();\n    const result = await this.client.request({\n      url: this.generationUrl('finalize/'),\n      method: 'POST',\n      token,\n    });\n\n    if (!result.ok) {\n      throw new Error(\n        `SWIRL failed to finalize generation ${this.generation} of ${\n          this.type\n        }: ${describe(result)}`,\n      );\n    }\n\n    this.settled = true;\n\n    this.logger.info(\n      `Finalized SWIRL index generation ${this.generation} for ${this.type} with ${this.numRecords} documents`,\n    );\n  }\n\n  /**\n   * Covers the case where the failure happened elsewhere in the indexing\n   * pipeline, in which case finalize is never called and the open generation\n   * would otherwise block the next run. `BatchSearchEngineIndexer` has no\n   * error hook, so this follows the approach the Postgres engine takes.\n   *\n   * @internal\n   */\n  async _destroy(error: Error | null, done: (error?: Error | null) => void) {\n    if (!error) {\n      done();\n      return;\n    }\n\n    await this.abort();\n    done(error);\n  }\n\n  /** Best effort: an abort that fails is logged, never rethrown. */\n  private async abort(): Promise<void> {\n    if (this.settled || !this.generation) {\n      return;\n    }\n    this.settled = true;\n\n    try {\n      const token = await this.client.mintToken();\n      await this.client.request({\n        url: this.generationUrl('abort/'),\n        method: 'POST',\n        token,\n      });\n      this.logger.info(\n        `Aborted SWIRL index generation ${this.generation} for ${this.type}`,\n      );\n    } catch (e) {\n      this.logger.warn(\n        `Could not abort SWIRL index generation ${this.generation} for ${this.type}: ${e}`,\n      );\n    }\n  }\n\n  private generationUrl(suffix: string): string {\n    return this.client.url(\n      `/swirl/index/${encodeURIComponent(this.type)}/${encodeURIComponent(\n        this.generation!,\n      )}/${suffix}`,\n    );\n  }\n\n  private async postWithRetry(\n    url: string,\n    body: unknown,\n  ): Promise<SwirlRequestResult> {\n    let lastError: unknown;\n\n    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {\n      if (attempt > 0) {\n        await sleep(this.retryBaseDelayMs * 2 ** (attempt - 1));\n      }\n\n      try {\n        const token = await this.client.mintToken();\n        const result = await this.client.request({\n          url,\n          method: 'POST',\n          token,\n          body,\n        });\n\n        if (result.status < 500) {\n          return result;\n        }\n\n        lastError = new Error(describe(result));\n        this.logger.warn(\n          `SWIRL returned ${result.status} for ${this.type}, attempt ${\n            attempt + 1\n          } of ${this.maxRetries + 1}`,\n        );\n      } catch (e) {\n        lastError = e;\n        this.logger.warn(\n          `SWIRL request for ${this.type} failed, attempt ${attempt + 1} of ${\n            this.maxRetries + 1\n          }: ${e}`,\n        );\n      }\n    }\n\n    throw new Error(\n      `SWIRL request for ${this.type} failed after ${\n        this.maxRetries + 1\n      } attempts: ${lastError}`,\n    );\n  }\n}\n\nfunction describe(result: SwirlRequestResult): string {\n  const detail =\n    typeof result.body === 'string'\n      ? result.body\n      : JSON.stringify(result.body ?? {});\n  return `HTTP ${result.status} ${detail}`;\n}\n"],"names":["BatchSearchEngineIndexer"],"mappings":";;;;AAqCA,MAAM,KAAA,GAAQ,CAAC,EAAA,KACb,IAAI,QAAc,CAAA,OAAA,KAAW;AAC3B,EAAA,UAAA,CAAW,SAAS,EAAE,CAAA;AACxB,CAAC,CAAA;AAUI,MAAM,qBAAqBA,gDAAA,CAAyB;AAAA,EACxC,IAAA;AAAA,EACA,MAAA;AAAA,EACA,MAAA;AAAA,EACA,UAAA;AAAA,EACA,gBAAA;AAAA,EAET,UAAA;AAAA,EACA,UAAA,GAAa,CAAA;AAAA,EACb,OAAA,GAAU,KAAA;AAAA,EAElB,YAAY,OAAA,EAA8B;AACxC,IAAA,KAAA,CAAM,EAAE,SAAA,EAAW,OAAA,CAAQ,SAAA,EAAW,CAAA;AACtC,IAAA,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AACpB,IAAA,IAAA,CAAK,SAAS,OAAA,CAAQ,MAAA;AACtB,IAAA,IAAA,CAAK,MAAA,GAAS,QAAQ,MAAA,CAAO,KAAA,CAAM,EAAE,YAAA,EAAc,OAAA,CAAQ,MAAM,CAAA;AACjE,IAAA,IAAA,CAAK,UAAA,GAAa,QAAQ,UAAA,IAAc,CAAA;AACxC,IAAA,IAAA,CAAK,gBAAA,GAAmB,QAAQ,gBAAA,IAAoB,GAAA;AAAA,EACtD;AAAA,EAEA,MAAM,UAAA,GAA4B;AAChC,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,SAAA,EAAU;AAC1C,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,MAAA,CAAO,OAAA,CAAQ;AAAA,MACvC,GAAA,EAAK,KAAK,MAAA,CAAO,GAAA;AAAA,QACf,CAAA,aAAA,EAAgB,kBAAA,CAAmB,IAAA,CAAK,IAAI,CAAC,CAAA,OAAA;AAAA,OAC/C;AAAA,MACA,MAAA,EAAQ,MAAA;AAAA,MACR;AAAA,KACD,CAAA;AAED,IAAA,IAAI,CAAC,OAAO,EAAA,EAAI;AACd,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,uCAAA,EAA0C,IAAA,CAAK,IAAI,CAAA,EAAA,EAAK,QAAA;AAAA,UACtD;AAAA,SACD,CAAA;AAAA,OACH;AAAA,IACF;AAEA,IAAA,MAAM,UAAA,GAAa,OAAO,IAAA,EAAM,UAAA;AAChC,IAAA,IAAI,UAAA,KAAe,MAAA,IAAa,UAAA,KAAe,IAAA,EAAM;AACnD,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,8BAAA,EAAiC,KAAK,IAAI,CAAA,8BAAA;AAAA,OAC5C;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,UAAA,GAAa,OAAO,UAAU,CAAA;AACnC,IAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,MACV,CAAA,8BAAA,EAAiC,IAAA,CAAK,UAAU,CAAA,KAAA,EAAQ,KAAK,IAAI,CAAA;AAAA,KACnE;AAAA,EACF;AAAA,EAEA,MAAM,MAAM,SAAA,EAA+C;AACzD,IAAA,MAAM,SAAS,MAAM,IAAA,CAAK,cAAc,IAAA,CAAK,aAAA,CAAc,OAAO,CAAA,EAAG;AAAA,MACnE;AAAA,KACD,CAAA;AAED,IAAA,IAAI,CAAC,OAAO,EAAA,EAAI;AACd,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,0BAAA,EAA6B,UAAU,MAAM,CAAA,CAAA,EAC3C,KAAK,IACP,CAAA,YAAA,EAAe,QAAA,CAAS,MAAM,CAAC,CAAA;AAAA,OACjC;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,cAAc,SAAA,CAAU,MAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,QAAA,GAA0B;AAG9B,IAAA,IAAI,IAAA,CAAK,eAAe,CAAA,EAAG;AACzB,MAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,QACV,CAAA,UAAA,EAAa,KAAK,IAAI,CAAA,+CAAA;AAAA,OACxB;AACA,MAAA,MAAM,KAAK,KAAA,EAAM;AACjB,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,SAAA,EAAU;AAC1C,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,MAAA,CAAO,OAAA,CAAQ;AAAA,MACvC,GAAA,EAAK,IAAA,CAAK,aAAA,CAAc,WAAW,CAAA;AAAA,MACnC,MAAA,EAAQ,MAAA;AAAA,MACR;AAAA,KACD,CAAA;AAED,IAAA,IAAI,CAAC,OAAO,EAAA,EAAI;AACd,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,oCAAA,EAAuC,KAAK,UAAU,CAAA,IAAA,EACpD,KAAK,IACP,CAAA,EAAA,EAAK,QAAA,CAAS,MAAM,CAAC,CAAA;AAAA,OACvB;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAEf,IAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,MACV,CAAA,iCAAA,EAAoC,KAAK,UAAU,CAAA,KAAA,EAAQ,KAAK,IAAI,CAAA,MAAA,EAAS,KAAK,UAAU,CAAA,UAAA;AAAA,KAC9F;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,QAAA,CAAS,KAAA,EAAqB,IAAA,EAAsC;AACxE,IAAA,IAAI,CAAC,KAAA,EAAO;AACV,MAAA,IAAA,EAAK;AACL,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,KAAK,KAAA,EAAM;AACjB,IAAA,IAAA,CAAK,KAAK,CAAA;AAAA,EACZ;AAAA;AAAA,EAGA,MAAc,KAAA,GAAuB;AACnC,IAAA,IAAI,IAAA,CAAK,OAAA,IAAW,CAAC,IAAA,CAAK,UAAA,EAAY;AACpC,MAAA;AAAA,IACF;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAEf,IAAA,IAAI;AACF,MAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,SAAA,EAAU;AAC1C,MAAA,MAAM,IAAA,CAAK,OAAO,OAAA,CAAQ;AAAA,QACxB,GAAA,EAAK,IAAA,CAAK,aAAA,CAAc,QAAQ,CAAA;AAAA,QAChC,MAAA,EAAQ,MAAA;AAAA,QACR;AAAA,OACD,CAAA;AACD,MAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,QACV,CAAA,+BAAA,EAAkC,IAAA,CAAK,UAAU,CAAA,KAAA,EAAQ,KAAK,IAAI,CAAA;AAAA,OACpE;AAAA,IACF,SAAS,CAAA,EAAG;AACV,MAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,QACV,0CAA0C,IAAA,CAAK,UAAU,QAAQ,IAAA,CAAK,IAAI,KAAK,CAAC,CAAA;AAAA,OAClF;AAAA,IACF;AAAA,EACF;AAAA,EAEQ,cAAc,MAAA,EAAwB;AAC5C,IAAA,OAAO,KAAK,MAAA,CAAO,GAAA;AAAA,MACjB,CAAA,aAAA,EAAgB,kBAAA,CAAmB,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,EAAI,kBAAA;AAAA,QAC/C,IAAA,CAAK;AAAA,OACN,IAAI,MAAM,CAAA;AAAA,KACb;AAAA,EACF;AAAA,EAEA,MAAc,aAAA,CACZ,GAAA,EACA,IAAA,EAC6B;AAC7B,IAAA,IAAI,SAAA;AAEJ,IAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,IAAA,CAAK,YAAY,OAAA,EAAA,EAAW;AAC3D,MAAA,IAAI,UAAU,CAAA,EAAG;AACf,QAAA,MAAM,KAAA,CAAM,IAAA,CAAK,gBAAA,GAAmB,CAAA,KAAM,UAAU,CAAA,CAAE,CAAA;AAAA,MACxD;AAEA,MAAA,IAAI;AACF,QAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,MAAA,CAAO,SAAA,EAAU;AAC1C,QAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,MAAA,CAAO,OAAA,CAAQ;AAAA,UACvC,GAAA;AAAA,UACA,MAAA,EAAQ,MAAA;AAAA,UACR,KAAA;AAAA,UACA;AAAA,SACD,CAAA;AAED,QAAA,IAAI,MAAA,CAAO,SAAS,GAAA,EAAK;AACvB,UAAA,OAAO,MAAA;AAAA,QACT;AAEA,QAAA,SAAA,GAAY,IAAI,KAAA,CAAM,QAAA,CAAS,MAAM,CAAC,CAAA;AACtC,QAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,UACV,CAAA,eAAA,EAAkB,MAAA,CAAO,MAAM,CAAA,KAAA,EAAQ,IAAA,CAAK,IAAI,CAAA,UAAA,EAC9C,OAAA,GAAU,CACZ,CAAA,IAAA,EAAO,IAAA,CAAK,UAAA,GAAa,CAAC,CAAA;AAAA,SAC5B;AAAA,MACF,SAAS,CAAA,EAAG;AACV,QAAA,SAAA,GAAY,CAAA;AACZ,QAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,UACV,CAAA,kBAAA,EAAqB,IAAA,CAAK,IAAI,CAAA,iBAAA,EAAoB,OAAA,GAAU,CAAC,CAAA,IAAA,EAC3D,IAAA,CAAK,UAAA,GAAa,CACpB,CAAA,EAAA,EAAK,CAAC,CAAA;AAAA,SACR;AAAA,MACF;AAAA,IACF;AAEA,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,kBAAA,EAAqB,KAAK,IAAI,CAAA,cAAA,EAC5B,KAAK,UAAA,GAAa,CACpB,cAAc,SAAS,CAAA;AAAA,KACzB;AAAA,EACF;AACF;AAEA,SAAS,SAAS,MAAA,EAAoC;AACpD,EAAA,MAAM,MAAA,GACJ,OAAO,MAAA,CAAO,IAAA,KAAS,QAAA,GACnB,MAAA,CAAO,IAAA,GACP,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,IAAA,IAAQ,EAAE,CAAA;AACtC,EAAA,OAAO,CAAA,KAAA,EAAQ,MAAA,CAAO,MAAM,CAAA,CAAA,EAAI,MAAM,CAAA,CAAA;AACxC;;"}

package/dist/engines/SwirlNoopIndexer.cjs.js

@@ -0,0 +1,29 @@
+'use strict';
+
+var pluginSearchBackendNode = require('@backstage/plugin-search-backend-node');
+
+class SwirlNoopIndexer extends pluginSearchBackendNode.BatchSearchEngineIndexer {
+  type;
+  logger;
+  numRecords = 0;
+  constructor(options) {
+    super({ batchSize: 100 });
+    this.type = options.type;
+    this.logger = options.logger.child({ documentType: options.type });
+  }
+  async initialize() {
+  }
+  async index(documents) {
+    this.numRecords += documents.length;
+  }
+  async finalize() {
+    if (this.numRecords > 0) {
+      this.logger.warn(
+        `Discarded ${this.numRecords} documents written to ${this.type}: the federated type is not indexed`
+      );
+    }
+  }
+}
+
+exports.SwirlNoopIndexer = SwirlNoopIndexer;
+//# sourceMappingURL=SwirlNoopIndexer.cjs.js.map

package/dist/engines/SwirlNoopIndexer.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SwirlNoopIndexer.cjs.js","sources":["../../src/engines/SwirlNoopIndexer.ts"],"sourcesContent":["/*\n * Copyright 2026 SWIRL AI Connect\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { BatchSearchEngineIndexer } from '@backstage/plugin-search-backend-node';\nimport { IndexableDocument } from '@backstage/plugin-search-common';\n\n/**\n * Options for {@link SwirlNoopIndexer}.\n *\n * @public\n */\nexport type SwirlNoopIndexerOptions = {\n  type: string;\n  logger: LoggerService;\n};\n\n/**\n * The indexer handed back for the federated document type. The federated lane\n * has nothing to index: its collator yields zero documents and exists only so\n * the type is registered. Anything written here is dropped, so a stray\n * document can never reach the SWIRL ingest API under this type.\n *\n * @public\n */\nexport class SwirlNoopIndexer extends BatchSearchEngineIndexer {\n  private readonly type: string;\n  private readonly logger: LoggerService;\n  private numRecords = 0;\n\n  constructor(options: SwirlNoopIndexerOptions) {\n    super({ batchSize: 100 });\n    this.type = options.type;\n    this.logger = options.logger.child({ documentType: options.type });\n  }\n\n  async initialize(): Promise<void> {}\n\n  async index(documents: IndexableDocument[]): Promise<void> {\n    this.numRecords += documents.length;\n  }\n\n  async finalize(): Promise<void> {\n    if (this.numRecords > 0) {\n      this.logger.warn(\n        `Discarded ${this.numRecords} documents written to ${this.type}: the federated type is not indexed`,\n      );\n    }\n  }\n}\n"],"names":["BatchSearchEngineIndexer"],"mappings":";;;;AAsCO,MAAM,yBAAyBA,gDAAA,CAAyB;AAAA,EAC5C,IAAA;AAAA,EACA,MAAA;AAAA,EACT,UAAA,GAAa,CAAA;AAAA,EAErB,YAAY,OAAA,EAAkC;AAC5C,IAAA,KAAA,CAAM,EAAE,SAAA,EAAW,GAAA,EAAK,CAAA;AACxB,IAAA,IAAA,CAAK,OAAO,OAAA,CAAQ,IAAA;AACpB,IAAA,IAAA,CAAK,MAAA,GAAS,QAAQ,MAAA,CAAO,KAAA,CAAM,EAAE,YAAA,EAAc,OAAA,CAAQ,MAAM,CAAA;AAAA,EACnE;AAAA,EAEA,MAAM,UAAA,GAA4B;AAAA,EAAC;AAAA,EAEnC,MAAM,MAAM,SAAA,EAA+C;AACzD,IAAA,IAAA,CAAK,cAAc,SAAA,CAAU,MAAA;AAAA,EAC/B;AAAA,EAEA,MAAM,QAAA,GAA0B;AAC9B,IAAA,IAAI,IAAA,CAAK,aAAa,CAAA,EAAG;AACvB,MAAA,IAAA,CAAK,MAAA,CAAO,IAAA;AAAA,QACV,CAAA,UAAA,EAAa,IAAA,CAAK,UAAU,CAAA,sBAAA,EAAyB,KAAK,IAAI,CAAA,mCAAA;AAAA,OAChE;AAAA,IACF;AAAA,EACF;AACF;;"}

package/dist/engines/SwirlSearchEngine.cjs.js

@@ -0,0 +1,377 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+var SwirlClient = require('./SwirlClient.cjs.js');
+var SwirlIndexer = require('./SwirlIndexer.cjs.js');
+var SwirlNoopIndexer = require('./SwirlNoopIndexer.cjs.js');
+var types = require('./types.cjs.js');
+
+class SwirlSearchEngine {
+  options;
+  logger;
+  client;
+  preTag;
+  postTag;
+  constructor(options, deps) {
+    this.options = options;
+    this.logger = deps.logger;
+    this.client = new SwirlClient.SwirlClient({
+      baseUrl: options.baseUrl,
+      auth: deps.auth,
+      audience: options.audience,
+      timeoutMs: options.queryTimeoutMs,
+      fetchImpl: deps.fetchImpl
+    });
+    const tag = node_crypto.randomUUID();
+    this.preTag = `<${tag}>`;
+    this.postTag = `</${tag}>`;
+  }
+  static async fromConfig(config, deps) {
+    const engine = new SwirlSearchEngine(readSwirlConfig(config), deps);
+    await engine.pushTuning();
+    return engine;
+  }
+  /**
+   * Mirrors the app-config tuning block to SWIRL so that relevance is
+   * configured in one place. A SWIRL that is not up yet, or an older SWIRL
+   * that does not know the endpoint, must not stop the backend from booting.
+   *
+   * SWIRL answers with the effective tuning in its own flat form plus
+   * `accepted_keys`, naming every key it took in the shape it was sent, and a
+   * `bm25` notice when it stored BM25 parameters it cannot apply. Both are
+   * logged, because a tuning block that is accepted by Backstage and then
+   * quietly dropped by SWIRL is exactly the failure this call exists to make
+   * visible. A 400 names the keys SWIRL did not recognise; that is a warning,
+   * not a boot failure.
+   */
+  async pushTuning() {
+    try {
+      const token = await this.client.mintToken();
+      const result = await this.client.request({
+        url: this.client.url("/swirl/index/config/"),
+        method: "POST",
+        token,
+        body: this.options.tuning
+      });
+      if (!result.ok) {
+        const rejected = rejectedTuningKeys(result.body);
+        const detail = rejected.length ? ` SWIRL did not recognise: ${rejected.join(", ")}.` : describeTuningError(result.body);
+        this.logger.warn(
+          `SWIRL rejected the relevance tuning block: HTTP ${result.status}.${detail} SWIRL keeps its current tuning.`
+        );
+        return;
+      }
+      const body = result.body ?? {};
+      const accepted = Array.isArray(body.accepted_keys) ? body.accepted_keys.map(String) : [];
+      this.logger.info(
+        accepted.length ? `Mirrored the relevance tuning block to SWIRL; SWIRL accepted: ${accepted.join(
+          ", "
+        )}` : "Mirrored the relevance tuning block to SWIRL; SWIRL reported no accepted tuning keys"
+      );
+      if (typeof body.bm25 === "string" && body.bm25) {
+        this.logger.warn(
+          `SWIRL stored the bm25 tuning values but reports them "${body.bm25}", so search.swirl.tuning.bm25 has no effect on ranking.`
+        );
+      }
+    } catch (e) {
+      this.logger.warn(
+        `Could not send the relevance tuning block to SWIRL at ${this.options.baseUrl}: ${e}. SWIRL keeps its current tuning.`
+      );
+    }
+  }
+  translator(query, options) {
+    const pageSize = query.pageLimit || 25;
+    const cursor = decodePageCursor(query.pageCursor);
+    const federated = options.federatedEnabled && (query.types === void 0 || query.types.includes(types.SWIRL_FEDERATED_TYPE));
+    const indexTypes = query.types?.filter(
+      (type) => type !== types.SWIRL_FEDERATED_TYPE
+    );
+    return {
+      term: query.term ?? "",
+      indexTypes,
+      federated,
+      filters: query.filters ?? {},
+      pageSize,
+      cursor
+    };
+  }
+  setTranslator(translator) {
+    this.translator = translator;
+  }
+  async getIndexer(type) {
+    if (type === types.SWIRL_FEDERATED_TYPE) {
+      return new SwirlNoopIndexer.SwirlNoopIndexer({ type, logger: this.logger });
+    }
+    return new SwirlIndexer.SwirlIndexer({
+      type,
+      batchSize: this.options.indexerBatchSize,
+      client: this.client,
+      logger: this.logger
+    });
+  }
+  async query(query, options) {
+    const concrete = this.translator(query, {
+      federatedEnabled: this.options.federated.enabled
+    });
+    const token = await this.resolveToken(options);
+    const result = concrete.cursor ? await this.fetchResultPage(concrete, concrete.cursor, token) : await this.fetchFirstPage(concrete, token);
+    this.assertIndexPresent(result);
+    if (!result.ok) {
+      throw new Error(
+        `SWIRL returned HTTP ${result.status} for the query ${JSON.stringify(
+          concrete.term
+        )}`
+      );
+    }
+    const body = result.body ?? {};
+    const page = concrete.cursor?.p ?? 0;
+    const searchId = concrete.cursor?.s ?? body.info?.search?.id;
+    const swirlResults = body.results ?? [];
+    const results = swirlResults.map(
+      (entry, index) => this.toIndexableResult(entry, page * concrete.pageSize + index + 1)
+    );
+    const hasNextPage = searchId !== void 0 && swirlResults.length >= concrete.pageSize;
+    return {
+      results,
+      numberOfResults: body.info?.results?.found_total ?? body.info?.results?.retrieved_total ?? void 0,
+      nextPageCursor: hasNextPage ? encodePageCursor({ s: searchId, p: page + 1 }) : void 0,
+      previousPageCursor: page > 0 && searchId !== void 0 ? encodePageCursor({ s: searchId, p: page - 1 }) : void 0
+    };
+  }
+  /**
+   * Page 0 federates: SWIRL runs the query across the Backstage index and,
+   * when the federated lane is active, the connected providers too.
+   */
+  async fetchFirstPage(concrete, token) {
+    const providers = [types.SWIRL_INDEX_PROVIDER_TAG];
+    if (concrete.federated) {
+      providers.push(...this.options.federated.providerTags);
+    }
+    return this.client.request({
+      url: this.client.url("/swirl/search/", {
+        qs: concrete.term,
+        providers: providers.join(","),
+        backstage_types: concrete.indexTypes?.join(",") ?? "",
+        backstage_filters: JSON.stringify(concrete.filters),
+        backstage_timeout_ms: concrete.federated ? this.options.federated.timeoutMs : void 0,
+        results_requested: concrete.pageSize,
+        rag: "false"
+      }),
+      method: "GET",
+      token,
+      timeoutMs: this.options.queryTimeoutMs
+    });
+  }
+  /**
+   * Page N is a database read in SWIRL, not a second federation. That keeps
+   * the paging loop in Backstage's AuthorizedSearchEngine cheap.
+   */
+  async fetchResultPage(concrete, cursor, token) {
+    return this.client.request({
+      url: this.client.url("/swirl/results/", {
+        search_id: String(cursor.s),
+        page: cursor.p + 1,
+        results_requested: concrete.pageSize
+      }),
+      method: "GET",
+      token,
+      timeoutMs: this.options.queryTimeoutMs
+    });
+  }
+  /**
+   * The search router hands the engine a plugin token minted per request,
+   * carrying the caller's identity in its `obo` claim; that token is what
+   * SWIRL verifies. Programmatic callers that reach the engine directly get
+   * a freshly minted one instead.
+   */
+  async resolveToken(options) {
+    if (options && "token" in options && options.token) {
+      return options.token;
+    }
+    const credentials = options && "credentials" in options ? options.credentials : void 0;
+    return this.client.mintToken(credentials);
+  }
+  /**
+   * SWIRL reports a type with no live index either as a 404 with an
+   * `missing_index` error body, or as a structured `__MISSING_INDEX__` entry
+   * in the response messages. Either way the caller asked for something that
+   * has never been indexed, which is worth saying out loud rather than
+   * returning an empty result set or a bare 500.
+   */
+  assertIndexPresent(result) {
+    const body = result.body;
+    if (result.status === 404 && body?.error === "missing_index") {
+      throw missingIndexError(body?.types);
+    }
+    for (const message of body?.messages ?? []) {
+      if (typeof message !== "string" || !message.includes("__MISSING_INDEX__")) {
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(message);
+      } catch {
+        continue;
+      }
+      if (parsed?.type === "__MISSING_INDEX__") {
+        throw missingIndexError(parsed.types);
+      }
+    }
+  }
+  toIndexableResult(entry, rank) {
+    const backstage = entry.payload?.backstage;
+    const indexed = backstage?.type !== void 0 && backstage?.document !== void 0;
+    return {
+      type: indexed ? backstage.type : types.SWIRL_FEDERATED_TYPE,
+      document: indexed ? backstage.document : {
+        // Stripped defensively. SWIRL's relevancy processor writes the
+        // marked up text back over `title` and `body`, which is what its
+        // own UI renders; a Backstage renderer shows document text as
+        // plain text, so the markers arrived on screen as literal
+        // `<em>`. Current SWIRL keeps these fields clean, older ones do
+        // not, and the engine has to be safe against both.
+        title: this.stripMarkers(entry.title),
+        text: this.stripMarkers(entry.body),
+        location: entry.url ?? "",
+        source: entry.searchprovider ?? "",
+        // Federated results are not in any Backstage index, so SWIRL's
+        // score is the only ranking signal a renderer can show. Indexed
+        // documents are handed back exactly as Backstage collated them.
+        score: types.swirlResultScore(entry)
+      },
+      rank,
+      highlight: this.toHighlight(entry)
+    };
+  }
+  toHighlight(entry) {
+    if (!this.options.highlight.enabled) {
+      return { preTag: this.preTag, postTag: this.postTag, fields: {} };
+    }
+    const fields = {};
+    const title = this.rewriteHighlight(entry.title_hit_highlights);
+    const text = this.rewriteHighlight(entry.body_hit_highlights);
+    if (title) {
+      fields.title = title;
+    }
+    if (text) {
+      fields.text = text;
+    }
+    return { preTag: this.preTag, postTag: this.postTag, fields };
+  }
+  /** Removes the configured marker pair, leaving the text it wrapped. */
+  stripMarkers(value) {
+    if (!value) {
+      return "";
+    }
+    const { startMarker, endMarker } = this.options.highlight;
+    return value.split(startMarker).join("").split(endMarker).join("");
+  }
+  /**
+   * SWIRL wraps hits in a configurable marker pair, `<em>` and `</em>` out of
+   * the box. Backstage expects the engine's own per-instance tags instead, so
+   * that a document body containing the marker cannot forge a highlight.
+   *
+   * The `maxChars` budget counts visible characters, not tags, and the walk
+   * never emits an unbalanced tag: a snippet cut short inside a hit closes it.
+   */
+  rewriteHighlight(highlights) {
+    const raw = (highlights ?? []).find((value) => Boolean(value));
+    if (!raw) {
+      return void 0;
+    }
+    const { startMarker, endMarker, maxChars } = this.options.highlight;
+    const pattern = new RegExp(
+      `${escapeRegExp(startMarker)}([\\s\\S]*?)${escapeRegExp(endMarker)}`,
+      "g"
+    );
+    let out = "";
+    let budget = maxChars;
+    let cursor = 0;
+    const take = (value, hit) => {
+      if (budget <= 0 || !value) {
+        return;
+      }
+      const kept = value.slice(0, budget);
+      budget -= kept.length;
+      out += hit ? `${this.preTag}${kept}${this.postTag}` : kept;
+    };
+    for (const match of raw.matchAll(pattern)) {
+      const at = match.index ?? 0;
+      take(raw.slice(cursor, at), false);
+      take(match[1], true);
+      cursor = at + match[0].length;
+    }
+    take(raw.slice(cursor), false);
+    return out;
+  }
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function rejectedTuningKeys(body) {
+  const detail = typeof body?.detail === "string" ? body.detail : "";
+  const match = detail.match(/unknown tuning key\(s\):\s*(.*)/i);
+  if (!match) {
+    return [];
+  }
+  return match[1].split(/\.\s*Known keys/i)[0].replace(/\.\s*$/, "").split(",").map((key) => key.trim()).filter(Boolean);
+}
+function describeTuningError(body) {
+  const detail = typeof body?.detail === "string" ? body.detail : "";
+  return detail ? ` ${detail}` : "";
+}
+function missingIndexError(types$1) {
+  const named = Array.isArray(types$1) && types$1.length ? types$1.join(", ") : void 0;
+  const error = new Error(
+    named ? `SWIRL has no live index for the requested document type(s): ${named}. Wait for the collator to run, or check the SWIRL ingest logs.` : "SWIRL has no live index for one of the requested document types. Wait for the collator to run, or check the SWIRL ingest logs."
+  );
+  error.name = types.MISSING_INDEX_ERROR_NAME;
+  return error;
+}
+function decodePageCursor(pageCursor) {
+  if (!pageCursor) {
+    return void 0;
+  }
+  const decoded = JSON.parse(
+    Buffer.from(pageCursor, "base64").toString("utf-8")
+  );
+  if (decoded === null || typeof decoded !== "object" || decoded.s === void 0 || typeof decoded.p !== "number" || decoded.p < 0) {
+    throw new Error("Invalid page cursor");
+  }
+  return { s: decoded.s, p: decoded.p };
+}
+function encodePageCursor(cursor) {
+  return Buffer.from(JSON.stringify(cursor), "utf-8").toString("base64");
+}
+function readSwirlConfig(config) {
+  const swirl = config.getConfig("search.swirl");
+  const federated = swirl.getOptionalConfig("federated");
+  const highlight = swirl.getOptionalConfig("highlight");
+  const tuning = swirl.getOptionalConfig("tuning");
+  return {
+    baseUrl: swirl.getString("baseUrl"),
+    audience: swirl.getOptionalString("audience") ?? "search",
+    indexerBatchSize: swirl.getOptionalNumber("indexerBatchSize") ?? 500,
+    queryTimeoutMs: swirl.getOptionalNumber("queryTimeoutMs") ?? 8e3,
+    federated: {
+      enabled: federated?.getOptionalBoolean("enabled") ?? true,
+      providerTags: federated?.getOptionalStringArray("providerTags") ?? [
+        "backstage"
+      ],
+      timeoutMs: federated?.getOptionalNumber("timeoutMs") ?? 5e3
+    },
+    tuning: tuning?.get() ?? {},
+    highlight: {
+      enabled: highlight?.getOptionalBoolean("enabled") ?? true,
+      maxChars: highlight?.getOptionalNumber("maxChars") ?? 200,
+      startMarker: highlight?.getOptionalString("startMarker") ?? types.SWIRL_HIGHLIGHT_START_MARKER,
+      endMarker: highlight?.getOptionalString("endMarker") ?? types.SWIRL_HIGHLIGHT_END_MARKER
+    }
+  };
+}
+
+exports.SwirlSearchEngine = SwirlSearchEngine;
+exports.decodePageCursor = decodePageCursor;
+exports.encodePageCursor = encodePageCursor;
+exports.readSwirlConfig = readSwirlConfig;
+//# sourceMappingURL=SwirlSearchEngine.cjs.js.map