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

1"""Single-engine ownership and the persisted identity of one installation's database.""" 

2 

3import fcntl 

4import os 

5import sqlite3 

6import uuid 

7from pathlib import Path 

8from types import TracebackType 

9from typing import Self 

10 

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) 

25 

26APPLICATION_DATABASE_VERSION = 3 

27"""`PRAGMA user_version` of application.db; the app compares it before accepting an update.""" 

28 

29INSTALLATION_SCHEMA = SchemaComponent( 

30 "installation", 

31 1, 

32 "CREATE TABLE IF NOT EXISTS engine_metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)", 

33) 

34 

35 

36class Installation: 

37 """Hold the engine lock and confirm application.db belongs to this installation. 

38 

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 """ 

42 

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 

63 

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 

69 

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 

87 

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 

98 

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() 

106 

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 

120 

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) 

128 

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 

143 

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") 

161 

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 

171 

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") 

187 

188 

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 

194 

195 

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