timecs 2.0.0__py3-none-any.whl

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.
Files changed (94) hide show
  1. app.py +3014 -0
  2. ast_scanner.py +36187 -0
  3. banner.py +146 -0
  4. ci_reporter.py +570 -0
  5. cli.py +2347 -0
  6. config_loader.py +307 -0
  7. cross_file_engine.py +1781 -0
  8. delivery_models.py +145 -0
  9. delivery_repository.py +78 -0
  10. diff_scan.py +127 -0
  11. durable_delivery_sink.py +103 -0
  12. event_bus.py +155 -0
  13. event_publisher.py +345 -0
  14. event_taxonomy.py +313 -0
  15. function_summarizer.py +354 -0
  16. html_auditor.py +274 -0
  17. iac_auditor.py +400 -0
  18. in_app_adapter.py +115 -0
  19. js_scanner.py +895 -0
  20. manifest_parser.py +960 -0
  21. master_rules_bank.py +389 -0
  22. notification_models.py +346 -0
  23. notification_policy.py +309 -0
  24. notification_repository.py +118 -0
  25. notification_routes.py +394 -0
  26. notification_service.py +199 -0
  27. osv_client.py +437 -0
  28. remediation/__init__.py +39 -0
  29. remediation/base.py +102 -0
  30. remediation/contracts.py +196 -0
  31. remediation/cwe1188_binding.py +78 -0
  32. remediation/cwe1336_jinja.py +91 -0
  33. remediation/cwe22_path_traversal.py +348 -0
  34. remediation/cwe295_ssl.py +87 -0
  35. remediation/cwe327_weak_hash.py +78 -0
  36. remediation/cwe377_tempfile.py +77 -0
  37. remediation/cwe489_debug.py +80 -0
  38. remediation/cwe502_yaml.py +89 -0
  39. remediation/cwe614_cookie.py +91 -0
  40. remediation/cwe78_cmdi.py +415 -0
  41. remediation/cwe798_credentials.py +153 -0
  42. remediation/cwe89_sqli.py +425 -0
  43. remediation/cwe916_password_hash.py +131 -0
  44. remediation/cwe95_eval.py +77 -0
  45. remediation/dispatcher.py +114 -0
  46. remediation/orchestrator.py +541 -0
  47. remediation/patch_engine.py +213 -0
  48. remediation/verification.py +253 -0
  49. rule_engine.py +1535 -0
  50. sarif_adapter.py +719 -0
  51. sarif_exporter.py +88 -0
  52. sca_reachability/__init__.py +28 -0
  53. sca_reachability/ast_analyzer.py +366 -0
  54. sca_reachability/call_graph.py +203 -0
  55. sca_reachability/contracts.py +365 -0
  56. sca_reachability/dist_import_map.py +46 -0
  57. sca_reachability/engine.py +603 -0
  58. sca_reachability/resolver.py +169 -0
  59. scanners/__init__.py +70 -0
  60. scanners/container_scanner.py +323 -0
  61. scanners/cve_index.py +521 -0
  62. scanners/iac_scanner.py +328 -0
  63. scanners/sbom.py +183 -0
  64. scanners/sca_scanner.py +667 -0
  65. scanners/secret_scanner.py +345 -0
  66. scanners/yaml_lite.py +217 -0
  67. secret_filters.py +435 -0
  68. secret_scanner.py +943 -0
  69. sqlite_delivery_repository.py +277 -0
  70. sqlite_notification_repository.py +441 -0
  71. ssrf_guard.py +276 -0
  72. staged_scanner.py +492 -0
  73. suppression_resolver.py +282 -0
  74. symbol_indexer.py +424 -0
  75. tcs/__init__.py +1 -0
  76. tcs/analysis/__init__.py +1 -0
  77. tcs/analysis/def_use.py +408 -0
  78. tcs/analysis/function_contracts.py +290 -0
  79. tcs/parallel_analyzer.py +276 -0
  80. tcs/parallel_scanner.py +630 -0
  81. tcs/treesitter_packer.py +1446 -0
  82. tcs_cli.py +2086 -0
  83. tcs_config.py +218 -0
  84. tcs_gui.py +2123 -0
  85. timecs-2.0.0.dist-info/METADATA +142 -0
  86. timecs-2.0.0.dist-info/RECORD +94 -0
  87. timecs-2.0.0.dist-info/WHEEL +5 -0
  88. timecs-2.0.0.dist-info/entry_points.txt +4 -0
  89. timecs-2.0.0.dist-info/licenses/LICENSE +201 -0
  90. timecs-2.0.0.dist-info/top_level.txt +49 -0
  91. version_matcher.py +934 -0
  92. webhook_adapter.py +495 -0
  93. webhook_client.py +483 -0
  94. webhook_formatters.py +245 -0
delivery_models.py ADDED
@@ -0,0 +1,145 @@
1
+ """
2
+ TimeCodeSecurity Delivery Audit Models & Schema.
3
+
4
+ Defines the persisted DeliveryAuditLog entity and Pydantic DTOs for Phase 15D.
5
+ Audit records are application-level append-only records.
6
+
7
+ Invariants:
8
+ - Strictly persists delivery telemetry without sensitive payload or secret exposure.
9
+ - Never persists target_ip, webhook secrets, authorization headers, request bodies, or response bodies.
10
+ - error_message is strictly bounded to <= 512 characters.
11
+ - All timestamps represent explicit UTC time.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import datetime
17
+ from typing import Any, Dict, Optional
18
+ from pydantic import BaseModel, Field, validator
19
+
20
+ from sqlalchemy import (
21
+ Column,
22
+ DateTime,
23
+ Float,
24
+ Index,
25
+ Integer,
26
+ String,
27
+ Text,
28
+ )
29
+
30
+ try:
31
+ from app import Base
32
+ except ImportError:
33
+ from sqlalchemy.orm import declarative_base
34
+ Base = declarative_base()
35
+
36
+
37
+ MAX_AUDIT_ERROR_LENGTH: int = 512
38
+
39
+
40
+ class DeliveryAuditLog(Base):
41
+ """
42
+ SQLAlchemy model representing a permanent delivery audit record.
43
+ Application-level append-only: no update or delete operations are permitted.
44
+ """
45
+ __tablename__ = "delivery_audit_logs"
46
+
47
+ id = Column(String(36), primary_key=True, index=True)
48
+ organization_id = Column(Integer, nullable=False, index=True)
49
+ event_id = Column(String(64), nullable=False, index=True)
50
+ scan_id = Column(String(64), nullable=True, index=True)
51
+ idempotency_key = Column(String(64), nullable=False, index=True)
52
+ channel = Column(String(32), nullable=False)
53
+ status = Column(String(64), nullable=False, index=True)
54
+ status_code = Column(Integer, nullable=True)
55
+ attempts = Column(Integer, nullable=False, default=1)
56
+ duration_ms = Column(Float, nullable=False, default=0.0)
57
+ error_message = Column(String(MAX_AUDIT_ERROR_LENGTH), nullable=True)
58
+ created_at = Column(DateTime, nullable=False, default=lambda: datetime.datetime.now(datetime.timezone.utc))
59
+
60
+ __table_args__ = (
61
+ Index("ix_delivery_audit_org_created_id", "organization_id", "created_at", "id"),
62
+ Index("ix_delivery_audit_org_idempotency", "organization_id", "idempotency_key"),
63
+ Index("ix_delivery_audit_org_status", "organization_id", "status"),
64
+ )
65
+
66
+ def to_dict(self) -> Dict[str, Any]:
67
+ """Serializes model attributes into a safe public dictionary."""
68
+ return {
69
+ "id": self.id,
70
+ "organization_id": self.organization_id,
71
+ "event_id": self.event_id,
72
+ "scan_id": self.scan_id,
73
+ "idempotency_key": self.idempotency_key,
74
+ "channel": self.channel,
75
+ "status": self.status,
76
+ "status_code": self.status_code,
77
+ "attempts": self.attempts,
78
+ "duration_ms": self.duration_ms,
79
+ "error_message": self.error_message,
80
+ "created_at": (
81
+ self.created_at.replace(tzinfo=datetime.timezone.utc).isoformat()
82
+ if self.created_at and self.created_at.tzinfo is None
83
+ else self.created_at.isoformat() if self.created_at else None
84
+ ),
85
+ }
86
+
87
+
88
+ class DeliveryAuditLogCreate(BaseModel):
89
+ """Internal DTO for creating a delivery audit log."""
90
+ id: Optional[str] = None
91
+ organization_id: int
92
+ event_id: str
93
+ scan_id: Optional[str] = None
94
+ idempotency_key: str
95
+ channel: str = "WEBHOOK"
96
+ status: str
97
+ status_code: Optional[int] = None
98
+ attempts: int = 1
99
+ duration_ms: float = 0.0
100
+ error_message: Optional[str] = None
101
+ created_at: Optional[datetime.datetime] = None
102
+
103
+ @validator("organization_id")
104
+ def validate_org_id(cls, v: int) -> int:
105
+ if v <= 0:
106
+ raise ValueError("organization_id must be a positive integer.")
107
+ return v
108
+
109
+ @validator("error_message")
110
+ def truncate_error(cls, v: Optional[str]) -> Optional[str]:
111
+ if v and len(v) > MAX_AUDIT_ERROR_LENGTH:
112
+ return v[:MAX_AUDIT_ERROR_LENGTH]
113
+ return v
114
+
115
+
116
+ class DeliveryAuditLogRead(BaseModel):
117
+ """
118
+ Safe public representation of a delivery audit log.
119
+ Strictly excludes target_ip, secrets, request payloads, response bodies, and auth headers.
120
+ """
121
+ id: str
122
+ organization_id: int
123
+ event_id: str
124
+ scan_id: Optional[str] = None
125
+ idempotency_key: str
126
+ channel: str
127
+ status: str
128
+ status_code: Optional[int] = None
129
+ attempts: int
130
+ duration_ms: float
131
+ error_message: Optional[str] = None
132
+ created_at: str
133
+
134
+ class Config:
135
+ from_attributes = True
136
+ orm_mode = True
137
+
138
+
139
+ class DeliveryStatsResponse(BaseModel):
140
+ """Summary statistics for webhook delivery telemetry."""
141
+ organization_id: int
142
+ total_deliveries: int
143
+ success_count: int
144
+ failure_count: int
145
+ average_duration_ms: float
delivery_repository.py ADDED
@@ -0,0 +1,78 @@
1
+ """
2
+ TimeCodeSecurity Delivery Repository Interface.
3
+
4
+ Defines the abstract multi-tenant contract for delivery audit log persistence,
5
+ querying, and telemetry.
6
+
7
+ Invariants:
8
+ - Strictly append-only: no update or delete operations exist.
9
+ - All query operations require strict organization_id scoping.
10
+ - Deterministic pagination strictly orders by created_at DESC, id DESC.
11
+ - Bounded limits (1..100) and validated offsets (>= 0).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from abc import ABC, abstractmethod
17
+ from datetime import datetime
18
+ from typing import Any, List, Optional, Tuple, Union
19
+
20
+ from delivery_models import (
21
+ DeliveryAuditLog,
22
+ DeliveryAuditLogCreate,
23
+ DeliveryStatsResponse,
24
+ )
25
+
26
+
27
+ class DeliveryRepository(ABC):
28
+ """
29
+ Abstract append-only interface for delivery audit storage.
30
+ Enforces tenant isolation and immutable audit retention.
31
+ """
32
+
33
+ @abstractmethod
34
+ def create(self, record: Union[DeliveryAuditLogCreate, Any, dict]) -> DeliveryAuditLog:
35
+ """
36
+ Appends a new delivery audit record.
37
+ Strictly append-only; existing records cannot be modified.
38
+ """
39
+ pass
40
+
41
+ @abstractmethod
42
+ def get_by_id(
43
+ self,
44
+ delivery_id: str,
45
+ organization_id: int,
46
+ ) -> Optional[DeliveryAuditLog]:
47
+ """
48
+ Retrieves a single delivery audit record enforcing organization scope.
49
+ Returns None if not found or if belonging to another organization.
50
+ """
51
+ pass
52
+
53
+ @abstractmethod
54
+ def list(
55
+ self,
56
+ organization_id: int,
57
+ status: Optional[str] = None,
58
+ limit: int = 50,
59
+ offset: int = 0,
60
+ ) -> Tuple[List[DeliveryAuditLog], int]:
61
+ """
62
+ Lists delivery audit logs with deterministic ordering:
63
+ ORDER BY created_at DESC, id DESC.
64
+ Enforces organization boundary, limit (1..100), and offset (>= 0).
65
+ Returns a tuple of (items, total_count).
66
+ """
67
+ pass
68
+
69
+ @abstractmethod
70
+ def get_stats(
71
+ self,
72
+ organization_id: int,
73
+ since: Optional[datetime] = None,
74
+ ) -> DeliveryStatsResponse:
75
+ """
76
+ Computes delivery statistics for an organization since an optional timestamp.
77
+ """
78
+ pass
diff_scan.py ADDED
@@ -0,0 +1,127 @@
1
+ """Working-tree-versus-ref line intervals for `tcs scan --diff`.
2
+
3
+ Only added/modified line numbers are returned. A finding survives the diff filter when its
4
+ file changed and its own line sits inside a `+` hunk; an untracked file counts as entirely new.
5
+ Analysis still runs over the whole tree, so cross-file context is never truncated -- the diff
6
+ narrows what is *reported*, not what is *seen*.
7
+ """
8
+
9
+ import re
10
+ import subprocess
11
+ import sys
12
+ from pathlib import Path
13
+ from typing import Dict, List, Optional, Tuple
14
+
15
+ _HUNK_HEADER = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
16
+ _BINARY_PREFIX_BYTES = 8192
17
+
18
+
19
+ def resolve_repo_root(start: Optional[Path] = None) -> Path:
20
+ """The enclosing git repository root, or ValueError outside a repository."""
21
+ cwd = str(start) if start is not None else None
22
+ try:
23
+ result = subprocess.run(
24
+ ["git", "rev-parse", "--show-toplevel"],
25
+ cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False,
26
+ )
27
+ except OSError as exc:
28
+ raise ValueError(f"--diff requires git on PATH: {exc}") from exc
29
+ toplevel = result.stdout.decode("utf-8", errors="replace").strip()
30
+ if result.returncode != 0 or not toplevel:
31
+ raise ValueError("--diff requires a git repository (git rev-parse --show-toplevel failed)")
32
+ return Path(toplevel)
33
+
34
+
35
+ def _run_git(repo_root: Path, args: List[str]) -> bytes:
36
+ result = subprocess.run(
37
+ ["git", *args],
38
+ cwd=str(repo_root), stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False,
39
+ )
40
+ if result.returncode != 0:
41
+ detail = result.stderr.decode("utf-8", errors="replace").strip()
42
+ raise ValueError(f"git {' '.join(args)} failed: {detail}")
43
+ return result.stdout
44
+
45
+
46
+ def _decode_paths(raw: bytes) -> List[str]:
47
+ return [part.decode("utf-8", errors="replace")
48
+ for part in raw.split(b"\x00") if part]
49
+
50
+
51
+ def added_intervals_from_patch(patch: str) -> List[Tuple[int, int]]:
52
+ """`+` line spans of one unified diff, parsed from its `@@` hunk headers.
53
+
54
+ A hunk whose new-side count is 0 (`+c,0`) is a pure deletion: it adds no line, so it
55
+ contributes no interval.
56
+ """
57
+ intervals: List[Tuple[int, int]] = []
58
+ for line in patch.splitlines():
59
+ match = _HUNK_HEADER.match(line)
60
+ if not match:
61
+ continue
62
+ start = int(match.group(1))
63
+ count = int(match.group(2)) if match.group(2) is not None else 1
64
+ if count > 0:
65
+ intervals.append((start, start + count - 1))
66
+ return intervals
67
+
68
+
69
+ def _line_count(path: Path) -> int:
70
+ try:
71
+ raw = path.read_bytes()
72
+ except OSError:
73
+ return 0
74
+ if b"\x00" in raw[:_BINARY_PREFIX_BYTES]:
75
+ return 0
76
+ if not raw:
77
+ return 0
78
+ count = raw.count(b"\n")
79
+ return count if raw.endswith(b"\n") else count + 1
80
+
81
+
82
+ def changed_line_intervals(repo_root: Path, ref: str = "HEAD") -> Dict[str, List[Tuple[int, int]]]:
83
+ """Map repo-relative POSIX path -> added/modified 1-indexed intervals versus `ref`.
84
+
85
+ `git diff <ref>` compares the commit with the working tree (staged and unstaged alike).
86
+ Deleted files carry no lines to report and are filtered out; untracked files are all new.
87
+ """
88
+ verify = subprocess.run(
89
+ ["git", "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}"],
90
+ cwd=str(repo_root), stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False,
91
+ )
92
+ if verify.returncode != 0:
93
+ raise ValueError(f"Unknown git ref: {ref}")
94
+
95
+ tracked = _decode_paths(_run_git(
96
+ repo_root, ["diff", "--name-only", "-z", "--diff-filter=d", ref, "--"]))
97
+ untracked = _decode_paths(_run_git(
98
+ repo_root, ["ls-files", "--others", "--exclude-standard", "-z"]))
99
+
100
+ intervals: Dict[str, List[Tuple[int, int]]] = {}
101
+ for rel_path in tracked:
102
+ patch = _run_git(repo_root, ["diff", "-U0", ref, "--", rel_path])
103
+ spans = added_intervals_from_patch(patch.decode("utf-8", errors="replace"))
104
+ if spans:
105
+ intervals[rel_path] = spans
106
+ for rel_path in untracked:
107
+ lines = _line_count(repo_root / rel_path)
108
+ if lines:
109
+ intervals[rel_path] = [(1, lines)]
110
+ return intervals
111
+
112
+
113
+ def main() -> int:
114
+ """Print the intervals for one ref, for manual inspection."""
115
+ ref = sys.argv[1] if len(sys.argv) > 1 else "HEAD"
116
+ try:
117
+ intervals = changed_line_intervals(resolve_repo_root(), ref)
118
+ except ValueError as exc:
119
+ print(f"error: {exc}", file=sys.stderr)
120
+ return 2
121
+ for path in sorted(intervals):
122
+ print(f"{path}: {intervals[path]}")
123
+ return 0
124
+
125
+
126
+ if __name__ == "__main__":
127
+ sys.exit(main())
@@ -0,0 +1,103 @@
1
+ """
2
+ TimeCodeSecurity Durable Delivery Result Sink.
3
+
4
+ Bridges Phase 15C webhook execution to persistent relational storage (delivery_audit_logs)
5
+ while preserving live diagnostic telemetry in InMemoryDeliveryResultSink.
6
+
7
+ Invariants:
8
+ - Thread-safe for concurrent worker threads.
9
+ - Obtains a fresh independent SQLAlchemy session for each persistence operation.
10
+ - Never shares sessions across workers or with FastAPI/scanner threads.
11
+ - Audit persistence failure is decoupled from webhook delivery:
12
+ - Errors are logged with bounded diagnostic text.
13
+ - In-memory result is safely retained.
14
+ - Webhook is NEVER retried due to an audit write failure.
15
+ - Original DeliveryResult status is NEVER mutated.
16
+ - Worker threads NEVER terminate due to audit database failure.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import logging
22
+ import threading
23
+ from typing import Callable, List, Optional
24
+
25
+ from sqlalchemy.orm import Session, sessionmaker
26
+
27
+ from delivery_models import DeliveryAuditLog
28
+ from sqlite_delivery_repository import SqliteDeliveryRepository
29
+ from webhook_adapter import DeliveryResult, InMemoryDeliveryResultSink
30
+
31
+ logger = logging.getLogger("tcs.durable_delivery_sink")
32
+
33
+
34
+ class DurableDeliveryResultSink:
35
+ """
36
+ Composite sink that records results to in-memory telemetry and
37
+ persistently writes audit records to the database.
38
+ """
39
+
40
+ def __init__(
41
+ self,
42
+ session_factory: Optional[Callable[[], Session]] = None,
43
+ memory_sink: Optional[InMemoryDeliveryResultSink] = None,
44
+ repository_factory: Optional[Callable[[Session], SqliteDeliveryRepository]] = None,
45
+ ) -> None:
46
+ self._session_factory = session_factory
47
+ self._memory_sink = memory_sink or InMemoryDeliveryResultSink()
48
+ self._repository_factory = repository_factory or (lambda s: SqliteDeliveryRepository(session=s))
49
+ self._db_lock = threading.Lock()
50
+
51
+ @property
52
+ def memory_sink(self) -> InMemoryDeliveryResultSink:
53
+ return self._memory_sink
54
+
55
+ def record(self, result: DeliveryResult) -> None:
56
+ """
57
+ Records the delivery result into memory and persists to the database.
58
+ Failures in database persistence are isolated and do NOT alter delivery status.
59
+ """
60
+ # 1. Non-failing in-memory record
61
+ try:
62
+ self._memory_sink.record(result)
63
+ except Exception as exc:
64
+ logger.error("Failed to record delivery result in memory sink: %s", str(exc)[:200])
65
+
66
+ # 2. Synchronous worker-local DB persistence with independent session
67
+ if self._session_factory is not None:
68
+ session: Optional[Session] = None
69
+ try:
70
+ with self._db_lock:
71
+ session = self._session_factory()
72
+ repo = self._repository_factory(session)
73
+ repo.create(result)
74
+ session.commit()
75
+ except Exception as exc:
76
+ if session is not None:
77
+ try:
78
+ session.rollback()
79
+ except Exception:
80
+ pass
81
+ logger.error(
82
+ "Failed to persist delivery audit log for event_id=%s idempotency_key=%s: %s",
83
+ result.event_id,
84
+ result.idempotency_key,
85
+ str(exc)[:200],
86
+ )
87
+ # Webhook delivery is NOT retried.
88
+ # DeliveryResult is NOT mutated.
89
+ # Worker thread does NOT terminate.
90
+ finally:
91
+ if session is not None:
92
+ try:
93
+ session.close()
94
+ except Exception:
95
+ pass
96
+
97
+ def get_recent(self) -> List[DeliveryResult]:
98
+ """Delegates to internal memory sink for live telemetry."""
99
+ return self._memory_sink.get_recent()
100
+
101
+ def clear(self) -> None:
102
+ """Delegates to internal memory sink."""
103
+ self._memory_sink.clear()
event_bus.py ADDED
@@ -0,0 +1,155 @@
1
+ """
2
+ TimeCodeSecurity In-Memory Synchronous Event Bus.
3
+
4
+ Provides deterministic, insertion-ordered FIFO event dispatch with
5
+ strict subscriber failure isolation.
6
+
7
+ Invariants:
8
+ - Synchronous and deterministic FIFO invocation ordering.
9
+ - Subscriber failure isolation: exceptions in one subscriber never abort
10
+ dispatch to subsequent subscribers or bubble up to fail security scans.
11
+ - Catches standard Exception (never BaseException).
12
+ - Structured DispatchResult captures execution telemetry and error states.
13
+ - Zero network, database, or notification delivery dependencies.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import logging
19
+ import time
20
+ import uuid
21
+ from dataclasses import dataclass
22
+ from typing import Callable, Optional, List, Tuple, Any
23
+
24
+ from event_taxonomy import SecurityDomainEvent, EventType
25
+
26
+ logger = logging.getLogger("tcs.event_bus")
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class SubscriptionHandle:
31
+ """Opaque handle representing an active subscription."""
32
+ id: str
33
+ event_type: Optional[EventType]
34
+ name: str
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class DispatchResult:
39
+ """Result telemetry for a single subscriber dispatch attempt."""
40
+ handle_id: str
41
+ subscriber_name: str
42
+ event_type: EventType
43
+ status: str # "SUCCESS" or "FAILED"
44
+ error: Optional[str] = None
45
+ duration_ms: float = 0.0
46
+
47
+
48
+ class InMemoryEventBus:
49
+ """
50
+ Synchronous in-memory event dispatcher.
51
+ Preserves strict insertion-ordered (FIFO) subscriber execution.
52
+ """
53
+
54
+ def __init__(self) -> None:
55
+ self._subscribers: List[Tuple[SubscriptionHandle, Callable[[SecurityDomainEvent], None]]] = []
56
+
57
+ def subscribe(
58
+ self,
59
+ handler: Callable[[SecurityDomainEvent], None],
60
+ event_type: Optional[EventType] = None,
61
+ name: Optional[str] = None
62
+ ) -> SubscriptionHandle:
63
+ """
64
+ Registers a subscriber handler with optional event-type filtering.
65
+ Subscribers are invoked in exact FIFO registration order.
66
+ """
67
+ if not callable(handler):
68
+ raise TypeError("Subscriber handler must be a callable.")
69
+
70
+ if event_type is not None and not isinstance(event_type, EventType):
71
+ if isinstance(event_type, str):
72
+ event_type = EventType(event_type)
73
+ else:
74
+ raise ValueError(f"Invalid event_type filter: {event_type}")
75
+
76
+ subscriber_name = name or getattr(handler, "__name__", "anonymous_subscriber")
77
+ handle = SubscriptionHandle(
78
+ id=f"sub_{uuid.uuid4().hex[:12]}",
79
+ event_type=event_type,
80
+ name=subscriber_name
81
+ )
82
+ self._subscribers.append((handle, handler))
83
+ return handle
84
+
85
+ def unsubscribe(self, handle: SubscriptionHandle) -> bool:
86
+ """
87
+ Safely removes a subscriber by its handle.
88
+ Returns True if removed, False if not found.
89
+ """
90
+ initial_len = len(self._subscribers)
91
+ self._subscribers = [
92
+ (h, fn) for (h, fn) in self._subscribers if h.id != handle.id
93
+ ]
94
+ return len(self._subscribers) < initial_len
95
+
96
+ def publish(self, event: SecurityDomainEvent) -> List[DispatchResult]:
97
+ """
98
+ Dispatches an event synchronously to all matching subscribers in FIFO order.
99
+ Isolates all subscriber errors and returns structured dispatch results.
100
+ """
101
+ if not isinstance(event, SecurityDomainEvent):
102
+ raise TypeError(f"Expected SecurityDomainEvent instance, got {type(event).__name__}")
103
+
104
+ dispatch_results: List[DispatchResult] = []
105
+
106
+ for handle, handler in list(self._subscribers):
107
+ # Check event-type filter
108
+ if handle.event_type is not None and handle.event_type != event.event_type:
109
+ continue
110
+
111
+ t0 = time.perf_counter()
112
+ try:
113
+ handler(event)
114
+ duration_ms = round((time.perf_counter() - t0) * 1000.0, 3)
115
+ dispatch_results.append(
116
+ DispatchResult(
117
+ handle_id=handle.id,
118
+ subscriber_name=handle.name,
119
+ event_type=event.event_type,
120
+ status="SUCCESS",
121
+ duration_ms=duration_ms
122
+ )
123
+ )
124
+ except Exception as exc:
125
+ duration_ms = round((time.perf_counter() - t0) * 1000.0, 3)
126
+ error_summary = f"{type(exc).__name__}: {str(exc)}"
127
+ logger.error(
128
+ "Subscriber '%s' failed processing event %s [%s]: %s",
129
+ handle.name, event.event_id, event.event_type.value, error_summary
130
+ )
131
+ dispatch_results.append(
132
+ DispatchResult(
133
+ handle_id=handle.id,
134
+ subscriber_name=handle.name,
135
+ event_type=event.event_type,
136
+ status="FAILED",
137
+ error=error_summary,
138
+ duration_ms=duration_ms
139
+ )
140
+ )
141
+
142
+ return dispatch_results
143
+
144
+ def clear(self) -> None:
145
+ """Removes all registered subscribers."""
146
+ self._subscribers.clear()
147
+
148
+ def subscriber_count(self, event_type: Optional[EventType] = None) -> int:
149
+ """Returns the count of registered subscribers matching event_type filter."""
150
+ if event_type is None:
151
+ return len(self._subscribers)
152
+ return sum(
153
+ 1 for (h, _) in self._subscribers
154
+ if h.event_type is None or h.event_type == event_type
155
+ )