@microsoft/agents-hosting 1.9.0-beta.18.g6b8111bba5 → 1.9.0-beta.20.g0c48a31a21
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.
- package/README.md +18 -10
- package/dist/package.json +3 -3
- package/dist/src/app/agentApplication.d.ts +1 -0
- package/dist/src/app/agentApplication.js +18 -5
- package/dist/src/app/agentApplication.js.map +1 -1
- package/dist/src/app/agentApplicationBuilder.d.ts +9 -2
- package/dist/src/app/agentApplicationBuilder.js +9 -0
- package/dist/src/app/agentApplicationBuilder.js.map +1 -1
- package/dist/src/app/agentApplicationOptions.d.ts +10 -4
- package/dist/src/app/auth/handlerStorage.d.ts +5 -3
- package/dist/src/app/auth/handlerStorage.js +36 -10
- package/dist/src/app/auth/handlerStorage.js.map +1 -1
- package/dist/src/app/auth/types.d.ts +2 -2
- package/dist/src/app/index.d.ts +1 -0
- package/dist/src/app/proactive/proactive.js +10 -6
- package/dist/src/app/proactive/proactive.js.map +1 -1
- package/dist/src/app/proactive/proactiveOptions.d.ts +2 -2
- package/dist/src/app/rateLimit.d.ts +315 -0
- package/dist/src/app/rateLimit.js +333 -0
- package/dist/src/app/rateLimit.js.map +1 -0
- package/dist/src/app/turnState.d.ts +6 -3
- package/dist/src/app/turnState.js +43 -4
- package/dist/src/app/turnState.js.map +1 -1
- package/dist/src/errorHelper.js +40 -9
- package/dist/src/errorHelper.js.map +1 -1
- package/dist/src/observability/traces.d.ts +6 -4
- package/dist/src/observability/traces.js +10 -9
- package/dist/src/observability/traces.js.map +1 -1
- package/dist/src/state/agentState.d.ts +8 -3
- package/dist/src/state/agentState.js +26 -8
- package/dist/src/state/agentState.js.map +1 -1
- package/dist/src/state/conversationState.d.ts +2 -2
- package/dist/src/state/conversationState.js.map +1 -1
- package/dist/src/state/userState.d.ts +2 -2
- package/dist/src/state/userState.js.map +1 -1
- package/dist/src/statusCodes.d.ts +5 -0
- package/dist/src/statusCodes.js +5 -0
- package/dist/src/statusCodes.js.map +1 -1
- package/dist/src/storage/fileStorage.d.ts +83 -71
- package/dist/src/storage/fileStorage.js +272 -136
- package/dist/src/storage/fileStorage.js.map +1 -1
- package/dist/src/storage/memoryStorage.d.ts +85 -62
- package/dist/src/storage/memoryStorage.js +240 -109
- package/dist/src/storage/memoryStorage.js.map +1 -1
- package/dist/src/storage/storage.d.ts +101 -16
- package/dist/src/storage/storage.js +25 -0
- package/dist/src/storage/storage.js.map +1 -1
- package/dist/src/storage/storageCompatibility.d.ts +17 -0
- package/dist/src/storage/storageCompatibility.js +157 -0
- package/dist/src/storage/storageCompatibility.js.map +1 -0
- package/package.json +3 -3
- package/src/app/agentApplication.ts +16 -0
- package/src/app/agentApplicationBuilder.ts +13 -2
- package/src/app/agentApplicationOptions.ts +11 -4
- package/src/app/auth/handlerStorage.ts +51 -7
- package/src/app/auth/types.ts +2 -2
- package/src/app/index.ts +7 -0
- package/src/app/proactive/proactive.ts +19 -9
- package/src/app/proactive/proactiveOptions.ts +2 -2
- package/src/app/rateLimit.ts +659 -0
- package/src/app/turnState.ts +50 -7
- package/src/errorHelper.ts +46 -8
- package/src/observability/traces.ts +8 -7
- package/src/state/agentState.ts +39 -13
- package/src/state/conversationState.ts +2 -2
- package/src/state/userState.ts +2 -2
- package/src/statusCodes.ts +6 -0
- package/src/storage/fileStorage.ts +289 -134
- package/src/storage/memoryStorage.ts +266 -109
- package/src/storage/storage.ts +115 -17
- package/src/storage/storageCompatibility.ts +185 -0
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright (c) Microsoft Corporation. All rights reserved.
|
|
3
|
+
* Licensed under the MIT License.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { ExceptionHelper } from '@microsoft/agents-activity'
|
|
7
|
+
import { Errors } from '../errorHelper'
|
|
8
|
+
import {
|
|
9
|
+
Storage,
|
|
10
|
+
StorageDeleteOptions,
|
|
11
|
+
StorageDeleteResults,
|
|
12
|
+
StorageOperationStatus,
|
|
13
|
+
StorageProvider,
|
|
14
|
+
StorageReadResults,
|
|
15
|
+
StorageV2,
|
|
16
|
+
StorageWriteMode,
|
|
17
|
+
StorageWriteOptions,
|
|
18
|
+
StorageWriteResults,
|
|
19
|
+
} from './storage'
|
|
20
|
+
|
|
21
|
+
/** Returns true when a storage implementation declares the V2 contract. */
|
|
22
|
+
export function isStorageV2 (storage: StorageProvider): storage is StorageV2 {
|
|
23
|
+
return storage instanceof StorageV2
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Converts a supported storage implementation to the V2 contract. */
|
|
27
|
+
export function asStorageV2 (storage: StorageProvider): StorageV2 {
|
|
28
|
+
return isStorageV2(storage) ? storage : new StorageToStorageV2Adapter(storage)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
|
|
32
|
+
export function getStorageReadValue<T extends object> (results: StorageReadResults<T> | null | undefined, key: string): T | undefined {
|
|
33
|
+
const result = results?.[key]
|
|
34
|
+
if (result?.status === StorageOperationStatus.NotFound) return undefined
|
|
35
|
+
if (result?.status === StorageOperationStatus.Succeeded) return result.value
|
|
36
|
+
throwStorageResultError('read', key, result?.status)
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Adapts the legacy storage contract to version 2 where its semantics allow it. */
|
|
40
|
+
class StorageToStorageV2Adapter extends StorageV2 {
|
|
41
|
+
constructor (private readonly storage: Storage) {
|
|
42
|
+
super()
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
async read<T extends object = Record<string, unknown>> (keys: string[]): Promise<StorageReadResults<T>> {
|
|
46
|
+
validateKeys(keys)
|
|
47
|
+
if (keys.length === 0) return {}
|
|
48
|
+
|
|
49
|
+
const items = await this.storage.read(keys)
|
|
50
|
+
return Object.fromEntries(keys.map(key => {
|
|
51
|
+
const value = items[key]
|
|
52
|
+
return [key, Object.prototype.hasOwnProperty.call(items, key)
|
|
53
|
+
? { key, status: StorageOperationStatus.Succeeded, value: value as T, version: value?.eTag as string | undefined }
|
|
54
|
+
: { key, status: StorageOperationStatus.NotFound }]
|
|
55
|
+
}))
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
async write<T extends object = Record<string, unknown>> (changes: Record<string, T>, options?: StorageWriteOptions): Promise<StorageWriteResults> {
|
|
59
|
+
validateChanges(changes)
|
|
60
|
+
if (options?.mode !== undefined && options.mode !== StorageWriteMode.Upsert) {
|
|
61
|
+
throwUnsupportedOption('mode')
|
|
62
|
+
}
|
|
63
|
+
if (options?.ttl !== undefined) {
|
|
64
|
+
throwUnsupportedOption('ttl')
|
|
65
|
+
}
|
|
66
|
+
validateExpectedVersion(options?.expectedVersion)
|
|
67
|
+
if (Object.keys(changes).length === 0) return {}
|
|
68
|
+
const legacyChanges = Object.fromEntries(Object.entries(changes).map(([key, value]) => [
|
|
69
|
+
key,
|
|
70
|
+
options?.expectedVersion === undefined
|
|
71
|
+
? removeLegacyETag(value)
|
|
72
|
+
: { ...removeLegacyETag(value), eTag: options.expectedVersion },
|
|
73
|
+
]))
|
|
74
|
+
await this.storage.write(legacyChanges)
|
|
75
|
+
return Object.fromEntries(Object.keys(changes).map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
async delete (keys: string[], options?: StorageDeleteOptions): Promise<StorageDeleteResults> {
|
|
79
|
+
validateDeleteKeys(keys)
|
|
80
|
+
validateExpectedVersion(options?.expectedVersion)
|
|
81
|
+
if (options?.expectedVersion !== undefined) {
|
|
82
|
+
throwUnsupportedOption('expectedVersion')
|
|
83
|
+
}
|
|
84
|
+
if (keys.length === 0) return {}
|
|
85
|
+
|
|
86
|
+
await this.storage.delete(keys)
|
|
87
|
+
return Object.fromEntries(keys.map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function validateKeys (keys: string[]): void {
|
|
92
|
+
if (!Array.isArray(keys)) {
|
|
93
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageReadKeysRequired)
|
|
94
|
+
}
|
|
95
|
+
if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
|
|
96
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function validateDeleteKeys (keys: string[]): void {
|
|
101
|
+
if (!Array.isArray(keys)) {
|
|
102
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageDeleteKeysRequired)
|
|
103
|
+
}
|
|
104
|
+
if (keys.some(key => typeof key !== 'string' || key.trim() === '')) {
|
|
105
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function validateChanges (changes: Record<string, unknown>): void {
|
|
110
|
+
if (changes === null || typeof changes !== 'object' || Array.isArray(changes)) {
|
|
111
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageWriteChangesRequired)
|
|
112
|
+
}
|
|
113
|
+
if (Object.keys(changes).some(key => key.trim() === '')) {
|
|
114
|
+
throw ExceptionHelper.generateException(ReferenceError, Errors.StorageV2KeyRequired)
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function removeLegacyETag<T> (value: T): T {
|
|
119
|
+
if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
|
|
120
|
+
const { eTag: _eTag, ...withoutETag } = value as Record<string, unknown>
|
|
121
|
+
return withoutETag as T
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function validateExpectedVersion (expectedVersion: string | undefined): void {
|
|
125
|
+
if (expectedVersion === '') {
|
|
126
|
+
throw ExceptionHelper.generateException(RangeError, Errors.StorageV2ExpectedVersionEmpty)
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function throwUnsupportedOption (option: string): never {
|
|
131
|
+
throw ExceptionHelper.generateException(Error, Errors.StorageV2UnsupportedOption, undefined, { option })
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** Throws when a V2 write did not succeed for every requested key. */
|
|
135
|
+
export function assertStorageWriteSucceeded (results: StorageWriteResults | null | undefined, keys: string[]): void {
|
|
136
|
+
assertStorageResults('write', results, keys, new Set([StorageOperationStatus.Succeeded]))
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Throws the state-specific concurrency error when a state write does not succeed. */
|
|
140
|
+
export function assertAgentStateWriteSucceeded (
|
|
141
|
+
results: StorageWriteResults | null | undefined,
|
|
142
|
+
key: string,
|
|
143
|
+
name: string
|
|
144
|
+
): void {
|
|
145
|
+
const status = results?.[key]?.status
|
|
146
|
+
if (status !== StorageOperationStatus.Succeeded) {
|
|
147
|
+
throw ExceptionHelper.generateException(Error, Errors.AgentStateWriteConflict, undefined, {
|
|
148
|
+
name,
|
|
149
|
+
key,
|
|
150
|
+
status: status ?? 'missing',
|
|
151
|
+
})
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Throws when a V2 delete did not complete with idempotent V1 semantics. */
|
|
156
|
+
export function assertStorageDeleteSucceeded (results: StorageDeleteResults | null | undefined, keys: string[]): void {
|
|
157
|
+
assertStorageResults(
|
|
158
|
+
'delete',
|
|
159
|
+
results,
|
|
160
|
+
keys,
|
|
161
|
+
new Set([StorageOperationStatus.Succeeded, StorageOperationStatus.NotFound])
|
|
162
|
+
)
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function assertStorageResults (
|
|
166
|
+
operation: 'write' | 'delete',
|
|
167
|
+
results: StorageWriteResults | StorageDeleteResults | null | undefined,
|
|
168
|
+
keys: string[],
|
|
169
|
+
acceptedStatuses: ReadonlySet<StorageOperationStatus>
|
|
170
|
+
): void {
|
|
171
|
+
for (const key of keys) {
|
|
172
|
+
const status = results?.[key]?.status
|
|
173
|
+
if (status === undefined || !acceptedStatuses.has(status)) {
|
|
174
|
+
throwStorageResultError(operation, key, status)
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function throwStorageResultError (operation: 'read' | 'write' | 'delete', key: string, status?: StorageOperationStatus): never {
|
|
180
|
+
throw ExceptionHelper.generateException(Error, Errors.StorageV2OperationFailed, undefined, {
|
|
181
|
+
operation,
|
|
182
|
+
key,
|
|
183
|
+
status: status ?? 'missing',
|
|
184
|
+
})
|
|
185
|
+
}
|