agl 41.1.0 → 42.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/changelog.md +48 -0
  2. package/dist_serve/bundle.js +2190 -2193
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +3 -68
  5. package/dist_serve/bundle.js.third-party-notices.txt +4 -137
  6. package/dist_ts/00_commitinfo_data.js +1 -1
  7. package/dist_ts/aglapi/aglapisurface.document.js +4 -4
  8. package/dist_ts/classes.authmodels.d.ts +2 -8
  9. package/dist_ts/classes.authmodels.js +60 -23
  10. package/dist_ts/classes.authstore.d.ts +22 -0
  11. package/dist_ts/classes.authstore.js +152 -23
  12. package/dist_ts/classes.cli.d.ts +3 -6
  13. package/dist_ts/classes.cli.js +38 -51
  14. package/dist_ts/classes.config.d.ts +17 -3
  15. package/dist_ts/classes.config.js +55 -18
  16. package/dist_ts/classes.controller.d.ts +12 -12
  17. package/dist_ts/classes.controller.js +46 -117
  18. package/dist_ts/classes.controllermanagement.d.ts +42 -9
  19. package/dist_ts/classes.controllermanagement.js +72 -23
  20. package/dist_ts/classes.controllerservice.d.ts +3 -31
  21. package/dist_ts/classes.controllerservice.js +3 -47
  22. package/dist_ts/classes.inferencegateway.js +4 -3
  23. package/dist_ts/classes.inferenceusage.d.ts +19 -7
  24. package/dist_ts/classes.inferenceusage.js +49 -13
  25. package/dist_ts/classes.inferenceusagetap.d.ts +15 -3
  26. package/dist_ts/classes.inferenceusagetap.js +16 -9
  27. package/dist_ts/classes.mcpcontrollerhost.js +9 -3
  28. package/dist_ts/classes.processinspection.d.ts +8 -1
  29. package/dist_ts/classes.processinspection.js +92 -2
  30. package/dist_ts/classes.proxycontrol.js +6 -1
  31. package/dist_ts/classes.proxydaemon.d.ts +2 -2
  32. package/dist_ts/classes.proxydaemon.js +1 -1
  33. package/dist_ts/classes.proxystore.d.ts +2 -11
  34. package/dist_ts/classes.proxystore.js +3 -25
  35. package/dist_ts/classes.tpmsecretcodec.d.ts +13 -0
  36. package/dist_ts/classes.tpmsecretcodec.js +28 -0
  37. package/dist_ts/classes.trustedproxysecrets.d.ts +91 -0
  38. package/dist_ts/classes.trustedproxysecrets.js +338 -0
  39. package/dist_ts/classes.upgradecoordinator.d.ts +14 -1
  40. package/dist_ts/classes.upgradecoordinator.js +21 -3
  41. package/dist_ts/classes.upgradetransaction.d.ts +32 -0
  42. package/dist_ts/classes.upgradetransaction.js +101 -4
  43. package/dist_ts/classes.usagefeed.js +3 -2
  44. package/dist_ts/functions.controlleradmission.d.ts +67 -0
  45. package/dist_ts/functions.controlleradmission.js +127 -0
  46. package/dist_ts/functions.remotecli.d.ts +27 -0
  47. package/dist_ts/functions.remotecli.js +236 -0
  48. package/dist_ts/functions.retiredenvironment.d.ts +11 -2
  49. package/dist_ts/functions.retiredenvironment.js +22 -5
  50. package/dist_ts/index.d.ts +1 -0
  51. package/dist_ts/index.js +2 -1
  52. package/dist_ts/interfaces.auth.d.ts +29 -4
  53. package/dist_ts/interfaces.auth.js +5 -1
  54. package/dist_ts/interfaces.config.d.ts +14 -0
  55. package/dist_ts/interfaces.config.js +9 -2
  56. package/dist_ts/interfaces.lifecycle.d.ts +3 -0
  57. package/dist_ts_authswitch/classes.authoritydaemon.js +6 -1
  58. package/dist_ts_interfaces/interfaces.d.ts +2 -2
  59. package/dist_ts_interfaces/interfaces.js +1 -1
  60. package/dist_ts_interfaces/management.d.ts +2 -2
  61. package/dist_ts_interfaces/management.js +2 -2
  62. package/dist_ts_interfaces/metrics.d.ts +29 -7
  63. package/dist_ts_interfaces/metrics.js +14 -1
  64. package/dist_ts_interfaces/requests.d.ts +1 -2
  65. package/dist_ts_interfaces/requests.js +1 -1
  66. package/dist_ts_interfaces/requests.upgrade.d.ts +0 -12
  67. package/package.json +12 -11
  68. package/readme.md +99 -28
  69. package/ts/00_commitinfo_data.ts +1 -1
  70. package/ts/aglapi/aglapisurface.document.ts +3 -3
  71. package/ts/classes.authmodels.ts +68 -25
  72. package/ts/classes.authstore.ts +151 -24
  73. package/ts/classes.cli.ts +38 -61
  74. package/ts/classes.config.ts +70 -21
  75. package/ts/classes.controller.ts +50 -163
  76. package/ts/classes.controllermanagement.ts +123 -49
  77. package/ts/classes.controllerservice.ts +3 -56
  78. package/ts/classes.inferencegateway.ts +3 -2
  79. package/ts/classes.inferenceusage.ts +58 -19
  80. package/ts/classes.inferenceusagetap.ts +27 -8
  81. package/ts/classes.mcpcontrollerhost.ts +10 -5
  82. package/ts/classes.processinspection.ts +84 -3
  83. package/ts/classes.proxycontrol.ts +2 -0
  84. package/ts/classes.proxydaemon.ts +3 -2
  85. package/ts/classes.proxystore.ts +4 -25
  86. package/ts/classes.tpmsecretcodec.ts +26 -0
  87. package/ts/classes.trustedproxysecrets.ts +317 -0
  88. package/ts/classes.upgradecoordinator.ts +33 -3
  89. package/ts/classes.upgradetransaction.ts +130 -1
  90. package/ts/classes.usagefeed.ts +2 -1
  91. package/ts/functions.controlleradmission.ts +168 -0
  92. package/ts/functions.remotecli.ts +264 -0
  93. package/ts/functions.retiredenvironment.ts +25 -3
  94. package/ts/index.ts +1 -0
  95. package/ts/interfaces.auth.ts +36 -3
  96. package/ts/interfaces.config.ts +15 -0
  97. package/ts/interfaces.lifecycle.ts +3 -0
  98. package/ts_authswitch/classes.authoritydaemon.ts +2 -0
  99. package/ts_interfaces/interfaces.ts +2 -2
  100. package/ts_interfaces/management.ts +2 -2
  101. package/ts_interfaces/metrics.ts +34 -7
  102. package/ts_interfaces/requests.ts +0 -10
  103. package/ts_interfaces/requests.upgrade.ts +0 -16
  104. package/ts_web/00_commitinfo_data.ts +1 -1
  105. package/ts_web/classes.controllersocketclient.ts +5 -2
  106. package/ts_web/elements.metricsboard.ts +68 -18
@@ -86,13 +86,13 @@ interface IUpgradeSemver {
86
86
  }
87
87
 
88
88
  const upgradeOwnerCommands = [
89
- '__serve', '__upgrade-worker', 'upgrade', 'start', 'restart', 'service', 'foreground', 'temp-password', 'config',
89
+ '__serve', '__upgrade-worker', 'upgrade', 'start', 'restart', 'service', 'foreground', 'temp-password', 'config', 'remote',
90
90
  ] as const;
91
91
  /** The CLI commands this release runs under an upgrade lock or a start lease. */
92
92
  type TUpgradeOwnerCommand = (typeof upgradeOwnerCommands)[number];
93
93
  const upgradeOwnerCommandSet: ReadonlySet<string> = new Set(upgradeOwnerCommands);
94
94
  /**
95
- * A command a later release's CLI holds a start lease under (`agl remote` from 42 on), read back after a rollback:
95
+ * A command a later release's CLI holds a start lease under, read back after a rollback:
96
96
  * its owner is live while that command runs and stale once it ended, like any other.
97
97
  */
98
98
  const laterReleaseStartCommandPattern = /^[a-z][a-z0-9-]{0,31}$/;
@@ -253,6 +253,12 @@ export interface IUpgradeAuthorityHandoff {
253
253
  export interface IUpgradeTransactionV2 extends IUpgradeTransactionBase {
254
254
  version: typeof coordinationVersion;
255
255
  sourceVersion: string;
256
+ /**
257
+ * What the source package declares about gateway sources (`controllerGatewaySourcesVersion` in its installed
258
+ * `package.json`), recorded by the CLI that creates the transaction and never changed afterwards. Absent when the
259
+ * source declares none, as every release before 42, whose CLI never writes it: absence means unsupported.
260
+ */
261
+ sourceGatewaySourcesVersion?: number;
256
262
  targetVersion?: string;
257
263
  registryUrl?: string;
258
264
  targetStartupInvoked?: true;
@@ -845,6 +851,14 @@ const parseUpgradeAuthorityHandoff = (valueArg: unknown): IUpgradeAuthorityHando
845
851
  };
846
852
  };
847
853
 
854
+ /**
855
+ * A declared gateway-sources contract (`controllerGatewaySourcesVersion` in a package, `sourceGatewaySourcesVersion`
856
+ * in an upgrade transaction): a safe integer of 1 or more.
857
+ */
858
+ export const isControllerGatewaySourcesVersion = (valueArg: unknown): valueArg is number => (
859
+ typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 1
860
+ );
861
+
848
862
  const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 => {
849
863
  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
850
864
  throw new Error('Upgrade transaction metadata is malformed.');
@@ -855,6 +869,7 @@ const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 =>
855
869
  'continueSessions', 'gracePeriodMs', 'phase', 'message', 'createdAt', 'updatedAt',
856
870
  'phaseStartedAt', 'sessions',
857
871
  ...(value.blockers === undefined ? [] : ['blockers']),
872
+ ...(value.sourceGatewaySourcesVersion === undefined ? [] : ['sourceGatewaySourcesVersion']),
858
873
  ...(value.targetVersion === undefined ? [] : ['targetVersion']),
859
874
  ...(value.registryUrl === undefined ? [] : ['registryUrl']),
860
875
  ...(value.targetStartupInvoked === undefined ? [] : ['targetStartupInvoked']),
@@ -874,6 +889,8 @@ const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 =>
874
889
  || !Number.isSafeInteger(value.revision)
875
890
  || (value.revision as number) < 0
876
891
  || typeof value.controllerWasRunning !== 'boolean'
892
+ || (value.sourceGatewaySourcesVersion !== undefined
893
+ && !isControllerGatewaySourcesVersion(value.sourceGatewaySourcesVersion))
877
894
  || (value.targetStartupInvoked !== undefined && value.targetStartupInvoked !== true)
878
895
  || typeof value.continueSessions !== 'boolean'
879
896
  || !Number.isSafeInteger(value.gracePeriodMs)
@@ -1001,6 +1018,9 @@ const parseUpgradeTransactionV2 = (valueArg: unknown): IUpgradeTransactionV2 =>
1001
1018
  revision: value.revision as number,
1002
1019
  port: assertPort(value.port),
1003
1020
  sourceVersion: assertBoundedText(value.sourceVersion, 'The upgrade source version', 128),
1021
+ ...(value.sourceGatewaySourcesVersion === undefined
1022
+ ? {}
1023
+ : { sourceGatewaySourcesVersion: value.sourceGatewaySourcesVersion as number }),
1004
1024
  ...(value.targetVersion === undefined
1005
1025
  ? {}
1006
1026
  : { targetVersion: assertBoundedText(value.targetVersion, 'The upgrade target version', 128) }),
@@ -3017,7 +3037,7 @@ export class UpgradeCoordinator {
3017
3037
  token: string;
3018
3038
  cliPath: string;
3019
3039
  /** `__serve` is the service unit's controller starting without a CLI: after a failure, at login or at boot. */
3020
- command: 'start' | 'restart' | 'service' | 'foreground' | 'temp-password' | 'config' | '__serve';
3040
+ command: 'start' | 'restart' | 'service' | 'foreground' | 'temp-password' | 'config' | 'remote' | '__serve';
3021
3041
  upgradeToken?: string;
3022
3042
  }): Promise<UpgradeStartLease> {
3023
3043
  await this.init();
@@ -3488,6 +3508,8 @@ export class UpgradeCoordinator {
3488
3508
  token: string;
3489
3509
  port: number;
3490
3510
  sourceVersion: string;
3511
+ /** The source package's `controllerGatewaySourcesVersion`, read from its installed `package.json`. */
3512
+ sourceGatewaySourcesVersion?: number;
3491
3513
  registryUrl?: string;
3492
3514
  controllerWasRunning: boolean;
3493
3515
  continueSessions: boolean;
@@ -3501,6 +3523,9 @@ export class UpgradeCoordinator {
3501
3523
  revision: 0,
3502
3524
  port: assertPort(optionsArg.port),
3503
3525
  sourceVersion: assertBoundedText(optionsArg.sourceVersion, 'The upgrade source version', 128),
3526
+ ...(optionsArg.sourceGatewaySourcesVersion === undefined
3527
+ ? {}
3528
+ : { sourceGatewaySourcesVersion: optionsArg.sourceGatewaySourcesVersion }),
3504
3529
  ...(optionsArg.registryUrl === undefined
3505
3530
  ? {}
3506
3531
  : { registryUrl: normalizeUpgradeRegistryUrl(optionsArg.registryUrl) }),
@@ -3665,6 +3690,11 @@ export class UpgradeCoordinator {
3665
3690
  && next.version === coordinationVersion
3666
3691
  && currentArg.registryUrl !== next.registryUrl
3667
3692
  ) throw new Error('The upgrade registry cannot change after the transaction is created.');
3693
+ if (
3694
+ currentArg.version === coordinationVersion
3695
+ && next.version === coordinationVersion
3696
+ && currentArg.sourceGatewaySourcesVersion !== next.sourceGatewaySourcesVersion
3697
+ ) throw new Error('The upgrade source\'s gateway-sources declaration cannot change after the transaction is created.');
3668
3698
  if (
3669
3699
  (currentArg.preparationAcceptedAt !== undefined
3670
3700
  && next.preparationAcceptedAt !== currentArg.preparationAcceptedAt)
@@ -8,9 +8,14 @@ import {
8
8
  type IControllerStatus,
9
9
  } from '../ts_interfaces/index.js';
10
10
  import { resolveAGLHomePaths } from './classes.aglhome.js';
11
+ import { SmartDataAuthStore } from './classes.authstore.js';
12
+ import { readDatabaseConfig } from './classes.config.js';
13
+ import { controllerGatewaySourcesVersion, type IControllerRuntimeConfig } from './interfaces.config.js';
11
14
  import {
12
15
  isControllerManagementProtocolVersion,
13
16
  isLoopbackPortListening,
17
+ isManagedControllerManagementProtocol,
18
+ unmanagedControllerError,
14
19
  queryControllerStatus,
15
20
  requestControllerUpgradeFinalize,
16
21
  requestControllerUpgradePrepareBegin,
@@ -30,6 +35,7 @@ import {
30
35
  import {
31
36
  createUpgradeToken,
32
37
  compareUpgradeSemver,
38
+ isControllerGatewaySourcesVersion,
33
39
  type TUpgradeTransaction,
34
40
  type IUpgradeTransactionInventoryEntry,
35
41
  type IUpgradeTransactionV3,
@@ -151,6 +157,11 @@ export interface IPnpmGlobalInstallation {
151
157
  * none, as every release older than the loopback management endpoint.
152
158
  */
153
159
  managementProtocolVersion?: number;
160
+ /**
161
+ * What the installed `package.json` declares about gateway sources (`controllerGatewaySourcesVersion`); absent when
162
+ * it declares none, as every release before 42. An upgrade transaction records it for its source.
163
+ */
164
+ gatewaySourcesVersion?: number;
154
165
  }
155
166
 
156
167
  /**
@@ -161,6 +172,14 @@ const readDeclaredManagementProtocolVersion = (valueArg: unknown): number | unde
161
172
  valueArg === undefined ? undefined : isControllerManagementProtocolVersion(valueArg) ? valueArg : false
162
173
  );
163
174
 
175
+ /**
176
+ * What a `package.json` declares as `controllerGatewaySourcesVersion`: `undefined` for no declaration (unsupported),
177
+ * `false` for one that is not a safe integer of 1 or more, which makes the package metadata incompatible.
178
+ */
179
+ const readDeclaredGatewaySourcesVersion = (valueArg: unknown): number | undefined | false => (
180
+ valueArg === undefined ? undefined : isControllerGatewaySourcesVersion(valueArg) ? valueArg : false
181
+ );
182
+
164
183
  export interface IDetachedUpgradeWorker {
165
184
  pid: number;
166
185
  processGroupId: number;
@@ -613,6 +632,7 @@ export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstal
613
632
  bin?: unknown;
614
633
  controllerUpgradeManagementVersion?: unknown;
615
634
  controllerManagementProtocolVersion?: unknown;
635
+ controllerGatewaySourcesVersion?: unknown;
616
636
  };
617
637
  const currentIdentity: { cliName: string; cliRelativePath: string; managementVersion: number } = (
618
638
  currentPackageIdentity
@@ -620,12 +640,14 @@ export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstal
620
640
  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
621
641
  packageJson.controllerManagementProtocolVersion,
622
642
  );
643
+ const gatewaySourcesVersion = readDeclaredGatewaySourcesVersion(packageJson.controllerGatewaySourcesVersion);
623
644
  if (
624
645
  packageJson.name !== controllerPackageName
625
646
  || packageJson.version !== dependency.version
626
647
  || packageJson.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
627
648
  || Number(controllerUpgradeManagementVersion) !== currentIdentity.managementVersion
628
649
  || managementProtocolVersion === false
650
+ || gatewaySourcesVersion === false
629
651
  || !declaresControllerCommands(packageJson.bin, currentIdentity)
630
652
  ) {
631
653
  throw new Error(`The pnpm-global ${controllerPackageName} package metadata is incompatible.`);
@@ -642,6 +664,7 @@ export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstal
642
664
  cliPath,
643
665
  packageVersion: dependency.version,
644
666
  ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
667
+ ...(gatewaySourcesVersion === undefined ? {} : { gatewaySourcesVersion }),
645
668
  };
646
669
  };
647
670
 
@@ -773,11 +796,13 @@ const readExactGlobalPackage = async (
773
796
  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
774
797
  manifest.controllerManagementProtocolVersion,
775
798
  );
799
+ const gatewaySourcesVersion = readDeclaredGatewaySourcesVersion(manifest.controllerGatewaySourcesVersion);
776
800
  if (
777
801
  manifest.name !== identityArg.packageName
778
802
  || manifest.version !== identityArg.version
779
803
  || manifest.controllerUpgradeManagementVersion !== identityArg.managementVersion
780
804
  || managementProtocolVersion === false
805
+ || gatewaySourcesVersion === false
781
806
  || !bin
782
807
  || typeof bin !== 'object'
783
808
  || Array.isArray(bin)
@@ -798,6 +823,7 @@ const readExactGlobalPackage = async (
798
823
  cliPath,
799
824
  packageVersion: identityArg.version,
800
825
  ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
826
+ ...(gatewaySourcesVersion === undefined ? {} : { gatewaySourcesVersion }),
801
827
  packageName: identityArg.packageName,
802
828
  cliName: identityArg.cliName,
803
829
  cliRelativePath: identityArg.cliRelativePath,
@@ -981,12 +1007,14 @@ const resolveAuthoritativeRecoveryInstallation = async (
981
1007
  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
982
1008
  manifest.controllerManagementProtocolVersion,
983
1009
  );
1010
+ const gatewaySourcesVersion = readDeclaredGatewaySourcesVersion(manifest.controllerGatewaySourcesVersion);
984
1011
  if (
985
1012
  manifest.name !== currentIdentity.packageName
986
1013
  || typeof manifest.version !== 'string'
987
1014
  || !currentIdentity.versions.includes(manifest.version)
988
1015
  || manifest.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
989
1016
  || managementProtocolVersion === false
1017
+ || gatewaySourcesVersion === false
990
1018
  || !declaresControllerCommands(bin, currentIdentity)
991
1019
  ) throw new Error('The authoritative recovery package identity is incompatible.');
992
1020
  if (!(await plugins.fs.promises.stat(cliPath)).isFile()) {
@@ -1001,6 +1029,7 @@ const resolveAuthoritativeRecoveryInstallation = async (
1001
1029
  cliPath,
1002
1030
  packageVersion: manifest.version,
1003
1031
  ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
1032
+ ...(gatewaySourcesVersion === undefined ? {} : { gatewaySourcesVersion }),
1004
1033
  };
1005
1034
  };
1006
1035
 
@@ -2004,6 +2033,7 @@ const queryUpgradeManagedController = async (
2004
2033
  packageVersion: identityArg.packageVersion,
2005
2034
  upgradeManagementVersion: identityArg.managementVersion,
2006
2035
  managementProtocolVersion: installationArg.managementProtocolVersion,
2036
+ identity: 'transaction',
2007
2037
  });
2008
2038
 
2009
2039
  const finalizeControllerUpgrade = async (
@@ -2362,6 +2392,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
2362
2392
  protocolVersion: controllerProtocolVersion,
2363
2393
  upgradeManagementVersion: initialTransaction.sourceManagementVersion,
2364
2394
  managementProtocolVersion: currentInstallation.managementProtocolVersion,
2395
+ identity: 'transaction',
2365
2396
  });
2366
2397
  assertExpectedController(runningStatus, payload.expectedController);
2367
2398
  if (
@@ -2770,6 +2801,7 @@ export async function runUpgradeWorker(
2770
2801
  protocolVersion: controllerProtocolVersion,
2771
2802
  upgradeManagementVersion: controllerUpgradeManagementVersion,
2772
2803
  managementProtocolVersion: currentInstallation.managementProtocolVersion,
2804
+ identity: 'transaction',
2773
2805
  });
2774
2806
  assertExpectedController(runningStatus, payloadArg.expectedController);
2775
2807
  if (
@@ -2946,6 +2978,71 @@ export async function runUpgradeWorker(
2946
2978
  }
2947
2979
  }
2948
2980
 
2981
+ /**
2982
+ * Reads what the port's stored runtime configuration holds without running this release on the store, so the older
2983
+ * release a recovery is about to restore still starts on it. A home without a database stores no configuration.
2984
+ */
2985
+ const readStoredRuntimeConfigForRollback = async (
2986
+ portArg: number,
2987
+ ): Promise<IControllerRuntimeConfig | undefined> => {
2988
+ const databaseConfig = readDatabaseConfig();
2989
+ if (
2990
+ databaseConfig.embeddedDataDirectory !== undefined
2991
+ && !plugins.fs.existsSync(databaseConfig.embeddedDataDirectory)
2992
+ ) return undefined;
2993
+ return await new SmartDataAuthStore(databaseConfig).readRuntimeConfigOnly(portArg);
2994
+ };
2995
+
2996
+ /**
2997
+ * Refuses a rollback through this release's upgrade path, before anything is restored, while the port's stored
2998
+ * runtime configuration names gateway sources and the release it would put back does not declare them: the upgrade
2999
+ * transaction records the source package's `controllerGatewaySourcesVersion` (`sourceGatewaySourcesVersion`), and a
3000
+ * source without one (every release before 42, a package transition's bridge package) or below this release's
3001
+ * declaration would refuse to start on them. Only this release, still installed, can remove them with
3002
+ * `agl remote unset`.
3003
+ */
3004
+ export const assertRollbackKeepsGatewaySources = async (
3005
+ optionsArg: {
3006
+ sourcePackageName: string;
3007
+ sourceVersion: string;
3008
+ /** The transaction's `sourceGatewaySourcesVersion`; `undefined` when it records none. */
3009
+ sourceGatewaySourcesVersion: number | undefined;
3010
+ port: number;
3011
+ },
3012
+ readRuntimeConfigArg: (portArg: number) => Promise<IControllerRuntimeConfig | undefined> = readStoredRuntimeConfigForRollback,
3013
+ ): Promise<void> => {
3014
+ if (
3015
+ optionsArg.sourceGatewaySourcesVersion !== undefined
3016
+ && optionsArg.sourceGatewaySourcesVersion >= controllerGatewaySourcesVersion
3017
+ ) return;
3018
+ const config = await readRuntimeConfigArg(optionsArg.port);
3019
+ if (config?.gatewaySources === undefined) return;
3020
+ throw new Error(
3021
+ `The stored runtime configuration of controller:${optionsArg.port} names gatewaySources, which `
3022
+ + `${optionsArg.sourcePackageName}@${optionsArg.sourceVersion} cannot enforce, so this recovery does not roll back `
3023
+ + `to it. Run \`${currentCliName} remote unset --port ${optionsArg.port}\` with this release before rolling back, `
3024
+ + `then \`${currentCliName} upgrade --port ${optionsArg.port}\` again to finish the recovery.`,
3025
+ );
3026
+ };
3027
+
3028
+ /**
3029
+ * A stalled upgrade's recovery restored its source package and would start its controller to finalize it: that is
3030
+ * refused for a source whose package declares no management endpoint (a release older than it), since this release
3031
+ * could neither read that controller's status nor finalize it. Nothing is started; the restored package stays
3032
+ * installed and the transaction open, and the restored release's own CLI finishes the recovery over its socket.
3033
+ */
3034
+ const assertRestoredSourceManaged = (
3035
+ installationArg: IPnpmGlobalInstallation,
3036
+ sourceArg: { packageName: string; cliName: string; port: number },
3037
+ ): void => {
3038
+ if (isManagedControllerManagementProtocol(installationArg.managementProtocolVersion)) return;
3039
+ throw new Error(`${unmanagedControllerError({
3040
+ packageName: sourceArg.packageName,
3041
+ packageVersion: installationArg.packageVersion,
3042
+ }).message} The stalled upgrade restored that release without starting its controller; run \`${
3043
+ sourceArg.cliName} upgrade --port ${sourceArg.port}\` again, which runs the restored release, to let it finish the recovery.`);
3044
+ };
3045
+
2949
3046
  const recoverPackageTransition = async (optionsArg: {
2950
3047
  coordinator: UpgradeCoordinator;
2951
3048
  token: string;
@@ -3041,6 +3138,7 @@ const recoverPackageTransition = async (optionsArg: {
3041
3138
  packageVersion: upgradeTransactionTargetVersion(current)!,
3042
3139
  upgradeManagementVersion: current.targetManagementVersion,
3043
3140
  managementProtocolVersion: targetInstallation.managementProtocolVersion,
3141
+ identity: 'transaction',
3044
3142
  }).catch(() => undefined);
3045
3143
  if (!status) {
3046
3144
  if (await retainedUpgradeTargetIsAuthoritative({
@@ -3081,6 +3179,13 @@ const recoverPackageTransition = async (optionsArg: {
3081
3179
  return true;
3082
3180
  }
3083
3181
 
3182
+ // The bridge package declares no gateway sources, and a package-transition transaction records none.
3183
+ await assertRollbackKeepsGatewaySources({
3184
+ sourcePackageName: transaction.sourcePackageName,
3185
+ sourceVersion: transaction.sourceVersion,
3186
+ sourceGatewaySourcesVersion: undefined,
3187
+ port: transaction.port,
3188
+ });
3084
3189
  const sourceSpec = `${transaction.sourcePackageName}@${transaction.sourceVersion}`;
3085
3190
  let sourceTopology: IPackageTransitionTopology;
3086
3191
  if (transaction.packageTransitionStarted === true) {
@@ -3092,11 +3197,17 @@ const recoverPackageTransition = async (optionsArg: {
3092
3197
  const sourceInstallation = sourceTopology.source;
3093
3198
  if (!sourceInstallation) throw new Error('The exact bridge package is unavailable.');
3094
3199
  if (transaction.controllerWasRunning) {
3200
+ assertRestoredSourceManaged(sourceInstallation, {
3201
+ packageName: transaction.sourcePackageName,
3202
+ cliName: transaction.sourceCliName,
3203
+ port: transaction.port,
3204
+ });
3095
3205
  let status = await queryControllerStatus(transaction.port, {
3096
3206
  packageName: transaction.sourcePackageName,
3097
3207
  packageVersion: transaction.sourceVersion,
3098
3208
  upgradeManagementVersion: transaction.sourceManagementVersion,
3099
3209
  managementProtocolVersion: sourceInstallation.managementProtocolVersion,
3210
+ identity: 'transaction',
3100
3211
  }).catch(() => undefined);
3101
3212
  if (!status) {
3102
3213
  await startRestoredController(
@@ -3127,7 +3238,12 @@ const recoverPackageTransition = async (optionsArg: {
3127
3238
  return true;
3128
3239
  };
3129
3240
 
3130
- const recoverStalledUpgradeUnderLock = async (optionsArg: {
3241
+ /**
3242
+ * The body of a stalled upgrade's recovery, which a recovery worker runs while it holds the upgrade lock: it finishes
3243
+ * an upgrade past its target's startup and otherwise restores the source and finalizes it. Returns false when a
3244
+ * retained target still owns the transaction.
3245
+ */
3246
+ export const recoverStalledUpgradeUnderLock = async (optionsArg: {
3131
3247
  coordinator: UpgradeCoordinator;
3132
3248
  token: string;
3133
3249
  transaction: TUpgradeTransaction;
@@ -3178,6 +3294,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
3178
3294
  packageVersion: targetInstallation.packageVersion,
3179
3295
  upgradeManagementVersion: controllerUpgradeManagementVersion,
3180
3296
  managementProtocolVersion: targetInstallation.managementProtocolVersion,
3297
+ identity: 'transaction',
3181
3298
  }).catch(() => undefined);
3182
3299
  if (!status) {
3183
3300
  if (await retainedUpgradeTargetIsAuthoritative({
@@ -3223,6 +3340,12 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
3223
3340
  return true;
3224
3341
  }
3225
3342
 
3343
+ await assertRollbackKeepsGatewaySources({
3344
+ sourcePackageName: controllerPackageName,
3345
+ sourceVersion: transaction.sourceVersion,
3346
+ sourceGatewaySourcesVersion: transaction.sourceGatewaySourcesVersion,
3347
+ port: transaction.port,
3348
+ });
3226
3349
  const restorePackage = () => restorePreviousInstallation({
3227
3350
  ...optionsArg.installation,
3228
3351
  packageVersion: transaction.sourceVersion,
@@ -3232,11 +3355,17 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
3232
3355
  ? await handoff.restore(restorePackage)
3233
3356
  : { restored: await restorePackage(), errors: [] };
3234
3357
  if (transaction.controllerWasRunning) {
3358
+ assertRestoredSourceManaged(sourceInstallation, {
3359
+ packageName: controllerPackageName,
3360
+ cliName: currentCliName,
3361
+ port: transaction.port,
3362
+ });
3235
3363
  let status = await queryControllerStatus(transaction.port, {
3236
3364
  packageName: controllerPackageName,
3237
3365
  packageVersion: sourceInstallation.packageVersion,
3238
3366
  upgradeManagementVersion: controllerUpgradeManagementVersion,
3239
3367
  managementProtocolVersion: sourceInstallation.managementProtocolVersion,
3368
+ identity: 'transaction',
3240
3369
  }).catch(() => undefined);
3241
3370
  if (!status) {
3242
3371
  await startRestoredController(
@@ -68,7 +68,8 @@ const bucketOrder = (leftArg: IControllerUsageBucket, rightArg: IControllerUsage
68
68
 
69
69
  const sameCounts = (leftArg: IControllerUsageBucket, rightArg: IControllerUsageBucket): boolean => leftArg.calls === rightArg.calls
70
70
  && leftArg.inputTokens === rightArg.inputTokens && leftArg.outputTokens === rightArg.outputTokens
71
- && leftArg.cacheReadTokens === rightArg.cacheReadTokens && leftArg.cacheWriteTokens === rightArg.cacheWriteTokens;
71
+ && leftArg.cacheReadTokens === rightArg.cacheReadTokens && leftArg.cacheWriteTokens === rightArg.cacheWriteTokens
72
+ && leftArg.cacheReadUnknownCalls === rightArg.cacheReadUnknownCalls && leftArg.cacheWriteUnknownCalls === rightArg.cacheWriteUnknownCalls;
72
73
 
73
74
  /**
74
75
  * The metrics board's usage feed in the controller. The proxy keeps the token usage and has no push, so the feed reads
@@ -0,0 +1,168 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { IControllerRuntimeConfig, TControllerTlsMode } from './interfaces.config.js';
3
+
4
+ /** The header a trusted TLS reverse proxy injects with the controller's trusted-proxy secret. */
5
+ export const trustedProxySecretHeader = 'x-harness-controller-proxy-secret';
6
+
7
+ /** At most this many gateway source addresses per controller. */
8
+ export const maximumGatewaySources = 16;
9
+
10
+ const ipv4MappedPattern = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/iu;
11
+
12
+ /**
13
+ * A peer or configured address as one canonical IP literal: IPv4 dotted, an IPv4-mapped IPv6 address as its IPv4
14
+ * address (a dual-stack listener reports IPv4 peers so), IPv6 compressed and lower case. Undefined for anything
15
+ * else, a scoped IPv6 address and SmartServe's `unknown` included.
16
+ */
17
+ export const canonicalIpAddress = (valueArg: string): string | undefined => {
18
+ const mapped = ipv4MappedPattern.exec(valueArg);
19
+ const candidate = mapped ? mapped[1]! : valueArg;
20
+ const family = plugins.net.isIP(candidate);
21
+ if (family === 4) return candidate;
22
+ if (family !== 6 || candidate.includes('%')) return undefined;
23
+ try {
24
+ return new URL(`http://[${candidate}]/`).hostname.slice(1, -1);
25
+ } catch {
26
+ return undefined;
27
+ }
28
+ };
29
+
30
+ /** 127.0.0.0/8 and ::1, given as canonical addresses. */
31
+ export const isLoopbackAddress = (addressArg: string): boolean =>
32
+ addressArg === '::1' || (plugins.net.isIPv4(addressArg) && addressArg.startsWith('127.'));
33
+
34
+ const describeInput = (valueArg: string): string => JSON.stringify(valueArg.slice(0, 64));
35
+
36
+ /** One configured gateway source address, canonical; loopback and unspecified addresses are refused. */
37
+ export const canonicalGatewaySource = (valueArg: string): string => {
38
+ const address = canonicalIpAddress(valueArg.trim());
39
+ if (address === undefined) {
40
+ throw new Error(`Gateway source ${describeInput(valueArg)} is not an IPv4 or unscoped IPv6 address.`);
41
+ }
42
+ if (isLoopbackAddress(address)) {
43
+ throw new Error(`Gateway source ${address} is a loopback address; loopback is always admitted without one.`);
44
+ }
45
+ if (address === '0.0.0.0' || address === '::') {
46
+ throw new Error(`Gateway source ${address} is the unspecified address; name the gateway's own address.`);
47
+ }
48
+ return address;
49
+ };
50
+
51
+ /** The configured gateway source addresses, canonical, sorted and without duplicates. */
52
+ export const canonicalGatewaySources = (valuesArg: readonly string[]): string[] => {
53
+ const sources = [...new Set(valuesArg.map(canonicalGatewaySource))].sort();
54
+ if (sources.length > maximumGatewaySources) {
55
+ throw new Error(`A controller takes at most ${maximumGatewaySources} gateway source addresses.`);
56
+ }
57
+ return sources;
58
+ };
59
+
60
+ /**
61
+ * The one interface address the controller listens on: loopback in local mode and in TLS-proxy mode without a
62
+ * gateway source (a reverse proxy on this host), every interface otherwise, IPv6 as well when a gateway source is
63
+ * IPv6. Admission then refuses every address off loopback that is not a gateway source.
64
+ */
65
+ export const controllerListenHostname = (
66
+ configArg: Pick<IControllerRuntimeConfig, 'tlsMode' | 'gatewaySources'>,
67
+ ): string => {
68
+ const sources = configArg.tlsMode === 'proxy' ? configArg.gatewaySources ?? [] : [];
69
+ if (sources.length === 0) return '127.0.0.1';
70
+ return sources.some((sourceArg) => plugins.net.isIPv6(sourceArg)) ? '::' : '0.0.0.0';
71
+ };
72
+
73
+ /** The only methods admitted off loopback without an `Origin`: a browser sends none on navigations and asset loads. */
74
+ const originlessMethods: ReadonlySet<string> = new Set(['GET', 'HEAD']);
75
+
76
+ export type TControllerAdmissionKind = 'request' | 'upgrade';
77
+
78
+ /**
79
+ * Why a request or WebSocket upgrade was refused: `source` (off loopback and not from a gateway source, or off
80
+ * loopback at all in local mode), `secret` (without the trusted-proxy secret), `origin` (another browser origin, or
81
+ * off loopback without one on an upgrade or on a request other than GET and HEAD), `forwarded_proto` (an upgrade
82
+ * through the proxy without `X-Forwarded-Proto: https`).
83
+ */
84
+ export type TControllerAdmissionRefusal = 'source' | 'secret' | 'origin' | 'forwarded_proto';
85
+
86
+ export interface IControllerAdmissionPolicy {
87
+ publicOrigin: string;
88
+ tlsMode: TControllerTlsMode;
89
+ /** Canonical, as `IControllerRuntimeConfig.gatewaySources` holds them. */
90
+ gatewaySources: readonly string[];
91
+ /** Whether a header value is the trusted-proxy secret (the current one or a rotation's); never in local mode. */
92
+ acceptsProxySecret(valueArg: string | null): boolean;
93
+ }
94
+
95
+ export interface IControllerAdmissionRequest {
96
+ headers: Headers;
97
+ /**
98
+ * The HTTP method as received (`Request.method`), never SmartServe's `IRequestContext.method`, which reports any
99
+ * method it does not know as GET.
100
+ */
101
+ method: string;
102
+ /** The direct peer, as SmartServe reports it (`IConnectionInfo.remoteAddr`). */
103
+ remoteAddr: string;
104
+ }
105
+
106
+ /**
107
+ * The admission of every HTTP request and WebSocket upgrade on the controller's one listener; undefined admits.
108
+ *
109
+ * Off loopback a request needs both a configured gateway source address and the trusted-proxy secret. An upgrade
110
+ * there also needs the public origin as `Origin` and `X-Forwarded-Proto: https`: only the operator's own tools on
111
+ * loopback connect without an `Origin`. A GET or HEAD request there may come without one, as a browser's navigation
112
+ * and asset requests do; every other method needs the public origin, and no request may carry another. On loopback
113
+ * a request is served as it always was, and an upgrade with an `Origin` needs the public origin, and in TLS-proxy
114
+ * mode the forwarded protocol and the secret as well: a reverse proxy on this host forwards from loopback.
115
+ */
116
+ export const controllerAdmissionRefusal = (
117
+ kindArg: TControllerAdmissionKind,
118
+ requestArg: IControllerAdmissionRequest,
119
+ policyArg: IControllerAdmissionPolicy,
120
+ ): TControllerAdmissionRefusal | undefined => {
121
+ const peer = canonicalIpAddress(requestArg.remoteAddr);
122
+ const origin = requestArg.headers.get('origin');
123
+ if (peer === undefined || !isLoopbackAddress(peer)) {
124
+ if (policyArg.tlsMode !== 'proxy' || peer === undefined || !policyArg.gatewaySources.includes(peer)) return 'source';
125
+ if (!policyArg.acceptsProxySecret(requestArg.headers.get(trustedProxySecretHeader))) return 'secret';
126
+ if (origin === null) {
127
+ return kindArg === 'request' && originlessMethods.has(requestArg.method) ? undefined : 'origin';
128
+ }
129
+ if (origin !== policyArg.publicOrigin) return 'origin';
130
+ if (kindArg === 'upgrade' && requestArg.headers.get('x-forwarded-proto') !== 'https') return 'forwarded_proto';
131
+ return undefined;
132
+ }
133
+ if (kindArg === 'request' || origin === null) return undefined;
134
+ if (origin !== policyArg.publicOrigin) return 'origin';
135
+ if (policyArg.tlsMode === 'local') return undefined;
136
+ if (requestArg.headers.get('x-forwarded-proto') !== 'https') return 'forwarded_proto';
137
+ if (!policyArg.acceptsProxySecret(requestArg.headers.get(trustedProxySecretHeader))) return 'secret';
138
+ return undefined;
139
+ };
140
+
141
+ /**
142
+ * The listener options of the controller's one TypedServer: the interface it binds (`controllerListenHostname`) and
143
+ * the admission of every HTTP request and WebSocket upgrade on it, every surface included, by
144
+ * `controllerAdmissionRefusal`. A refusal answers 403.
145
+ */
146
+ export const controllerListenerOptions = (
147
+ configArg: Pick<IControllerRuntimeConfig, 'publicOrigin' | 'tlsMode' | 'gatewaySources'>,
148
+ acceptsProxySecretArg: (valueArg: string | null) => boolean,
149
+ ): Required<Pick<plugins.typedserver.IServerOptions, 'listenHostname' | 'requestAdmission' | 'websocketAdmission'>> => {
150
+ const policy: IControllerAdmissionPolicy = {
151
+ publicOrigin: configArg.publicOrigin,
152
+ tlsMode: configArg.tlsMode,
153
+ gatewaySources: [...(configArg.tlsMode === 'proxy' ? configArg.gatewaySources ?? [] : [])],
154
+ acceptsProxySecret: (valueArg) => configArg.tlsMode === 'proxy' && acceptsProxySecretArg(valueArg),
155
+ };
156
+ const admit = (kindArg: TControllerAdmissionKind): plugins.typedserver.TRequestAdmissionFunction => (contextArg) => (
157
+ controllerAdmissionRefusal(kindArg, {
158
+ headers: contextArg.headers,
159
+ method: contextArg.request.method,
160
+ remoteAddr: contextArg.connectionInfo?.remoteAddr ?? 'unknown',
161
+ }, policy) === undefined
162
+ );
163
+ return {
164
+ listenHostname: controllerListenHostname(configArg),
165
+ requestAdmission: admit('request'),
166
+ websocketAdmission: admit('upgrade'),
167
+ };
168
+ };