teams_rb 2.0.3 → 2.1.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +39 -1
- data/docs/README.md +1 -1
- data/docs/essentials/README.md +1 -1
- data/docs/essentials/on-event.md +12 -2
- data/docs/essentials/sending-messages.md +7 -4
- data/docs/in-depth-guides/README.md +2 -0
- data/docs/in-depth-guides/agent-365.md +3 -1
- data/docs/in-depth-guides/files.md +99 -0
- data/docs/in-depth-guides/state.md +59 -0
- data/docs/in-depth-guides/streaming.md +6 -5
- data/docs/in-depth-guides/user-authentication.md +36 -8
- data/lib/teams/activity_context.rb +118 -15
- data/lib/teams/api/citation_appearance.rb +10 -2
- data/lib/teams/api/file_download_info.rb +34 -0
- data/lib/teams/api/message_activity.rb +37 -12
- data/lib/teams/api/sensitivity_usage_info.rb +38 -0
- data/lib/teams/app.rb +195 -153
- data/lib/teams/auth/jwt_validator.rb +17 -2
- data/lib/teams/cards/generated.rb +430 -430
- data/lib/teams/errors.rb +175 -4
- data/lib/teams/files/downloaded_file.rb +35 -0
- data/lib/teams/files/downloader.rb +405 -0
- data/lib/teams/files/files_accessor.rb +175 -0
- data/lib/teams/files/graph_share.rb +44 -0
- data/lib/teams/files/incoming_file.rb +128 -0
- data/lib/teams/files/inline_image.rb +88 -0
- data/lib/teams/files.rb +8 -0
- data/lib/teams/http_stream.rb +28 -28
- data/lib/teams/oauth/flow.rb +184 -0
- data/lib/teams/oauth/handlers.rb +376 -0
- data/lib/teams/oauth/pending_sign_ins.rb +300 -0
- data/lib/teams/oauth.rb +5 -0
- data/lib/teams/state/turn_state.rb +163 -0
- data/lib/teams/state/turn_state_container.rb +54 -0
- data/lib/teams/state/turn_state_loader.rb +143 -0
- data/lib/teams/state.rb +5 -0
- data/lib/teams/version.rb +1 -1
- data/lib/teams.rb +5 -0
- metadata +20 -1
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "time"
|
|
4
|
+
|
|
5
|
+
module Teams
|
|
6
|
+
module OAuth
|
|
7
|
+
# A sign-in awaiting its callback: the connection it started on, when,
|
|
8
|
+
# and whether the card offered silent SSO (a token exchange resource).
|
|
9
|
+
PendingSignIn = Struct.new(:connection_name, :created_at, :sso_offered, keyword_init: true)
|
|
10
|
+
|
|
11
|
+
# Timestamps shared by the pending and exchange markers: ISO 8601 UTC,
|
|
12
|
+
# readable across the SDKs (a value without an offset is read as UTC).
|
|
13
|
+
module Timestamps
|
|
14
|
+
module_function
|
|
15
|
+
|
|
16
|
+
def format(epoch_seconds)
|
|
17
|
+
Time.at(epoch_seconds).utc.iso8601(6)
|
|
18
|
+
end
|
|
19
|
+
|
|
20
|
+
def parse(raw)
|
|
21
|
+
return nil unless raw.is_a?(String)
|
|
22
|
+
|
|
23
|
+
value = raw.match?(/(z|[+-]\d{2}:?\d{2})\z/i) ? raw : "#{raw}Z"
|
|
24
|
+
Time.iso8601(value).to_f
|
|
25
|
+
rescue ArgumentError
|
|
26
|
+
nil
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# Process-local pending sign-ins, used when per-turn state is off. Bounded
|
|
31
|
+
# and short-lived; a callback handled by another process cannot be
|
|
32
|
+
# attributed from here.
|
|
33
|
+
class LocalPendingCache
|
|
34
|
+
TTL = 300.0
|
|
35
|
+
MAX_ENTRIES = 1000
|
|
36
|
+
|
|
37
|
+
def initialize
|
|
38
|
+
@entries = {}
|
|
39
|
+
@mutex = Mutex.new
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def record(conversation_id, user_id, connection_name, sso_offered:)
|
|
43
|
+
key = cache_key(conversation_id, user_id, connection_name)
|
|
44
|
+
return unless key
|
|
45
|
+
|
|
46
|
+
@mutex.synchronize do
|
|
47
|
+
now = Time.now.to_f
|
|
48
|
+
prune(now)
|
|
49
|
+
@entries.delete(key)
|
|
50
|
+
@entries[key] = PendingSignIn.new(connection_name: connection_name.strip, created_at: now, sso_offered:)
|
|
51
|
+
@entries.shift while @entries.size > MAX_ENTRIES
|
|
52
|
+
end
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# Unexpired hints for this conversation and user, newest first.
|
|
56
|
+
def entries(conversation_id, user_id)
|
|
57
|
+
return [] if blank?(conversation_id) || blank?(user_id)
|
|
58
|
+
|
|
59
|
+
found = @mutex.synchronize do
|
|
60
|
+
prune(Time.now.to_f)
|
|
61
|
+
@entries.select { |(conv, user, _), _| conv == conversation_id && user == user_id }.values
|
|
62
|
+
end
|
|
63
|
+
PendingSignIns.sort(found)
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
def clear(conversation_id, user_id, connection_name = nil)
|
|
67
|
+
return if blank?(conversation_id) || blank?(user_id)
|
|
68
|
+
|
|
69
|
+
target = connection_name.nil? ? nil : OAuth.lookup_key(connection_name)
|
|
70
|
+
return if connection_name && target.nil?
|
|
71
|
+
|
|
72
|
+
@mutex.synchronize do
|
|
73
|
+
@entries.delete_if do |(conv, user, connection), _|
|
|
74
|
+
conv == conversation_id && user == user_id && (target.nil? || connection == target)
|
|
75
|
+
end
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# Restores an exact prior set of hints, keeping their timestamps.
|
|
80
|
+
def replace(conversation_id, user_id, pending)
|
|
81
|
+
return if blank?(conversation_id) || blank?(user_id)
|
|
82
|
+
|
|
83
|
+
clear(conversation_id, user_id)
|
|
84
|
+
@mutex.synchronize do
|
|
85
|
+
pending.each do |hint|
|
|
86
|
+
key = cache_key(conversation_id, user_id, hint.connection_name)
|
|
87
|
+
@entries[key] = hint.dup.tap { |entry| entry.connection_name = hint.connection_name.strip } if key
|
|
88
|
+
end
|
|
89
|
+
end
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
private
|
|
93
|
+
|
|
94
|
+
def cache_key(conversation_id, user_id, connection_name)
|
|
95
|
+
return nil if blank?(conversation_id) || blank?(user_id)
|
|
96
|
+
|
|
97
|
+
connection = OAuth.lookup_key(connection_name)
|
|
98
|
+
connection ? [conversation_id, user_id, connection] : nil
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
def prune(now)
|
|
102
|
+
@entries.delete_if { |_, entry| now - entry.created_at >= TTL }
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
def blank?(value)
|
|
106
|
+
value.nil? || value.to_s.empty?
|
|
107
|
+
end
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
# Pending sign-ins are recorded in the user state scope when per-turn
|
|
111
|
+
# state is available ("__oauth:pending:{connection}" plus an
|
|
112
|
+
# "__oauth:pending:sso:{connection}" marker when silent SSO was offered),
|
|
113
|
+
# and in the process-local cache otherwise. Same keys and lifetimes as
|
|
114
|
+
# the Python SDK.
|
|
115
|
+
module PendingSignIns
|
|
116
|
+
KEY_PREFIX = "__oauth:pending:"
|
|
117
|
+
SSO_INFIX = "sso:"
|
|
118
|
+
MAX_AGE = 5 * 60
|
|
119
|
+
MAX_CLOCK_SKEW = 60
|
|
120
|
+
|
|
121
|
+
module_function
|
|
122
|
+
|
|
123
|
+
def record(state, local, connection_name, sso_offered:, conversation_id:, user_id:)
|
|
124
|
+
user = state&.user
|
|
125
|
+
return local.record(conversation_id, user_id, connection_name, sso_offered:) unless user
|
|
126
|
+
|
|
127
|
+
read_markers(user)
|
|
128
|
+
remove_connection(user, connection_name)
|
|
129
|
+
stamp = Timestamps.format(Time.now.to_f)
|
|
130
|
+
user[pending_key(connection_name)] = stamp
|
|
131
|
+
user[sso_key(connection_name)] = stamp if sso_offered
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
# Live pending sign-ins, newest first.
|
|
135
|
+
def list(state, local, conversation_id:, user_id:)
|
|
136
|
+
user = state&.user
|
|
137
|
+
return local.entries(conversation_id, user_id) unless user
|
|
138
|
+
|
|
139
|
+
sort(read_markers(user).values)
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
# Clears one connection's hint, or every hint when connection_name is nil.
|
|
143
|
+
def clear(state, local, connection_name = nil, conversation_id:, user_id:)
|
|
144
|
+
user = state&.user
|
|
145
|
+
return local.clear(conversation_id, user_id, connection_name) unless user
|
|
146
|
+
|
|
147
|
+
if connection_name.nil?
|
|
148
|
+
user.keys.each { |key| user.delete(key) if key.start_with?(KEY_PREFIX) }
|
|
149
|
+
else
|
|
150
|
+
remove_connection(user, connection_name)
|
|
151
|
+
end
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
def replace(state, local, pending, conversation_id:, user_id:)
|
|
155
|
+
user = state&.user
|
|
156
|
+
return local.replace(conversation_id, user_id, pending) unless user
|
|
157
|
+
|
|
158
|
+
clear(state, local, conversation_id:, user_id:)
|
|
159
|
+
pending.each do |hint|
|
|
160
|
+
stamp = Timestamps.format(hint.created_at)
|
|
161
|
+
user[pending_key(hint.connection_name)] = stamp
|
|
162
|
+
user[sso_key(hint.connection_name)] = stamp if hint.sso_offered
|
|
163
|
+
end
|
|
164
|
+
end
|
|
165
|
+
|
|
166
|
+
def sort(pending)
|
|
167
|
+
pending.sort_by { |hint| [-hint.created_at, hint.connection_name.downcase] }
|
|
168
|
+
end
|
|
169
|
+
|
|
170
|
+
def pending_key(connection_name)
|
|
171
|
+
"#{KEY_PREFIX}#{connection_name.strip}"
|
|
172
|
+
end
|
|
173
|
+
|
|
174
|
+
def sso_key(connection_name)
|
|
175
|
+
"#{KEY_PREFIX}#{SSO_INFIX}#{connection_name.strip}"
|
|
176
|
+
end
|
|
177
|
+
|
|
178
|
+
# [key, connection_name, sso_marker?] for every pending marker. "sso:"
|
|
179
|
+
# can start a real connection name, so "__oauth:pending:sso:x" is x's
|
|
180
|
+
# SSO marker only while x's own marker exists.
|
|
181
|
+
def markers(user)
|
|
182
|
+
keys = user.keys.select { |key| key.start_with?(KEY_PREFIX) }
|
|
183
|
+
keys.map do |key|
|
|
184
|
+
name = key.delete_prefix(KEY_PREFIX)
|
|
185
|
+
if name.start_with?(SSO_INFIX)
|
|
186
|
+
owner = name.delete_prefix(SSO_INFIX)
|
|
187
|
+
next [key, owner, true] if keys.include?(pending_key(owner))
|
|
188
|
+
end
|
|
189
|
+
[key, name, false]
|
|
190
|
+
end
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
# Parses live markers into hints keyed by lowercased connection name,
|
|
194
|
+
# dropping malformed, future-dated, and expired markers from state.
|
|
195
|
+
def read_markers(user)
|
|
196
|
+
now = Time.now.to_f
|
|
197
|
+
hints = {}
|
|
198
|
+
sso_owners = {}
|
|
199
|
+
markers(user).each do |key, name, sso_marker|
|
|
200
|
+
next unless user.key?(key)
|
|
201
|
+
|
|
202
|
+
created_at = Timestamps.parse(user[key])
|
|
203
|
+
if created_at.nil? || created_at - now > MAX_CLOCK_SKEW || now - created_at > MAX_AGE
|
|
204
|
+
user.delete(key)
|
|
205
|
+
next
|
|
206
|
+
end
|
|
207
|
+
if sso_marker
|
|
208
|
+
sso_owners[name.downcase] = name
|
|
209
|
+
next
|
|
210
|
+
end
|
|
211
|
+
|
|
212
|
+
candidate = PendingSignIn.new(connection_name: name, created_at:, sso_offered: false)
|
|
213
|
+
existing = hints[name.downcase]
|
|
214
|
+
if existing
|
|
215
|
+
loser, winner = candidate.created_at >= existing.created_at ? [existing, candidate] : [candidate, existing]
|
|
216
|
+
user.delete(pending_key(loser.connection_name))
|
|
217
|
+
user.delete(sso_key(loser.connection_name))
|
|
218
|
+
candidate = winner
|
|
219
|
+
end
|
|
220
|
+
hints[name.downcase] = candidate
|
|
221
|
+
end
|
|
222
|
+
sso_owners.each { |lowered, owner| user.delete(sso_key(owner)) unless hints.key?(lowered) }
|
|
223
|
+
hints.each { |lowered, hint| hint.sso_offered = sso_owners.key?(lowered) }
|
|
224
|
+
hints
|
|
225
|
+
end
|
|
226
|
+
|
|
227
|
+
def remove_connection(user, connection_name)
|
|
228
|
+
target = OAuth.lookup_key(connection_name)
|
|
229
|
+
markers(user).each { |key, name, _| user.delete(key) if OAuth.lookup_key(name) == target }
|
|
230
|
+
end
|
|
231
|
+
end
|
|
232
|
+
|
|
233
|
+
# Completed token exchanges, recorded in conversation state so a
|
|
234
|
+
# duplicate routed to another instance still short-circuits (best-effort:
|
|
235
|
+
# storage has no compare-and-set, so the in-process guard is what makes
|
|
236
|
+
# same-instance dedup atomic, as in the other SDKs).
|
|
237
|
+
module ExchangeMarkers
|
|
238
|
+
KEY_PREFIX = "__oauth:exchange:"
|
|
239
|
+
TTL = 5 * 60
|
|
240
|
+
MAX_ENTRIES = 1000
|
|
241
|
+
|
|
242
|
+
module_function
|
|
243
|
+
|
|
244
|
+
def key(exchange_id)
|
|
245
|
+
"#{KEY_PREFIX}#{exchange_id}"
|
|
246
|
+
end
|
|
247
|
+
|
|
248
|
+
def completed?(state, exchange_id)
|
|
249
|
+
return false if state.nil? || exchange_id.to_s.empty?
|
|
250
|
+
|
|
251
|
+
raw = state.conversation[key(exchange_id)]
|
|
252
|
+
return false if raw.nil?
|
|
253
|
+
|
|
254
|
+
completed_at = parse(raw)
|
|
255
|
+
if completed_at.nil? || Time.now.to_f - completed_at > TTL
|
|
256
|
+
state.conversation.delete(key(exchange_id))
|
|
257
|
+
return false
|
|
258
|
+
end
|
|
259
|
+
true
|
|
260
|
+
end
|
|
261
|
+
|
|
262
|
+
# Never cleared when the exchange finishes, so a late duplicate from a
|
|
263
|
+
# second Teams endpoint still deduplicates; markers age out after TTL,
|
|
264
|
+
# and the oldest are trimmed past MAX_ENTRIES (never the new one).
|
|
265
|
+
def record(state, exchange_id)
|
|
266
|
+
return if state.nil? || exchange_id.to_s.empty?
|
|
267
|
+
|
|
268
|
+
conversation = state.conversation
|
|
269
|
+
now = Time.now.to_f
|
|
270
|
+
conversation.keys.each do |stored|
|
|
271
|
+
next unless stored.start_with?(KEY_PREFIX)
|
|
272
|
+
|
|
273
|
+
completed_at = parse(conversation[stored])
|
|
274
|
+
conversation.delete(stored) if completed_at.nil? || now - completed_at > TTL
|
|
275
|
+
end
|
|
276
|
+
written = key(exchange_id)
|
|
277
|
+
conversation[written] = Timestamps.format(now)
|
|
278
|
+
|
|
279
|
+
stored_keys = conversation.keys.select { |stored| stored.start_with?(KEY_PREFIX) }
|
|
280
|
+
overflow = stored_keys.size - MAX_ENTRIES
|
|
281
|
+
return unless overflow.positive?
|
|
282
|
+
|
|
283
|
+
stored_keys.sort_by { |stored| [parse(conversation[stored]) || -Float::INFINITY, stored] }.each do |stored|
|
|
284
|
+
break unless overflow.positive?
|
|
285
|
+
next if stored == written
|
|
286
|
+
|
|
287
|
+
conversation.delete(stored)
|
|
288
|
+
overflow -= 1
|
|
289
|
+
end
|
|
290
|
+
end
|
|
291
|
+
|
|
292
|
+
def parse(raw)
|
|
293
|
+
completed_at = Timestamps.parse(raw)
|
|
294
|
+
return nil if completed_at.nil? || completed_at > Time.now.to_f + PendingSignIns::MAX_CLOCK_SKEW
|
|
295
|
+
|
|
296
|
+
completed_at
|
|
297
|
+
end
|
|
298
|
+
end
|
|
299
|
+
end
|
|
300
|
+
end
|
data/lib/teams/oauth.rb
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "digest"
|
|
4
|
+
require "json"
|
|
5
|
+
|
|
6
|
+
module Teams
|
|
7
|
+
module State
|
|
8
|
+
# Raised when a sealed TurnState is used after its turn ended.
|
|
9
|
+
class TurnStateSealedError < Teams::Error; end
|
|
10
|
+
|
|
11
|
+
# One state scope (conversation or user) for a single turn. Behaves like a
|
|
12
|
+
# Hash, mirroring Python's mapping-shaped TurnState, and adds what the
|
|
13
|
+
# loader relies on:
|
|
14
|
+
#
|
|
15
|
+
# - Dirty tracking: contents are compared to the loaded snapshot, so nested
|
|
16
|
+
# mutations persist without reassignment and reverted changes write
|
|
17
|
+
# nothing.
|
|
18
|
+
# - Sealing: at the end of the turn the scope is sealed and any later
|
|
19
|
+
# access raises TurnStateSealedError.
|
|
20
|
+
#
|
|
21
|
+
# Values must be JSON-serializable (String, Integer, Float, true/false,
|
|
22
|
+
# nil, Array, Hash); a scope is saved as JSON at the end of the turn, so a
|
|
23
|
+
# non-JSON value raises then. Keys are strings: a symbol key is read and
|
|
24
|
+
# written as its string, and nested hash keys come back as strings after a
|
|
25
|
+
# save.
|
|
26
|
+
class TurnState
|
|
27
|
+
include Enumerable
|
|
28
|
+
|
|
29
|
+
def initialize(data = nil)
|
|
30
|
+
@data = (data || {}).to_h.transform_keys(&:to_s)
|
|
31
|
+
@baseline = fingerprint
|
|
32
|
+
@sealed = false
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
def dirty?
|
|
36
|
+
current = fingerprint
|
|
37
|
+
current.nil? || current != @baseline
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
def empty?
|
|
41
|
+
@data.empty?
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def size
|
|
45
|
+
@data.size
|
|
46
|
+
end
|
|
47
|
+
alias length size
|
|
48
|
+
|
|
49
|
+
def sealed?
|
|
50
|
+
@sealed
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
def seal
|
|
54
|
+
@sealed = true
|
|
55
|
+
self
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# Forces the next save to write this scope.
|
|
59
|
+
def mark_dirty
|
|
60
|
+
@baseline = nil
|
|
61
|
+
self
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
# Marks the current contents as saved; used by the loader.
|
|
65
|
+
def mark_clean
|
|
66
|
+
current = fingerprint
|
|
67
|
+
@baseline = current if current
|
|
68
|
+
self
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
def [](key)
|
|
72
|
+
ensure_active!
|
|
73
|
+
@data[key.to_s]
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
def []=(key, value)
|
|
77
|
+
ensure_active!
|
|
78
|
+
@data[key.to_s] = value
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
def fetch(key, *default, &block)
|
|
82
|
+
ensure_active!
|
|
83
|
+
@data.fetch(key.to_s, *default, &block)
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def delete(key)
|
|
87
|
+
ensure_active!
|
|
88
|
+
@data.delete(key.to_s)
|
|
89
|
+
end
|
|
90
|
+
|
|
91
|
+
def key?(key)
|
|
92
|
+
ensure_active!
|
|
93
|
+
@data.key?(key.to_s)
|
|
94
|
+
end
|
|
95
|
+
alias include? key?
|
|
96
|
+
alias has_key? key?
|
|
97
|
+
alias member? key?
|
|
98
|
+
|
|
99
|
+
def keys
|
|
100
|
+
ensure_active!
|
|
101
|
+
@data.keys
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
def values
|
|
105
|
+
ensure_active!
|
|
106
|
+
@data.values
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
# Iterates over a snapshot, so the scope can be changed while iterating.
|
|
110
|
+
def each(&block)
|
|
111
|
+
ensure_active!
|
|
112
|
+
return enum_for(:each) unless block
|
|
113
|
+
|
|
114
|
+
@data.to_a.each(&block)
|
|
115
|
+
self
|
|
116
|
+
end
|
|
117
|
+
alias each_pair each
|
|
118
|
+
|
|
119
|
+
def clear
|
|
120
|
+
ensure_active!
|
|
121
|
+
@data.clear
|
|
122
|
+
self
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
# A shallow copy of the contents, for serialization. Does not check the
|
|
126
|
+
# seal: the loader serializes a scope just before sealing it.
|
|
127
|
+
def to_h
|
|
128
|
+
@data.dup
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
def inspect
|
|
132
|
+
status = if sealed?
|
|
133
|
+
"sealed"
|
|
134
|
+
else
|
|
135
|
+
dirty? ? "dirty" : "clean"
|
|
136
|
+
end
|
|
137
|
+
"#<#{self.class.name} #{@data.inspect} (#{status})>"
|
|
138
|
+
end
|
|
139
|
+
|
|
140
|
+
private
|
|
141
|
+
|
|
142
|
+
def ensure_active!
|
|
143
|
+
raise TurnStateSealedError, "TurnState has been sealed and can no longer be accessed." if @sealed
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
# Canonical JSON (sorted keys) digest; nil when the contents cannot be
|
|
147
|
+
# encoded, which counts as dirty.
|
|
148
|
+
def fingerprint
|
|
149
|
+
Digest::SHA256.hexdigest(JSON.generate(canonical(@data)))
|
|
150
|
+
rescue JSON::GeneratorError, EncodingError
|
|
151
|
+
nil
|
|
152
|
+
end
|
|
153
|
+
|
|
154
|
+
def canonical(value)
|
|
155
|
+
case value
|
|
156
|
+
when Hash then value.map { |key, item| [key.to_s, canonical(item)] }.sort_by(&:first).to_h
|
|
157
|
+
when Array then value.map { |item| canonical(item) }
|
|
158
|
+
else value
|
|
159
|
+
end
|
|
160
|
+
end
|
|
161
|
+
end
|
|
162
|
+
end
|
|
163
|
+
end
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Teams
|
|
4
|
+
module State
|
|
5
|
+
# The state scopes loaded for one turn, exposed as ctx.state, with the
|
|
6
|
+
# identity they were loaded for. Mirrors the TypeScript, Python, and .NET
|
|
7
|
+
# turn state containers.
|
|
8
|
+
#
|
|
9
|
+
# conversation is always present; user is nil when the activity has no
|
|
10
|
+
# from identity. conversation_id/user_id are fixed at construction so a
|
|
11
|
+
# save always targets the keys the scopes were loaded from.
|
|
12
|
+
class TurnStateContainer
|
|
13
|
+
attr_reader :conversation, :user, :conversation_id, :user_id
|
|
14
|
+
|
|
15
|
+
def initialize(conversation:, conversation_id:, user: nil, user_id: nil, deleter: nil, saver: nil)
|
|
16
|
+
@conversation = conversation
|
|
17
|
+
@conversation_id = conversation_id
|
|
18
|
+
@user = user
|
|
19
|
+
@user_id = user_id
|
|
20
|
+
@deleter = deleter
|
|
21
|
+
@saver = saver
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
# Seals every scope so post-turn access raises.
|
|
25
|
+
def seal
|
|
26
|
+
conversation.seal
|
|
27
|
+
user&.seal
|
|
28
|
+
self
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
# Removes both scopes from storage immediately, then clears them in
|
|
32
|
+
# memory so the rest of the turn sees the deletion.
|
|
33
|
+
def delete
|
|
34
|
+
raise Error, "State deletion is not available: state is not enabled for this app." unless @deleter
|
|
35
|
+
|
|
36
|
+
@deleter.call
|
|
37
|
+
conversation.clear.mark_clean
|
|
38
|
+
user&.clear&.mark_clean
|
|
39
|
+
nil
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
# Persists dirty scopes; called by the app at the end of the turn.
|
|
43
|
+
def save
|
|
44
|
+
@saver&.call(self)
|
|
45
|
+
nil
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
def inspect
|
|
49
|
+
"#<#{self.class.name} conversation=#{conversation.inspect} conversation_id=#{conversation_id.inspect} " \
|
|
50
|
+
"user=#{user.inspect} user_id=#{user_id.inspect}>"
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
end
|
|
54
|
+
end
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
5
|
+
module Teams
|
|
6
|
+
module State
|
|
7
|
+
# Configuration for per-turn state: the backing storage (any object with
|
|
8
|
+
# get/set/delete, like Teams::Storage::MemoryStore; defaults to the app's
|
|
9
|
+
# storage) and the key namespace. Expiry and other storage behavior belong
|
|
10
|
+
# to the storage provider.
|
|
11
|
+
StateOptions = Struct.new(:storage, :key_prefix, keyword_init: true) do
|
|
12
|
+
def initialize(storage: nil, key_prefix: "ts")
|
|
13
|
+
super
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
# Loads and persists TurnState scopes over the storage interface, like the
|
|
18
|
+
# TypeScript, Python, and .NET loaders. Scopes are stored as JSON strings
|
|
19
|
+
# under {prefix}:conv:{conversationId} and
|
|
20
|
+
# {prefix}:user:{conversationId}:{userId}, with each id percent-encoded
|
|
21
|
+
# so distinct ids can never share a key.
|
|
22
|
+
class TurnStateLoader
|
|
23
|
+
UNRESERVED = /[^A-Za-z0-9_.~-]/
|
|
24
|
+
|
|
25
|
+
attr_reader :key_prefix
|
|
26
|
+
|
|
27
|
+
def initialize(storage:, key_prefix: "ts", logger: nil)
|
|
28
|
+
raise ArgumentError, "TurnStateLoader requires a storage backend" unless storage
|
|
29
|
+
|
|
30
|
+
@storage = storage
|
|
31
|
+
@key_prefix = key_prefix
|
|
32
|
+
@logger = logger
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
def conversation_key(conversation_id)
|
|
36
|
+
"#{key_prefix}:conv:#{encode_segment(conversation_id)}"
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def user_key(conversation_id, user_id)
|
|
40
|
+
"#{key_prefix}:user:#{encode_segment(conversation_id)}:#{encode_segment(user_id)}"
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# Loads both scopes; user is nil when user_id is.
|
|
44
|
+
def load(conversation_id, user_id = nil)
|
|
45
|
+
conversation = load_scope(conversation_key(conversation_id))
|
|
46
|
+
user = user_id ? load_scope(user_key(conversation_id, user_id)) : nil
|
|
47
|
+
|
|
48
|
+
TurnStateContainer.new(
|
|
49
|
+
conversation:,
|
|
50
|
+
conversation_id:,
|
|
51
|
+
user:,
|
|
52
|
+
user_id:,
|
|
53
|
+
deleter: -> { delete(conversation_id, user_id) },
|
|
54
|
+
saver: method(:save)
|
|
55
|
+
)
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# Persists dirty scopes under the identity the container was loaded for;
|
|
59
|
+
# dirty scopes that became empty are deleted. Every scope is serialized
|
|
60
|
+
# before any storage write, so an unserializable value cannot leave
|
|
61
|
+
# state half-saved, and scopes are marked clean only after all writes
|
|
62
|
+
# succeed.
|
|
63
|
+
def save(container)
|
|
64
|
+
raise ArgumentError, "TurnStateContainer#conversation_id must be set to save state" if blank?(container.conversation_id)
|
|
65
|
+
if container.user && blank?(container.user_id)
|
|
66
|
+
raise ArgumentError, "TurnStateContainer#user_id must be set to save user state"
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
deletes = []
|
|
70
|
+
sets = []
|
|
71
|
+
clean = []
|
|
72
|
+
prepare(conversation_key(container.conversation_id), container.conversation, deletes, sets, clean)
|
|
73
|
+
if container.user
|
|
74
|
+
prepare(user_key(container.conversation_id, container.user_id), container.user, deletes, sets, clean)
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
deletes.each { |key| @storage.delete(key) }
|
|
78
|
+
sets.each { |key, value| @storage.set(key, value) }
|
|
79
|
+
clean.each(&:mark_clean)
|
|
80
|
+
nil
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
def delete(conversation_id, user_id = nil)
|
|
84
|
+
@storage.delete(conversation_key(conversation_id))
|
|
85
|
+
@storage.delete(user_key(conversation_id, user_id)) if user_id
|
|
86
|
+
nil
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
private
|
|
90
|
+
|
|
91
|
+
def prepare(key, scope, deletes, sets, clean)
|
|
92
|
+
return unless scope.dirty?
|
|
93
|
+
|
|
94
|
+
if scope.empty?
|
|
95
|
+
deletes << key
|
|
96
|
+
else
|
|
97
|
+
sets << [key, JSON.generate(scope.to_h, strict: true)]
|
|
98
|
+
end
|
|
99
|
+
clean << scope
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
def load_scope(key)
|
|
103
|
+
raw = @storage.get(key)
|
|
104
|
+
return TurnState.new if raw.nil?
|
|
105
|
+
|
|
106
|
+
data = deserialize(raw)
|
|
107
|
+
unless data
|
|
108
|
+
@storage.delete(key)
|
|
109
|
+
return TurnState.new
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
TurnState.new(data)
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
# Never raises: unreadable or malformed blobs count as missing. Storage
|
|
116
|
+
# providers that hand back already-parsed hashes are accepted.
|
|
117
|
+
def deserialize(raw)
|
|
118
|
+
parsed = case raw
|
|
119
|
+
when Hash then raw
|
|
120
|
+
when String
|
|
121
|
+
begin
|
|
122
|
+
JSON.parse(raw)
|
|
123
|
+
rescue JSON::ParserError
|
|
124
|
+
@logger&.debug("Discarding unreadable state blob at load")
|
|
125
|
+
return nil
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
return nil unless parsed.is_a?(Hash)
|
|
129
|
+
return nil unless parsed.keys.all?(String)
|
|
130
|
+
|
|
131
|
+
parsed
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
def encode_segment(value)
|
|
135
|
+
value.to_s.b.gsub(UNRESERVED) { |byte| format("%%%02X", byte.ord) }
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
def blank?(value)
|
|
139
|
+
value.nil? || value.to_s.empty?
|
|
140
|
+
end
|
|
141
|
+
end
|
|
142
|
+
end
|
|
143
|
+
end
|
data/lib/teams/state.rb
ADDED
data/lib/teams/version.rb
CHANGED
data/lib/teams.rb
CHANGED
|
@@ -26,10 +26,13 @@ require_relative "teams/api/channel_data"
|
|
|
26
26
|
require_relative "teams/api/activity_value"
|
|
27
27
|
require_relative "teams/api/quoted_reply_entity"
|
|
28
28
|
require_relative "teams/api/sent_activity"
|
|
29
|
+
require_relative "teams/api/sensitivity_usage_info"
|
|
29
30
|
require_relative "teams/api/citation_appearance"
|
|
30
31
|
require_relative "teams/api/task_module"
|
|
31
32
|
require_relative "teams/api/message_extension"
|
|
32
33
|
require_relative "teams/api/search"
|
|
34
|
+
require_relative "teams/api/file_download_info"
|
|
35
|
+
require_relative "teams/files"
|
|
33
36
|
require_relative "teams/activity"
|
|
34
37
|
require_relative "teams/activity_context"
|
|
35
38
|
require_relative "teams/function_context"
|
|
@@ -37,6 +40,8 @@ require_relative "teams/http_stream"
|
|
|
37
40
|
require_relative "teams/router"
|
|
38
41
|
require_relative "teams/response"
|
|
39
42
|
require_relative "teams/storage/memory_store"
|
|
43
|
+
require_relative "teams/state"
|
|
44
|
+
require_relative "teams/oauth"
|
|
40
45
|
require_relative "teams/common/http_client"
|
|
41
46
|
require_relative "teams/api/conversation_reference"
|
|
42
47
|
require_relative "teams/auth/client_secret_credentials"
|