docs: correct Coding Curriculum & Playground in the beta README
Evidence: spikersoft-backend@master Program.cs:80 (eight graders); LessonsController.cs:534 (batch timeout is 200 server_error). Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
d517ec843e
commit
3012fbafcf
1 file changed
+10
-10
@@ -447,7 +447,7 @@ SpikerSoft's flagship coding-education tools run **eight parallel language track
|
||||
|
||||
All three tracks share the same lesson UI (the language-agnostic `LanguageRunner` Angular component), the same attempt/progress APIs, the same PASS/FAIL line protocol, and the same offline-first PWA model. A student can start a lesson at home, finish it on a campus bus with no signal, and see their unlocks update the moment connectivity returns. The JavaScript Playground is reachable at `/tools/(tools:javascript-playground)`, Python at `/tools/(tools:python-playground)`, and C# at `/tools/(tools:csharp-playground)`.
|
||||
|
||||
Backend dispatch is strategy-based: `ILessonGradingExecutorFactory` picks Roslyn / CPython / Node per `LessonGradingRuntime`, `IFreePlayCodeExecutorFactory` picks the per-language free-play executor from request metadata, and `IStudentCodeHintAnalyzerFactory` returns the language-appropriate hint analyzer (`StudentCodeHintAnalyzer` for C#, `PythonStudentCodeHintAnalyzer` for Python, `JavaScriptStudentCodeHintAnalyzer` for JavaScript). A future TypeScript curriculum plugs into the same JS runtime via the new `LessonMetadata.Preprocessor = LessonPreprocessor.TypeScript` flag — no second runtime needed.
|
||||
Backend dispatch is strategy-based: `ILessonGradingExecutorFactory` picks Roslyn, CPython, Node, regex-via-Node, Clang for C and C++, DuckDB for SQL, or the Blink replay for x86 per `LessonGradingRuntime`, `IFreePlayCodeExecutorFactory` picks the per-language free-play executor from request metadata, and `IStudentCodeHintAnalyzerFactory` returns the language-appropriate hint analyzer (`StudentCodeHintAnalyzer` for C#, `PythonStudentCodeHintAnalyzer` for Python, `JavaScriptStudentCodeHintAnalyzer` for JavaScript, `SqlStudentCodeHintAnalyzer` for SQL). A future TypeScript curriculum plugs into the same JS runtime via the new `LessonMetadata.Preprocessor = LessonPreprocessor.TypeScript` flag — no second runtime needed.
|
||||
|
||||
### Python curriculum tiers
|
||||
|
||||
@@ -476,7 +476,7 @@ Python lessons live under [`SpikerSoft.Business.CodeExecution/Domain/Lessons/Cur
|
||||
|
||||
### JavaScript curriculum tiers
|
||||
|
||||
JavaScript lessons live under [`SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/JavaScript/`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/JavaScript/) and use the **30000–31999** lesson-number range with `DisplayNumber = LessonNumber - 30000` so the sidebar shows clean 1..N badges. See [`.cursor/rules/javascript-curriculum.mdc`](.cursor/rules/javascript-curriculum.mdc) for the locals-first / Node↔QuickJS parity rules:
|
||||
JavaScript lessons live under [`SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/JavaScript/`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Curriculum/JavaScript/) and use the **30000–31999** lesson-number range with `DisplayNumber = LessonNumber - 30000` so the sidebar shows clean 1..N badges:
|
||||
|
||||
| Tier | Numbers | Topic |
|
||||
|------|---------|-------|
|
||||
@@ -502,7 +502,7 @@ JavaScript lessons live under [`SpikerSoft.Business.CodeExecution/Domain/Lessons
|
||||
|
||||
Every challenge lesson is reachable from "Hello, World" using only language features that were formally introduced (and graded) in an earlier lesson. A student who works the curriculum top-to-bottom never has to leave the platform to look up a syntactic form they have not been taught — if the reference solution uses an `f-string`, decorator, optional chain, or generator expression, an earlier lesson exists that puts that exact construct in front of them as a "recipe to copy". Reference solutions for every gradable challenge are checked in alongside the lesson and executed end-to-end on every CI run (the `ReferenceSolutionPasses` tests, collected by the `SpikerSoft.UnitTests.slnf` solution filter), so a contract violation surfaces as a red test, not as a confused student.
|
||||
|
||||
The audit findings that drove the most recent Python and JavaScript reorderings are living documents in [`docs/curriculum/python-curriculum-audit.md`](docs/curriculum/python-curriculum-audit.md) and [`docs/curriculum/javascript-curriculum-audit.md`](docs/curriculum/javascript-curriculum-audit.md). Re-run the same audit when adding a new tier; the verification gate is `dotnet test SpikerSoft.UnitTests.slnf --filter "ReferenceSolutionPasses"`.
|
||||
The verification gate when adding a tier is `dotnet test SpikerSoft.UnitTests.slnf --filter "ReferenceSolutionPasses"`.
|
||||
|
||||
### Regex Playground & Curriculum
|
||||
|
||||
@@ -526,8 +526,8 @@ Four further curricula live under `SpikerSoft.Business.CodeExecution/Domain/Less
|
||||
|---|---|---|---|
|
||||
| **C** | 11 chapters | browser Clang toolchain (see below) | `/tools/(tools:c-playground)` |
|
||||
| **C++** | 11 chapters | browser Clang toolchain | `/tools/(tools:cpp-playground)` |
|
||||
| **SQL** | 24 chapters | DuckDB-WASM | `/tools/(tools:sql-playground)` |
|
||||
| **x86 assembly** | 13 chapters | Blink WASM emulator | `/tools/(tools:x86-playground)` |
|
||||
| **SQL** | 17 chapters | DuckDB-WASM | `/tools/(tools:sql-playground)` |
|
||||
| **x86 assembly** | 10 chapters | Blink WASM emulator | `/tools/(tools:x86-playground)` |
|
||||
|
||||
- **Browser Clang toolchain** (`libraries/platform/clang-runtime/`): a worker-hosted Clang + LLD + WASI-libc + libc++ build (browsercc, LLVM 20.1.2) paired with `@bjorn3/browser_wasi_shim` — full C89→C23 and C++98→C++23 entirely client-side, a sibling to the Roslyn-WASM / Pyodide / QuickJS runtimes. Server-side grading routes through `CCodeRunnerController` / `CppCodeRunnerController` / `SqlCodeRunnerController`.
|
||||
- **x86 playground** (`libraries/features/dev-tools-x86-playground/`): the Blink-based emulator with a GDB-like register/memory/disassembly debugger; supports GNU `as`, FASM, and NASM syntax — all client-side. (This was a TODO item; it shipped.)
|
||||
@@ -582,7 +582,7 @@ Browser graders (`SpikerSoft.Wasm` for C#, Pyodide for Python, QuickJS for JavaS
|
||||
|
||||
**The architectural rule:** code execution NEVER runs in the API process. If the code-runner container crashes mid-grade, the API stays up; a fresh client retry round-trips through Rabbit on the next batch flush. This is enforced by the API's DI graph — only [`ILessonRegradeClient`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Services/ILessonRegradeClient.cs) is registered there; no `ILessonGradingExecutor` implementation is reachable from `SpikerSoft.Api`.
|
||||
|
||||
**The flow:** [`LessonsController.BatchProgress`](spikersoft-backend/SpikerSoft.Api/Domain/Lessons/LessonsController.cs) builds a [`LessonRegradeRequest`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Messaging/LessonRegradeRequest.cs) for each queued submission and hands it to [`LessonRegradeClient`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Services/LessonRegradeClient.cs), which publishes it to the `lesson.regrade.requests` exchange and blocks on the worker's reply via RabbitMQ **Direct-Reply-To** (`amq.rabbitmq.reply-to`). The worker's [`LessonRegradeWorkerHostedService`](spikersoft-backend/SpikerSoft.EventHandlers.CodeExecution/Services/LessonRegradeWorkerHostedService.cs) consumes the request, dispatches through the same [`ILessonGradingExecutorFactory`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/CodeExecution/Execution/ILessonGradingExecutorFactory.cs) that backs the live "Submit" path (Roslyn / CPython / Node / Regex-via-Node — no code duplication between live-submit and regrade), and publishes a [`LessonRegradeResponse`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Messaging/LessonRegradeResponse.cs) back to the API's reply queue.
|
||||
**The flow:** [`LessonsController.BatchProgress`](spikersoft-backend/SpikerSoft.Api/Domain/Lessons/LessonsController.cs) builds a [`LessonRegradeRequest`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Messaging/LessonRegradeRequest.cs) for each queued submission and hands it to [`LessonRegradeClient`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Services/LessonRegradeClient.cs), which publishes it to the `lesson.regrade.requests` queue and blocks on the worker's reply via RabbitMQ **Direct-Reply-To** (`amq.rabbitmq.reply-to`). The worker's [`LessonRegradeWorkerHostedService`](spikersoft-backend/SpikerSoft.EventHandlers.CodeExecution/Services/LessonRegradeWorkerHostedService.cs) consumes the request, dispatches through the same [`ILessonGradingExecutorFactory`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/CodeExecution/Execution/ILessonGradingExecutorFactory.cs) that backs the live "Submit" path (one executor per runtime — no separate regrade code path), and publishes a [`LessonRegradeResponse`](spikersoft-backend/SpikerSoft.Business.CodeExecution/Domain/Lessons/Messaging/LessonRegradeResponse.cs) back to the API's reply queue.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -597,7 +597,7 @@ sequenceDiagram
|
||||
API->>API: Build LessonRegradeRequest<br/>(lessonNumber, attemptToken,<br/>studentCode, testCode, runtime)
|
||||
API->>MQ: publish to lesson.regrade.requests<br/>reply-to = amq.rabbitmq.reply-to
|
||||
MQ->>Worker: deliver request
|
||||
Note over Worker: ILessonGradingExecutorFactory<br/>picks Roslyn / CPython / Node / Regex
|
||||
Note over Worker: ILessonGradingExecutorFactory<br/>picks the executor for that runtime
|
||||
Worker->>Worker: Execute & grade
|
||||
Worker->>MQ: publish LessonRegradeResponse<br/>to API's Direct-Reply queue
|
||||
MQ->>API: deliver response
|
||||
@@ -605,13 +605,13 @@ sequenceDiagram
|
||||
API->>API: Persist progress if AllTestsPassed
|
||||
API->>SPA: 200 OK with per-attempt status
|
||||
else Timeout (worker down / overloaded)
|
||||
API->>SPA: 5xx server_error<br/>(IndexedDB keeps the attempt; SPA retries)
|
||||
API->>SPA: 200 with per-attempt server_error<br/>(IndexedDB keeps the attempt; SPA retries)
|
||||
end
|
||||
```
|
||||
|
||||
**Idempotency.** Each request carries the SPA-generated `attemptToken`. If the worker grades a token, the API records it; if a network blip causes the SPA to retry, the controller short-circuits on the duplicate token rather than re-publishing — so the worker never regrades the same attempt twice.
|
||||
**Idempotency.** Each request carries the SPA-generated `attemptToken`. After a verified pass the API deletes the stored offline attempt, so a replayed token finds no state and is not published again. A timed-out attempt stays stored, and the next flush publishes it again; the worker grades whatever it receives.
|
||||
|
||||
**Timeout handling.** `LessonRegradeClient` enforces a per-call timeout (default 30 s). On expiry, the call throws `TimeoutException`, the controller maps it to HTTP `server_error`, and the SPA leaves the offline attempt in IndexedDB so the next batch flush picks it up. The same attempt token is re-used so the worker still de-dupes correctly when it eventually catches up.
|
||||
**Timeout handling.** `LessonRegradeClient` waits for the worker for the request's 30 s grading cap plus 5 s of RPC overhead. On expiry it throws `TimeoutException`, and the batch endpoint stays HTTP 200 while marking that attempt `server_error`. The SPA leaves the offline attempt in IndexedDB so the next batch flush picks it up, reusing the same attempt token.
|
||||
|
||||
**Same factory, same code.** Both worker consumer paths (live-submit `code.execution.requests` and offline-regrade `lesson.regrade.requests`) dispatch through `ILessonGradingExecutorFactory`. There is no separate "regrade" code path that could drift from the live grader — fixing a hint in `RoslynLessonGradingExecutor` fixes both modes simultaneously.
|
||||
|
||||
|
||||
Reference in new issue
Block a user