Coverage for src/copytrading_engine/host/installation.py: 81%
132 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"""Single-engine ownership and the persisted identity of one installation's database."""
3import fcntl
4import os
5import sqlite3
6import uuid
7from pathlib import Path
8from types import TracebackType
9from typing import Self
11from copytrading_engine.host.errors import (
12 ForeignInstallation,
13 InstallationAlreadyRunning,
14 InvalidCommand,
15 StoreClosed,
16 StoreUnavailable,
17 UnknownSchemaVersion,
18)
19from copytrading_engine.shared.sqlite import (
20 SchemaComponent,
21 SchemaMismatch,
22 ensure_schema,
23 verify_schema,
24)
26APPLICATION_DATABASE_VERSION = 3
27"""`PRAGMA user_version` of application.db; the app compares it before accepting an update."""
29INSTALLATION_SCHEMA = SchemaComponent(
30 "installation",
31 1,
32 "CREATE TABLE IF NOT EXISTS engine_metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)",
33)
36class Installation:
37 """Hold the engine lock and confirm application.db belongs to this installation.
39 Open it before any store that writes application.db, and close it after them:
40 the lock is what keeps a second engine from writing the same database.
41 """
43 def __init__(
44 self,
45 path: Path,
46 *,
47 instance_id: str | None = None,
48 lock_path: Path | None = None,
49 read_only: bool = False,
50 busy_timeout_ms: int = 500,
51 ) -> None:
52 if busy_timeout_ms <= 0: 52 ↛ 53line 52 didn't jump to line 53 because the condition on line 52 was never true
53 raise ValueError("busy_timeout_ms must be positive")
54 self.path = Path(path)
55 self.read_only = read_only
56 self.busy_timeout_ms = busy_timeout_ms
57 self._lock_path = (
58 Path(lock_path) if lock_path else self.path.with_suffix(self.path.suffix + ".lock")
59 )
60 self._requested_id = canonical_instance_id(instance_id) if instance_id is not None else None
61 self._lock_fd: int | None = None
62 self._instance_id: str | None = None
64 @property
65 def instance_id(self) -> str:
66 if self._instance_id is None: 66 ↛ 67line 66 didn't jump to line 67 because the condition on line 66 was never true
67 raise StoreClosed("installation has not been opened")
68 return self._instance_id
70 def connect(self) -> sqlite3.Connection:
71 """Open a connection to application.db in this installation's access mode."""
72 if self.read_only:
73 uri = f"{self.path.resolve(strict=True).as_uri()}?mode=ro&immutable=1"
74 connection = sqlite3.connect(
75 uri, uri=True, timeout=self.busy_timeout_ms / 1000, isolation_level=None
76 )
77 else:
78 connection = sqlite3.connect(
79 self.path, timeout=self.busy_timeout_ms / 1000, isolation_level=None
80 )
81 try:
82 connection.execute(f"PRAGMA busy_timeout = {self.busy_timeout_ms}")
83 except BaseException:
84 connection.close()
85 raise
86 return connection
88 def __enter__(self) -> Self:
89 if self._lock_fd is not None or self._instance_id is not None: 89 ↛ 90line 89 didn't jump to line 90 because the condition on line 89 was never true
90 raise StoreClosed("installation cannot be opened more than once")
91 self._acquire_lock()
92 try:
93 self._instance_id = self._open_identity()
94 except BaseException:
95 self._release_lock()
96 raise
97 return self
99 def __exit__(
100 self,
101 exc_type: type[BaseException] | None,
102 exc: BaseException | None,
103 traceback: TracebackType | None,
104 ) -> None:
105 self._release_lock()
107 def _acquire_lock(self) -> None:
108 self._lock_path.parent.mkdir(parents=True, exist_ok=True)
109 fd = os.open(self._lock_path, os.O_CREAT | os.O_RDWR, 0o600)
110 try:
111 os.fchmod(fd, 0o600)
112 fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
113 except BlockingIOError as exc:
114 os.close(fd)
115 raise InstallationAlreadyRunning("installation already has an engine owner") from exc
116 except BaseException:
117 os.close(fd)
118 raise
119 self._lock_fd = fd
121 def _release_lock(self) -> None:
122 fd, self._lock_fd = self._lock_fd, None
123 if fd is not None: 123 ↛ exitline 123 didn't return from function '_release_lock' because the condition on line 123 was always true
124 try:
125 fcntl.flock(fd, fcntl.LOCK_UN)
126 finally:
127 os.close(fd)
129 def _open_identity(self) -> str:
130 try:
131 if not self.read_only:
132 self.path.parent.mkdir(parents=True, exist_ok=True)
133 db_fd = os.open(self.path, os.O_CREAT | os.O_RDWR, 0o600)
134 os.fchmod(db_fd, 0o600)
135 os.close(db_fd)
136 connection = self.connect()
137 try:
138 return self._verify_or_create(connection)
139 finally:
140 connection.close()
141 except (sqlite3.Error, OSError) as exc:
142 raise StoreUnavailable("durable storage is unavailable") from exc
144 def _verify_or_create(self, connection: sqlite3.Connection) -> str:
145 version = connection.execute("PRAGMA user_version").fetchone()[0]
146 if self.read_only:
147 if version != APPLICATION_DATABASE_VERSION: 147 ↛ 148line 147 didn't jump to line 148 because the condition on line 147 was never true
148 raise UnknownSchemaVersion("restore candidate database schema is not supported")
149 _verify(connection)
150 elif version == 0:
151 if connection.execute( 151 ↛ 154line 151 didn't jump to line 154 because the condition on line 151 was never true
152 "SELECT 1 FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
153 ).fetchone():
154 raise UnknownSchemaVersion("unversioned database contains unknown tables")
155 self._create(connection)
156 elif version == APPLICATION_DATABASE_VERSION:
157 connection.execute("PRAGMA journal_mode = WAL")
158 _verify(connection)
159 else:
160 raise UnknownSchemaVersion("database schema version is not supported")
162 row = connection.execute(
163 "SELECT value FROM engine_metadata WHERE key = 'instance_id'"
164 ).fetchone()
165 if row is None: 165 ↛ 166line 165 didn't jump to line 166 because the condition on line 165 was never true
166 raise UnknownSchemaVersion("database has no installation identity")
167 persisted = canonical_instance_id(row[0])
168 if self._requested_id and persisted != self._requested_id:
169 raise ForeignInstallation("database belongs to a different installation")
170 return persisted
172 def _create(self, connection: sqlite3.Connection) -> None:
173 connection.execute("PRAGMA journal_mode = WAL")
174 connection.execute("PRAGMA synchronous = FULL")
175 connection.execute("BEGIN IMMEDIATE")
176 try:
177 ensure_schema(connection, INSTALLATION_SCHEMA)
178 connection.execute(
179 "INSERT INTO engine_metadata(key, value) VALUES ('instance_id', ?)",
180 (self._requested_id or str(uuid.uuid4()),),
181 )
182 connection.execute(f"PRAGMA user_version = {APPLICATION_DATABASE_VERSION}")
183 except BaseException:
184 connection.execute("ROLLBACK")
185 raise
186 connection.execute("COMMIT")
189def _verify(connection: sqlite3.Connection) -> None:
190 try:
191 verify_schema(connection, INSTALLATION_SCHEMA)
192 except SchemaMismatch as exc:
193 raise UnknownSchemaVersion("database installation schema is incomplete") from exc
196def canonical_instance_id(value: str | None) -> str:
197 """Return the canonical UUID text; reject missing or non-canonical spellings."""
198 if value is None: 198 ↛ 199line 198 didn't jump to line 199 because the condition on line 198 was never true
199 raise InvalidCommand("instance_id is required")
200 try:
201 parsed = uuid.UUID(value)
202 except (ValueError, AttributeError) as exc:
203 raise InvalidCommand("instance_id must be a UUID") from exc
204 canonical = str(parsed)
205 if value.lower() != canonical: 205 ↛ 206line 205 didn't jump to line 206 because the condition on line 205 was never true
206 raise InvalidCommand("instance_id must use canonical UUID formatting")
207 return canonical