@milaboratories/pl-client 3.11.5 → 3.12.1

package/dist/test/test_config.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"test_config.cjs","names":["path","fs","plAddressToConfig","inferAuthRefreshTime","UnauthenticatedPlClient","LLPlClient","PlClient","startTcpProxy","resourceIdToString"],"sources":["../../src/test/test_config.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport { LLPlClient } from \"../core/ll_client\";\nimport type { AuthInformation, AuthOps, PlClientConfig } from \"../core/config\";\nimport { plAddressToConfig } from \"../core/config\";\nimport { UnauthenticatedPlClient } from \"../core/unauth_client\";\nimport { PlClient } from \"../core/client\";\nimport { randomUUID } from \"node:crypto\";\nimport type { OptionalSignedResourceId } from \"../core/types\";\nimport { NullSignedResourceId, resourceIdToString } from \"../core/types\";\nimport { inferAuthRefreshTime } from \"../core/auth\";\nimport * as path from \"node:path\";\nimport type { TestTcpProxy } from \"./tcp-proxy\";\nimport { startTcpProxy } from \"./tcp-proxy\";\n\nexport { TestTcpProxy };\n\nexport interface TestConfig {\n  address: string;\n  test_proxy?: string;\n  test_user?: string;\n  test_password?: string;\n}\n\nconst CONFIG_FILE = \"test_config.json\";\n// const AUTH_DATA_FILE = '.test_auth.json';\n\nlet authDataFilePath: string | undefined;\n\nfunction getFullAuthDataFilePath() {\n  if (authDataFilePath === undefined) authDataFilePath = path.resolve(\".test_auth.json\");\n  return authDataFilePath;\n}\n\nexport function getTestConfig(): TestConfig {\n  let conf: Partial<TestConfig> = {};\n  if (fs.existsSync(CONFIG_FILE))\n    conf = JSON.parse(fs.readFileSync(CONFIG_FILE, { encoding: \"utf-8\" })) as TestConfig;\n\n  if (process.env.PL_ADDRESS !== undefined) conf.address = process.env.PL_ADDRESS;\n\n  if (process.env.PL_TEST_USER !== undefined) conf.test_user = process.env.PL_TEST_USER;\n\n  if (process.env.PL_TEST_PASSWORD !== undefined) conf.test_password = process.env.PL_TEST_PASSWORD;\n\n  if (process.env.PL_TEST_PROXY !== undefined) conf.test_proxy = process.env.PL_TEST_PROXY;\n\n  if (conf.address === undefined)\n    throw new Error(\n      `can't resolve platform address (checked ${CONFIG_FILE} file and PL_ADDRESS environment var)`,\n    );\n\n  return conf as TestConfig;\n}\n\n/** Default request timeout for tests (ms) */\nexport const TEST_REQUEST_TIMEOUT = 500;\n\n/** Returns PlClientConfig with reduced timeout for tests */\nexport function plAddressToTestConfig(address: string): PlClientConfig {\n  const plConf = plAddressToConfig(address);\n  plConf.defaultRequestTimeout = TEST_REQUEST_TIMEOUT;\n  return plConf;\n}\n\ninterface AuthCache {\n  /** To check if config changed */\n  conf: TestConfig;\n  /** Backend's instance ID at the moment the JWT was issued. Restarts that\n   * reset state rotate this; the JWT's `iss` claim is bound to it and the\n   * backend rejects tokens minted by a different instance. Without this\n   * check, a cached JWT from a previous backend run would silently fail\n   * the first authenticated call after restart. */\n  instanceId: string;\n  expiration: number;\n  authInformation: AuthInformation;\n}\n\nfunction saveAuthInfoCallback(\n  tConf: TestConfig,\n  instanceId: string,\n): (authInformation: AuthInformation) => void {\n  return (authInformation) => {\n    const dst = getFullAuthDataFilePath();\n    const tmpDst = getFullAuthDataFilePath() + randomUUID();\n    fs.writeFileSync(\n      tmpDst,\n      Buffer.from(\n        JSON.stringify({\n          conf: tConf,\n          instanceId,\n          authInformation,\n          expiration: inferAuthRefreshTime(authInformation, 24 * 60 * 60),\n        } as AuthCache),\n      ),\n      \"utf8\",\n    );\n    fs.renameSync(tmpDst, dst);\n  };\n}\n\nconst cleanAuthInfoCallback = () => {\n  const p = getFullAuthDataFilePath();\n  if (fs.existsSync(p)) {\n    console.warn(`Removing: ${p}`);\n    fs.rmSync(p);\n  }\n};\n\nexport async function getTestClientConf(): Promise<{ conf: PlClientConfig; auth: AuthOps }> {\n  const tConf = getTestConfig();\n\n  const plConf = plAddressToTestConfig(tConf.address);\n  const uClient = await UnauthenticatedPlClient.build(plConf);\n  // ll.serverInfo is populated by build()'s ping; instanceId rotates on a\n  // backend restart that drops the persisted state.\n  const instanceId = uClient.ll.serverInfo.instanceId;\n\n  let authInformation: AuthInformation | undefined = undefined;\n\n  // Try recover from cache. The cache is keyed by config AND backend\n  // instanceId — a backend restart that rotates instanceId invalidates the\n  // cached JWT (the token's `iss` claim no longer matches the live\n  // instance), so we re-login instead of carrying the dead token through\n  // to the first authenticated call.\n  if (fs.existsSync(getFullAuthDataFilePath())) {\n    try {\n      const cache: AuthCache = JSON.parse(\n        fs.readFileSync(getFullAuthDataFilePath(), { encoding: \"utf-8\" }),\n      ) as AuthCache; // TODO runtime validation\n      if (\n        cache.conf.address === tConf.address &&\n        cache.conf.test_user === tConf.test_user &&\n        cache.conf.test_password === tConf.test_password &&\n        cache.expiration > Date.now() &&\n        cache.instanceId === instanceId\n      )\n        authInformation = cache.authInformation;\n    } catch {\n      // removing cache file on any error\n      fs.rmSync(getFullAuthDataFilePath());\n    }\n  }\n\n  const requireAuth = await uClient.requireAuth();\n\n  if (!requireAuth && (tConf.test_user !== undefined || tConf.test_password !== undefined))\n    throw new Error(\n      `Server require no auth, but test user name or test password are provided via (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (requireAuth && (tConf.test_user === undefined || tConf.test_password === undefined))\n    throw new Error(\n      `No auth information found in config (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (authInformation === undefined) {\n    if (requireAuth) authInformation = await uClient.login(tConf.test_user!, tConf.test_password!);\n    // No authorization is required\n    else authInformation = {};\n\n    // saving cache\n    saveAuthInfoCallback(tConf, instanceId)(authInformation);\n  }\n\n  return {\n    conf: plConf,\n    auth: {\n      authInformation,\n      onUpdate: saveAuthInfoCallback(tConf, instanceId),\n      onAuthError: cleanAuthInfoCallback,\n      onUpdateError: cleanAuthInfoCallback,\n    },\n  };\n}\n\nexport async function getTestLLClient(confOverrides: Partial<PlClientConfig> = {}) {\n  const { conf, auth } = await getTestClientConf();\n  return await LLPlClient.build({ ...conf, ...confOverrides }, { auth });\n}\n\nexport async function getTestClient(\n  alternativeRoot?: string,\n  confOverrides: Partial<PlClientConfig> = {},\n) {\n  const { conf, auth } = await getTestClientConf();\n  if (alternativeRoot !== undefined && conf.alternativeRoot !== undefined)\n    throw new Error(\"test pl address configured with alternative root\");\n  return await PlClient.init({ ...conf, ...confOverrides, alternativeRoot }, auth);\n}\n\nexport type WithTempRootOptions =\n  | {\n      /** If true and PL_ADDRESS is http://localhost or http://127.0.0.1:<port>,\n       * a TCP proxy will be started and PL client will connect through it. */\n      viaTcpProxy: true;\n      /** Artificial latency for proxy (ms). Default 0 */\n      proxyLatencyMs?: number;\n    }\n  | {\n      viaTcpProxy?: undefined;\n    };\n\nexport async function withTempRoot<T>(body: (pl: PlClient) => Promise<T>): Promise<T | void>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: Awaited<ReturnType<typeof startTcpProxy>>) => Promise<T>,\n  options: {\n    viaTcpProxy: true;\n    proxyLatencyMs?: number;\n  },\n): Promise<T>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: any) => Promise<T>,\n  options: WithTempRootOptions = {},\n): Promise<T | undefined> {\n  const alternativeRoot = `test_${Date.now()}_${randomUUID()}`;\n  let altRootId: OptionalSignedResourceId = NullSignedResourceId;\n  // Proxy management\n  let proxy: Awaited<ReturnType<typeof startTcpProxy>> | undefined;\n  let confOverrides: Partial<PlClientConfig> = {};\n  try {\n    // Optionally start TCP proxy and rewrite PL_ADDRESS to point to proxy\n    if (options.viaTcpProxy === true && process.env.PL_ADDRESS) {\n      try {\n        const url = new URL(process.env.PL_ADDRESS);\n        const isHttp = url.protocol === \"http:\";\n        const isLocal = url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\";\n        const port = parseInt(url.port);\n        if (isHttp && isLocal && Number.isFinite(port)) {\n          proxy = await startTcpProxy({ targetPort: port, latency: options.proxyLatencyMs ?? 0 });\n          // Override client connection host:port to proxy\n          confOverrides = { hostAndPort: `127.0.0.1:${proxy.port}` } as Partial<PlClientConfig>;\n        } else {\n          console.warn(\n            \"*** skipping proxy-based test, PL_ADDRESS is not localhost\",\n            process.env.PL_ADDRESS,\n          );\n          return;\n        }\n      } catch {\n        // ignore proxy setup errors; tests will run against original address\n      }\n    }\n\n    const client = await getTestClient(alternativeRoot, confOverrides);\n    altRootId = client.clientRoot;\n    try {\n      const value = await body(client, proxy);\n      const rawClient = await getTestClient();\n      try {\n        await rawClient.deleteAlternativeRoot(alternativeRoot);\n      } catch (cleanupErr: any) {\n        // Cleanup may fail if test intentionally deleted resources\n        console.warn(`Failed to clean up alternative root ${alternativeRoot}:`, cleanupErr.message);\n      } finally {\n        // Close the cleanup client to avoid dangling gRPC channels that can cause\n        // segfaults during process exit\n        await rawClient.close();\n      }\n      return value;\n    } finally {\n      // Close the test client to avoid dangling gRPC channels\n      await client.close();\n    }\n  } catch (err: any) {\n    console.log(`ALTERNATIVE ROOT: ${alternativeRoot} (${resourceIdToString(altRootId)})`);\n    throw err;\n    // throw new Error('withTempRoot error: ' + err.message, { cause: err });\n  } finally {\n    // Stop proxy if started\n    if (proxy) {\n      try {\n        await proxy.disconnectAll();\n      } catch {\n        /* ignore */\n      }\n      try {\n        await new Promise<void>((resolve) => proxy!.server.close(() => resolve()));\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"test_config.cjs","names":["path","fs","plAddressToConfig","inferAuthRefreshTime","UnauthenticatedPlClient","LLPlClient","PlClient","startTcpProxy","resourceIdToString"],"sources":["../../src/test/test_config.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport { LLPlClient } from \"../core/ll_client\";\nimport type { AuthInformation, AuthOps, PlClientConfig } from \"../core/config\";\nimport { plAddressToConfig } from \"../core/config\";\nimport { UnauthenticatedPlClient } from \"../core/unauth_client\";\nimport { PlClient } from \"../core/client\";\nimport { randomUUID } from \"node:crypto\";\nimport type { OptionalSignedResourceId } from \"../core/types\";\nimport { NullSignedResourceId, resourceIdToString } from \"../core/types\";\nimport { inferAuthRefreshTime } from \"../core/auth\";\nimport * as path from \"node:path\";\nimport type { TestTcpProxy } from \"./tcp-proxy\";\nimport { startTcpProxy } from \"./tcp-proxy\";\n\nexport { TestTcpProxy };\n\nexport interface TestConfig {\n  address: string;\n  test_proxy?: string;\n  test_user?: string;\n  test_password?: string;\n}\n\nconst CONFIG_FILE = \"test_config.json\";\n// const AUTH_DATA_FILE = '.test_auth.json';\n\nlet authDataFilePath: string | undefined;\n\nfunction getFullAuthDataFilePath() {\n  if (authDataFilePath === undefined) authDataFilePath = path.resolve(\".test_auth.json\");\n  return authDataFilePath;\n}\n\nexport function getTestConfig(): TestConfig {\n  let conf: Partial<TestConfig> = {};\n  if (fs.existsSync(CONFIG_FILE))\n    conf = JSON.parse(fs.readFileSync(CONFIG_FILE, { encoding: \"utf-8\" })) as TestConfig;\n\n  if (process.env.PL_ADDRESS !== undefined) conf.address = process.env.PL_ADDRESS;\n\n  if (process.env.PL_TEST_USER !== undefined) conf.test_user = process.env.PL_TEST_USER;\n\n  if (process.env.PL_TEST_PASSWORD !== undefined) conf.test_password = process.env.PL_TEST_PASSWORD;\n\n  if (process.env.PL_TEST_PROXY !== undefined) conf.test_proxy = process.env.PL_TEST_PROXY;\n\n  if (conf.address === undefined)\n    throw new Error(\n      `can't resolve platform address (checked ${CONFIG_FILE} file and PL_ADDRESS environment var)`,\n    );\n\n  return conf as TestConfig;\n}\n\n/** Default request timeout for tests (ms) */\nexport const TEST_REQUEST_TIMEOUT = 500;\n\n/** Returns PlClientConfig with reduced timeout for tests */\nexport function plAddressToTestConfig(address: string): PlClientConfig {\n  const plConf = plAddressToConfig(address);\n  plConf.defaultRequestTimeout = TEST_REQUEST_TIMEOUT;\n  return plConf;\n}\n\ninterface AuthCache {\n  /** To check if config changed */\n  conf: TestConfig;\n  /** Backend's instance ID at the moment the JWT was issued. Restarts that\n   * reset state rotate this; the JWT's `iss` claim is bound to it and the\n   * backend rejects tokens minted by a different instance. Without this\n   * check, a cached JWT from a previous backend run would silently fail\n   * the first authenticated call after restart. */\n  instanceId: string;\n  expiration: number;\n  authInformation: AuthInformation;\n}\n\nfunction saveAuthInfoCallback(\n  tConf: TestConfig,\n  instanceId: string,\n): (authInformation: AuthInformation) => void {\n  return (authInformation) => {\n    const dst = getFullAuthDataFilePath();\n    const tmpDst = getFullAuthDataFilePath() + randomUUID();\n    fs.writeFileSync(\n      tmpDst,\n      Buffer.from(\n        JSON.stringify({\n          conf: tConf,\n          instanceId,\n          authInformation,\n          expiration: inferAuthRefreshTime(authInformation, 24 * 60 * 60),\n        } as AuthCache),\n      ),\n      \"utf8\",\n    );\n    fs.renameSync(tmpDst, dst);\n  };\n}\n\nconst cleanAuthInfoCallback = () => {\n  const p = getFullAuthDataFilePath();\n  if (fs.existsSync(p)) {\n    console.warn(`Removing: ${p}`);\n    fs.rmSync(p);\n  }\n};\n\nexport async function getTestClientConf(): Promise<{ conf: PlClientConfig; auth: AuthOps }> {\n  const tConf = getTestConfig();\n\n  const plConf = plAddressToTestConfig(tConf.address);\n  const uClient = await UnauthenticatedPlClient.build(plConf);\n  // ll.serverInfo is populated by build()'s ping; instanceId rotates on a\n  // backend restart that drops the persisted state.\n  const instanceId = uClient.ll.serverInfo.instanceId;\n\n  let authInformation: AuthInformation | undefined = undefined;\n\n  // Try recover from cache. The cache is keyed by config AND backend\n  // instanceId — a backend restart that rotates instanceId invalidates the\n  // cached JWT (the token's `iss` claim no longer matches the live\n  // instance), so we re-login instead of carrying the dead token through\n  // to the first authenticated call.\n  if (fs.existsSync(getFullAuthDataFilePath())) {\n    try {\n      const cache: AuthCache = JSON.parse(\n        fs.readFileSync(getFullAuthDataFilePath(), { encoding: \"utf-8\" }),\n      ) as AuthCache; // TODO runtime validation\n      if (\n        cache.conf.address === tConf.address &&\n        cache.conf.test_user === tConf.test_user &&\n        cache.conf.test_password === tConf.test_password &&\n        cache.expiration > Date.now() &&\n        cache.instanceId === instanceId\n      )\n        authInformation = cache.authInformation;\n    } catch {\n      // removing cache file on any error\n      fs.rmSync(getFullAuthDataFilePath());\n    }\n  }\n\n  const requireAuth = await uClient.requireAuth();\n\n  if (!requireAuth && (tConf.test_user !== undefined || tConf.test_password !== undefined))\n    throw new Error(\n      `Server require no auth, but test user name or test password are provided via (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (requireAuth && (tConf.test_user === undefined || tConf.test_password === undefined))\n    throw new Error(\n      `No auth information found in config (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (authInformation === undefined) {\n    if (requireAuth) authInformation = await uClient.login(tConf.test_user!, tConf.test_password!);\n    // No authorization is required\n    else authInformation = {};\n\n    // saving cache\n    saveAuthInfoCallback(tConf, instanceId)(authInformation);\n  }\n\n  return {\n    conf: plConf,\n    auth: {\n      authInformation,\n      onUpdate: saveAuthInfoCallback(tConf, instanceId),\n      onAuthError: cleanAuthInfoCallback,\n      onUpdateError: cleanAuthInfoCallback,\n    },\n  };\n}\n\nexport async function getTestLLClient(confOverrides: Partial<PlClientConfig> = {}) {\n  const { conf, auth } = await getTestClientConf();\n  return await LLPlClient.build({ ...conf, ...confOverrides }, { auth });\n}\n\nexport async function getTestClient(\n  alternativeRoot?: string,\n  confOverrides: Partial<PlClientConfig> = {},\n) {\n  const { conf, auth } = await getTestClientConf();\n  if (alternativeRoot !== undefined && conf.alternativeRoot !== undefined)\n    throw new Error(\"test pl address configured with alternative root\");\n  return await PlClient.init({ ...conf, ...confOverrides, alternativeRoot }, auth);\n}\n\nexport type WithTempRootOptions =\n  | {\n      /** If true and PL_ADDRESS is http://localhost or http://127.0.0.1:<port>,\n       * a TCP proxy will be started and PL client will connect through it. */\n      viaTcpProxy: true;\n      /** Artificial latency for proxy (ms). Default 0 */\n      proxyLatencyMs?: number;\n    }\n  | {\n      viaTcpProxy?: undefined;\n    };\n\nexport async function withTempRoot<T>(body: (pl: PlClient) => Promise<T>): Promise<T | void>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: Awaited<ReturnType<typeof startTcpProxy>>) => Promise<T>,\n  options: {\n    viaTcpProxy: true;\n    proxyLatencyMs?: number;\n  },\n): Promise<T>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: any) => Promise<T>,\n  options: WithTempRootOptions = {},\n): Promise<T | undefined> {\n  const alternativeRoot = `test_${Date.now()}_${randomUUID()}`;\n  let altRootId: OptionalSignedResourceId = NullSignedResourceId;\n  // Proxy management\n  let proxy: Awaited<ReturnType<typeof startTcpProxy>> | undefined;\n  let confOverrides: Partial<PlClientConfig> = {};\n  try {\n    // Optionally start TCP proxy and rewrite PL_ADDRESS to point to proxy\n    if (options.viaTcpProxy === true && process.env.PL_ADDRESS) {\n      try {\n        const url = new URL(process.env.PL_ADDRESS);\n        const isHttp = url.protocol === \"http:\";\n        const isLocal = url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\";\n        const port = parseInt(url.port);\n        if (isHttp && isLocal && Number.isFinite(port)) {\n          proxy = await startTcpProxy({ targetPort: port, latency: options.proxyLatencyMs ?? 0 });\n          // Override client connection host:port to proxy\n          confOverrides = { hostAndPort: `127.0.0.1:${proxy.port}` } as Partial<PlClientConfig>;\n        } else {\n          console.warn(\n            \"*** skipping proxy-based test, PL_ADDRESS is not localhost\",\n            process.env.PL_ADDRESS,\n          );\n          return;\n        }\n      } catch {\n        // ignore proxy setup errors; tests will run against original address\n      }\n    }\n\n    const client = await getTestClient(alternativeRoot, confOverrides);\n    altRootId = client.clientRoot;\n    try {\n      const value = await body(client, proxy);\n      const rawClient = await getTestClient();\n      try {\n        await rawClient.deleteAlternativeRoot(alternativeRoot);\n      } catch (cleanupErr: any) {\n        // Cleanup may fail if test intentionally deleted resources\n        console.warn(`Failed to clean up alternative root ${alternativeRoot}:`, cleanupErr.message);\n      } finally {\n        // Close the cleanup client to avoid dangling gRPC channels that can cause\n        // segfaults during process exit\n        await rawClient.close();\n      }\n      return value;\n    } finally {\n      // Close the test client to avoid dangling gRPC channels\n      await client.close();\n    }\n  } catch (err: any) {\n    console.log(`ALTERNATIVE ROOT: ${alternativeRoot} (${resourceIdToString(altRootId)})`);\n    throw err;\n    // throw new Error('withTempRoot error: ' + err.message, { cause: err });\n  } finally {\n    // Stop proxy if started\n    if (proxy) {\n      try {\n        await proxy.disconnectAll();\n      } catch {\n        /* ignore */\n      }\n      try {\n        await new Promise<void>((resolve) => proxy!.server.close(() => resolve()));\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/test/test_config.d.ts

@@ -38,5 +38,5 @@ declare function withTempRoot<T>(body: (pl: PlClient, proxy: Awaited<ReturnType<
   proxyLatencyMs?: number;
 }): Promise<T>;
 //#endregion
-export { test_config_d_exports };
+export { TEST_REQUEST_TIMEOUT, TestConfig, type TestTcpProxy, WithTempRootOptions, getTestClient, getTestClientConf, getTestConfig, getTestLLClient, plAddressToTestConfig, test_config_d_exports, withTempRoot };
 //# sourceMappingURL=test_config.d.ts.map

package/dist/test/test_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test_config.d.ts","names":[],"sources":["../../src/test/test_config.ts"],"mappings":";;;;;;;;;UAgBiB,UAAA;EACf,OAAA;EACA,UAAA;EACA,SAAA;EACA,aAAA;AAAA;AAAA,iBAac,aAAA,CAAA,GAAiB,UAAA;;cAsBpB,oBAAA;;iBAGG,qBAAA,CAAsB,OAAA,WAAkB,cAAA;AAAA,iBAkDlC,iBAAA,CAAA,GAAqB,OAAA;EAAU,IAAA,EAAM,cAAA;EAAgB,IAAA,EAAM,OAAA;AAAA;AAAA,iBAmE3D,eAAA,CAAgB,aAAA,GAAe,OAAA,CAAQ,cAAA,IAAoB,OAAA,CAAA,UAAA;AAAA,iBAK3D,aAAA,CACpB,eAAA,WACA,aAAA,GAAe,OAAA,CAAQ,cAAA,IAAoB,OAAA,CAAA,QAAA;AAAA,KAQjC,mBAAA;EA5KV;;EAgLI,WAAA,QA9KS;EAgLT,cAAA;AAAA;EAGA,WAAA;AAAA;AAAA,iBAGgB,YAAA,GAAA,CAAgB,IAAA,GAAO,EAAA,EAAI,QAAA,KAAa,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;AAAA,iBAE7D,YAAA,GAAA,CACpB,IAAA,GAAO,EAAA,EAAI,QAAA,EAAU,KAAA,EAAO,OAAA,CAAQ,UAAA,QAAkB,aAAA,OAAoB,OAAA,CAAQ,CAAA,GAClF,OAAA;EACE,WAAA;EACA,cAAA;AAAA,IAED,OAAA,CAAQ,CAAA"}
+{"version":3,"file":"test_config.d.ts","names":[],"sources":["../../src/test/test_config.ts"],"mappings":";;;;;;;;;UAgBiB,UAAA;EACf,OAAA;EACA,UAAA;EACA,SAAA;EACA,aAAA;AAAA;AAAA,iBAac,aAAA,IAAiB,UAAU;;cAsB9B,oBAAA;;iBAGG,qBAAA,CAAsB,OAAA,WAAkB,cAAc;AAAA,iBAkDhD,iBAAA,IAAqB,OAAA;EAAU,IAAA,EAAM,cAAA;EAAgB,IAAA,EAAM,OAAA;AAAA;AAAA,iBAmE3D,eAAA,CAAgB,aAAA,GAAe,OAAA,CAAQ,cAAA,IAAoB,OAAA,CAAA,UAAA;AAAA,iBAK3D,aAAA,CACpB,eAAA,WACA,aAAA,GAAe,OAAA,CAAQ,cAAA,IAAoB,OAAA,CAAA,QAAA;AAAA,KAQjC,mBAAA;EA5KV;;EAgLI,WAAA,QA9KS;EAgLT,cAAA;AAAA;EAGA,WAAA;AAAA;AAAA,iBAGgB,YAAA,IAAgB,IAAA,GAAO,EAAA,EAAI,QAAA,KAAa,OAAA,CAAQ,CAAA,IAAK,OAAA,CAAQ,CAAA;AAAA,iBAE7D,YAAA,IACpB,IAAA,GAAO,EAAA,EAAI,QAAA,EAAU,KAAA,EAAO,OAAA,CAAQ,UAAA,QAAkB,aAAA,OAAoB,OAAA,CAAQ,CAAA,GAClF,OAAA;EACE,WAAA;EACA,cAAA;AAAA,IAED,OAAA,CAAQ,CAAA"}

package/dist/test/test_config.js

@@ -160,6 +160,6 @@ async function withTempRoot(body, options = {}) {
 	}
 }
 //#endregion
-export { test_config_exports };
+export { getTestClient, getTestClientConf, getTestConfig, getTestLLClient, plAddressToTestConfig, test_config_exports, withTempRoot };
 
 //# sourceMappingURL=test_config.js.map

package/dist/test/test_config.js.map

@@ -1 +1 @@
-{"version":3,"file":"test_config.js","names":["fs"],"sources":["../../src/test/test_config.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport { LLPlClient } from \"../core/ll_client\";\nimport type { AuthInformation, AuthOps, PlClientConfig } from \"../core/config\";\nimport { plAddressToConfig } from \"../core/config\";\nimport { UnauthenticatedPlClient } from \"../core/unauth_client\";\nimport { PlClient } from \"../core/client\";\nimport { randomUUID } from \"node:crypto\";\nimport type { OptionalSignedResourceId } from \"../core/types\";\nimport { NullSignedResourceId, resourceIdToString } from \"../core/types\";\nimport { inferAuthRefreshTime } from \"../core/auth\";\nimport * as path from \"node:path\";\nimport type { TestTcpProxy } from \"./tcp-proxy\";\nimport { startTcpProxy } from \"./tcp-proxy\";\n\nexport { TestTcpProxy };\n\nexport interface TestConfig {\n  address: string;\n  test_proxy?: string;\n  test_user?: string;\n  test_password?: string;\n}\n\nconst CONFIG_FILE = \"test_config.json\";\n// const AUTH_DATA_FILE = '.test_auth.json';\n\nlet authDataFilePath: string | undefined;\n\nfunction getFullAuthDataFilePath() {\n  if (authDataFilePath === undefined) authDataFilePath = path.resolve(\".test_auth.json\");\n  return authDataFilePath;\n}\n\nexport function getTestConfig(): TestConfig {\n  let conf: Partial<TestConfig> = {};\n  if (fs.existsSync(CONFIG_FILE))\n    conf = JSON.parse(fs.readFileSync(CONFIG_FILE, { encoding: \"utf-8\" })) as TestConfig;\n\n  if (process.env.PL_ADDRESS !== undefined) conf.address = process.env.PL_ADDRESS;\n\n  if (process.env.PL_TEST_USER !== undefined) conf.test_user = process.env.PL_TEST_USER;\n\n  if (process.env.PL_TEST_PASSWORD !== undefined) conf.test_password = process.env.PL_TEST_PASSWORD;\n\n  if (process.env.PL_TEST_PROXY !== undefined) conf.test_proxy = process.env.PL_TEST_PROXY;\n\n  if (conf.address === undefined)\n    throw new Error(\n      `can't resolve platform address (checked ${CONFIG_FILE} file and PL_ADDRESS environment var)`,\n    );\n\n  return conf as TestConfig;\n}\n\n/** Default request timeout for tests (ms) */\nexport const TEST_REQUEST_TIMEOUT = 500;\n\n/** Returns PlClientConfig with reduced timeout for tests */\nexport function plAddressToTestConfig(address: string): PlClientConfig {\n  const plConf = plAddressToConfig(address);\n  plConf.defaultRequestTimeout = TEST_REQUEST_TIMEOUT;\n  return plConf;\n}\n\ninterface AuthCache {\n  /** To check if config changed */\n  conf: TestConfig;\n  /** Backend's instance ID at the moment the JWT was issued. Restarts that\n   * reset state rotate this; the JWT's `iss` claim is bound to it and the\n   * backend rejects tokens minted by a different instance. Without this\n   * check, a cached JWT from a previous backend run would silently fail\n   * the first authenticated call after restart. */\n  instanceId: string;\n  expiration: number;\n  authInformation: AuthInformation;\n}\n\nfunction saveAuthInfoCallback(\n  tConf: TestConfig,\n  instanceId: string,\n): (authInformation: AuthInformation) => void {\n  return (authInformation) => {\n    const dst = getFullAuthDataFilePath();\n    const tmpDst = getFullAuthDataFilePath() + randomUUID();\n    fs.writeFileSync(\n      tmpDst,\n      Buffer.from(\n        JSON.stringify({\n          conf: tConf,\n          instanceId,\n          authInformation,\n          expiration: inferAuthRefreshTime(authInformation, 24 * 60 * 60),\n        } as AuthCache),\n      ),\n      \"utf8\",\n    );\n    fs.renameSync(tmpDst, dst);\n  };\n}\n\nconst cleanAuthInfoCallback = () => {\n  const p = getFullAuthDataFilePath();\n  if (fs.existsSync(p)) {\n    console.warn(`Removing: ${p}`);\n    fs.rmSync(p);\n  }\n};\n\nexport async function getTestClientConf(): Promise<{ conf: PlClientConfig; auth: AuthOps }> {\n  const tConf = getTestConfig();\n\n  const plConf = plAddressToTestConfig(tConf.address);\n  const uClient = await UnauthenticatedPlClient.build(plConf);\n  // ll.serverInfo is populated by build()'s ping; instanceId rotates on a\n  // backend restart that drops the persisted state.\n  const instanceId = uClient.ll.serverInfo.instanceId;\n\n  let authInformation: AuthInformation | undefined = undefined;\n\n  // Try recover from cache. The cache is keyed by config AND backend\n  // instanceId — a backend restart that rotates instanceId invalidates the\n  // cached JWT (the token's `iss` claim no longer matches the live\n  // instance), so we re-login instead of carrying the dead token through\n  // to the first authenticated call.\n  if (fs.existsSync(getFullAuthDataFilePath())) {\n    try {\n      const cache: AuthCache = JSON.parse(\n        fs.readFileSync(getFullAuthDataFilePath(), { encoding: \"utf-8\" }),\n      ) as AuthCache; // TODO runtime validation\n      if (\n        cache.conf.address === tConf.address &&\n        cache.conf.test_user === tConf.test_user &&\n        cache.conf.test_password === tConf.test_password &&\n        cache.expiration > Date.now() &&\n        cache.instanceId === instanceId\n      )\n        authInformation = cache.authInformation;\n    } catch {\n      // removing cache file on any error\n      fs.rmSync(getFullAuthDataFilePath());\n    }\n  }\n\n  const requireAuth = await uClient.requireAuth();\n\n  if (!requireAuth && (tConf.test_user !== undefined || tConf.test_password !== undefined))\n    throw new Error(\n      `Server require no auth, but test user name or test password are provided via (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (requireAuth && (tConf.test_user === undefined || tConf.test_password === undefined))\n    throw new Error(\n      `No auth information found in config (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (authInformation === undefined) {\n    if (requireAuth) authInformation = await uClient.login(tConf.test_user!, tConf.test_password!);\n    // No authorization is required\n    else authInformation = {};\n\n    // saving cache\n    saveAuthInfoCallback(tConf, instanceId)(authInformation);\n  }\n\n  return {\n    conf: plConf,\n    auth: {\n      authInformation,\n      onUpdate: saveAuthInfoCallback(tConf, instanceId),\n      onAuthError: cleanAuthInfoCallback,\n      onUpdateError: cleanAuthInfoCallback,\n    },\n  };\n}\n\nexport async function getTestLLClient(confOverrides: Partial<PlClientConfig> = {}) {\n  const { conf, auth } = await getTestClientConf();\n  return await LLPlClient.build({ ...conf, ...confOverrides }, { auth });\n}\n\nexport async function getTestClient(\n  alternativeRoot?: string,\n  confOverrides: Partial<PlClientConfig> = {},\n) {\n  const { conf, auth } = await getTestClientConf();\n  if (alternativeRoot !== undefined && conf.alternativeRoot !== undefined)\n    throw new Error(\"test pl address configured with alternative root\");\n  return await PlClient.init({ ...conf, ...confOverrides, alternativeRoot }, auth);\n}\n\nexport type WithTempRootOptions =\n  | {\n      /** If true and PL_ADDRESS is http://localhost or http://127.0.0.1:<port>,\n       * a TCP proxy will be started and PL client will connect through it. */\n      viaTcpProxy: true;\n      /** Artificial latency for proxy (ms). Default 0 */\n      proxyLatencyMs?: number;\n    }\n  | {\n      viaTcpProxy?: undefined;\n    };\n\nexport async function withTempRoot<T>(body: (pl: PlClient) => Promise<T>): Promise<T | void>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: Awaited<ReturnType<typeof startTcpProxy>>) => Promise<T>,\n  options: {\n    viaTcpProxy: true;\n    proxyLatencyMs?: number;\n  },\n): Promise<T>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: any) => Promise<T>,\n  options: WithTempRootOptions = {},\n): Promise<T | undefined> {\n  const alternativeRoot = `test_${Date.now()}_${randomUUID()}`;\n  let altRootId: OptionalSignedResourceId = NullSignedResourceId;\n  // Proxy management\n  let proxy: Awaited<ReturnType<typeof startTcpProxy>> | undefined;\n  let confOverrides: Partial<PlClientConfig> = {};\n  try {\n    // Optionally start TCP proxy and rewrite PL_ADDRESS to point to proxy\n    if (options.viaTcpProxy === true && process.env.PL_ADDRESS) {\n      try {\n        const url = new URL(process.env.PL_ADDRESS);\n        const isHttp = url.protocol === \"http:\";\n        const isLocal = url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\";\n        const port = parseInt(url.port);\n        if (isHttp && isLocal && Number.isFinite(port)) {\n          proxy = await startTcpProxy({ targetPort: port, latency: options.proxyLatencyMs ?? 0 });\n          // Override client connection host:port to proxy\n          confOverrides = { hostAndPort: `127.0.0.1:${proxy.port}` } as Partial<PlClientConfig>;\n        } else {\n          console.warn(\n            \"*** skipping proxy-based test, PL_ADDRESS is not localhost\",\n            process.env.PL_ADDRESS,\n          );\n          return;\n        }\n      } catch {\n        // ignore proxy setup errors; tests will run against original address\n      }\n    }\n\n    const client = await getTestClient(alternativeRoot, confOverrides);\n    altRootId = client.clientRoot;\n    try {\n      const value = await body(client, proxy);\n      const rawClient = await getTestClient();\n      try {\n        await rawClient.deleteAlternativeRoot(alternativeRoot);\n      } catch (cleanupErr: any) {\n        // Cleanup may fail if test intentionally deleted resources\n        console.warn(`Failed to clean up alternative root ${alternativeRoot}:`, cleanupErr.message);\n      } finally {\n        // Close the cleanup client to avoid dangling gRPC channels that can cause\n        // segfaults during process exit\n        await rawClient.close();\n      }\n      return value;\n    } finally {\n      // Close the test client to avoid dangling gRPC channels\n      await client.close();\n    }\n  } catch (err: any) {\n    console.log(`ALTERNATIVE ROOT: ${alternativeRoot} (${resourceIdToString(altRootId)})`);\n    throw err;\n    // throw new Error('withTempRoot error: ' + err.message, { cause: err });\n  } finally {\n    // Stop proxy if started\n    if (proxy) {\n      try {\n        await proxy.disconnectAll();\n      } catch {\n        /* ignore */\n      }\n      try {\n        await new Promise<void>((resolve) => proxy!.server.close(() => resolve()));\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"test_config.js","names":["fs"],"sources":["../../src/test/test_config.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport { LLPlClient } from \"../core/ll_client\";\nimport type { AuthInformation, AuthOps, PlClientConfig } from \"../core/config\";\nimport { plAddressToConfig } from \"../core/config\";\nimport { UnauthenticatedPlClient } from \"../core/unauth_client\";\nimport { PlClient } from \"../core/client\";\nimport { randomUUID } from \"node:crypto\";\nimport type { OptionalSignedResourceId } from \"../core/types\";\nimport { NullSignedResourceId, resourceIdToString } from \"../core/types\";\nimport { inferAuthRefreshTime } from \"../core/auth\";\nimport * as path from \"node:path\";\nimport type { TestTcpProxy } from \"./tcp-proxy\";\nimport { startTcpProxy } from \"./tcp-proxy\";\n\nexport { TestTcpProxy };\n\nexport interface TestConfig {\n  address: string;\n  test_proxy?: string;\n  test_user?: string;\n  test_password?: string;\n}\n\nconst CONFIG_FILE = \"test_config.json\";\n// const AUTH_DATA_FILE = '.test_auth.json';\n\nlet authDataFilePath: string | undefined;\n\nfunction getFullAuthDataFilePath() {\n  if (authDataFilePath === undefined) authDataFilePath = path.resolve(\".test_auth.json\");\n  return authDataFilePath;\n}\n\nexport function getTestConfig(): TestConfig {\n  let conf: Partial<TestConfig> = {};\n  if (fs.existsSync(CONFIG_FILE))\n    conf = JSON.parse(fs.readFileSync(CONFIG_FILE, { encoding: \"utf-8\" })) as TestConfig;\n\n  if (process.env.PL_ADDRESS !== undefined) conf.address = process.env.PL_ADDRESS;\n\n  if (process.env.PL_TEST_USER !== undefined) conf.test_user = process.env.PL_TEST_USER;\n\n  if (process.env.PL_TEST_PASSWORD !== undefined) conf.test_password = process.env.PL_TEST_PASSWORD;\n\n  if (process.env.PL_TEST_PROXY !== undefined) conf.test_proxy = process.env.PL_TEST_PROXY;\n\n  if (conf.address === undefined)\n    throw new Error(\n      `can't resolve platform address (checked ${CONFIG_FILE} file and PL_ADDRESS environment var)`,\n    );\n\n  return conf as TestConfig;\n}\n\n/** Default request timeout for tests (ms) */\nexport const TEST_REQUEST_TIMEOUT = 500;\n\n/** Returns PlClientConfig with reduced timeout for tests */\nexport function plAddressToTestConfig(address: string): PlClientConfig {\n  const plConf = plAddressToConfig(address);\n  plConf.defaultRequestTimeout = TEST_REQUEST_TIMEOUT;\n  return plConf;\n}\n\ninterface AuthCache {\n  /** To check if config changed */\n  conf: TestConfig;\n  /** Backend's instance ID at the moment the JWT was issued. Restarts that\n   * reset state rotate this; the JWT's `iss` claim is bound to it and the\n   * backend rejects tokens minted by a different instance. Without this\n   * check, a cached JWT from a previous backend run would silently fail\n   * the first authenticated call after restart. */\n  instanceId: string;\n  expiration: number;\n  authInformation: AuthInformation;\n}\n\nfunction saveAuthInfoCallback(\n  tConf: TestConfig,\n  instanceId: string,\n): (authInformation: AuthInformation) => void {\n  return (authInformation) => {\n    const dst = getFullAuthDataFilePath();\n    const tmpDst = getFullAuthDataFilePath() + randomUUID();\n    fs.writeFileSync(\n      tmpDst,\n      Buffer.from(\n        JSON.stringify({\n          conf: tConf,\n          instanceId,\n          authInformation,\n          expiration: inferAuthRefreshTime(authInformation, 24 * 60 * 60),\n        } as AuthCache),\n      ),\n      \"utf8\",\n    );\n    fs.renameSync(tmpDst, dst);\n  };\n}\n\nconst cleanAuthInfoCallback = () => {\n  const p = getFullAuthDataFilePath();\n  if (fs.existsSync(p)) {\n    console.warn(`Removing: ${p}`);\n    fs.rmSync(p);\n  }\n};\n\nexport async function getTestClientConf(): Promise<{ conf: PlClientConfig; auth: AuthOps }> {\n  const tConf = getTestConfig();\n\n  const plConf = plAddressToTestConfig(tConf.address);\n  const uClient = await UnauthenticatedPlClient.build(plConf);\n  // ll.serverInfo is populated by build()'s ping; instanceId rotates on a\n  // backend restart that drops the persisted state.\n  const instanceId = uClient.ll.serverInfo.instanceId;\n\n  let authInformation: AuthInformation | undefined = undefined;\n\n  // Try recover from cache. The cache is keyed by config AND backend\n  // instanceId — a backend restart that rotates instanceId invalidates the\n  // cached JWT (the token's `iss` claim no longer matches the live\n  // instance), so we re-login instead of carrying the dead token through\n  // to the first authenticated call.\n  if (fs.existsSync(getFullAuthDataFilePath())) {\n    try {\n      const cache: AuthCache = JSON.parse(\n        fs.readFileSync(getFullAuthDataFilePath(), { encoding: \"utf-8\" }),\n      ) as AuthCache; // TODO runtime validation\n      if (\n        cache.conf.address === tConf.address &&\n        cache.conf.test_user === tConf.test_user &&\n        cache.conf.test_password === tConf.test_password &&\n        cache.expiration > Date.now() &&\n        cache.instanceId === instanceId\n      )\n        authInformation = cache.authInformation;\n    } catch {\n      // removing cache file on any error\n      fs.rmSync(getFullAuthDataFilePath());\n    }\n  }\n\n  const requireAuth = await uClient.requireAuth();\n\n  if (!requireAuth && (tConf.test_user !== undefined || tConf.test_password !== undefined))\n    throw new Error(\n      `Server require no auth, but test user name or test password are provided via (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (requireAuth && (tConf.test_user === undefined || tConf.test_password === undefined))\n    throw new Error(\n      `No auth information found in config (${CONFIG_FILE}) or env variables: PL_TEST_USER and PL_TEST_PASSWORD`,\n    );\n\n  if (authInformation === undefined) {\n    if (requireAuth) authInformation = await uClient.login(tConf.test_user!, tConf.test_password!);\n    // No authorization is required\n    else authInformation = {};\n\n    // saving cache\n    saveAuthInfoCallback(tConf, instanceId)(authInformation);\n  }\n\n  return {\n    conf: plConf,\n    auth: {\n      authInformation,\n      onUpdate: saveAuthInfoCallback(tConf, instanceId),\n      onAuthError: cleanAuthInfoCallback,\n      onUpdateError: cleanAuthInfoCallback,\n    },\n  };\n}\n\nexport async function getTestLLClient(confOverrides: Partial<PlClientConfig> = {}) {\n  const { conf, auth } = await getTestClientConf();\n  return await LLPlClient.build({ ...conf, ...confOverrides }, { auth });\n}\n\nexport async function getTestClient(\n  alternativeRoot?: string,\n  confOverrides: Partial<PlClientConfig> = {},\n) {\n  const { conf, auth } = await getTestClientConf();\n  if (alternativeRoot !== undefined && conf.alternativeRoot !== undefined)\n    throw new Error(\"test pl address configured with alternative root\");\n  return await PlClient.init({ ...conf, ...confOverrides, alternativeRoot }, auth);\n}\n\nexport type WithTempRootOptions =\n  | {\n      /** If true and PL_ADDRESS is http://localhost or http://127.0.0.1:<port>,\n       * a TCP proxy will be started and PL client will connect through it. */\n      viaTcpProxy: true;\n      /** Artificial latency for proxy (ms). Default 0 */\n      proxyLatencyMs?: number;\n    }\n  | {\n      viaTcpProxy?: undefined;\n    };\n\nexport async function withTempRoot<T>(body: (pl: PlClient) => Promise<T>): Promise<T | void>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: Awaited<ReturnType<typeof startTcpProxy>>) => Promise<T>,\n  options: {\n    viaTcpProxy: true;\n    proxyLatencyMs?: number;\n  },\n): Promise<T>;\n\nexport async function withTempRoot<T>(\n  body: (pl: PlClient, proxy: any) => Promise<T>,\n  options: WithTempRootOptions = {},\n): Promise<T | undefined> {\n  const alternativeRoot = `test_${Date.now()}_${randomUUID()}`;\n  let altRootId: OptionalSignedResourceId = NullSignedResourceId;\n  // Proxy management\n  let proxy: Awaited<ReturnType<typeof startTcpProxy>> | undefined;\n  let confOverrides: Partial<PlClientConfig> = {};\n  try {\n    // Optionally start TCP proxy and rewrite PL_ADDRESS to point to proxy\n    if (options.viaTcpProxy === true && process.env.PL_ADDRESS) {\n      try {\n        const url = new URL(process.env.PL_ADDRESS);\n        const isHttp = url.protocol === \"http:\";\n        const isLocal = url.hostname === \"127.0.0.1\" || url.hostname === \"localhost\";\n        const port = parseInt(url.port);\n        if (isHttp && isLocal && Number.isFinite(port)) {\n          proxy = await startTcpProxy({ targetPort: port, latency: options.proxyLatencyMs ?? 0 });\n          // Override client connection host:port to proxy\n          confOverrides = { hostAndPort: `127.0.0.1:${proxy.port}` } as Partial<PlClientConfig>;\n        } else {\n          console.warn(\n            \"*** skipping proxy-based test, PL_ADDRESS is not localhost\",\n            process.env.PL_ADDRESS,\n          );\n          return;\n        }\n      } catch {\n        // ignore proxy setup errors; tests will run against original address\n      }\n    }\n\n    const client = await getTestClient(alternativeRoot, confOverrides);\n    altRootId = client.clientRoot;\n    try {\n      const value = await body(client, proxy);\n      const rawClient = await getTestClient();\n      try {\n        await rawClient.deleteAlternativeRoot(alternativeRoot);\n      } catch (cleanupErr: any) {\n        // Cleanup may fail if test intentionally deleted resources\n        console.warn(`Failed to clean up alternative root ${alternativeRoot}:`, cleanupErr.message);\n      } finally {\n        // Close the cleanup client to avoid dangling gRPC channels that can cause\n        // segfaults during process exit\n        await rawClient.close();\n      }\n      return value;\n    } finally {\n      // Close the test client to avoid dangling gRPC channels\n      await client.close();\n    }\n  } catch (err: any) {\n    console.log(`ALTERNATIVE ROOT: ${alternativeRoot} (${resourceIdToString(altRootId)})`);\n    throw err;\n    // throw new Error('withTempRoot error: ' + err.message, { cause: err });\n  } finally {\n    // Stop proxy if started\n    if (proxy) {\n      try {\n        await proxy.disconnectAll();\n      } catch {\n        /* ignore */\n      }\n      try {\n        await new Promise<void>((resolve) => proxy!.server.close(() => resolve()));\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/util/pl.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"pl.cjs","names":[],"sources":["../../src/util/pl.ts"],"sourcesContent":["export type PlJWTPayload = {\n  sub: string; // user ID\n  iss: string; // backend instance ID\n\n  // deprecated. Prior backend capability auth:v2. Use uid instead.\n  user: {\n    login: string;\n  };\n\n  exp: number;\n  iat: number;\n};\n\nexport function parsePlJwt(token: string): PlJWTPayload {\n  return JSON.parse(Buffer.from(token.split(\".\")[1], \"base64\").toString());\n}\n"],"mappings":";AAaA,SAAgB,WAAW,OAA6B;AACtD,QAAO,KAAK,MAAM,OAAO,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC"}
+{"version":3,"file":"pl.cjs","names":[],"sources":["../../src/util/pl.ts"],"sourcesContent":["export type PlJWTPayload = {\n  sub: string; // user ID\n  iss: string; // backend instance ID\n\n  // deprecated. Prior backend capability auth:v2. Use uid instead.\n  user: {\n    login: string;\n  };\n\n  exp: number;\n  iat: number;\n};\n\nexport function parsePlJwt(token: string): PlJWTPayload {\n  return JSON.parse(Buffer.from(token.split(\".\")[1], \"base64\").toString());\n}\n"],"mappings":";AAaA,SAAgB,WAAW,OAA6B;CACtD,OAAO,KAAK,MAAM,OAAO,KAAK,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,SAAS,CAAC;AACzE"}

package/dist/util/pl.js.map

@@ -1 +1 @@
-{"version":3,"file":"pl.js","names":[],"sources":["../../src/util/pl.ts"],"sourcesContent":["export type PlJWTPayload = {\n  sub: string; // user ID\n  iss: string; // backend instance ID\n\n  // deprecated. Prior backend capability auth:v2. Use uid instead.\n  user: {\n    login: string;\n  };\n\n  exp: number;\n  iat: number;\n};\n\nexport function parsePlJwt(token: string): PlJWTPayload {\n  return JSON.parse(Buffer.from(token.split(\".\")[1], \"base64\").toString());\n}\n"],"mappings":";AAaA,SAAgB,WAAW,OAA6B;AACtD,QAAO,KAAK,MAAM,OAAO,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC"}
+{"version":3,"file":"pl.js","names":[],"sources":["../../src/util/pl.ts"],"sourcesContent":["export type PlJWTPayload = {\n  sub: string; // user ID\n  iss: string; // backend instance ID\n\n  // deprecated. Prior backend capability auth:v2. Use uid instead.\n  user: {\n    login: string;\n  };\n\n  exp: number;\n  iat: number;\n};\n\nexport function parsePlJwt(token: string): PlJWTPayload {\n  return JSON.parse(Buffer.from(token.split(\".\")[1], \"base64\").toString());\n}\n"],"mappings":";AAaA,SAAgB,WAAW,OAA6B;CACtD,OAAO,KAAK,MAAM,OAAO,KAAK,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,SAAS,CAAC;AACzE"}

package/dist/util/util.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"util.cjs","names":[],"sources":["../../src/util/util.ts"],"sourcesContent":["function isArrayBufferOrView(value: unknown): value is ArrayBufferLike {\n  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);\n}\n\nexport function toBytes(value: string | Uint8Array): Uint8Array {\n  if (typeof value === \"string\") return Buffer.from(value);\n  else if (isArrayBufferOrView(value)) return value;\n  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n  else throw new Error(`Unexpected type: ${value}`);\n}\n"],"mappings":";AAAA,SAAS,oBAAoB,OAA0C;AACrE,QAAO,iBAAiB,eAAe,YAAY,OAAO,MAAM;;AAGlE,SAAgB,QAAQ,OAAwC;AAC9D,KAAI,OAAO,UAAU,SAAU,QAAO,OAAO,KAAK,MAAM;UAC/C,oBAAoB,MAAM,CAAE,QAAO;KAEvC,OAAM,IAAI,MAAM,oBAAoB,QAAQ"}
+{"version":3,"file":"util.cjs","names":[],"sources":["../../src/util/util.ts"],"sourcesContent":["function isArrayBufferOrView(value: unknown): value is ArrayBufferLike {\n  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);\n}\n\nexport function toBytes(value: string | Uint8Array): Uint8Array {\n  if (typeof value === \"string\") return Buffer.from(value);\n  else if (isArrayBufferOrView(value)) return value;\n  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n  else throw new Error(`Unexpected type: ${value}`);\n}\n"],"mappings":";AAAA,SAAS,oBAAoB,OAA0C;CACrE,OAAO,iBAAiB,eAAe,YAAY,OAAO,KAAK;AACjE;AAEA,SAAgB,QAAQ,OAAwC;CAC9D,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK,KAAK;MAClD,IAAI,oBAAoB,KAAK,GAAG,OAAO;MAEvC,MAAM,IAAI,MAAM,oBAAoB,OAAO;AAClD"}

package/dist/util/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","names":[],"sources":["../../src/util/util.ts"],"sourcesContent":["function isArrayBufferOrView(value: unknown): value is ArrayBufferLike {\n  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);\n}\n\nexport function toBytes(value: string | Uint8Array): Uint8Array {\n  if (typeof value === \"string\") return Buffer.from(value);\n  else if (isArrayBufferOrView(value)) return value;\n  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n  else throw new Error(`Unexpected type: ${value}`);\n}\n"],"mappings":";AAAA,SAAS,oBAAoB,OAA0C;AACrE,QAAO,iBAAiB,eAAe,YAAY,OAAO,MAAM;;AAGlE,SAAgB,QAAQ,OAAwC;AAC9D,KAAI,OAAO,UAAU,SAAU,QAAO,OAAO,KAAK,MAAM;UAC/C,oBAAoB,MAAM,CAAE,QAAO;KAEvC,OAAM,IAAI,MAAM,oBAAoB,QAAQ"}
+{"version":3,"file":"util.js","names":[],"sources":["../../src/util/util.ts"],"sourcesContent":["function isArrayBufferOrView(value: unknown): value is ArrayBufferLike {\n  return value instanceof ArrayBuffer || ArrayBuffer.isView(value);\n}\n\nexport function toBytes(value: string | Uint8Array): Uint8Array {\n  if (typeof value === \"string\") return Buffer.from(value);\n  else if (isArrayBufferOrView(value)) return value;\n  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n  else throw new Error(`Unexpected type: ${value}`);\n}\n"],"mappings":";AAAA,SAAS,oBAAoB,OAA0C;CACrE,OAAO,iBAAiB,eAAe,YAAY,OAAO,KAAK;AACjE;AAEA,SAAgB,QAAQ,OAAwC;CAC9D,IAAI,OAAO,UAAU,UAAU,OAAO,OAAO,KAAK,KAAK;MAClD,IAAI,oBAAoB,KAAK,GAAG,OAAO;MAEvC,MAAM,IAAI,MAAM,oBAAoB,OAAO;AAClD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-client",
-  "version": "3.11.5",
+  "version": "3.12.1",
   "description": "New TS/JS client for Platform API",
   "files": [
     "./dist/**/*",
@@ -30,8 +30,8 @@
     "undici": "~7.16.0",
     "utility-types": "^3.11.0",
     "yaml": "^2.8.0",
+    "@milaboratories/pl-model-common": "1.46.3",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-common": "1.46.2",
     "@milaboratories/ts-helpers": "1.8.3"
   },
   "devDependencies": {
@@ -42,8 +42,8 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.3",
     "@milaboratories/build-configs": "2.0.0",
-    "@milaboratories/ts-builder": "1.5.2",
-    "@milaboratories/ts-configs": "1.2.3"
+    "@milaboratories/ts-builder": "1.6.0",
+    "@milaboratories/ts-configs": "1.3.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/core/capabilities.ts

@@ -5,8 +5,7 @@
  * to detect incompatibilities between blocks and backend via
  * via `TemplateDataV3.requiredCapabilities`.
  *
- * Mirror of `pl/platform/api/plapiserver/server_capabilities.go` — keep
- * tokens in sync with the backend's advertised list. Format is
+ * Keep tokens in sync with the backend's advertised list. Format is
  * `<feature>:<version>`; bump the version when wire semantics change.
  *
  * Shared across:
@@ -15,7 +14,15 @@
  *   - `@platforma-sdk/block-tools`       — copies it onto the published manifest
  *   - `@milaboratories/pl-middle-layer`  — checks it at install time
  */
-export type BackendCapability = "auth:v2" | "treeFilter:v2" | "wasm:v1";
+export type BackendCapability =
+  | "auth:v2"
+  | "treeFilter:v2"
+  | "wasm:v1"
+  // Project-sharing capability tokens.
+  | "crossTreeRefs:v1" // cross-color field attach (accept a foreign-colored shared envelope)
+  | "userListing:v1" // list users for the recipient picker
+  | "publicGrants:v1" // public (everyone) grants allowed for any role
+  | "txListGrants:v1"; // list grants inside a transaction (batched recipient reads)
 
 /** True iff `capabilities` advertises the requested token. */
 export function hasCapability(

package/src/core/client.ts

@@ -2,6 +2,7 @@ import type { AuthOps, PlClientConfig, PlConnectionStatusListener, wireProtocol
 import type { PlCallOps } from "./ll_client";
 import { LLPlClient } from "./ll_client";
 import { PlTransaction, TxCommitConflict } from "./transaction";
+import type { Role } from "./transaction";
 import type { OptionalSignedResourceId, SignedResourceId } from "./types";
 import {
   ensureSignedResourceIdNotNull,
@@ -80,6 +81,11 @@ export class PlClient {
 
   private _userResources?: UserResources;
 
+  /** Cached effective role of the authenticated session, fetched once during
+   *  init via the GetSessionInfo RPC. `null` for an anonymous (no-auth)
+   *  connection — mirrors {@link authUser}. Read through {@link currentUserRole}. */
+  private _currentUserRole: Role | null = null;
+
   private _txCommittedStat: TxStat = initialTxStat();
   private _txConflictStat: TxStat = initialTxStat();
   private _txErrorStat: TxStat = initialTxStat();
@@ -232,10 +238,24 @@ export class PlClient {
     return this._ll!.hasCapability(capability);
   }
 
+  /** Effective role of the authenticated session, resolved once during init via
+   *  the GetSessionInfo RPC and cached. `null` for an anonymous (no-auth)
+   *  connection, or when the backend predates GetSessionInfo. Mirrors
+   *  {@link authUser}'s null contract. */
+  public get currentUserRole(): Role | null {
+    this.checkInitialized();
+    return this._currentUserRole;
+  }
+
+  /** Login of the authenticated user, or `null` for an anonymous connection. */
+  public get authUser(): string | null {
+    this.checkInitialized();
+    return this.userResources.authUser;
+  }
+
   /**
-   * True if the backend honors per-file `permissions` on workdir fill rules
-   * (PR #1830 in milaboratory/pl). See `LLPlClient.supportsWritableWorkdirFiles`
-   * for the full definition.
+   * True if the backend honors per-file `permissions` on workdir fill rules.
+   * See {@link LLPlClient.supportsWritableWorkdirFiles} for the full definition.
    */
   public get supportsWritableWorkdirFiles(): boolean {
     this.checkInitialized();
@@ -276,6 +296,13 @@ export class PlClient {
 
     const userRoot = await this.userResources.getUserRoot({ createIfNotExists: true });
 
+    // Resolve the caller's role once; only the publicGrants-gated share-with-everybody check uses it,
+    // so skip it for anonymous connections or when publicGrants:v1 is absent. Use _ll.hasCapability,
+    // not this.hasCapability: we are mid-init, so this.checkInitialized() would throw.
+    if (this.userResources.authUser !== null && this._ll.hasCapability("publicGrants:v1")) {
+      this._currentUserRole = (await this._ll.getSessionInfo()).role;
+    }
+
     if (this.conf.alternativeRoot === undefined) {
       this._clientRoot = userRoot;
     } else {

package/src/core/errors.ts

@@ -20,6 +20,8 @@ export function isUnauthenticated(err: unknown, nested: boolean = false): boolea
   if ((err as any).name == "RpcError" && (err as any).code == "UNAUTHENTICATED") return true;
   if ((err as any).name == "RESTError" && (err as any).status.code == Code.UNAUTHENTICATED)
     return true;
+  // PlError (e.g. UnrecoverablePlError from a failed streaming tx) carries the status code numerically.
+  if (err instanceof PlError && err.status?.code === Code.UNAUTHENTICATED) return true;
   if ((err as any).cause !== undefined && !nested)
     return isUnauthenticated((err as any).cause, true);
   return false;

package/src/core/final.ts

@@ -87,6 +87,10 @@ export const DefaultFinalResourceDataPredicate: FinalResourceDataPredicate = (r)
     case ResourceTypeName.UserProject:
     case ResourceTypeName.Projects:
     case ResourceTypeName.ClientRoot:
+    // Never final — these sharing resources gain and lose dynamic child fields over their lifetime.
+    case ResourceTypeName.SharingOutbox:
+    case ResourceTypeName.SharingState:
+    case ResourceTypeName.SharedEnvelope:
       return false;
     default:
       if (

package/src/core/ll_client.test.ts

@@ -50,7 +50,15 @@ test("unauthenticated status change", async () => {
     return;
   }
 
-  const client = await LLPlClient.build(plAddressToTestConfig(cfg.address));
+  // The flip to Unauthenticated is async, so await it via the status listener.
+  let onUnauthenticated!: () => void;
+  const unauthenticated = new Promise<void>((resolve) => (onUnauthenticated = resolve));
+
+  const client = await LLPlClient.build(plAddressToTestConfig(cfg.address), {
+    statusListener: (s) => {
+      if (s === "Unauthenticated") onUnauthenticated();
+    },
+  });
   expect(client.status).toBe("OK");
 
   const tx = client.createTx(true);
@@ -73,7 +81,12 @@ test("unauthenticated status change", async () => {
     await tx.await();
   }).rejects.toThrow(UnauthenticatedError);
 
-  await tp.setImmediate();
+  await Promise.race([
+    unauthenticated,
+    tp
+      .setTimeout(5000)
+      .then(() => Promise.reject(new Error("status never became Unauthenticated"))),
+  ]);
 
   expect(client.status).toEqual("Unauthenticated");
 });

package/src/core/ll_client.ts

@@ -42,7 +42,7 @@ import {
   TxAPI_ServerMessage,
 } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
 import type { MiLogger } from "@milaboratories/ts-helpers";
-import { isAbortedError } from "./errors";
+import { isAbortedError, isUnauthenticated } from "./errors";
 import { Timestamp } from "../proto-grpc/google/protobuf/timestamp";
 
 export interface PlCallOps {
@@ -122,6 +122,7 @@ export class LLPlClient implements WireClientProviderFactory {
   private _authMethodsSync?: grpcTypes.AuthAPI_ListMethods_Response;
 
   private _status: PlConnectionStatus = "OK";
+  private authProbeInFlight = false;
   private readonly statusListener?: PlConnectionStatusListener;
 
   private _wireProto: wireProtocol = "grpc";
@@ -393,6 +394,25 @@ export class LLPlClient implements WireClientProviderFactory {
     });
   }
 
+  /**
+   * UNAUTHENTICATED covers both a dead session (must reset) and a per-request authorization failure
+   * such as a revoked resource signature (must not). Disambiguate by probing getSessionInfo — an
+   * authenticated call with no resource signature: success means the session is alive and the failure
+   * was resource-level; a probe that is itself Unauthenticated means real auth loss. Coalesced via
+   * authProbeInFlight so a burst of failures costs one probe.
+   */
+  private async verifyThenMaybeEscalateUnauthenticated(): Promise<void> {
+    if (this._status !== "OK" || this.authProbeInFlight) return;
+    this.authProbeInFlight = true;
+    try {
+      await this.getSessionInfo();
+    } catch (e) {
+      if (isUnauthenticated(e)) this.updateStatus("Unauthenticated");
+    } finally {
+      this.authProbeInFlight = false;
+    }
+  }
+
   public get status(): PlConnectionStatus {
     return this._status;
   }
@@ -458,7 +478,7 @@ export class LLPlClient implements WireClientProviderFactory {
         }
 
         if (respErr.error.code === Code.UNAUTHENTICATED) {
-          this.updateStatus("Unauthenticated");
+          void this.verifyThenMaybeEscalateUnauthenticated();
         }
 
         // Let later middleware to deal with standard gRPC error.
@@ -476,7 +496,7 @@ export class LLPlClient implements WireClientProviderFactory {
             onReceiveStatus: (status, next) => {
               if (status.code == GrpcStatus.UNAUTHENTICATED)
                 // (!!!) don't change to "==="
-                this.updateStatus("Unauthenticated");
+                void this.verifyThenMaybeEscalateUnauthenticated();
               if (status.code == GrpcStatus.UNAVAILABLE)
                 // (!!!) don't change to "==="
                 this.updateStatus("Disconnected");
@@ -649,7 +669,7 @@ export class LLPlClient implements WireClientProviderFactory {
   /** Request a one-time PKCE nonce + its expiry from the backend. The desktop is
    * expected to place the nonce verbatim into the OIDC auth-request before
    * redirecting to the IdP; the backend enforces the expiry on {@link loginSSO}. */
-  public async beginSSOLogin(): Promise<{ nonce: string; expiresAt: Date }> {
+  public async beginSSOLogin(): Promise<{ nonce: string; expiresAt: Date; clientSecret?: string }> {
     const cl = this.clientProvider.get();
     if (cl instanceof GrpcPlApiClient) {
       const resp = (await cl.beginSSOLogin({}).response).flow;
@@ -660,6 +680,7 @@ export class LLPlClient implements WireClientProviderFactory {
       return {
         nonce: resp.publicPkce.nonce,
         expiresAt: Timestamp.toDate(exp),
+        clientSecret: resp.publicPkce.clientSecret,
       };
     } else {
       const wsResponse = notEmpty(
@@ -667,7 +688,11 @@ export class LLPlClient implements WireClientProviderFactory {
         "REST: empty response for beginSSOLogin request",
       );
       const pkce = notEmpty(wsResponse.publicPkce, "REST: missing publicPkce in beginSSOLogin");
-      return { nonce: pkce.nonce, expiresAt: new Date(pkce.expiresAt) };
+      return {
+        nonce: pkce.nonce,
+        expiresAt: new Date(pkce.expiresAt),
+        clientSecret: pkce.clientSecret,
+      };
     }
   }
 
@@ -737,13 +762,12 @@ export class LLPlClient implements WireClientProviderFactory {
   }
 
   /**
-   * True if the backend honors per-file `permissions` on workdir fill rules
-   * (PR #1830 in milaboratory/pl). Backends before this change ignore the
-   * requested mode and always land files at the canonical archive perm,
-   * making `exec.builder().writeFile/addFile({ writable: true })` a no-op.
+   * True if the backend honors per-file `permissions` on workdir fill rules, so
+   * `exec.builder().writeFile/addFile({ writable: true })` takes effect. When false
+   * the requested mode is ignored and files land at the canonical archive perm.
    *
-   * Tagged at 3.5.0 cut without the change, so [3, 5, 0] excludes the tagged
-   * release but includes dev builds past the tag (e.g. "3.5.0-224-g0ca182").
+   * [3, 5, 0] excludes the tagged 3.5.0 release but includes dev builds past the
+   * tag (e.g. "3.5.0-224-g0ca182"), which is where the support lands.
    */
   public get supportsWritableWorkdirFiles(): boolean {
     return isAfterVersion(this.serverInfo.coreVersion, [3, 5, 0]);
@@ -926,6 +950,37 @@ export class LLPlClient implements WireClientProviderFactory {
     return responses;
   }
 
+  /** Returns the authenticated caller's session id and effective role.
+   *  Models the {@link getUserRoot} wrapper: gRPC unary with a REST fallback. */
+  public async getSessionInfo(): Promise<grpcTypes.AuthAPI_GetSessionInfo_Response> {
+    const cl = this.clientProvider.get();
+    if (cl instanceof GrpcPlApiClient) {
+      return (await cl.getSessionInfo({})).response;
+    } else {
+      const resp = notEmpty(
+        (await cl.POST("/v1/auth/session-info", { body: {} })).data,
+        "REST: empty response for getSessionInfo request",
+      );
+      return {
+        sessionId: Uint8Array.from(Buffer.from(resp.sessionId, "base64")),
+        role: resp.role as AuthAPI_Role,
+      };
+    }
+  }
+
+  /** Lists the users known to the server — the recipient picker's source. A user
+   *  becomes known on first login; provisioned users who have never logged in do not
+   *  appear. gRPC-only (unary, no REST binding). */
+  public async listUsers(): Promise<grpcTypes.AuthAPI_User[]> {
+    const cl = this.clientProvider.get();
+
+    if (!(cl instanceof GrpcPlApiClient)) {
+      throw new Error("ListUsers requires gRPC wire protocol; REST is not supported");
+    }
+
+    return (await cl.listUsers({})).response.users;
+  }
+
   public async txSync(txId: bigint): Promise<void> {
     const cl = this.clientProvider.get();
     if (cl instanceof GrpcPlApiClient) {