YuryShkoda
850695024f
A failed session (e.g. SAS %abort;, or a non-zero JS/PY/R exit) is a normal outcome of running arbitrary user code, not a request-shape or server problem. The #388 fix stopped processProgram() from hanging forever on a failed SAS session, but did so by throwing a SessionExecutionError, which surfaced as an HTTP 400 with a bespoke JSON shape - breaking Studio's log tab, which only renders on 2xx. Align the SAS branch with the pre-existing JS/PY/R behaviour: resolve instead of throwing, and let Execution.ts fold session.failureReason into the log the same way it already does for a debug-mode run. This removes the now-dead SessionExecutionError class and its try/catch wrapper entirely. Update the diagrams in api/docs/diagrams/ to match.
2.3 KiB
Code execution & session diagrams
Mermaid diagrams describing how @sasjs/server executes submitted code
(SAS/JS/PY/R) against pooled "sessions". Written for fast context-loading by
an AI coding agent: each diagram is self-contained, node/edge labels carry
the actual file:line references, and prose is kept to the minimum needed to
disambiguate the diagram.
| File | Covers |
|---|---|
| session-lifecycle.md | SessionState state machine; how it differs between the SAS runtime and the JS/PY/R runtimes |
| sas-execution-handshake.md | The SYSIN/AUTOEXEC file-swap mechanism a SAS session uses to turn one long-lived sas process into a single-use execution slot |
| request-execution-flow.md | End-to-end flowchart from HTTP request to response, covering session-pool acquisition and both runtime branches (SAS vs JS/PY/R) |
Core concept
A "session" is not a request-scoped object. It is a pooled, reusable
execution slot with a filesystem folder (session.path) and a state
(SessionState). For the SAS runtime specifically, a session also owns one
real OS process, spawned at session-creation time and consumed by exactly
one code submission (see sas-execution-handshake.md). For JS/PY/R, a
session is just an ID + folder; the actual interpreter process is spawned
fresh per request inside processProgram.
Key source files
api/src/controllers/internal/Session.ts— session pool + lifecycle (SessionController,SASSessionController),SessionStatetransitions.api/src/controllers/internal/processProgram.ts— writes the submitted code into the session and drives it to completion/failure, per runtime.api/src/controllers/internal/Execution.ts—ExecutionController, the entry point controllers call; acquires a session, callsprocessProgram, reads backlog.log/webout.txt/headers, and builds the HTTP response. A failed session (any runtime) is embedded in that same response, not thrown as a separate error.api/src/controllers/internal/create{SAS,JS,Python,R}Program.ts— per-runtime code templating (wraps the user's submitted code with boilerplate: variable injection,_weboutredirection, etc).api/src/types/Session.ts—SessionStateenum andSessioninterface.