Coverage for src/copytrading_engine/trading/adapters/capabilities.py: 85%
227 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
1"""Read-only connection checks required before a saved trading revision is activated."""
3import asyncio
4import difflib
5import logging
6from collections.abc import Awaitable, Callable
7from typing import Literal, Protocol
9import discord
10import httpx
11from pydantic import BaseModel, ConfigDict, SecretStr
13from copytrading_engine.execution.adapters.alpaca.broker import AlpacaBroker, AlpacaCredentials
14from copytrading_engine.parsing.providers.registry import ManagedDecoder, builtin_registry
15from copytrading_engine.parsing.readiness import ModelReadiness, probe_model
16from copytrading_engine.shared.cleanup import close_logged
17from copytrading_engine.sources.source import require_history_channel
18from copytrading_engine.trading.adapters.notifications import discord_webhook
19from copytrading_engine.trading.domain.config import (
20 AccountConfiguration,
21 BrokerCheck,
22 BrokerCredentials,
23 ConnectionCheck,
24 ModelCheck,
25 NotificationCheck,
26 NotificationConfiguration,
27 ProviderConfiguration,
28 SourceCheck,
29 SourceConfiguration,
30 TradingConfiguration,
31 TradingSecrets,
32)
34log = logging.getLogger(__name__)
36type CapabilityState = Literal["ready", "failed", "not_configured"]
37type CapabilityName = Literal["source", "model", "broker", "notification", "configuration"]
40class CapabilityCheck(BaseModel):
41 """Safe identity and permission evidence; never carries submitted credentials."""
43 model_config = ConfigDict(extra="forbid", frozen=True)
45 name: CapabilityName
46 state: CapabilityState
47 subject: str | None = None
48 environment: Literal["paper", "live"] | None = None
49 identity: str | None = None
50 adapter: str
51 reason_code: str | None = None
52 # A close name the provider lists, when the model asked for does not exist.
53 suggestion: str | None = None
54 # The stocks a configuration check is about, such as those a removed account still holds.
55 symbols: tuple[str, ...] = ()
58class TradingCapabilityReport(BaseModel):
59 model_config = ConfigDict(extra="forbid", frozen=True)
61 configuration_revision: str
62 activatable: bool
63 checks: tuple[CapabilityCheck, ...]
64 cost_notice: str
67class CapabilityProbes(Protocol):
68 async def source(self, configuration: SourceConfiguration, token: str) -> CapabilityCheck: ...
70 async def model(self, configuration: ProviderConfiguration, token: str) -> CapabilityCheck: ...
72 async def broker(
73 self, account: AccountConfiguration, credentials: BrokerCredentials
74 ) -> CapabilityCheck: ...
76 async def notification(
77 self, configuration: NotificationConfiguration | None, token: str | None
78 ) -> CapabilityCheck: ...
81def _refused_keys_reason(account: AccountConfiguration, credentials: BrokerCredentials) -> str:
82 """Why keys the chosen environment refused were refused. Alpaca serves paper and live from
83 separate servers that each accept only their own keys, so keys the other server accepts (one
84 read-only account read) are that environment's keys: "broker_keys_are_paper" or
85 "broker_keys_are_live". Otherwise the keys are simply refused."""
86 other = "live" if account.environment == "paper" else "paper"
87 broker = None
88 try:
89 broker = AlpacaBroker(AlpacaCredentials(credentials.key, credentials.secret), other)
90 broker.account()
91 except Exception: # noqa: BLE001 - refused on both servers, or unreachable
92 return "broker_auth_or_permissions_failed"
93 finally:
94 if broker is not None: 94 ↛ 96line 94 didn't jump to line 96 because the condition on line 94 was always true
95 broker.close()
96 return f"broker_keys_are_{other}"
99def _failed(
100 name: CapabilityName,
101 code: str,
102 *,
103 subject: str | None = None,
104 environment: Literal["paper", "live"] | None = None,
105 adapter: str = "connection_probe",
106 suggestion: str | None = None,
107) -> CapabilityCheck:
108 return CapabilityCheck(
109 name=name,
110 state="failed",
111 subject=subject,
112 environment=environment,
113 identity=None,
114 adapter=adapter,
115 reason_code=code,
116 suggestion=suggestion,
117 )
120async def _closest_model(decoder: ManagedDecoder, asked: str) -> str | None:
121 """The listed model name nearest to a mistyped one, or nothing when the list is unavailable."""
122 try:
123 names = await asyncio.wait_for(decoder.model_names(), timeout=15)
124 except asyncio.CancelledError:
125 raise
126 except Exception: # noqa: BLE001 - a missing list only means no suggestion
127 return None
128 matches = difflib.get_close_matches(asked, names, n=1, cutoff=0.6)
129 return matches[0] if matches else None
132async def _safely(
133 name: CapabilityName,
134 operation: Awaitable[CapabilityCheck],
135 *,
136 subject: str | None = None,
137 environment: Literal["paper", "live"] | None = None,
138) -> CapabilityCheck:
139 try:
140 return await operation
141 except asyncio.CancelledError:
142 raise
143 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check
144 return _failed(
145 name, f"{name}_capability_unavailable", subject=subject, environment=environment
146 )
149class TradingCapabilityService:
150 """Run source, provider, broker, and notification checks without saving config."""
152 def __init__(self, probes: CapabilityProbes | None = None) -> None:
153 self._probes = probes or NativeCapabilityProbes()
155 async def validate(
156 self, configuration: TradingConfiguration, secrets: TradingSecrets
157 ) -> TradingCapabilityReport:
158 configuration = TradingConfiguration.model_validate(configuration.model_dump())
159 secrets = TradingSecrets.model_validate(secrets.model_dump())
160 by_account = {credential.account_id: credential for credential in secrets.brokers}
161 account_ids = {account.id for account in configuration.accounts}
162 checks: list[CapabilityCheck] = []
163 # An account without keys fails its own broker check below; keys for an account the
164 # setup doesn't have are named here, once each.
165 checks.extend(
166 _failed("configuration", "broker_keys_without_account", subject=account_id)
167 for account_id in sorted(set(by_account) - account_ids)
168 )
170 operations = [
171 _safely(
172 "source",
173 self._probes.source(configuration.source, secrets.discord_token.get_secret_value()),
174 ),
175 _safely(
176 "model",
177 self._probes.model(
178 configuration.provider, secrets.provider_api_key.get_secret_value()
179 ),
180 ),
181 _safely(
182 "notification",
183 self._probes.notification(
184 configuration.notification,
185 secrets.notification_token.get_secret_value()
186 if secrets.notification_token is not None
187 else None,
188 ),
189 ),
190 ]
191 for account in configuration.accounts:
192 credentials = by_account.get(account.id)
193 if credentials is None:
194 operations.append(
195 asyncio.sleep(
196 0,
197 result=_failed(
198 "broker",
199 "broker_credentials_missing",
200 subject=account.id,
201 environment=account.environment,
202 ),
203 )
204 )
205 else:
206 operations.append(
207 _safely(
208 "broker",
209 self._probes.broker(account, credentials),
210 subject=account.id,
211 environment=account.environment,
212 )
213 )
214 checks.extend(await asyncio.gather(*operations))
215 activatable = all(check.state in {"ready", "not_configured"} for check in checks)
216 return TradingCapabilityReport(
217 configuration_revision=configuration.revision(),
218 activatable=activatable,
219 checks=tuple(checks),
220 cost_notice=(
221 "Model validation sends one short no-trade prompt to the configured provider; "
222 "provider charges may apply. Notification validation checks bot/chat access "
223 "without sending a message."
224 ),
225 )
227 async def check(self, connection: ConnectionCheck) -> CapabilityCheck:
228 """One service, the moment the owner connects it: the same read-only check a full
229 validation runs for it, without saving anything or granting a start."""
230 match connection:
231 case SourceCheck():
232 return await _safely(
233 "source",
234 self._probes.source(connection.source, connection.token.get_secret_value()),
235 )
236 case ModelCheck():
237 return await _safely(
238 "model",
239 self._probes.model(connection.provider, connection.api_key.get_secret_value()),
240 )
241 case BrokerCheck():
242 account = connection.account
243 return await _safely(
244 "broker",
245 self._probes.broker(account, connection.credentials),
246 subject=account.id,
247 environment=account.environment,
248 )
249 case NotificationCheck(): 249 ↛ exitline 249 didn't return from function 'check' because the pattern on line 249 always matched
250 return await _safely(
251 "notification",
252 self._probes.notification(
253 connection.notification, connection.token.get_secret_value()
254 ),
255 )
258class NativeCapabilityProbes:
259 """Actual read-only adapters used by the desktop engine."""
261 def __init__(
262 self,
263 *,
264 discord_client_factory: Callable[..., discord.Client] = discord.Client,
265 http_client_factory: Callable[..., httpx.AsyncClient] = httpx.AsyncClient,
266 source_timeout_seconds: float = 20,
267 ) -> None:
268 if source_timeout_seconds <= 0: 268 ↛ 269line 268 didn't jump to line 269 because the condition on line 268 was never true
269 raise ValueError("Source probe timeout must be positive")
270 self._discord_client_factory = discord_client_factory
271 self._http_client_factory = http_client_factory
272 self._source_timeout_seconds = source_timeout_seconds
274 async def source(self, configuration: SourceConfiguration, token: str) -> CapabilityCheck:
275 # discord.py-self does not expose discord.Intents. Its documented client
276 # defaults are also what the existing DiscordSession adapter uses.
277 client = self._discord_client_factory()
278 stage = "login"
279 try:
280 async with asyncio.timeout(self._source_timeout_seconds):
281 await client.login(token)
282 user = client.user
283 if user is None: 283 ↛ 284line 283 didn't jump to line 284 because the condition on line 283 was never true
284 return _failed("source", "source_identity_unavailable")
285 for channel_id in configuration.channel_ids:
286 stage = "channel"
287 channel = await client.fetch_channel(int(channel_id))
288 try:
289 readable = require_history_channel(channel)
290 except ValueError:
291 return _failed("source", "source_channel_not_readable")
292 stage = "history"
293 history = readable.history(limit=1)
294 try:
295 await anext(history, None)
296 finally:
297 close = getattr(history, "aclose", None)
298 if close is not None: 298 ↛ 285line 298 didn't jump to line 285 because the condition on line 298 was always true
299 await close()
300 return CapabilityCheck(
301 name="source",
302 state="ready",
303 identity=f"discord_user:{user.id}",
304 adapter="discord-py-self-user-token",
305 reason_code=None,
306 )
307 except asyncio.CancelledError:
308 raise
309 except TimeoutError:
310 reason = (
311 "source_history_probe_timed_out" if stage == "history" else "source_probe_timed_out"
312 )
313 return _failed("source", reason)
314 except discord.Forbidden:
315 reason = (
316 "source_history_permission_denied"
317 if stage == "history"
318 else "source_channel_access_denied"
319 )
320 return _failed("source", reason)
321 except discord.HTTPException:
322 reason = (
323 "source_history_read_failed"
324 if stage == "history"
325 else "source_auth_or_channel_access"
326 )
327 return _failed("source", reason)
328 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check
329 reason = (
330 "source_history_read_failed"
331 if stage == "history"
332 else "source_auth_or_channel_access"
333 )
334 return _failed("source", reason)
335 finally:
336 await close_logged(client.close, resource="source_probe", log=log)
338 async def model(self, configuration: ProviderConfiguration, token: str) -> CapabilityCheck:
339 decoder = None
340 try:
341 decoder = await builtin_registry().create(
342 configuration.name,
343 configuration.reader(SecretStr(token), timeout=20),
344 )
345 health = ModelReadiness()
346 await asyncio.wait_for(probe_model(decoder, health), timeout=25)
347 if health.error == "provider_key_rejected":
348 return _failed("model", "model_key_rejected", adapter=configuration.name)
349 if health.error == "provider_model_not_found":
350 return _failed(
351 "model",
352 "model_not_found",
353 adapter=configuration.name,
354 suggestion=await _closest_model(decoder, configuration.model),
355 )
356 if health.error in {"provider_unavailable", "provider_timeout"}:
357 return _failed("model", "model_unreachable", adapter=configuration.name)
358 if not health.ready:
359 return _failed("model", "model_probe_rejected", adapter=configuration.name)
360 return CapabilityCheck(
361 name="model",
362 state="ready",
363 identity=f"{configuration.name}:{configuration.model}",
364 adapter=configuration.name,
365 reason_code=None,
366 )
367 except asyncio.CancelledError:
368 raise
369 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check
370 return _failed("model", "model_auth_or_probe_failed", adapter=configuration.name)
371 finally:
372 if decoder is not None:
373 await close_logged(decoder.close, resource="model_probe", log=log)
375 async def broker(
376 self, account: AccountConfiguration, credentials: BrokerCredentials
377 ) -> CapabilityCheck:
378 return await asyncio.to_thread(self._broker_read, account, credentials)
380 @staticmethod
381 def _broker_read(
382 account: AccountConfiguration, credentials: BrokerCredentials
383 ) -> CapabilityCheck:
384 broker = None
385 try:
386 broker = AlpacaBroker(
387 AlpacaCredentials(credentials.key, credentials.secret), account.environment
388 )
389 identity = broker.account()
390 if not identity.active: 390 ↛ 391line 390 didn't jump to line 391 because the condition on line 390 was never true
391 return _failed(
392 "broker",
393 "broker_account_not_tradeable",
394 subject=account.id,
395 environment=account.environment,
396 adapter="alpaca_read_only",
397 )
398 broker.positions()
399 broker.open_orders()
400 return CapabilityCheck(
401 name="broker",
402 state="ready",
403 subject=account.id,
404 environment=account.environment,
405 identity=identity.id,
406 adapter="alpaca_read_only",
407 reason_code=None,
408 )
409 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check
410 return _failed(
411 "broker",
412 _refused_keys_reason(account, credentials),
413 subject=account.id,
414 environment=account.environment,
415 adapter="alpaca_read_only",
416 )
417 finally:
418 if broker is not None:
419 broker.close()
421 async def notification(
422 self, configuration: NotificationConfiguration | None, token: str | None
423 ) -> CapabilityCheck:
424 if configuration is None: 424 ↛ 425line 424 didn't jump to line 425 because the condition on line 424 was never true
425 return CapabilityCheck(
426 name="notification",
427 state="not_configured",
428 adapter="not_configured",
429 reason_code=None,
430 )
431 if token is None or not token: 431 ↛ 432line 431 didn't jump to line 432 because the condition on line 431 was never true
432 return _failed("notification", "notification_credentials_missing")
433 if configuration.service == "discord":
434 return await self._discord_webhook(token)
435 try:
436 async with self._http_client_factory(timeout=8, follow_redirects=False) as client:
437 base = f"https://api.telegram.org/bot{token}"
438 async with asyncio.timeout(10):
439 bot_response = await client.get(f"{base}/getMe")
440 bot_response.raise_for_status()
441 bot_body = bot_response.json()
442 if not isinstance(bot_body, dict) or bot_body.get("ok") is not True: 442 ↛ 443line 442 didn't jump to line 443 because the condition on line 442 was never true
443 return _failed("notification", "notification_bot_identity_failed")
444 chat_response = await client.get(
445 f"{base}/getChat", params={"chat_id": configuration.chat_id}
446 )
447 chat_response.raise_for_status()
448 chat_body = chat_response.json()
449 if not isinstance(chat_body, dict) or chat_body.get("ok") is not True: 449 ↛ 450line 449 didn't jump to line 450 because the condition on line 449 was never true
450 return _failed("notification", "notification_chat_access_failed")
451 bot = bot_body.get("result")
452 chat = chat_body.get("result")
453 if not isinstance(bot, dict) or not isinstance(chat, dict): 453 ↛ 454line 453 didn't jump to line 454 because the condition on line 453 was never true
454 return _failed("notification", "notification_identity_invalid")
455 username = bot.get("username")
456 chat_id = chat.get("id")
457 if not isinstance(username, str) or type(chat_id) not in {int, str}: 457 ↛ 458line 457 didn't jump to line 458 because the condition on line 457 was never true
458 return _failed("notification", "notification_identity_invalid")
459 return CapabilityCheck(
460 name="notification",
461 state="ready",
462 identity=f"telegram_bot:@{username};chat:{chat_id}",
463 adapter="telegram_read_only",
464 reason_code=None,
465 )
466 except asyncio.CancelledError:
467 raise
468 except Exception: # noqa: BLE001 - any client failure becomes a failed capability check
469 return _failed("notification", "notification_auth_or_chat_access_failed")
471 async def _discord_webhook(self, url: str) -> CapabilityCheck:
472 """Reads the webhook's name and channel, which Discord answers without posting anything."""
473 adapter = "discord_webhook_read_only"
474 try:
475 host, path = discord_webhook(url)
476 except ValueError:
477 return _failed("notification", "notification_webhook_invalid", adapter=adapter)
478 try:
479 async with self._http_client_factory(timeout=8, follow_redirects=False) as client:
480 async with asyncio.timeout(10):
481 response = await client.get(f"https://{host}{path}")
482 response.raise_for_status()
483 body = response.json()
484 except asyncio.CancelledError:
485 raise
486 except Exception: # noqa: BLE001 - the URL is the secret, so no detail is kept
487 return _failed("notification", "notification_webhook_unreachable", adapter=adapter)
488 name = body.get("name") if isinstance(body, dict) else None
489 channel = body.get("channel_id") if isinstance(body, dict) else None
490 if not isinstance(name, str) or not isinstance(channel, str): 490 ↛ 491line 490 didn't jump to line 491 because the condition on line 490 was never true
491 return _failed("notification", "notification_identity_invalid", adapter=adapter)
492 return CapabilityCheck(
493 name="notification",
494 state="ready",
495 identity=f"discord_webhook:{name};channel:{channel}",
496 adapter=adapter,
497 reason_code=None,
498 )