Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,10 @@ jobs:
- name: Yarn
run: corepack enable

# `comline-simulator` is a git dependency that compiles to WASM in its
# `prepack` (Rust to wasm-bindgen). The image has cargo, wasm-bindgen and
# wasm-opt; this caches the registry and git checkouts across runs.
# `comline-web-kit` (the playground's simulate view) is a git dependency,
# and so is its engine, `comline-simulator`, which compiles to WASM in
# its `prepack` (Rust to wasm-bindgen). The image has cargo, wasm-bindgen
# and wasm-opt; this caches the registry and git checkouts across runs.
- name: Cache cargo
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
Expand All @@ -57,8 +58,8 @@ jobs:
key: ${{ runner.os }}-${{ runner.arch }}-cargo-${{ hashFiles('yarn.lock') }}
restore-keys: ${{ runner.os }}-${{ runner.arch }}-cargo-

# Yarn Berry's global cache holds the built `comline-simulator`
# archive: a hit skips the Rust build entirely.
# Yarn Berry's global cache holds the packed `comline-web-kit` and the
# built `comline-simulator` archives: a hit skips the Rust build entirely.
- name: Cache yarn
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
Expand All @@ -70,6 +71,7 @@ jobs:
- name: Install dependencies
env:
COMLINE_SIMULATOR_SCRIPT: '0' # the tutorial only needs the lean sim
COMLINE_KIT_EDITOR: '0' # and not the kit's editor WASM
run: yarn install

- name: build
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,6 @@ vite.config.ts.timestamp-*

# JetBrains IDEA settings
.idea/

# Playwright
/test-results
10 changes: 6 additions & 4 deletions .yarnrc.yml
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
yarnPath: .yarn/releases/yarn-4.18.0.cjs
nodeLinker: node-modules

# `comline-simulator` is the sim engine — a git dep that builds itself to WASM
# in its `prepack`/`prepare`. Yarn 4 gates git deps and disables scripts by
# default; both are needed. The build is not byte-reproducible (wasm-opt runs
# only where installed) so let Yarn refresh the tarball checksum.
# `comline-web-kit` (the playground's simulate view, a workspace of the
# playground repo) and `comline-simulator` (its engine) are git deps that
# build in their `prepack`. Yarn 4 gates git deps and disables scripts by
# default; both are needed. The builds are not byte-reproducible (wasm-opt
# runs only where installed) so let Yarn refresh the tarball checksums.
approvedGitRepositories:
- "https://github.com/ComlineProject/playground.git"
- "https://github.com/ComlineProject/simulator.git"
enableScripts: true
checksumBehavior: update
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
"type": "module",
"dependencies": {
"@sveltejs/adapter-static": "^3.0.10",
"comline-simulator": "git+https://github.com/ComlineProject/simulator.git#1eab1f84f1ae7760135ca4a7a519c78091001a44"
"comline-web-kit": "git+https://github.com/ComlineProject/playground.git#workspace=comline-web-kit&commit=fe53d2edcd25cf8bcd77d9f52a3c2ec09d453136"
},
"resolutions": {
"cookie": "^0.7.2",
Expand Down
273 changes: 47 additions & 226 deletions src/lib/sim/Simulation.svelte
Original file line number Diff line number Diff line change
@@ -1,246 +1,67 @@
<script lang="ts">
import { onMount, onDestroy } from 'svelte';
import init, { Sim } from 'comline-simulator';
import wasmUrl from 'comline-simulator/pkg/comline_simulator_bg.wasm?url';
// The "Try it" lesson: the playground's simulate view (comline-web-kit) in
// its lesson layout, on the Chat client and server that chat.lesson.json
// wires together. It opens on the client's calls; clicking the server
// shows what it answers `send` with.
import { createSim, loadSim, type ProjectShape, type SimView } from 'comline-web-kit/sim';
import 'comline-web-kit/sim.css';
import lesson from '$lib/sim/lessons/chat.lesson.json';

interface Frame {
seq: number;
from: string;
to: string;
bytes: number[];
at: number;
kind: string;
}
interface Instance {
id: string;
name: string;
role: 'client' | 'server';
protocol: string;
behaviors: Record<string, { kind: string }>;
}
interface Model {
instances: Instance[];
connections: { id: string; clientId: string; serverId: string }[];
}

const BEHAVIOURS = [
{ kind: 'reply', label: 'reply (a default Message)' },
{ kind: 'echo', label: 'echo (bounce the request back)' },
{ kind: 'drop', label: 'drop (never answer)' }
];

let sim: Sim | null = null;
let model = $state<Model | null>(null);
let frames = $state<Frame[]>([]);
let text = $state('hello');
let result = $state<string | null>(null);
let busy = $state(false);
let loading = $state(true);
let error = $state<string | null>(null);

const client = $derived(model?.instances.find((i) => i.role === 'client') ?? null);
const server = $derived(model?.instances.find((i) => i.role === 'server') ?? null);
const conn = $derived(model?.connections[0] ?? null);
const behaviour = $derived(server?.behaviors['send']?.kind ?? 'reply');

function refresh() {
if (!sim) return;
model = JSON.parse(sim.session_json()) as Model;
const c = model.connections[0];
frames = c ? (JSON.parse(sim.frames(c.id)) as Frame[]) : [];
}

function setBehaviour(kind: string) {
if (!sim || !server) return;
sim.set_behavior(server.id, 'send', kind, '{}');
result = null;
refresh();
}

function send() {
if (!sim || !conn || busy) return;
busy = true;
result = null;
try {
const id = sim.call(conn.id, 'send', JSON.stringify({ text }));
// canned behaviours settle fast; the cap also covers `drop` → timeout
for (let i = 0; i < 400 && sim.pending() > 0; i++) sim.advance(25);
const raw = sim.result(id);
const r = raw ? (JSON.parse(raw) as Record<string, unknown>) : null;
result =
r === null
? 'still in flight'
: r.status === 'ok'
? `reply · ${JSON.stringify(r.value)}`
: r.status === 'err'
? `error ${r.ordinal} · ${JSON.stringify(r.body)}`
: r.status === 'timeout'
? 'timed out — no reply came back'
: String(r.status);
} finally {
busy = false;
refresh();
}
/** Mounts the view into `host` once its engine has loaded. */
function simulation(host: HTMLElement) {
let view: SimView | null = null;
let gone = false;
loadSim()
.then(() => {
if (gone) return;
view = createSim({
layout: 'lesson',
behaviours: ['reply', 'echo', 'drop'],
select: 'chat-2'
});
host.append(view.el);
view.setShape(lesson.shape as ProjectShape, lesson.session);
})
.catch((e) => {
error = `could not start the simulation · ${(e as Error).message ?? e}`;
})
.finally(() => {
loading = false;
});
return {
destroy() {
gone = true;
view?.destroy();
}
};
}

onMount(async () => {
try {
await init({ module_or_path: wasmUrl });
sim = new Sim(JSON.stringify(lesson.shape), lesson.session);
sim.set_call_timeout(2000);
refresh();
} catch (e) {
error = `could not start the simulation · ${(e as Error).message ?? e}`;
}
});

onDestroy(() => sim?.free());
</script>

<div class="sim">
<div class="lesson-sim">
{#if error}
<p class="err">{error}</p>
{:else if !model}
{:else if loading}
<p class="muted">loading the simulation…</p>
{:else}
<div class="wire">
<div class="node client">{client?.name ?? 'client'}<span>{client?.protocol} client</span></div>
<div class="link" class:dropping={behaviour === 'drop'}></div>
<div class="node server">{server?.name ?? 'server'}<span>{server?.protocol} server</span></div>
</div>

<label class="ctl">
server answers <code>send</code> with
<select value={behaviour} onchange={(e) => setBehaviour(e.currentTarget.value)}>
{#each BEHAVIOURS as b (b.kind)}
<option value={b.kind}>{b.label}</option>
{/each}
</select>
</label>

<form
class="ctl call"
onsubmit={(e) => {
e.preventDefault();
send();
}}
>
<code>send</code>(<input bind:value={text} aria-label="text argument" />)
<button type="submit" disabled={busy}>send</button>
</form>

{#if result}
<p class="result">{result}</p>
{/if}

<ol class="frames">
{#each frames as f (f.seq)}
<li>
<span class="seq">{String(f.seq).padStart(2, '0')}</span>
<span class="dir">{f.from} → {f.to}</span>
<span class="kind">{f.kind}</span>
<span class="len">{f.bytes.length} B</span>
</li>
{:else}
<li class="muted">no frames yet — send a call</li>
{/each}
</ol>
{/if}
<div use:simulation></div>
</div>

<style>
.sim {
width: min(100%, 32rem);
/* The tutorial's palette, for the view's --cl-* properties. */
.lesson-sim {
--cl-bg: #1a1714;
--cl-bg-2: #322922;
--cl-fg: #f2e1ca;
--cl-muted: #a8927a;
--cl-accent: #dbb594;
--cl-border: #614a39;

width: min(100%, 40rem);
margin: 1rem auto;
padding: 0.9rem;
text-align: left;
border-style: ridge;
border-color: #614a39;
}
.wire {
display: flex;
align-items: center;
gap: 0.5rem;
margin-bottom: 0.9rem;
}
.node {
flex: 1;
display: flex;
flex-direction: column;
align-items: center;
padding: 0.5rem;
background-color: #322922;
color: #dbb594;
border-style: ridge;
border-color: #4d3c2f;
}
.node span {
font-size: 0.75rem;
opacity: 0.7;
}
.link {
flex: 0 0 2.5rem;
height: 2px;
background: #dbb594;
}
.link.dropping {
background: repeating-linear-gradient(90deg, #dbb594 0 4px, transparent 4px 8px);
}
.ctl {
display: block;
margin: 0.5rem 0;
}
.ctl.call {
display: flex;
align-items: center;
gap: 0.3rem;
flex-wrap: wrap;
}
.ctl input {
flex: 1;
min-width: 6rem;
}
select,
input,
button {
font: inherit;
}
button {
padding: 0.2rem 0.8rem;
background-color: #322922;
color: #dbb594;
border-color: #4d3c2f;
border-style: ridge;
cursor: pointer;
}
button:disabled {
opacity: 0.5;
cursor: default;
}
.result {
margin: 0.5rem 0;
padding: 0.4rem 0.6rem;
background: #2a211d;
color: #dbb594;
}
.frames {
list-style: none;
margin: 0.6rem 0 0;
padding: 0;
font-size: 0.85rem;
}
.frames li {
display: flex;
gap: 0.6rem;
padding: 0.15rem 0;
border-top: 1px solid #4d3c2f;
}
.frames .seq {
opacity: 0.6;
}
.frames .len {
margin-left: auto;
opacity: 0.6;
}
.muted {
opacity: 0.6;
Expand Down
13 changes: 7 additions & 6 deletions src/routes/part-1_introduction/sect-3_try-it/+page.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,19 @@
<TutorialPage previous_url={pageUrl('p1-s2')} next_url={pageUrl('p1-s4')}>
<h2>Try it</h2>
<p>
Below is a Chat client and server, both generated from the same schema and wired together. Send a
call and watch it serialise, cross the connection, get dispatched, and come back.
Below is a Chat client and server, both generated from the same schema and wired together. Send
a call from the client and watch it serialise, cross the connection, get dispatched, and come
back.
</p>
<p>
Change what the server does with <code>send</code> — reply, echo the request straight back, or
drop it and let the client time out.
Click the server to change what it does with <code>send</code>: reply, echo the request straight
back, or drop it and let the client time out.
</p>

<Simulation />

<p>
This is the real runtime: the same framing, envelope and dispatch the generated code uses, run in
your browser as WebAssembly.
This is the real runtime: the same framing, envelope and dispatch the generated code uses, run
in your browser as WebAssembly.
</p>
</TutorialPage>
Loading
Loading