@microsoft/agents-hosting 1.9.0-beta.3.gb2d23c1c44 → 1.9.1

package/src/storage/storageCompatibility.ts

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
+import {
+  Storage,
+  StorageDeleteOptions,
+  StorageDeleteResults,
+  StorageOperationStatus,
+  StorageProvider,
+  StorageReadResults,
+  StorageV2,
+  StorageWriteMode,
+  StorageWriteOptions,
+  StorageWriteResults,
+} from './storage'
+
+/** Returns true when a storage implementation declares the V2 contract. */
+export function isStorageV2 (storage: StorageProvider): storage is StorageV2 {
+  return storage instanceof StorageV2
+}
+
+/** Converts a supported storage implementation to the V2 contract. */
+export function asStorageV2 (storage: StorageProvider): StorageV2 {
+  return isStorageV2(storage) ? storage : new StorageToStorageV2Adapter(storage)
+}
+
+/** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
+export function getStorageReadValue<T extends object> (results: StorageReadResults<T> | null | undefined, key: string): T | undefined {
+  const result = results?.[key]
+  if (result?.status === StorageOperationStatus.NotFound) return undefined
+  if (result?.status === StorageOperationStatus.Succeeded) return result.value
+  throwStorageResultError('read', key, result?.status)
+}
+
+/** Adapts the legacy storage contract to version 2 where its semantics allow it. */
+class StorageToStorageV2Adapter extends StorageV2 {
+  constructor (private readonly storage: Storage) {
+    super()
+  }
+
+  async read<T extends object = Record<string, unknown>> (keys: string[]): Promise<StorageReadResults<T>> {
+    validateKeys(keys)
+    if (keys.length === 0) return {}
+
+    const items = await this.storage.read(keys)
+    return Object.fromEntries(keys.map(key => {
+      const value = items[key]
+      return [key, Object.prototype.hasOwnProperty.call(items, key)
+        ? { key, status: StorageOperationStatus.Succeeded, value: value as T, version: value?.eTag as string | undefined }
+        : { key, status: StorageOperationStatus.NotFound }]
+    }))
+  }
+
+  async write<T extends object = Record<string, unknown>> (changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults> {
+    validateChanges(changes)
+    if (options?.mode !== undefined && options.mode !== StorageWriteMode.Upsert) {
+      throwUnsupportedOption('mode')
+    }
+    if (options?.ttl !== undefined) {
+      throwUnsupportedOption('ttl')
+    }
+    validateExpectedVersion(options?.expectedVersion)
+    if (Object.keys(changes).length === 0) return {}
+    const legacyChanges = Object.fromEntries(Object.entries(changes).map(([key, value]) => [
+      key,
+      options?.expectedVersion === undefined
+        ? removeLegacyETag(value)
+        : { ...removeLegacyETag(value), eTag: options.expectedVersion },
+    ]))
+    await this.storage.write(legacyChanges)
+    return Object.fromEntries(Object.keys(changes).map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
+  }
+
+  async delete (keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults> {
+    validateDeleteKeys(keys)
+    validateExpectedVersion(options?.expectedVersion)
+    if (options?.expectedVersion !== undefined) {
+      throwUnsupportedOption('expectedVersion')
+    }
+    if (keys.length === 0) return {}
+
+    await this.storage.delete(keys)
+    return Object.fromEntries(keys.map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
+  }
+}
+
+function validateKeys (keys: string[]): void {
+  if (!Array.isArray(keys)) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageReadKeysRequired)
+  }
+  if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
+  }
+}
+
+function validateDeleteKeys (keys: string[]): void {
+  if (!Array.isArray(keys)) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageDeleteKeysRequired)
+  }
+  if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
+  }
+}
+
+function validateChanges (changes: Record<string, unknown>): void {
+  if (changes === null || typeof changes !== 'object' || Array.isArray(changes)) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageWriteChangesRequired)
+  }
+  if (Object.keys(changes).some(key => key.trim() === '')) {
+    throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
+  }
+}
+
+function removeLegacyETag<T> (value: T): T {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
+  const { eTag: _eTag, ...withoutETag } = value as Record<string, unknown>
+  return withoutETag as T
+}
+
+function validateExpectedVersion (expectedVersion: string | undefined): void {
+  if (expectedVersion === '') {
+    throw ExceptionHelper.generateException(RangeError, Errors.StorageV2ExpectedVersionEmpty)
+  }
+}
+
+function throwUnsupportedOption (option: string): never {
+  throw ExceptionHelper.generateException(Error, Errors.StorageV2UnsupportedOption, undefined, { option })
+}
+
+/** Throws when a V2 write did not succeed for every requested key. */
+export function assertStorageWriteSucceeded (results: StorageWriteResults | null | undefined, keys: string[]): void {
+  assertStorageResults('write', results, keys, new Set([StorageOperationStatus.Succeeded]))
+}
+
+/** Throws the state-specific concurrency error when a state write does not succeed. */
+export function assertAgentStateWriteSucceeded (
+  results: StorageWriteResults | null | undefined,
+  key: string,
+  name: string
+): void {
+  const status = results?.[key]?.status
+  if (status !== StorageOperationStatus.Succeeded) {
+    throw ExceptionHelper.generateException(Error, Errors.AgentStateWriteConflict, undefined, {
+      name,
+      key,
+      status: status ?? 'missing',
+    })
+  }
+}
+
+/** Throws when a V2 delete did not complete with idempotent V1 semantics. */
+export function assertStorageDeleteSucceeded (results: StorageDeleteResults | null | undefined, keys: string[]): void {
+  assertStorageResults(
+    'delete',
+    results,
+    keys,
+    new Set([StorageOperationStatus.Succeeded, StorageOperationStatus.NotFound])
+  )
+}
+
+function assertStorageResults (
+  operation: 'write' | 'delete',
+  results: StorageWriteResults | StorageDeleteResults | null | undefined,
+  keys: string[],
+  acceptedStatuses: ReadonlySet<StorageOperationStatus>
+): void {
+  for (const key of keys) {
+    const status = results?.[key]?.status
+    if (status === undefined || !acceptedStatuses.has(status)) {
+      throwStorageResultError(operation, key, status)
+    }
+  }
+}
+
+function throwStorageResultError (operation: 'read' | 'write' | 'delete', key: string, status?: StorageOperationStatus): never {
+  throw ExceptionHelper.generateException(Error, Errors.StorageV2OperationFailed, undefined, {
+    operation,
+    key,
+    status: status ?? 'missing',
+  })
+}

package/src/storage/storageExpiry.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { StorageWriteOptions } from './storage'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
+
+export function getStorageWriteExpiry (options?: StorageWriteOptions): number | undefined {
+  const ttl = options?.ttl
+  if (ttl === undefined) {
+    return undefined
+  }
+
+  if (!Number.isFinite(ttl) || ttl <= 0) {
+    throw ExceptionHelper.generateException(RangeError, Errors.InvalidStorageTtl)
+  }
+
+  return Date.now() + ttl * 1000
+}

package/src/utils/env.ts

@@ -10,6 +10,69 @@
  * normalize behavior across the package without growing the public API.
  */
 
+export interface LoadEnv {
+  [upperKey: string]: { key: string, value: any }
+}
+
+type ParserSettings<K extends string> = {
+  [key in K]: (value: string) => { key?: string, value?: any } | undefined
+}
+
+/**
+ * Indexes non-empty environment values case-insensitively while preserving
+ * their original key spelling.
+ */
+export function loadEnvSettings (
+  callback: (key: string, value: string) => void,
+  environment: NodeJS.ProcessEnv = process.env
+): LoadEnv {
+  const env: LoadEnv = {}
+  for (const [envKey, envValue] of Object.entries(environment)) {
+    if (!envValue?.trim()) {
+      continue
+    }
+
+    env[envKey.toUpperCase()] = { key: envKey, value: envValue }
+    callback(envKey, envValue)
+  }
+
+  return env
+}
+
+/**
+ * Creates a case-insensitive parser for a fixed set of environment keys.
+ */
+export function envParser<K extends string> (
+  settings: ParserSettings<K> & ThisType<ParserSettings<K>>
+) {
+  const keys = Object.keys(settings) as K[]
+  const upperKeys = keys.reduce((acc, key) => {
+    acc[key.toUpperCase()] = key
+    return acc
+  }, {} as Record<string, K>)
+
+  return {
+    keys,
+    parse (key: K, value: string) {
+      const match = upperKeys[key.toUpperCase()]
+      if (!match) {
+        return {}
+      }
+
+      const result = settings[match](value)
+      return { key: result?.key ?? match, value: result?.value }
+    }
+  }
+}
+
+export const envParserUtils = {
+  bypass: (value: string) => ({ value }),
+  redirect: <Parser extends ReturnType<typeof envParser>>(
+    parser: Parser,
+    key: Parameters<Parser['parse']>[0]
+  ) => (value: string) => parser.parse(key, value)
+}
+
 /**
  * Parses an environment-variable string into a boolean.
  *

package/src/utils.ts

@@ -12,3 +12,13 @@ export const prune = <T extends Record<string, any>>(obj: T) => {
   const entries = Object.entries(obj).filter(([, value]) => value !== undefined)
   return Object.fromEntries(entries) as T
 }
+
+export const mergeDefined = <T extends Record<string, any>>(
+  ...layers: readonly (Partial<T> | undefined)[]
+): T => {
+  const result: Partial<T> = {}
+  for (const layer of layers) {
+    if (layer) Object.assign(result, prune(layer))
+  }
+  return result as T
+}