jY|UdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z ddl m Z ddlmZmZmZej$eZej*Zded <ej0Zej4ad ed <eej:aded <d,d Zd-dZ d.dZ!Gddee Z"e dGddZ#eeeefZ$GddZ%e%Z&d/dZ'd0dZ(dddddd d1dZ)dZ*d2d3dZ+Gd d!Z,da-d"ed#<d$d%d4d&Z.d5d'Z/d(Z0d)Z1d.d*Z2gd+Z3y)6u*스텝 락의 소유자 신원과 살아있음 — 죽음을 추측하지 않고 확인한다. ## 왜 있나 `step_run.status='running'` 한 칸이 락이었다. 그 칸은 **누가 잡았는지**도 **그가 살아있는지**도 적지 않아서, 시스템은 죽음을 **경과 시간으로 추측**했다 (`step_running_timeout_seconds`, 기본 3600초). 그래서: - 프로세스를 강제 종료하면 `running` 행이 남고 한 시간을 기다려야 했다 (2026-08-26 새벽 실측 손실 40분) - `force` 로도 못 뺏었다 (`_try_claim_running` 의 `WHERE status != 'running'`) - 다섯 달치 시체가 쌓였다 (2026-03-25 부터 14행) 이 모듈은 락에 **소유자 신원**과 **하트비트**를 실어, 죽음을 추측 대신 **확인**하게 한다. ## 판정 순서 (`judge_owner`) 위에서부터 첫 일치에서 멈춘다. | # | 조건 | 판정 | |---|---|---| | 1 | boot_id 가 이 프로세스 **and** 등록부에 없다 | DEAD | | 2 | boot_id 가 이 프로세스 **and** 등록부에 있다 | ALIVE | | 3 | host 가 이 호스트 **and** PID 가 죽은 프로세스 | DEAD | | 4 | host 가 이 호스트 **and** PID 는 살아있으나 boot_id 다름 | 하트비트로 | | 5 | 다른 호스트 / 신원 미상 | 하트비트 lease 로 | | 6 | 신원·하트비트 둘 다 없음 (구 행) | UNKNOWN — 호출자가 경과 시간으로 | `UNKNOWN` 은 「모른다」다. 호출자는 이를 **살아있음으로 취급**하거나 기존 경과 시간 경로로 떨어뜨린다 — 절대 죽음으로 읽지 않는다 (fail-closed). ) annotationsN) dataclass)datetimetimezone)Enum)DictOptionalTuplestr PROCESS_HOSTint _IDENTITY_PID_IDENTITY_BOOT_IDc(tj}t5t|k7rI|at t j atjtjd|tttfcdddS#1swYyxYw)u(host, pid, boot_id). fork 로 PID 가 바뀌었으면 신원을 새로 만든다. ★신원을 새로 만들 때 **등록부도 비운다.** fork 직후 자식은 부모의 등록부를 통째로 물려받는데, 그 내용은 전부 거짓이다 — 자식은 그 스텝들을 하고 있지 않다. 안 비우면 자식이 부모의 락을 「내가 잡고 있다」고 읽는다. uV프로세스 신원 재생성 (PID %s) — fork 로 보인다. 등록부를 비웠다.N) osgetpid_IDENTITY_LOCKrr uuiduuid4rREGISTRYresetloggerwarningr )pids H/Users/manta/Documents/Projects/TheRoad-I1/backend/app/core/step_lock.pyprocess_identityrAsc ))+C  C M #DJJL 1  NN  NNh ],== s A#BBctdS)Nrrprocess_boot_idr"W  a  r!ctdS)Nrr r!r process_pidr&[r#r!ceZdZdZdZdZdZy) OwnerVerdictu.소유자가 살아있는가에 대한 판정.alivedeadunknownN)__name__ __module__ __qualname____doc__ALIVEDEADUNKNOWNr r!rr(r(_s8 E DGr!r(T)frozenceZdZUdZdZded<dZded<dZded<dZded<dZ ded <e d d Z e dd Z dd Zy) LockOwneru`step_run` 행에서 읽은 소유자 신원. 전부 nullable — 신원 칸이 생기기 전에 만들어진 행은 모두 None 이다. N Optional[str]host Optional[int]rboot_id heartbeat_atrun_idc |jd} | t|nd}||jd||jd|jd|jdS#ttf$rd}Y\wxYw)u:`_get_step_run()` 이 준 dict 에서 신원만 뽑는다. owner_pidN owner_host owner_boot_idr:r;)r7rr9r:r;)getr TypeError ValueError)clsrowraw_pidrs rfrom_rowzLockOwner.from_rowts''+& ")"5#g,4C&GGO,0778$   :& C sA++A?>A?c^t|jxr|jtk(SN)boolr9r"selfs ris_this_processzLockOwner.is_this_processs"DLL!Gdllo6G&GGr!c|js |jsyd|jxsdd|j |jndd|jxsdddS)Nuowner=<신원 없음>zowner=?:)r9r7rrJs rdescribezLockOwner.describes[||DII*TYY%#&aDHH4Hc'R$bq)* , r!)rDrreturnz 'LockOwner')rRrIrRr )r,r-r.r/r7__annotations__rr9r:r; classmethodrFpropertyrLrQr r!rr5r5gsh D-C!G]!"&L-& FM     HH r!r5cBeZdZdZd dZd dZd dZd d dZd dZd dZ y)HeldLockRegistryu이 프로세스가 **지금 실제로 일하고 있는** 락의 목록. DB 가 「이 프로세스가 소유자」라고 말하는데 여기에 없으면, 그 일을 하던 스레드는 사라진 것이다 — 프로세스 안의 일은 프로세스가 안다. ★등록은 **claim 보다 먼저** 한다. claim 성공 직후·등록 직전의 창에서 다른 스레드가 판정하면 살아있는 락을 죽었다고 읽기 때문이다. claim 이 실패하면 등록을 되돌린다. ★한 키에 run_id 를 **하나만** 담으면 안 된다. 같은 스텝을 노리는 두 스레드 A·B 가 있을 때, 나중에 등록한 B 가 A 를 덮어쓰고, claim 에 진 B 가 물러나며 지우면 **A 의 항목까지 사라진다.** 그 뒤 C 가 판정하면 「DB 는 이 프로세스가 소유자라는데 등록부에 없다」 → 살아있는 A 를 죽었다고 읽는다. 그래서 키마다 run_id **집합**을 담는다 — 진 쪽의 퇴장이 산 쪽을 건드리지 않는다. cDtj|_i|_yrH) threadingLock_lock_heldrJs r__init__zHeldLockRegistry.__init__s^^% )+ r!c|j5|jj|tj |dddy#1swYyxYwrH)r\r] setdefaultsetadd)rKkeyr;s rregisterzHeldLockRegistry.registers4 ZZ JJ ! !#su - 1 1& 9ZZs 4A  Ac|j5|jj|}|s dddy|j||s |j|=dddy#1swYyxYw)uS내 run_id 만 뺀다 — 같은 키의 다른 소유자를 건드리지 않는다.N)r\r]r@discardrKrcr;run_idss r unregisterzHeldLockRegistry.unregistersN ZZjjnnS)GZ OOF #JJsO ZZsA AA'Nc|j5|jj|}|s dddy|dn||vcdddS#1swYyxYw)NFT)r\r]r@rgs rholdszHeldLockRegistry.holdssB ZZjjnnS)GZ">4v/@ ZZsAAAc |j5|jjDcic]\}}|t|c}}cdddScc}}w#1swYyxYwrH)r\r]itemsra)rKrcrhs rsnapshotzHeldLockRegistry.snapshotsI ZZ:>**:J:J:LM:L,#wCW%:LMZMZsAAAAAcz|j5|jjdddy#1swYyxYw)uV등록부를 비운다. fork 로 신원이 바뀔 때와 테스트에서만 부른다.N)r\r]clearrJs rrzHeldLockRegistry.resets# ZZ JJ   ZZs1:rRNone)rcLockKeyr;r rRrrrH)rcrsr;r6rRrI)rRzDict[LockKey, set]) r,r-r.r/r^rdrirkrnrr r!rrXrXs'",:$ANr!rXc||dkry tj|dy#t$rYyt$rYyt$r!}t j d||Yd}~yd}~wwxYw)u이 호스트에서 그 PID 가 살아있나. Returns: True — 살아있다 False — 없다 (ESRCH) None — 판단 못 한다 (pid 가 없거나 이상하다) ★`PermissionError` 는 **살아있다**는 뜻이다 — 프로세스가 있는데 다른 사용자 소유라 신호를 못 보내는 것이다. 죽음으로 읽으면 남의 일을 빼앗는다 (fail-closed). NrFTzis_pid_alive(%s) OSError: %s)rkillProcessLookupErrorPermissionErrorOSErrorrdebug)rexcs r is_pid_aliver{se {cQh Q     3S#>s! AAAAAc&||dk(ryt|tr|}n/ tjt|j dd}|j |j tj}|S#t t tf$rYywxYw)u@시각 칸을 datetime 으로. 실패하면 None. `heartbeat_at` / `cancel_requested_at` 은 timestamptz 라 드라이버가 이미 datetime 을 준다. `started_at` 같은 옛 칸은 text 다. 둘 다 받는다. tz 없는 값은 UTC 로 읽는다 (기존 `_evaluate_running_state` 와 같은 규칙). NZz+00:00)tzinfo) isinstancer fromisoformatr replacerBrAAttributeErrorrrutc)rawparseds r parse_isors {cRi#x  ++CH,<,._stalled$sv'<,##,BVBV ~~ 1#c;#_AfXV(=$w y  Dww y  r!u, 이 프로세스지만 조회 키가 없다u, 이 프로세스가 실제로 잡고 있다uX 이 프로세스 소유인데 등록부에 없다 (일하던 스레드가 사라졌다)Fu* 같은 호스트인데 그 PID 가 없다Tu/ PID 는 살아있으나 하트비트가 없다u, PID 는 살아있음u PID 살아있고 하트비트 ru초 전r}u 하트비트 uA 신원·하트비트 둘 다 없다 (경과 시간 판정으로))rfloatrr rRTuple[OwnerVerdict, str])rrrrrrLr(r2rQrkr;r0r1rr:r7r r{r total_seconds) rrcrrrrregr heartbeatr)rs ` ` ` r judge_ownerrs@@*(C +hll+C   ;$$>>#$$PQ  99S%,, '"">>#$$PQ    ~~ !4 5  %,,-I zzejjL0UYY' E>!!>>#$$NO  D=  ((~~'((WX?113Cm# %=>>"">>#$$CC9GT Y--/ - C$ $   ~~ s3iw ?    >>  ]^ r!z UPDATE step_run SET heartbeat_at = CURRENT_TIMESTAMP, updated_at = :now WHERE project_id = :pid AND episode_id = :eid AND step_id = :sid AND run_id = :run_id AND owner_boot_id = :boot_id AND status = 'running' c ddlm}||nt}|j}|syt j t jj}t}d}|} |jD]F\\} } } } | D]8} |j|t|| | | | |d}||jxsdz }:H|j|j|S#|jwxYw)u등록부에 있는 락의 `heartbeat_at` 을 한 번 갱신한다. ★갱신은 **소유자 일치 조건부**다 (`run_id` + `owner_boot_id` + `running`). 이미 빼앗긴 락을 되살리지 않는다. Returns: 갱신된 행 수. rtext)rreidsidr;r9) sqlalchemyrrrnrrrr isoformatr"rmexecute_HEARTBEAT_SQLrowcountcommitclose)session_factoryr _sql_textrheldrr9updatedsession project_id episode_idstep_idrhr;results r beat_oncers-*(C <<>D  ,,x|| $ . . 0CGGG:>**, 6 -ZWw! >)B%%"$& E6??/a/";G   N  s )A)C$$C6cDeZdZdZddd d dZd dZd d dZd dZy) HeartbeatThreadu프로세스당 하나. 주기적으로 `beat_once` 를 부른다. ★하트비트 실패는 로그만 남기고 계속한다 — 하트비트가 주행을 죽이면 안 된다. DB 가 잠깐 끊겼다고 락을 잃는 것보다 lease 가 만료되는 쪽이 낫고, lease 는 어차피 다시 뛰면 회복된다. ★일하는 스레드의 세션을 공유하지 않는다 — 매 회 새 세션을 열고 닫는다. SQLAlchemy 세션은 스레드 안전하지 않다. N)interval_secondsrc~||_||_||nt|_t j |_d|_yrH)_session_factory _intervalr _registryrZEvent_stop_thread)rKrrrs rr^zHeartbeatThread.__init__s6!0)%-%9x__& 37 r!c`|j|jjry|jjt j |j dd|_|jjtjd|jtddy)Nzstep-lock-heartbeatT)targetnamedaemonu7스텝 락 하트비트 시작 (간격=%ds, boot_id=%s)rP) ris_aliverrprZThread_loopstartrinforr"rJs rrzHeartbeatThread.starts << # (=(=(?   ''::$9$    E NNO-bq1 r!c|jj|j|jj|yy)N)timeout)rrarjoin)rKrs rstopzHeartbeatThread.stops4  << # LL  g  . $r!c6|jj|jsH t|j|j |jj|jsGyy#t $r }tjd|Yd}~Ld}~wwxYw)Nu2스텝 락 하트비트 실패 (계속 진행): %s) rwaitrrrr Exceptionrr)rKrzs rrzHeartbeatThread._loopsm**//$..1 Z$//@**//$..1 ZSUXYY Zs A// B8BB)rr rOptional[HeldLockRegistry]rRrrrq)g@)rrrRrr)r,r-r.r/r^rrrr r!rrrsB!#/3 8 8 - 8  8  / Zr!rzOptional[HeartbeatThread] _HEARTBEATrrc\t t||atjtS)uI프로세스 전역 하트비트를 켠다 (여러 번 불러도 하나).r)rrr)rrs rstart_heartbeatrs.$ .>  r!c:ttjyyrH)rrr r!rstop_heartbeatrsr!z SELECT project_id, episode_id, step_id, run_id, owner_host, owner_pid, owner_boot_id, heartbeat_at, started_at FROM step_run WHERE status = 'running' AND owner_host = :host a UPDATE step_run SET status = 'failed', run_id = :revoked_run_id, error_message = :reason, last_recovery_reason = :reason, recovery_count = COALESCE(recovery_count, 0) + 1, completed_at = :now, updated_at = :now WHERE project_id = :pid AND episode_id = :eid AND step_id = :sid AND status = 'running' AND run_id = :run_id c fddlm}|j|tdtij }|syt jtjj}d}|D]}tj|j|j|j|j |j"d}|j$r,t&j)d|j*|j,t/|j0}|dur|j*|j,|j"d} | j@s~|dz }t&jCd|j*|j,||jE|S)u백엔드가 뜰 때, **이 호스트의 죽은 프로세스**가 잡은 락을 푼다. 풀기 = `running` → `failed`. **행을 지우지 않는다** — 죽은 것을 죽었다고 적는 것이다. 다음 `resume` 이 바로 가져간다. ★이 하나가 「서버를 죽였는데 그 서버가 잡은 락이 남아 한 시간을 기다리는」 사고를 없앤다. 다시 띄우는 순간 풀린다. ★대상은 **`owner_host` 가 이 호스트인 행뿐**이다. 신원 칸이 NULL 인 구 행과 다른 호스트의 행은 건드리지 않는다 — 자동 대량 정리 금지. Returns: 풀기한 행 수. rrr7)r>r=r?r:r;ufstartup reclaim: %s/%s 가 이 프로세스 boot_id 를 갖고 있다 — 건너뛴다 (조사 필요)Fu2startup reclaim 건너뜀: %s/%s %s (pid_alive=%s)u0startup reclaim: 소유 프로세스가 없다 (z , started_at=z, revoked_run_id=)Niz reclaimed-)reasonrevoked_run_idrrrrr;r%u%[STARTUP-RECLAIM] %s/%s 풀기 — %s)#rrr_RECLAIM_SELECTr fetchallrrrrrr5rFr>r=r?r:r;rLrerrorrrr{rrrQ started_at_RECLAIM_UPDATErrrrrr) dbrrowsr reclaimedrDrr)rrs rreclaim_dead_locks_on_startupr s- ::i06<2H I R R TD  ,,x|| $ . . 0CI"".. ..,,jj $    LL3   UYY'   KKD U^^-=u  ?u~~?O>PQ..)):3::,a I Io6Udm *4::<.9>>>>;;jj9   ?? NI NN7 V W^IIK r!)r rr"r&r(r5rsrXrr{rrrrrrr)rRzTuple[str, int, str]rS)rRr )rr8rRzOptional[bool])rROptional[datetime])rr5rczOptional[LockKey]rrrr rrrrIrRrrH)rrrRr )rr rRrrq)4r/ __future__rloggingrsocketrZr dataclassesrrrenumrtypingrr r getLoggerr,r gethostnamer rTr[rrrr rrrr"r&r(r5rsrXrr{rrrrrrrrrrr__all__r r!rrsB#  !'((   8 $'F&&( c(!RYY[ s ZTZZ\*3*>,!!3 $& & & V S# 22j   42""+/"'l l l  l  l ) l llh"J/Z/Zd)- %,AC FR r!