Coverage for src/robot_dispatch/db/models.py: 99%

105 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-07 17:18 +0000

1from __future__ import annotations 

2 

3import uuid 

4from datetime import UTC, datetime 

5from typing import Any 

6 

7from sqlalchemy import JSON, DateTime, ForeignKey, Index, Integer, String, Text, Uuid 

8from sqlalchemy.dialects.postgresql import JSONB 

9from sqlalchemy.orm import Mapped, mapped_column, relationship 

10 

11from robot_dispatch.db.base import Base 

12from robot_dispatch.domain.enums import RobotStatus, TaskStatus 

13 

14JSON_TYPE = JSON().with_variant(JSONB(), "postgresql") 

15 

16 

17def utcnow() -> datetime: 

18 return datetime.now(tz=UTC) 

19 

20 

21class RobotCapability(Base): 

22 __tablename__ = "robot_capabilities" 

23 

24 robot_id: Mapped[uuid.UUID] = mapped_column( 

25 Uuid(as_uuid=True), ForeignKey("robots.id", ondelete="CASCADE"), primary_key=True 

26 ) 

27 name: Mapped[str] = mapped_column(String(64), primary_key=True) 

28 

29 robot: Mapped[Robot] = relationship(back_populates="capabilities") 

30 

31 def __repr__(self) -> str: # pragma: no cover - debug helper 

32 return f"<RobotCapability {self.name}>" 

33 

34 

35class Robot(Base): 

36 __tablename__ = "robots" 

37 

38 id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4) 

39 name: Mapped[str] = mapped_column(String(128), nullable=False, unique=True) 

40 namespace: Mapped[str] = mapped_column(String(128), nullable=False) 

41 status: Mapped[str] = mapped_column( 

42 String(32), nullable=False, default=RobotStatus.OFFLINE.value, index=True 

43 ) 

44 last_seen_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) 

45 current_task_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True), nullable=True) 

46 created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow) 

47 updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow) 

48 

49 capabilities: Mapped[list[RobotCapability]] = relationship( 

50 back_populates="robot", lazy="selectin", cascade="all, delete-orphan" 

51 ) 

52 

53 __table_args__ = (Index("ix_robots_status_seen", "status", "last_seen_at"),) 

54 

55 @property 

56 def capability_names(self) -> list[str]: 

57 return sorted(capability.name for capability in self.capabilities) 

58 

59 def supports(self, task_type: str) -> bool: 

60 return any(capability.name == task_type for capability in self.capabilities) 

61 

62 def set_capabilities(self, names: list[str]) -> None: 

63 self.capabilities = [RobotCapability(name=name) for name in sorted(set(names))] 

64 

65 @classmethod 

66 def new( 

67 cls, 

68 *, 

69 name: str, 

70 namespace: str, 

71 capabilities: list[str], 

72 status: RobotStatus = RobotStatus.OFFLINE, 

73 last_seen_at: datetime | None = None, 

74 ) -> Robot: 

75 now = utcnow() 

76 robot = cls( 

77 id=uuid.uuid4(), 

78 name=name, 

79 namespace=namespace, 

80 status=status.value, 

81 last_seen_at=last_seen_at, 

82 created_at=now, 

83 updated_at=now, 

84 ) 

85 robot.set_capabilities(capabilities) 

86 return robot 

87 

88 def __repr__(self) -> str: # pragma: no cover - debug helper 

89 return f"<Robot {self.name} {self.status}>" 

90 

91 

92class Task(Base): 

93 __tablename__ = "tasks" 

94 

95 id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4) 

96 external_id: Mapped[str | None] = mapped_column(String(128), nullable=True, unique=True) 

97 type: Mapped[str] = mapped_column(String(64), nullable=False, index=True) 

98 payload: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False, default=dict) 

99 priority: Mapped[int] = mapped_column(Integer, nullable=False, default=100) 

100 status: Mapped[str] = mapped_column( 

101 String(32), nullable=False, default=TaskStatus.PENDING.value, index=True 

102 ) 

103 

104 robot_id: Mapped[uuid.UUID | None] = mapped_column( 

105 Uuid(as_uuid=True), ForeignKey("robots.id", ondelete="SET NULL"), nullable=True 

106 ) 

107 command_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True), nullable=True) 

108 

109 attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=0) 

110 max_attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=3) 

111 timeout_seconds: Mapped[int] = mapped_column(Integer, nullable=False, default=120) 

112 

113 available_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) 

114 lease_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) 

115 started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) 

116 finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) 

117 

118 last_error: Mapped[str | None] = mapped_column(Text, nullable=True) 

119 result: Mapped[dict[str, Any] | None] = mapped_column(JSON_TYPE, nullable=True) 

120 

121 created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) 

122 updated_at: Mapped[datetime] = mapped_column( 

123 DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow 

124 ) 

125 version: Mapped[int] = mapped_column(Integer, nullable=False, default=0) 

126 

127 __table_args__ = ( 

128 Index("ix_tasks_dispatch_queue", "status", "priority", "available_at"), 

129 Index("ix_tasks_robot_status", "robot_id", "status"), 

130 Index("ix_tasks_lease", "status", "lease_expires_at"), 

131 ) 

132 

133 @property 

134 def status_enum(self) -> TaskStatus: 

135 return TaskStatus(self.status) 

136 

137 @classmethod 

138 def new( 

139 cls, 

140 *, 

141 task_type: str, 

142 payload: dict[str, Any] | None = None, 

143 priority: int = 100, 

144 external_id: str | None = None, 

145 max_attempts: int = 3, 

146 timeout_seconds: int = 120, 

147 available_at: datetime | None = None, 

148 ) -> Task: 

149 now = utcnow() 

150 return cls( 

151 id=uuid.uuid4(), 

152 external_id=external_id, 

153 type=task_type, 

154 payload=payload or {}, 

155 priority=priority, 

156 status=TaskStatus.PENDING.value, 

157 attempts=0, 

158 max_attempts=max_attempts, 

159 timeout_seconds=timeout_seconds, 

160 available_at=available_at or now, 

161 created_at=now, 

162 updated_at=now, 

163 version=0, 

164 ) 

165 

166 def __repr__(self) -> str: # pragma: no cover - debug helper 

167 return f"<Task {self.type} {self.status} attempts={self.attempts}>" 

168 

169 

170class TaskEvent(Base): 

171 __tablename__ = "task_events" 

172 

173 id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4) 

174 task_id: Mapped[uuid.UUID] = mapped_column( 

175 Uuid(as_uuid=True), ForeignKey("tasks.id", ondelete="CASCADE"), nullable=False, index=True 

176 ) 

177 kind: Mapped[str] = mapped_column(String(32), nullable=False) 

178 from_status: Mapped[str | None] = mapped_column(String(32), nullable=True) 

179 to_status: Mapped[str | None] = mapped_column(String(32), nullable=True) 

180 robot_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True), nullable=True) 

181 message: Mapped[str | None] = mapped_column(Text, nullable=True) 

182 payload: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False, default=dict) 

183 created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) 

184 

185 @classmethod 

186 def new( 

187 cls, 

188 *, 

189 task_id: uuid.UUID, 

190 kind: str, 

191 from_status: str | None = None, 

192 to_status: str | None = None, 

193 robot_id: uuid.UUID | None = None, 

194 message: str | None = None, 

195 payload: dict[str, Any] | None = None, 

196 ) -> TaskEvent: 

197 return cls( 

198 id=uuid.uuid4(), 

199 task_id=task_id, 

200 kind=kind, 

201 from_status=from_status, 

202 to_status=to_status, 

203 robot_id=robot_id, 

204 message=message, 

205 payload=payload or {}, 

206 created_at=utcnow(), 

207 ) 

208 

209 

210class OutboxMessage(Base): 

211 """Transactional outbox: rows are written in the same transaction as the state change.""" 

212 

213 __tablename__ = "outbox_messages" 

214 

215 id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4) 

216 exchange: Mapped[str] = mapped_column(String(64), nullable=False) 

217 routing_key: Mapped[str] = mapped_column(String(128), nullable=False) 

218 payload: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False, default=dict) 

219 headers: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False, default=dict) 

220 message_id: Mapped[str] = mapped_column(String(64), nullable=False) 

221 expiration_ms: Mapped[int | None] = mapped_column(Integer, nullable=True) 

222 

223 attempts: Mapped[int] = mapped_column(Integer, nullable=False, default=0) 

224 last_error: Mapped[str | None] = mapped_column(Text, nullable=True) 

225 available_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) 

226 sent_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True) 

227 created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) 

228 

229 __table_args__ = (Index("ix_outbox_pending", "sent_at", "available_at"),) 

230 

231 @classmethod 

232 def new( 

233 cls, 

234 *, 

235 exchange: str, 

236 routing_key: str, 

237 payload: dict[str, Any], 

238 message_id: str, 

239 headers: dict[str, Any] | None = None, 

240 expiration_ms: int | None = None, 

241 ) -> OutboxMessage: 

242 now = utcnow() 

243 return cls( 

244 id=uuid.uuid4(), 

245 exchange=exchange, 

246 routing_key=routing_key, 

247 payload=payload, 

248 headers=headers or {}, 

249 message_id=message_id, 

250 expiration_ms=expiration_ms, 

251 attempts=0, 

252 available_at=now, 

253 created_at=now, 

254 )