Skip to content

Commit 52bea63

Browse files
MasterPtatoMasterPtato
committed
chore: write/update docs
1 parent 13210ec commit 52bea63

File tree

3 files changed

+384
-3
lines changed

3 files changed

+384
-3
lines changed

‎CLAUDE.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,6 @@ cargo test -- --nocapture
4040

4141
# Check for linting issues
4242
cargo clippy -- -W warnings
43-
44-
# When adding a new package to the workspace
45-
deno run -A scripts/cargo/update_workspace.ts
4643
```
4744

4845
### Docker Development Environment

‎docs/engine/ACTOR_LIFECYCLE_FLOW.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Actor Lifecycle Flow Diagram
2+
3+
```mermaid
4+
---
5+
config:
6+
theme: mc
7+
look: classic
8+
---
9+
sequenceDiagram
10+
participant A as API
11+
participant U as User
12+
participant G as Gateway
13+
14+
participant R as Runner
15+
participant RWS as Runner WS
16+
participant RWF as Runner Workflow
17+
participant AWF as Actor Workflow
18+
19+
critical runner connection
20+
R->>RWS: Connect
21+
RWS->>RWF: Create runner workflow
22+
end
23+
24+
critical actor creation
25+
U->>A: POST /actors
26+
27+
A->>AWF: Create actor workflow
28+
A->>U:
29+
end
30+
31+
critical initial request
32+
U->>G: Request to actor
33+
note over G: Await actor ready
34+
35+
critical actor allocation
36+
note over AWF: Allocate
37+
38+
AWF->>RWF: Send StartActor
39+
40+
RWF->>RWS:
41+
RWS->>R:
42+
note over R: Start actor
43+
R->>RWS: Actor state update: Running
44+
RWS->>RWF:
45+
RWF->>AWF:
46+
note over AWF: Publish Ready msg
47+
end
48+
AWF->>G: Receive runner ID
49+
50+
G->>RWS: Tunnel ToClientRequestStart
51+
RWS->>R:
52+
note over R: Handle request
53+
R->>RWS: ToServerResponseStart
54+
RWS->>G:
55+
G->>U:
56+
end
57+
58+
critical second request
59+
U->>G: Request to actor
60+
note over G: Actor already connectable
61+
G->>RWS: Tunnel ToClientRequestStart
62+
RWS->>R:
63+
note over R: Handle request
64+
R->>RWS: ToServerResponseStart
65+
RWS->>G:
66+
G->>U:
67+
end
68+
69+
note over A, AWF: Time passes
70+
71+
critical actor sleep
72+
R->>RWS: Actor intent: Sleep
73+
RWS->>RWF:
74+
RWF->>AWF:
75+
note over AWF: Mark as sleeping
76+
AWF->>RWF: Send StopActor
77+
RWF->>RWS:
78+
RWS->>R:
79+
note over R: Stop actor
80+
R->>RWS: Actor state update: Stopped
81+
RWS->>RWF:
82+
RWF->>AWF:
83+
note over AWF: Sleep
84+
end
85+
86+
critical request to sleeping actor
87+
U->>G: Request to actor
88+
note over G: Actor sleeping
89+
G->>AWF: Wake
90+
note over G: Await actor ready
91+
critical actor allocation
92+
note over AWF: Allocate
93+
AWF->>RWF: Send StartActor
94+
RWF->>RWS:
95+
RWS->>R:
96+
note over R: Start actor
97+
R->>RWS: Actor state update: Running
98+
RWS->>RWF:
99+
RWF->>AWF:
100+
note over AWF: Publish Ready msg
101+
end
102+
AWF->>G: Receive runner ID
103+
104+
G->>RWS: Tunnel ToClientRequestStart
105+
RWS->>R:
106+
note over R: Handle request
107+
R->>RWS: ToServerResponseStart
108+
RWS->>G:
109+
G->>U:
110+
end
111+
```

‎docs/engine/SERVERLESS_FLOW.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Serverless Flow Diagrams
2+
3+
## Ideal Serverless Flow
4+
5+
```mermaid
6+
---
7+
config:
8+
theme: mc
9+
look: classic
10+
---
11+
sequenceDiagram
12+
participant A as API
13+
participant U as User
14+
participant G as Gateway
15+
16+
participant R as Runner
17+
participant RWS as Runner WS
18+
participant RWF as Runner Workflow
19+
participant AWF as Actor Workflow
20+
participant S as Serverless
21+
participant SE as Serverless<br/>Endpoint
22+
23+
note over AWF: Actor already<br/>created and sleeping
24+
25+
critical request to sleeping actor
26+
U->>G: Request to actor
27+
note over G: Actor sleeping
28+
G->>AWF: Wake
29+
note over G: Await actor ready
30+
31+
critical actor allocation
32+
note over AWF: Allocate
33+
34+
note over AWF: No runners available,<br/>Start pending
35+
AWF->>S: Bump
36+
note over S: Desired: 1
37+
S->>SE: GET /start
38+
SE-->R: Same process
39+
40+
critical runner connection
41+
R->>RWS: Connect
42+
RWS->>RWF: Create runner workflow
43+
end
44+
45+
note over RWF: Allocate pending actors
46+
RWF->>AWF: Allocate
47+
48+
AWF->>RWF: Send StartActor
49+
50+
RWF->>RWS:
51+
RWS->>R:
52+
note over R: Start actor
53+
R->>RWS: Actor state update: Running
54+
RWS->>RWF:
55+
RWF->>AWF:
56+
note over AWF: Publish Ready msg
57+
end
58+
AWF->>G: Receive runner ID
59+
60+
G->>RWS: Tunnel ToClientRequestStart
61+
RWS->>R:
62+
note over R: Handle request
63+
R->>RWS: ToServerResponseStart
64+
RWS->>G:
65+
G->>U:
66+
end
67+
68+
%% note over A, AWF: Time passes
69+
70+
%% critical actor sleep
71+
%% R->>RWS: Actor intent: Sleep
72+
%% RWS->>RWF:
73+
%% RWF->>AWF:
74+
%% note over AWF: Mark as sleeping
75+
%% AWF->>RWF: Send StopActor
76+
%% RWF->>RWS:
77+
%% RWS->>R:
78+
%% note over R: Stop actor
79+
%% R->>RWS: Actor state update: Stopped
80+
%% RWS->>RWF:
81+
%% RWF->>AWF:
82+
%% note over AWF: Sleep
83+
%% end
84+
```
85+
86+
## Messy Serverless Flow
87+
88+
```mermaid
89+
---
90+
config:
91+
theme: mc
92+
look: classic
93+
---
94+
sequenceDiagram
95+
%% participant A as API
96+
participant U as User
97+
participant G as Gateway
98+
99+
participant R as Runner
100+
participant RWS as Runner WS
101+
participant RWF as Runner Workflow
102+
participant AWF as Actor Workflow
103+
participant S as Serverless
104+
participant SE as Serverless<br/>Endpoint
105+
106+
note over R, RWF: For simplicity, this represents multiple<br/>runners/runner workflows
107+
note over AWF: Actor already<br/>created and sleeping
108+
109+
critical request to sleeping actor
110+
U->>G: GET /sleep<br/>(actor endpoint)
111+
note over G: Actor sleeping
112+
G->>AWF: Wake
113+
note over G: Await actor ready
114+
115+
critical actor allocation
116+
note over AWF: Allocate
117+
note over AWF: No runners available,<br/>Start pending
118+
AWF->>S: Bump
119+
note over S: Desired: 1
120+
S->>SE: GET /start
121+
SE-->R: Same process
122+
123+
critical runner connection
124+
R->>RWS: Connect
125+
RWS->>RWF: Create runner workflow
126+
end
127+
128+
note over RWF: Allocate pending actors
129+
RWF->>AWF: Allocate
130+
131+
AWF->>RWF: Send StartActor
132+
133+
RWF->>RWS:
134+
RWS->>R:
135+
note over R: Start actor
136+
R->>RWS: Actor state update: Running
137+
RWS->>RWF:
138+
RWF->>AWF:
139+
note over AWF: Publish Ready msg
140+
end
141+
AWF->>G: Receive runner ID
142+
143+
G->>RWS: Tunnel ToClientRequestStart
144+
RWS->>R:
145+
note over R: Handle GET /sleep
146+
R->>RWS: Actor intent: Sleep
147+
RWS->>RWF:
148+
R->>RWS: ToServerResponseStart
149+
RWS->>G:
150+
G->>U:
151+
end
152+
153+
note over U: Immediately request<br/>sleep endpoint again
154+
155+
critical request to running actor
156+
U->>G: GET /sleep<br/>(actor endpoint)
157+
note over G: Actor running
158+
G->>RWS: Tunnel ToClientRequestStart
159+
RWS->>R:
160+
note over R: Handle GET /sleep
161+
R->>RWS: Actor intent: Sleep
162+
RWS->>RWF:
163+
R->>RWS: ToServerResponseStart
164+
RWS->>G:
165+
G->>U:
166+
end
167+
168+
critical actor sleep
169+
RWF->>AWF: Actor intent: Sleep
170+
note over AWF: Mark as sleeping
171+
AWF->>RWF: Send StopActor
172+
RWF->>AWF: Second actor intent: Sleep
173+
note over AWF: Ignored, already<br/>marked as sleeping
174+
end
175+
176+
critical request to actor marked as sleeping
177+
U->>G: GET /sleep<br/>(actor endpoint)
178+
note over G: Actor sleeping
179+
G->>AWF: Wake
180+
note over G: Await actor ready
181+
note over AWF: Actor is currently marked<br/>as sleeping but has not stopped<br/>yet, defer wake after stop
182+
critical actor sleep cont
183+
RWF->>RWS: Proxy StopActor<br/>(from before)
184+
RWS->>R:
185+
note over R: Stop actor
186+
R->>RWS: Actor state update: Stopped
187+
RWS->>RWF:
188+
RWF->>AWF:
189+
note over AWF: Deallocate
190+
AWF->>S: Bump
191+
note over AWF: Send Stopped msg
192+
end
193+
AWF->>G: Receive Stopped msg
194+
G->>AWF: Retry wake
195+
critical actor reallocation
196+
note over AWF: Deferred wake
197+
note over AWF: Allocate
198+
AWF->>RWF: Send StartActor
199+
RWF->>RWS:
200+
RWS->>R:
201+
note over R: Start actor
202+
R->>RWS: Actor state update: Running
203+
note over AWF: Ignore retry wake (from before)<br/>because we are already allocated
204+
205+
S->>RWF: Stop
206+
note over S: After grace
207+
S->>RWS: Evict WS
208+
RWS->>R:
209+
note over RWF: Remove from alloc idx
210+
note over RWF: Evict running actors
211+
RWF->>AWF: Actor lost
212+
note over AWF: Deallocate
213+
note over AWF: Send Stopped msg
214+
AWF->>G: Receive Stopped msg
215+
G->>AWF: Retry wake
216+
note over AWF: Allocate
217+
note over AWF: No runners available,<br/>Start pending
218+
AWF->>S: Bump
219+
note over S: Desired: 1
220+
S->>SE: GET /start
221+
note over R, SE: Second runner
222+
SE-->R: Same process
223+
224+
critical runner connection
225+
R->>RWS: Connect
226+
RWS->>RWF: Create runner workflow
227+
end
228+
229+
note over RWF: Allocate pending actors
230+
RWF->>AWF: Allocate
231+
232+
AWF->>RWF: Send StartActor
233+
234+
RWF->>RWS:
235+
RWS->>R:
236+
note over R: Start actor
237+
R->>RWS: Actor state update: Running
238+
RWS->>RWF:
239+
RWF->>AWF:
240+
note over AWF: Publish Ready msg
241+
end
242+
AWF->>G: Receive runner ID
243+
G->>RWS: Tunnel ToClientRequestStart
244+
RWS->>R:
245+
note over R: Handle GET /sleep
246+
R->>RWS: Actor intent: Sleep
247+
RWS->>RWF:
248+
R->>RWS: ToServerResponseStart
249+
RWS->>G:
250+
G->>U:
251+
end
252+
253+
critical actor sleep
254+
RWF->>AWF: Actor intent: Sleep
255+
note over AWF: Mark as sleeping
256+
AWF->>RWF: Send StopActor
257+
RWF->>RWS:
258+
RWS->>R:
259+
note over R: Stop actor
260+
R->>RWS: Actor state update: Stopped
261+
RWS->>RWF:
262+
RWF->>AWF:
263+
note over AWF: Deallocate
264+
AWF->>S: Bump
265+
note over AWF: Send Stopped msg
266+
end
267+
268+
S->>RWF: Stop
269+
note over RWF: Remove from alloc idx
270+
note over S: After grace
271+
S->>RWS: Evict WS
272+
RWS->>R:
273+
```

0 commit comments

Comments
 (0)