Coverage for src/copytrading_engine/trading/adapters/account_records.py: 97%

149 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-11-16 16:55 +0000

1"""Each account's record follows the Alpaca account its keys open, not the name in the setup. 

2 

3A record lives in `accounts/<name>/execution.sqlite3`, and its `identity` row names the Alpaca 

4account it was made with. Before the accounts open, the records are put under the names the setup 

5gives those Alpaca accounts now: the same keys under a new name open the same record, with its 

6lots, and a record a name used to hold for another Alpaca account moves aside to 

7`<name>-earlier` rather than block it. 

8 

9Nothing that holds a record is ever deleted here: only a folder with no record file gives way. A 

10record that can't be read is never moved, and the account it would affect doesn't open. Every 

11folder that moves is locked as an account owner locks it, and a move interrupted by a crash is 

12finished, or undone, before the next plan. 

13""" 

14 

15import fcntl 

16import json 

17import logging 

18import os 

19import shutil 

20import sqlite3 

21from collections.abc import Generator, Iterator, Mapping 

22from contextlib import ExitStack, closing, contextmanager 

23from dataclasses import dataclass, field 

24from enum import Enum 

25from pathlib import Path 

26 

27log = logging.getLogger(__name__) 

28 

29# An Alpaca account as a record names it: its environment and Alpaca's account ID. 

30type BrokerIdentity = tuple[str, str] 

31 

32RECORD = "execution.sqlite3" 

33LOCK = "executor.lock" 

34STAGED = ".moving-" 

35# Where a move in progress is written down; a dot-file, so it is never taken for an account. 

36JOURNAL = ".record-moves.json" 

37 

38 

39class Unbound(Enum): 

40 """A folder with no Alpaca account to go by.""" 

41 

42 # No record file at all: the folder holds nothing and may give way. 

43 EMPTY = "empty" 

44 # A record file that names no Alpaca account yet; it is moved aside, never deleted. 

45 UNNAMED = "unnamed" 

46 # A record file that couldn't be read; it is never moved or deleted. 

47 UNREADABLE = "unreadable" 

48 

49 

50type Held = BrokerIdentity | Unbound 

51 

52 

53@dataclass(frozen=True, slots=True) 

54class RecordPlan: 

55 """Folder renames, folders that give way, and the accounts that cannot open.""" 

56 

57 moves: dict[str, str] = field(default_factory=dict) 

58 cleared: tuple[str, ...] = () 

59 refusals: dict[str, str] = field(default_factory=dict) 

60 

61 

62def record_identity(account_dir: Path) -> Held: 

63 """The Alpaca account a folder's record was made with, or why there is none to go by.""" 

64 database = account_dir / RECORD 

65 if not database.exists(): 

66 return Unbound.EMPTY 

67 try: 

68 with closing(sqlite3.connect(database.as_uri() + "?mode=ro", uri=True)) as db: 

69 found = db.execute( 

70 "SELECT environment, account_id FROM identity WHERE singleton=1" 

71 ).fetchone() 

72 except sqlite3.Error: 

73 return Unbound.UNREADABLE 

74 return (found[0], found[1]) if found is not None else Unbound.UNNAMED 

75 

76 

77def account_folders(root: Path) -> Iterator[Path]: 

78 """Every account's folder; a dot-folder, such as one staged mid-move, is not an account.""" 

79 if root.is_dir(): 79 ↛ exitline 79 didn't return from function 'account_folders' because the condition on line 79 was always true

80 for child in sorted(root.iterdir()): 

81 if child.is_dir() and not child.is_symlink() and not child.name.startswith("."): 

82 yield child 

83 

84 

85def held_records(root: Path) -> dict[str, Held]: 

86 """Every account folder and the Alpaca account its record belongs to.""" 

87 return {child.name: record_identity(child) for child in account_folders(root)} 

88 

89 

90def plan_records( 

91 wanted: Mapping[str, BrokerIdentity | None], held: Mapping[str, Held] 

92) -> RecordPlan: 

93 """Where each record goes so every setup name holds its own Alpaca account's record. 

94 

95 `wanted` maps each setup name to the Alpaca account its keys open, or None when that could 

96 not be checked; such a name keeps its folder unless another account's record is in it. 

97 """ 

98 known = {name: identity for name, identity in wanted.items() if identity is not None} 

99 sharing: dict[BrokerIdentity, list[str]] = {} 

100 for name, identity in known.items(): 

101 sharing.setdefault(identity, []).append(name) 

102 refusals = { 

103 name: "alpaca_account_shared" 

104 for names in sharing.values() 

105 if len(names) > 1 

106 for name in names 

107 } 

108 # A setup name whose own folder can't be read can't be told apart from its record. 

109 refusals |= { 

110 name: "record_unreadable" 

111 for name in wanted 

112 if held.get(name) is Unbound.UNREADABLE and name not in refusals 

113 } 

114 owner = { 

115 identity: names[0] 

116 for identity, names in sharing.items() 

117 if len(names) == 1 and names[0] not in refusals 

118 } 

119 moves: dict[str, str] = {} 

120 for folder, identity in held.items(): 

121 if isinstance(identity, Unbound): 

122 # A record with no Alpaca account steps aside from a name another record needs. 

123 if identity is Unbound.UNNAMED and folder in known and folder not in refusals: 

124 moves[folder] = "" 

125 continue 

126 target = owner.get(identity) 

127 if target is not None and folder != target: 

128 moves[folder] = target 

129 elif target is None and folder in known and folder not in refusals: 

130 # The name now belongs to another Alpaca account; its old record steps aside. 

131 moves[folder] = "" 

132 # An UNNAMED folder only steps aside when a record must take its place. 

133 arriving = {target for target in moves.values() if target} 

134 for folder in [name for name, target in moves.items() if not target]: 

135 if held[folder] is Unbound.UNNAMED and folder not in arriving: 135 ↛ 136line 135 didn't jump to line 136 because the condition on line 135 was never true

136 del moves[folder] 

137 taken = set(held) | set(wanted) 

138 for folder in sorted(name for name, target in moves.items() if not target): 

139 parked = f"{folder}-earlier" 

140 suffix = 2 

141 while parked in taken: 

142 parked = f"{folder}-earlier-{suffix}" 

143 suffix += 1 

144 taken.add(parked) 

145 moves[folder] = parked 

146 cleared = tuple( 

147 sorted( 

148 folder 

149 for folder, identity in held.items() 

150 if identity is Unbound.EMPTY and folder in arriving and folder not in moves 

151 ) 

152 ) 

153 return RecordPlan(moves=moves, cleared=cleared, refusals=refusals) 

154 

155 

156@contextmanager 

157def _locked(root: Path, folders: list[str]) -> Generator[str | None]: 

158 """Each folder locked as its account owner locks it, held through the move; yields the 

159 first folder another CopyTrading has open, with nothing locked, or None.""" 

160 with ExitStack() as stack: 

161 for name in folders: 

162 lock = stack.enter_context((root / name / LOCK).open("a")) 

163 try: 

164 fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) 

165 except OSError: 

166 stack.close() 

167 yield name 

168 return 

169 yield None 

170 

171 

172def _write_journal(path: Path, moves: Mapping[str, str]) -> None: 

173 staging = path.with_suffix(".tmp") 

174 with staging.open("w") as handle: 

175 json.dump(dict(moves), handle) 

176 handle.flush() 

177 os.fsync(handle.fileno()) 

178 staging.replace(path) 

179 

180 

181def apply_record_plan(root: Path, plan: RecordPlan) -> str | None: 

182 """Make the moves, through temporary names so two records can trade places. Returns the 

183 folder another CopyTrading has open, and then changes nothing at all.""" 

184 touched = sorted(set(plan.moves) | set(plan.cleared)) 

185 if not touched: 

186 return None 

187 with _locked(root, touched) as busy: 

188 if busy is not None: 

189 log.warning("account_records_in_use folder=%s", busy) 

190 return busy 

191 journal = root / JOURNAL 

192 _write_journal(journal, plan.moves) 

193 for folder in plan.cleared: 

194 shutil.rmtree(root / folder) 

195 for folder in plan.moves: 

196 (root / folder).rename(root / f"{STAGED}{folder}") 

197 for folder, target in plan.moves.items(): 

198 (root / f"{STAGED}{folder}").rename(root / target) 

199 journal.unlink() 

200 return None 

201 

202 

203def recover_interrupted_moves(root: Path) -> None: 

204 """Finish the moves a crash interrupted, from their journal; without one, put each staged 

205 folder back under its own name. A folder that can go nowhere stays staged, never deleted.""" 

206 journal = root / JOURNAL 

207 moves: dict[str, str] = json.loads(journal.read_text()) if journal.is_file() else {} 

208 if root.is_dir(): 208 ↛ 220line 208 didn't jump to line 220 because the condition on line 208 was always true

209 for staged in sorted(root.iterdir()): 

210 if not staged.name.startswith(STAGED) or not staged.is_dir(): 

211 continue 

212 folder = staged.name.removeprefix(STAGED) 

213 for target in (moves.get(folder), folder): 213 ↛ 219line 213 didn't jump to line 219 because the loop on line 213 didn't complete

214 if target and not (root / target).exists(): 

215 staged.rename(root / target) 

216 log.warning("account_record_move_recovered from=%s to=%s", folder, target) 

217 break 

218 else: 

219 log.error("account_record_move_unrecoverable folder=%s", folder) 

220 journal.unlink(missing_ok=True) 

221 

222 

223def reconcile_records(root: Path, wanted: Mapping[str, BrokerIdentity | None]) -> RecordPlan: 

224 """Put each record under the name the setup gives its Alpaca account now.""" 

225 recover_interrupted_moves(root) 

226 plan = plan_records(wanted, held_records(root)) 

227 if apply_record_plan(root, plan) is None: 

228 return plan 

229 # Nothing moved, so each account a move was for would open the wrong record: none opens. 

230 involved = set(plan.moves) | set(plan.moves.values()) | set(plan.cleared) 

231 busy = {name: "account_in_use" for name in wanted if name in involved} 

232 return RecordPlan(refusals=busy | plan.refusals) 

233 

234 

235def delete_record(root: Path, name: str) -> str | None: 

236 """Delete the record of an account the setup no longer has, when its owner asks; the shares 

237 stay at Alpaca. Returns why it can't: another CopyTrading has it open, or there is none.""" 

238 folder = root / name 

239 if ( 

240 not name 

241 or name.startswith(".") 

242 or "/" in name 

243 or folder.is_symlink() 

244 or not folder.is_dir() 

245 ): 

246 return "not_found" 

247 with (folder / LOCK).open("a") as lock: 

248 try: 

249 fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB) 

250 except OSError: 

251 return "account_in_use" 

252 shutil.rmtree(folder) 

253 return None