diff options
Diffstat (limited to 'modules/swarm')
| -rw-r--r-- | modules/swarm/.nix/derivation.nix | 38 | ||||
| -rw-r--r-- | modules/swarm/SConstruct | 75 | ||||
| -rw-r--r-- | modules/swarm/c++/SConscript | 27 | ||||
| -rw-r--r-- | modules/swarm/c++/capability.hpp | 199 | ||||
| -rw-r--r-- | modules/swarm/c++/capacity.hpp | 236 | ||||
| -rw-r--r-- | modules/swarm/c++/interpret.hpp | 113 | ||||
| -rw-r--r-- | modules/swarm/c++/message.hpp | 140 | ||||
| -rw-r--r-- | modules/swarm/c++/probe_search.hpp | 198 | ||||
| -rw-r--r-- | modules/swarm/c++/registry.hpp | 427 | ||||
| -rw-r--r-- | modules/swarm/c++/run.hpp | 193 | ||||
| -rw-r--r-- | modules/swarm/c++/signal.hpp | 52 | ||||
| -rw-r--r-- | modules/swarm/c++/swarm.hpp | 11 | ||||
| -rw-r--r-- | modules/swarm/c++/wire.hpp | 119 | ||||
| -rw-r--r-- | modules/swarm/tests/SConscript | 32 | ||||
| -rw-r--r-- | modules/swarm/tests/capacity.cpp | 234 | ||||
| -rw-r--r-- | modules/swarm/tests/interpret.cpp | 133 | ||||
| -rw-r--r-- | modules/swarm/tests/probe_search.cpp | 202 | ||||
| -rw-r--r-- | modules/swarm/tests/registry.cpp | 298 | ||||
| -rw-r--r-- | modules/swarm/tests/run.cpp | 158 | ||||
| -rw-r--r-- | modules/swarm/tests/signal.cpp | 82 | ||||
| -rw-r--r-- | modules/swarm/tests/wire.cpp | 381 |
21 files changed, 3348 insertions, 0 deletions
diff --git a/modules/swarm/.nix/derivation.nix b/modules/swarm/.nix/derivation.nix new file mode 100644 index 0000000..afd07ef --- /dev/null +++ b/modules/swarm/.nix/derivation.nix @@ -0,0 +1,38 @@ +{ lib +, stdenv +, scons +, clang-tools +, forstio +, pname +, version +, kel +}: + +stdenv.mkDerivation { + pname = "${pname}-swarm"; + inherit version; + src = ./..; + + nativeBuildInputs = [ + scons + clang-tools + ]; + + # The module itself is forstio free -- it is schemas and arithmetic. forstio + # is here only for the test runner, exactly as in modules/core. + buildInputs = [ + forstio.core + kel.lbm.core + ]; + + doCheck = true; + + checkPhase = '' + scons test + ./bin/tests + ''; + + preferLocalBuild = true; + + outputs = [ "out" "dev" ]; +} diff --git a/modules/swarm/SConstruct b/modules/swarm/SConstruct new file mode 100644 index 0000000..089305e --- /dev/null +++ b/modules/swarm/SConstruct @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 + +import sys +import os +import os.path +import glob +import re + + +if sys.version_info < (3,): + def isbasestring(s): + return isinstance(s,basestring) +else: + def isbasestring(s): + return isinstance(s, (str,bytes)) + +def add_kel_source_files(self, sources, filetype, lib_env=None, shared=False, target_post=""): + + if isbasestring(filetype): + dir_path = self.Dir('.').abspath + filetype = sorted(glob.glob(dir_path+"/"+filetype)) + + for path in filetype: + target_name = re.sub( r'(.*?)(\.cpp|\.c\+\+)', r'\1' + target_post, path ) + if shared: + target_name+='.os' + sources.append( self.SharedObject( target=target_name, source=path ) ) + else: + target_name+='.o' + sources.append( self.StaticObject( target=target_name, source=path ) ) + pass + +def isAbsolutePath(key, dirname, env): + assert os.path.isabs(dirname), "%r must have absolute path syntax" % (key,) +env_vars = Variables( + args=ARGUMENTS +) + +env_vars.Add('prefix', + help='Installation target location of build results and headers', + default='/usr/local/', + validator=isAbsolutePath +) + +env=Environment(ENV=os.environ, variables=env_vars, CPPPATH=[], + CPPDEFINES=['SAW_UNIX'], + CXXFLAGS=[ + '-std=c++20', + '-g', + '-Wall', + '-Wextra' + ], + LIBS=[ + 'forstio-core' + ] +); +env.__class__.add_source_files = add_kel_source_files +env.Tool('compilation_db'); +env.cdb = env.CompilationDatabase('compile_commands.json'); + +env.objects = []; +env.sources = []; +env.headers = []; +env.targets = []; + +Export('env') +SConscript('c++/SConscript') +SConscript('tests/SConscript') + +env.Alias('cdb', env.cdb); +env.Alias('all', [env.targets]); +env.Default('all'); + + +env.Alias('install', '$prefix') diff --git a/modules/swarm/c++/SConscript b/modules/swarm/c++/SConscript new file mode 100644 index 0000000..4071add --- /dev/null +++ b/modules/swarm/c++/SConscript @@ -0,0 +1,27 @@ +#!/bin/false + +import os +import os.path +import glob + + +Import('env') + +dir_path = Dir('.').abspath + +swarm_env = env.Clone(); + +swarm_env.sources = sorted(glob.glob(dir_path + "/*.cpp")); +swarm_env.headers = sorted(glob.glob(dir_path + "/*.hpp")); + +env.sources += swarm_env.sources; +env.headers += swarm_env.headers; + +# Header only, like core. The StaticLibrary exists so dependents have something +# to name; it is built from zero translation units. +objects = [] +swarm_env.add_source_files(objects, swarm_env.sources, shared=False); +env.library_static = swarm_env.StaticLibrary('#build/kel-lbm-swarm', [objects]); + +env.Install('$prefix/lib/', env.library_static); +env.Install('$prefix/include/kel/lbm/swarm/', swarm_env.headers); diff --git a/modules/swarm/c++/capability.hpp b/modules/swarm/c++/capability.hpp new file mode 100644 index 0000000..8497969 --- /dev/null +++ b/modules/swarm/c++/capability.hpp @@ -0,0 +1,199 @@ +#pragma once + +#include <kel/lbm/abstract/schema.hpp> + +/** + * What a worker tells the orchestrator about itself. + * + * The envelope is deliberately backend agnostic: common fields, then one + * section named by "kind". Browsers running WebGL2 and native processes are + * both first class worker kinds, and the swarm is meant to take WebGPU runners + * later; a string tag survives version skew where a positional format does not. + * + * A worker of another kind carries its own section instead. Nothing has to + * carry a section it has no business describing, because each kind gets its own + * full capability type -- see CapabilityOf below and the hello variants in + * message.hpp. + */ +namespace kel { +namespace lbm { +namespace sch { + +/** + * Queryable WebGL2 limits, straight from glGetIntegerv. + * + * Worth knowing which of these actually bind. max_draw_buffers and + * max_color_attachments are guaranteed to be only 4, and since a D2Q9 lattice + * needs ceil(9/4) = 3 render targets they are the limits that decide whether a + * descriptor fits in a single pass at all. The rest are either generous in + * practice or bound by memory long before they bind by count. + */ +using GlLimits = Struct< + Member<UInt32, "max_texture_size">, + Member<UInt32, "max_3d_texture_size">, + Member<UInt32, "max_array_texture_layers">, + Member<UInt32, "max_draw_buffers">, + Member<UInt32, "max_color_attachments">, + Member<UInt32, "max_texture_image_units">, + Member<UInt32, "max_combined_texture_image_units">, + Member<UInt32, "max_renderbuffer_size">, + Member<UInt32, "max_fragment_uniform_vectors">, + Member<FixedArray<UInt32, 2u>, "max_viewport_dims"> +>; + +/** + * Extension and context properties. + * + * color_buffer_float is a hard gate: without EXT_color_buffer_float a float + * texture is not color renderable and there is no f32 solver on this device at + * all. The others are reported so the orchestrator can decide, not so the + * worker can. + */ +using GlFeatures = Struct< + Member<Bool, "webgl2">, + Member<Bool, "offscreen_canvas">, + Member<Bool, "color_buffer_float">, + Member<Bool, "color_buffer_half_float">, + Member<Bool, "texture_float_linear">, + Member<Bool, "float_blend">, + Member<Bool, "parallel_shader_compile">, + Member<Bool, "disjoint_timer_query"> +>; + +/** + * What the worker measured, as opposed to what it was told. + * + * There is no queryable "available VRAM" in WebGL2 -- navigator.deviceMemory is + * system RAM and unrelated -- and max_texture_size overstates capacity by + * roughly a hundredfold on a typical desktop. So these come from an actual + * allocation trial. + * + * probed_bytes_max is the largest allocation that survived; probed_bytes_safe + * applies safety_factor to leave room for the canvas, the compositor and other + * tabs. Both are reported so the orchestrator can apply its own policy rather + * than inheriting the worker's. + * + * probe_hit_texture_size_bound distinguishes "ran out of memory" from "ran into + * max_texture_size", which are very different signals about a device. + */ +using GlBudget = Struct< + Member<UInt64, "probed_bytes_max">, + Member<UInt64, "probed_bytes_safe">, + Member<UInt32, "probe_trials">, + Member<Bool, "context_lost_during_probe">, + Member<Bool, "probe_hit_texture_size_bound">, + Member<Float32, "safety_factor"> +>; + +/** + * One feasible way to lay a lattice out in textures on this device. + * + * This type has three jobs and keeping it as one type is what stops them + * drifting: it is an element of the capability report, it is the assignment + * message the orchestrator sends back, and it is the input to the shader + * preamble generator. + * + * The slot tables are the indirection that makes pixel stuffing expressible -- + * slot_tex_of_q[i] / slot_cmp_of_q[i] say which texture and which channel + * direction i lives in, and the aux tables do the same for the non + * distribution fields packed into otherwise idle slots. + */ +using PackingPlan = Struct< + Member<String, "layout">, + Member<String, "aux_mode">, + Member<UInt8, "d">, + Member<UInt8, "q">, + Member<UInt8, "ghost">, + Member<UInt8, "storage_bits">, + Member<UInt8, "slots_per_texel">, + Member<UInt8, "textures_df">, + Member<UInt8, "textures_aux">, + Member<UInt8, "states">, + Member<UInt8, "passes">, + Member<UInt8, "idle_slots">, + Member<FixedArray<UInt32, 3u>, "domain">, + Member<FixedArray<UInt32, 2u>, "tiles">, + Member<Bool, "tiles_pow2">, + Member<FixedArray<UInt32, 2u>, "texture_size">, + Member<UInt64, "bytes_total">, + Member<UInt64, "bytes_useful">, + Member<Array<UInt8, 1u>, "slot_tex_of_q">, + Member<Array<UInt8, 1u>, "slot_cmp_of_q">, + Member<Array<UInt8, 1u>, "slot_tex_of_aux">, + Member<Array<UInt8, 1u>, "slot_cmp_of_aux">, + Member<Array<String, 1u>, "aux_names"> +>; + +using WebGl2Capability = Struct< + Member<GlLimits, "limits">, + Member<GlFeatures, "features">, + Member<GlBudget, "budget">, + Member<Array<PackingPlan, 1u>, "feasible"> +>; + +/** + * A worker that is a process rather than a browser tab. + * + * Native workers are not only a test fixture -- they are a worker kind in their + * own right, and the orchestrator should be able to hand them real work. What + * they report is correspondingly different: there is no texture budget to probe + * because there are no textures, so the interesting numbers are threads and + * addressable memory. + */ +using NativeCapability = Struct< + Member<UInt32, "threads">, + Member<UInt64, "memory_bytes">, + Member<String, "cpu">, + Member<Bool, "has_sycl"> +>; + +/** + * The part every worker reports, whatever it is. + * + * This is deliberately the *whole* type rather than a prefix of a larger one. + * Decoding runs strict, so a struct naming every backend section would oblige a + * browser to describe a CPU and a native process to describe a texture budget. + * Instead the common part stands alone and is enough to route on: decode this, + * read "kind", then decode again as the matching full type below. The backend + * section is skipped on the first pass because unknown keys always are. + */ +using WorkerCapability = Struct< + Member<String, "worker_id">, + Member<String, "kind">, + Member<String, "schema_version">, + Member<UInt64, "reported_at_ms">, + Member<String, "user_agent"> +>; + +/** + * The common part plus exactly one backend section. One alias per kind, so + * adding a kind never widens what the existing ones have to fill in. + */ +template <typename Section, string_literal Key> +using CapabilityOf = Struct< + Member<String, "worker_id">, + Member<String, "kind">, + Member<String, "schema_version">, + Member<UInt64, "reported_at_ms">, + Member<String, "user_agent">, + Member<Section, Key> +>; + +using WebGl2WorkerCapability = CapabilityOf<WebGl2Capability, "webgl2">; +using NativeWorkerCapability = CapabilityOf<NativeCapability, "native">; + +/** + * The small, frequently resent part: enough to monitor a worker without + * re-sending its capability. Rides along on pong so a heartbeat doubles as a + * status update. + */ +using WorkerLive = Struct< + Member<String, "state">, + Member<UInt64, "uptime_ms">, + Member<UInt64, "steps_done">, + Member<String, "last_error"> +>; + +} // namespace sch +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/capacity.hpp b/modules/swarm/c++/capacity.hpp new file mode 100644 index 0000000..4073405 --- /dev/null +++ b/modules/swarm/c++/capacity.hpp @@ -0,0 +1,236 @@ +#pragma once + +#include <cstdint> + +/** + * How much lattice fits on a worker. + * + * This is pure arithmetic over a descriptor's Q and a device's reported limits, + * with no GL and no schema, which is the point: the orchestrator needs it to + * size assignments, the worker needs it to drive its allocation trial, and + * neither reason is a good one to make it untestable without a browser. + * + * Everything is constexpr so the ceilings can be asserted at compile time + * against a descriptor rather than discovered on a device that happens to be + * minimum spec. + */ +namespace kel { +namespace lbm { +namespace swarm { + +/** + * A WebGL2 implementation is only *guaranteed* these. Real desktop values are + * far higher, but a plan that relies on more than this is a plan that works on + * the developer's machine. + */ +struct webgl2_guaranteed { + static constexpr uint32_t max_texture_size = 2048u; + static constexpr uint32_t max_3d_texture_size = 256u; + static constexpr uint32_t max_array_texture_layers = 256u; + static constexpr uint32_t max_draw_buffers = 4u; + static constexpr uint32_t max_color_attachments = 4u; + static constexpr uint32_t max_texture_image_units = 16u; +}; + +/** + * Packing a Q-direction lattice into RGBA textures. + * + * One texel holds four scalars, so a descriptor needs ceil(Q/4) textures and + * wastes whatever is left over. The leftovers are not merely waste: the aux + * fields (the per cell info flag, later the particle fields) can be stuffed + * into them, which is why idle_slots is reported rather than just computed. + */ +struct packing_math { + static constexpr uint64_t slots_per_texel = 4u; + + static constexpr uint64_t planes(uint64_t q){ + return (q + slots_per_texel - 1u) / slots_per_texel; + } + + static constexpr uint64_t idle_slots(uint64_t q){ + return planes(q) * slots_per_texel - q; + } + + /** + * Aux planes needed once the idle slots have been used. Stuffing only + * works when the leftovers are big enough; D2Q9 has three idle slots, so + * a single info flag fits but the four fields a PSM run wants do not. + */ + static constexpr uint64_t aux_planes(uint64_t q, uint64_t aux_scalars, + bool stuffed){ + if(stuffed and aux_scalars <= idle_slots(q)){ + return 0u; + } + return (aux_scalars + slots_per_texel - 1u) / slots_per_texel; + } + + static constexpr uint64_t bytes_per_texel(uint64_t storage_bits){ + return slots_per_texel * storage_bits / 8u; + } + + /** + * Distributions are double buffered for the ping pong; aux fields are not, + * since nothing writes them during a step. + */ + static constexpr uint64_t bytes_per_cell(uint64_t q, uint64_t states, + uint64_t aux_scalars, bool stuffed, + uint64_t storage_bits = 32u){ + const uint64_t tex = states * planes(q) + aux_planes(q, aux_scalars, stuffed); + return tex * bytes_per_texel(storage_bits); + } + + /** + * Render targets needed per pass, against what the device allows. + * + * This is the limit that actually decides whether a descriptor is usable. + * Collision couples every direction, so a multi-pass split has to re-read + * all planes and recompute rho and u in each pass -- roughly double the + * arithmetic for the same bandwidth. Worth detecting rather than + * stumbling into. + */ + static constexpr uint64_t passes(uint64_t q, uint64_t mrt){ + if(mrt == 0u){ + return 0u; + } + return (planes(q) + mrt - 1u) / mrt; + } + + static constexpr bool fits_single_pass(uint64_t q, uint64_t mrt){ + return passes(q, mrt) == 1u; + } +}; + +/** + * Integer square root by bisection. + * + * std::sqrt is not constexpr before C++26 and this has to run at compile time + * for the ceiling assertions. Exactness also matters more than speed here: a + * domain edge that rounds up by one costs a whole row of cells against a + * budget that was measured, not guessed. + */ +constexpr uint64_t isqrt(uint64_t value){ + if(value < 2u){ + return value; + } + + uint64_t low = 1u; + uint64_t high = (value / 2u) + 1u; + + while(low < high){ + const uint64_t mid = low + (high - low + 1u) / 2u; + if(mid <= value / mid){ + low = mid; + } else { + high = mid - 1u; + } + } + + return low; +} + +/** + * A 2D domain and what it costs. + */ +struct domain_2d { + uint64_t nx; + uint64_t ny; + + constexpr uint64_t cells() const { return nx * ny; } +}; + +struct capacity_math { + /** + * Cells the texture dimension allows, independent of memory. + * + * On a typical desktop this is around a hundred times looser than what + * memory actually permits, which is exactly why the worker measures + * instead of trusting it -- but it is still a hard ceiling and a worker + * that hits *this* one is telling you something different about itself + * than a worker that ran out of memory. + */ + static constexpr uint64_t texture_bound_cells_2d(uint64_t max_texture_size, + uint64_t ghost){ + const uint64_t pad = 2u * ghost; + if(max_texture_size <= pad){ + return 0u; + } + const uint64_t edge = max_texture_size - pad; + return edge * edge; + } + + static constexpr uint64_t cells_from_bytes(uint64_t bytes, + uint64_t bytes_per_cell){ + if(bytes_per_cell == 0u){ + return 0u; + } + return bytes / bytes_per_cell; + } + + static constexpr uint64_t max_cells_2d(uint64_t budget_bytes, + uint64_t bytes_per_cell, + uint64_t max_texture_size, + uint64_t ghost){ + const uint64_t by_memory = cells_from_bytes(budget_bytes, bytes_per_cell); + const uint64_t by_texture = texture_bound_cells_2d(max_texture_size, ghost); + return (by_memory < by_texture) ? by_memory : by_texture; + } + + /** + * Largest domain of a given aspect ratio that fits in a cell count. + * + * Aspect arrives as a ratio of integers rather than a float so the result + * is reproducible across the orchestrator and the worker; they must agree + * exactly or an assignment will not fit the allocation the worker made. + * + * Rounds down on both axes, and clamps each edge to what the texture + * dimension allows, so the answer is always feasible rather than merely + * close. + */ + static constexpr domain_2d fit_domain_2d(uint64_t cells, + uint64_t aspect_num, + uint64_t aspect_den, + uint64_t max_texture_size, + uint64_t ghost){ + if(cells == 0u or aspect_num == 0u or aspect_den == 0u){ + return domain_2d{0u, 0u}; + } + + // ny = sqrt(cells * den / num), nx = ny * num / den + uint64_t ny = isqrt((cells * aspect_den) / aspect_num); + if(ny == 0u){ + ny = 1u; + } + uint64_t nx = (ny * aspect_num) / aspect_den; + if(nx == 0u){ + nx = 1u; + } + + const uint64_t pad = 2u * ghost; + const uint64_t edge = (max_texture_size > pad) ? (max_texture_size - pad) : 0u; + if(edge == 0u){ + return domain_2d{0u, 0u}; + } + if(nx > edge){ + nx = edge; + } + if(ny > edge){ + ny = edge; + } + + // Rounding up through the aspect ratio can overshoot the budget by a + // row; give the row back rather than hand out a domain that does not + // fit the measurement. + while(nx * ny > cells and ny > 1u){ + --ny; + } + while(nx * ny > cells and nx > 1u){ + --nx; + } + + return domain_2d{nx, ny}; + } +}; + +} // namespace swarm +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/interpret.hpp b/modules/swarm/c++/interpret.hpp new file mode 100644 index 0000000..1b2dcfa --- /dev/null +++ b/modules/swarm/c++/interpret.hpp @@ -0,0 +1,113 @@ +#pragma once + +#include "capability.hpp" +#include "capacity.hpp" + +#include <kel/lbm/abstract/data.hpp> + +#include <cstdint> +#include <iomanip> +#include <sstream> +#include <string> + +/** + * Turning a reported capability into the one number the orchestrator needs: + * how much lattice this worker can hold. + * + * Quoted in D2Q9 cells so worker kinds are directly comparable. A browser's + * figure comes from its measured texture budget; a native worker's from + * addressable memory. Neither is a promise -- both ignore everything else + * happening on the machine -- but a planning figure that means the same thing + * across kinds is what makes a heterogeneous registry useful rather than + * decorative. + * + * Here rather than in the orchestrator because it is pure and therefore worth + * testing, and because the browser worker may eventually want to reason about + * its own capacity the same way the orchestrator does. + */ +namespace kel { +namespace lbm { +namespace swarm { + +/** + * The reference packing every capacity figure is quoted in: D2Q9, double + * buffered, the info flag stuffed into an idle slot. 96 bytes per cell. + */ +constexpr uint64_t reference_bytes_per_cell(){ + return packing_math::bytes_per_cell(9u, 2u, 1u, true); +} + +namespace impl { + +inline std::string human_bytes(uint64_t bytes){ + std::ostringstream oss; + oss << std::fixed << std::setprecision(1); + + if(bytes >= (1ull << 30)){ + oss << (static_cast<double>(bytes) / static_cast<double>(1ull << 30)) + << " GiB"; + } else if(bytes >= (1ull << 20)){ + oss << (static_cast<double>(bytes) / static_cast<double>(1ull << 20)) + << " MiB"; + } else { + oss << bytes << " B"; + } + + return oss.str(); +} + +} // namespace impl + +inline uint64_t webgl2_capacity_cells(const data<sch::WebGl2Capability> &cap){ + const uint64_t budget = cap.get<"budget">().get<"probed_bytes_safe">().get(); + const uint64_t max_tex = cap.get<"limits">().get<"max_texture_size">().get(); + + // Both bounds, tighter wins -- a worker can be limited by either, and + // which one it is says something different about the device. + return capacity_math::max_cells_2d(budget, reference_bytes_per_cell(), + max_tex, 0u); +} + +inline uint64_t native_capacity_cells(const data<sch::NativeCapability> &cap){ + const uint64_t memory = cap.get<"memory_bytes">().get(); + + // No texture dimension to bind against, so memory is the only limit. Take + // a quarter of it: the rest of the machine exists. + return capacity_math::cells_from_bytes(memory / 4u, + reference_bytes_per_cell()); +} + +inline std::string webgl2_summary(const data<sch::WebGl2Capability> &cap){ + std::ostringstream oss; + + oss << "tex " << cap.get<"limits">().get<"max_texture_size">().get() + << ", mrt " << cap.get<"limits">().get<"max_draw_buffers">().get() + << ", budget " << impl::human_bytes( + cap.get<"budget">().get<"probed_bytes_safe">().get()); + + if(not cap.get<"features">().get<"color_buffer_float">().get()){ + // Without this there is no float render target and so no solver at + // all. Worth shouting about rather than leaving to be inferred. + oss << " [NO FLOAT RENDER]"; + } + + return oss.str(); +} + +inline std::string native_summary(const data<sch::NativeCapability> &cap){ + std::ostringstream oss; + + oss << cap.get<"threads">().get() << " threads, " + << impl::human_bytes(cap.get<"memory_bytes">().get()) + << ", " << cap.get<"cpu">().stl_string(); + + if(cap.get<"has_sycl">().get()){ + oss << ", sycl"; + } + + return oss.str(); +} + +} // namespace swarm +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/message.hpp b/modules/swarm/c++/message.hpp new file mode 100644 index 0000000..aba5a9c --- /dev/null +++ b/modules/swarm/c++/message.hpp @@ -0,0 +1,140 @@ +#pragma once + +#include "capability.hpp" + +#include <string_view> + +/** + * The worker/orchestrator control protocol. + * + * Every message is a JSON object carrying the same three leading members -- + * "type", "worker_id", "seq" -- followed by whatever that type adds. Decoding + * happens in two stages (see wire.hpp): read MsgHeader to learn the type, then + * decode the full typed struct. + * + * The reason the protocol is shaped this way rather than as a tagged union is + * that sch::Union has no JSON codec. It turns out not to matter: the Struct + * decoder skips keys it does not recognise, so reading a header out of a full + * message is well defined and costs one extra parse of a short string. + * + * A versioning note that the strictness buys and charges for. Wire codecs run + * strict, so a *missing* member is an error while an *unknown* member is + * ignored. That means a newer sender talking to an older receiver is fine, but + * an older sender talking to a newer receiver fails as soon as the newer side + * adds a member. Adding a field to a message is therefore a breaking change in + * one direction, which is what schema_version in the hello/welcome exchange is + * for -- catch the mismatch deliberately instead of discovering it as a + * confusing decode error. + */ +namespace kel { +namespace lbm { + +namespace sch { + +/** + * Prepends the common members so each message type only states what it adds. + */ +template <typename... Members> +using Envelope = Struct< + Member<String, "type">, + Member<String, "worker_id">, + Member<UInt64, "seq">, + Members... +>; + +/// Just the common members. Decoded first to learn which type follows. +using MsgHeader = Envelope<>; + +/** + * worker -> orchestrator. First message on the channel. + * + * MsgHello carries only the common capability fields, which is enough to learn + * the worker kind. Decode it first, read capability.kind, then decode the same + * text again as the matching variant below -- the backend section is skipped on + * the first pass because unknown keys always are. + * + * The alternative, one hello naming every backend section, does not work: wire + * codecs run strict, so it would oblige a browser to describe a CPU. + */ +using MsgHello = Envelope<Member<WorkerCapability, "capability">>; + +using MsgHelloWebGl2 = Envelope<Member<WebGl2WorkerCapability, "capability">>; +using MsgHelloNative = Envelope<Member<NativeWorkerCapability, "capability">>; + +/// orchestrator -> worker. Confirms registration and sets the heartbeat pace. +using MsgWelcome = Envelope< + Member<UInt64, "heartbeat_ms">, + Member<String, "schema_version"> +>; + +/// orchestrator -> worker. +using MsgPing = Envelope<Member<UInt64, "sent_at_ms">>; + +/** + * worker -> orchestrator. Echoes sent_at_ms so round trip time is measured + * against the orchestrator's own clock and the two machines never have to agree + * on what time it is. + */ +using MsgPong = Envelope< + Member<UInt64, "sent_at_ms">, + Member<UInt64, "worker_now_ms">, + Member<WorkerLive, "live"> +>; + +/// worker -> orchestrator. Initialised and idle. +using MsgReady = Envelope<Member<WorkerLive, "live">>; + +/// worker -> orchestrator. Unsolicited: a state change or an error. +using MsgStatus = Envelope<Member<WorkerLive, "live">>; + +} // namespace sch + +/** + * Wire values for the "type" member. + * + * Deliberately strings rather than an integer enum: the orchestrator and the + * worker are built from the same source today but will not always be, and a + * string tag misread is a routing failure you can see in a log, where an + * integer tag misread is a silently wrong payload. + */ +namespace msg { +inline constexpr std::string_view hello = "hello"; +inline constexpr std::string_view welcome = "welcome"; +inline constexpr std::string_view ping = "ping"; +inline constexpr std::string_view pong = "pong"; +inline constexpr std::string_view ready = "ready"; +inline constexpr std::string_view status = "status"; + +/// orchestrator -> everyone. A run begins or ends. +inline constexpr std::string_view run_start = "run_start"; +inline constexpr std::string_view run_end = "run_end"; +} // namespace msg + +/** + * Values for WorkerLive's "state". The orchestrator owns stale and gone -- a + * worker never reports those about itself, they are conclusions drawn from + * missed heartbeats. + */ +namespace wstate { +inline constexpr std::string_view registered = "registered"; +inline constexpr std::string_view ready = "ready"; +inline constexpr std::string_view busy = "busy"; +inline constexpr std::string_view error = "error"; +inline constexpr std::string_view stale = "stale"; +inline constexpr std::string_view gone = "gone"; +} // namespace wstate + +/** + * Bumped whenever a message or capability schema changes shape. Compared on + * hello/welcome so a mismatch is reported rather than hit as a decode failure. + */ +inline constexpr std::string_view schema_version = "1"; + +/// Worker kinds, the tag selecting which capability section is populated. +namespace wkind { +inline constexpr std::string_view webgl2 = "webgl2"; +inline constexpr std::string_view native = "native"; +} // namespace wkind + +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/probe_search.hpp b/modules/swarm/c++/probe_search.hpp new file mode 100644 index 0000000..f678937 --- /dev/null +++ b/modules/swarm/c++/probe_search.hpp @@ -0,0 +1,198 @@ +#pragma once + +#include <cstdint> + +/** + * Finding out how much a device will actually give you. + * + * WebGL2 reports limits but not capacity. MAX_TEXTURE_SIZE on a typical desktop + * implies something like 25 GB of lattice, roughly a hundred times what the GPU + * will really hand over, and there is no query for the real figure -- + * navigator.deviceMemory is system RAM and unrelated. So capacity is measured: + * try an allocation, see whether it survives, adjust. + * + * The strategy lives here rather than next to the GL calls because it is + * ordinary arithmetic and deserves to be tested as such. The caller owns the + * part that cannot be tested without a browser -- actually allocating -- and + * feeds the answers back in: + * + * allocation_search search{cfg}; + * while(not search.done()){ + * search.report(try_allocate(search.candidate())); + * } + * use(search.best_cells()); + * + * Grow by doubling until something fails, then bisect. Doubling finds the right + * order of magnitude in a handful of steps even when devices differ by a factor + * of a thousand; bisecting then tightens it without the linear crawl a pure + * step search would need. + */ +namespace kel { +namespace lbm { +namespace swarm { + +class allocation_search { +public: + struct config { + /** + * First attempt. Deliberately small: the opening trial should succeed + * on anything that can run at all, because a failure here means the + * device is unusable rather than merely modest. + */ + uint64_t start_cells = 65536u; + + /** + * Hard ceiling from the texture dimension, in cells. Zero means no + * ceiling. Reaching it is a different answer from running out of + * memory and is reported separately. + */ + uint64_t ceiling_cells = 0u; + + /// Bisection steps once a failure has bracketed the answer. Four gets + /// within about a sixteenth of the bracket, which is finer than the + /// figure deserves given it is a moving target anyway. + uint64_t bisect_steps = 4u; + + /// Backstop so a device that answers inconsistently cannot spin. + uint64_t max_trials = 32u; + }; + + explicit allocation_search(config cfg) : cfg_{cfg} { + candidate_ = cfg_.start_cells; + + if(cfg_.ceiling_cells > 0u and candidate_ > cfg_.ceiling_cells){ + candidate_ = cfg_.ceiling_cells; + } + + if(candidate_ == 0u){ + phase_ = phase::finished; + } + } + + bool done() const { return phase_ == phase::finished; } + + /// The cell count to attempt next. Meaningless once done(). + uint64_t candidate() const { return candidate_; } + + /// Largest allocation that survived. Zero means nothing did. + uint64_t best_cells() const { return best_; } + + uint64_t trials() const { return trials_; } + + /** + * True when the search stopped because the texture dimension ran out + * rather than because memory did. Worth distinguishing: one says the + * device is small, the other says it is oddly shaped. + */ + bool hit_ceiling() const { return hit_ceiling_; } + + void report(bool ok){ + if(phase_ == phase::finished){ + return; + } + + ++trials_; + + if(phase_ == phase::grow){ + report_grow(ok); + } else { + report_bisect(ok); + } + + if(trials_ >= cfg_.max_trials){ + phase_ = phase::finished; + } + } + +private: + enum class phase { grow, bisect, finished }; + + void report_grow(bool ok){ + if(not ok){ + failed_at_ = candidate_; + + if(best_ == 0u){ + // Even the opening attempt failed. There is nothing to + // bisect between, and the honest answer is zero. + phase_ = phase::finished; + return; + } + + phase_ = phase::bisect; + advance_bisect(); + return; + } + + best_ = candidate_; + + if(cfg_.ceiling_cells > 0u and candidate_ >= cfg_.ceiling_cells){ + // The texture dimension, not memory, is what stopped us. + hit_ceiling_ = true; + phase_ = phase::finished; + return; + } + + uint64_t next = candidate_ * 2u; + if(next < candidate_){ + // Overflow. Nothing sane gets here, but silently wrapping to a + // tiny candidate would turn a huge device into a small one. + phase_ = phase::finished; + return; + } + if(cfg_.ceiling_cells > 0u and next > cfg_.ceiling_cells){ + next = cfg_.ceiling_cells; + } + if(next == candidate_){ + phase_ = phase::finished; + return; + } + + candidate_ = next; + } + + void report_bisect(bool ok){ + if(ok){ + best_ = candidate_; + } else { + failed_at_ = candidate_; + } + advance_bisect(); + } + + void advance_bisect(){ + if(bisects_done_ >= cfg_.bisect_steps){ + phase_ = phase::finished; + return; + } + if(failed_at_ <= best_ + 1u){ + // Bracket closed; there is nothing left between them. + phase_ = phase::finished; + return; + } + + const uint64_t mid = best_ + ((failed_at_ - best_) / 2u); + if(mid == best_ or mid == failed_at_){ + phase_ = phase::finished; + return; + } + + candidate_ = mid; + ++bisects_done_; + } + + config cfg_; + + phase phase_ = phase::grow; + uint64_t candidate_ = 0u; + /// Largest known good. + uint64_t best_ = 0u; + /// Smallest known bad. + uint64_t failed_at_ = 0u; + uint64_t trials_ = 0u; + uint64_t bisects_done_ = 0u; + bool hit_ceiling_ = false; +}; + +} // namespace swarm +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/registry.hpp b/modules/swarm/c++/registry.hpp new file mode 100644 index 0000000..6159a72 --- /dev/null +++ b/modules/swarm/c++/registry.hpp @@ -0,0 +1,427 @@ +#pragma once + +#include "capability.hpp" + +#include <kel/lbm/abstract/data.hpp> + +#include <cstdint> +#include <iomanip> +#include <map> +#include <mutex> +#include <optional> +#include <sstream> +#include <string> +#include <vector> + +/** + * Who is connected, how healthy they are, and how much they can hold. + * + * Deliberately free of any transport. The registry never sees a socket, a peer + * connection or a data channel -- it is given a session id and timestamps, and + * it answers with decisions. Two reasons: + * + * 1. modules/swarm is compiled by em++ as well as by the host compiler, and + * libdatachannel does not exist in a browser. Anything in here that + * touched it would make the worker unbuildable. + * 2. The liveness state machine is the part most worth testing and the part + * least convenient to test through a real connection. Every entry point + * takes `now_ms` explicitly rather than reading a clock, so a test can + * drive a worker from healthy to dropped in a few microseconds and assert + * each transition on the way. + * + * Resolving a session id back to something sendable is the caller's job. + */ +namespace kel { +namespace lbm { +namespace swarm { + +enum class worker_state { + /// Connected, peer connection up, but no hello yet. + signalling, + /// Hello received and accepted. + registered, + /// Worker says it is initialised and idle. + ready, + /// Missed enough heartbeats to be doubtful, not enough to give up. + stale, +}; + +inline const char *to_string(worker_state state){ + switch(state){ + case worker_state::signalling: return "signalling"; + case worker_state::registered: return "registered"; + case worker_state::ready: return "ready"; + case worker_state::stale: return "stale"; + } + return "?"; +} + +/** + * Liveness thresholds. + * + * At namespace scope rather than nested in registry so it is a complete type + * where the constructor default argument needs it. + */ +struct worker_thresholds { + /// Missed pings before a worker is called stale. + uint64_t stale_after = 3u; + /// Missed pings before it is dropped entirely. + uint64_t drop_after = 6u; +}; + +/** + * What the orchestrator knows about one worker. + * + * Note which id is which. session_id is assigned by the orchestrator and is + * unique by construction; worker_id is whatever the worker called itself and is + * neither unique nor trustworthy. The registry is keyed on the former and + * merely carries the latter, so two workers choosing the same name is a display + * annoyance rather than a collision. + */ +struct worker_record { + std::string session_id; + std::string worker_id; + std::string kind; + + worker_state state = worker_state::signalling; + + uint64_t connected_at_ms = 0u; + uint64_t registered_at_ms = 0u; + uint64_t last_seen_ms = 0u; + + /// Sequence of the most recent ping, so a late pong can be told from a + /// current one rather than silently resetting the miss counter. + uint64_t ping_seq = 0u; + uint64_t outstanding_pings = 0u; + uint64_t pongs = 0u; + + /// Exponentially weighted mean round trip, milliseconds. Negative until + /// the first pong lands. + double rtt_ewma_ms = -1.0; + + /** + * Roughly how many lattice cells this worker could hold, derived from what + * it reported. The whole point of a capability is to answer this, so it is + * computed once on registration rather than recomputed per query. + */ + uint64_t capacity_cells = 0u; + + /// Short human readable form of the capability, for the monitor. + std::string summary; + + /// Last live block the worker sent, on a pong or a status. + data<sch::WorkerLive> live; +}; + +/** + * The orchestrator's only shared mutable state. + * + * libdatachannel delivers callbacks on its own threads and the heartbeat runs + * on another, so everything here is behind one mutex. The interface is + * deliberately coarse -- whole operations rather than accessors -- so callers + * cannot hold a reference to a record past the lock, which is the usual way a + * design like this goes wrong. + */ +class registry { +public: + using thresholds = worker_thresholds; + + explicit registry(worker_thresholds limits = {}) : limits_{limits} {} + + void add_session(const std::string &session_id, uint64_t now_ms){ + std::lock_guard<std::mutex> lock{mutex_}; + + worker_record rec; + rec.session_id = session_id; + rec.state = worker_state::signalling; + rec.connected_at_ms = now_ms; + rec.last_seen_ms = now_ms; + + records_[session_id] = std::move(rec); + } + + /// Returns false if the session is gone. + bool mark_registered(const std::string &session_id, + const std::string &worker_id, const std::string &kind, + uint64_t capacity_cells, std::string summary, + uint64_t now_ms){ + std::lock_guard<std::mutex> lock{mutex_}; + + auto iter = records_.find(session_id); + if(iter == records_.end()){ + return false; + } + + auto &rec = iter->second; + rec.worker_id = worker_id; + rec.kind = kind; + rec.capacity_cells = capacity_cells; + rec.summary = std::move(summary); + rec.state = worker_state::registered; + rec.registered_at_ms = now_ms; + rec.last_seen_ms = now_ms; + + return true; + } + + bool mark_ready(const std::string &session_id, data<sch::WorkerLive> live, + uint64_t now_ms){ + std::lock_guard<std::mutex> lock{mutex_}; + + auto iter = records_.find(session_id); + if(iter == records_.end()){ + return false; + } + + iter->second.state = worker_state::ready; + iter->second.live = std::move(live); + iter->second.last_seen_ms = now_ms; + + return true; + } + + bool update_live(const std::string &session_id, data<sch::WorkerLive> live, + uint64_t now_ms){ + std::lock_guard<std::mutex> lock{mutex_}; + + auto iter = records_.find(session_id); + if(iter == records_.end()){ + return false; + } + + iter->second.live = std::move(live); + iter->second.last_seen_ms = now_ms; + + return true; + } + + /** + * Records a pong. `echoed_sent_at_ms` is the orchestrator's own timestamp + * coming back, so round trip needs no agreement between the two clocks. + * Ignores the liveness effect of a pong whose sequence is not current. + */ + bool record_pong(const std::string &session_id, uint64_t seq, + uint64_t echoed_sent_at_ms, data<sch::WorkerLive> live, + uint64_t now_ms){ + std::lock_guard<std::mutex> lock{mutex_}; + + auto iter = records_.find(session_id); + if(iter == records_.end()){ + return false; + } + + auto &rec = iter->second; + + if(seq != rec.ping_seq){ + // A pong for a ping we have already given up on. Counting it would + // paper over a worker that is consistently one beat behind, so the + // liveness side is left alone; the message still proves the channel + // works, which is worth recording. + rec.last_seen_ms = now_ms; + return true; + } + + rec.outstanding_pings = 0u; + ++rec.pongs; + rec.last_seen_ms = now_ms; + rec.live = std::move(live); + + // Guard against a clock that went backwards rather than producing a + // negative round trip. + const double rtt = (now_ms > echoed_sent_at_ms) + ? static_cast<double>(now_ms - echoed_sent_at_ms) + : 0.0; + + if(rec.rtt_ewma_ms < 0.0){ + rec.rtt_ewma_ms = rtt; + } else { + // Smoothing factor chosen to react within a few beats without + // letting one slow sample dominate. + constexpr double alpha = 0.25; + rec.rtt_ewma_ms = (alpha * rtt) + ((1.0 - alpha) * rec.rtt_ewma_ms); + } + + // A worker that answers again stops being doubtful. It goes back to + // registered rather than ready, because readiness is something only the + // worker can assert. + if(rec.state == worker_state::stale){ + rec.state = worker_state::registered; + } + + return true; + } + + /// Removes a session. Returns the record if there was one. + std::optional<worker_record> remove(const std::string &session_id){ + std::lock_guard<std::mutex> lock{mutex_}; + + auto iter = records_.find(session_id); + if(iter == records_.end()){ + return std::nullopt; + } + + worker_record rec = std::move(iter->second); + records_.erase(iter); + + return rec; + } + + /** + * One heartbeat tick. + * + * Bumps the ping sequence and the miss counter for every session, applies + * the stale and drop thresholds, and returns what to do. Nothing is sent + * from here -- the registry has nothing to send on, and in the orchestrator + * sending runs callbacks, which while holding this lock is how it would + * deadlock. + */ + struct tick_result { + struct ping_target { + std::string session_id; + uint64_t seq; + }; + + std::vector<ping_target> to_ping; + /// Sessions that passed drop_after; already removed from the registry. + std::vector<worker_record> dropped; + /// Sessions that just crossed into stale, for logging. + std::vector<std::string> newly_stale; + }; + + tick_result tick(uint64_t now_ms){ + (void) now_ms; + + tick_result out; + + std::lock_guard<std::mutex> lock{mutex_}; + + for(auto iter = records_.begin(); iter != records_.end(); ){ + auto &rec = iter->second; + + // A session still negotiating has no channel to ping on. It is not + // unhealthy, it is just not up yet, so the thresholds do not apply. + if(rec.state == worker_state::signalling){ + ++iter; + continue; + } + + if(rec.outstanding_pings >= limits_.drop_after){ + out.dropped.push_back(rec); + iter = records_.erase(iter); + continue; + } + + if(rec.outstanding_pings >= limits_.stale_after and + rec.state != worker_state::stale){ + rec.state = worker_state::stale; + out.newly_stale.push_back(rec.session_id); + } + + ++rec.ping_seq; + ++rec.outstanding_pings; + + out.to_ping.push_back( + tick_result::ping_target{rec.session_id, rec.ping_seq}); + + ++iter; + } + + return out; + } + + std::size_t size() const { + std::lock_guard<std::mutex> lock{mutex_}; + return records_.size(); + } + + /// Snapshot for display. Copies, so the caller holds no lock. + std::vector<worker_record> snapshot() const { + std::lock_guard<std::mutex> lock{mutex_}; + + std::vector<worker_record> out; + out.reserve(records_.size()); + for(const auto &entry : records_){ + out.push_back(entry.second); + } + + return out; + } + +private: + mutable std::mutex mutex_; + std::map<std::string, worker_record> records_; + worker_thresholds limits_; +}; + +namespace impl { + +inline std::string human_cells(uint64_t cells){ + std::ostringstream oss; + oss << std::fixed << std::setprecision(1); + + if(cells >= 1000000000ull){ + oss << (static_cast<double>(cells) / 1e9) << "G"; + } else if(cells >= 1000000ull){ + oss << (static_cast<double>(cells) / 1e6) << "M"; + } else if(cells >= 1000ull){ + oss << (static_cast<double>(cells) / 1e3) << "k"; + } else { + oss << cells; + } + + return oss.str(); +} + +} // namespace impl + +/// Renders a snapshot as a fixed width table. +inline std::string render_table(const std::vector<worker_record> &records, + uint64_t now_ms){ + std::ostringstream oss; + + oss << " " << std::left + << std::setw(6) << "sess" + << std::setw(18) << "worker" + << std::setw(9) << "kind" + << std::setw(12) << "state" + << std::setw(9) << "rtt" + << std::setw(8) << "pongs" + << std::setw(8) << "seen" + << std::setw(8) << "cells" + << "detail" << "\n"; + + for(const auto &rec : records){ + std::ostringstream rtt; + if(rec.rtt_ewma_ms < 0.0){ + rtt << "-"; + } else { + rtt << std::fixed << std::setprecision(1) << rec.rtt_ewma_ms << "ms"; + } + + std::ostringstream seen; + const uint64_t age = (now_ms > rec.last_seen_ms) + ? (now_ms - rec.last_seen_ms) : 0u; + seen << (age / 1000u) << "s"; + + oss << " " << std::left + << std::setw(6) << rec.session_id + << std::setw(18) << (rec.worker_id.empty() ? "-" : rec.worker_id) + << std::setw(9) << (rec.kind.empty() ? "-" : rec.kind) + << std::setw(12) << to_string(rec.state) + << std::setw(9) << rtt.str() + << std::setw(8) << rec.pongs + << std::setw(8) << seen.str() + << std::setw(8) << impl::human_cells(rec.capacity_cells) + << rec.summary << "\n"; + } + + if(records.empty()){ + oss << " (no workers)\n"; + } + + return oss.str(); +} + +} // namespace swarm +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/run.hpp b/modules/swarm/c++/run.hpp new file mode 100644 index 0000000..b11bdf5 --- /dev/null +++ b/modules/swarm/c++/run.hpp @@ -0,0 +1,193 @@ +#pragma once + +#include "message.hpp" + +#include <kel/lbm/abstract/data.hpp> + +#include <cstdint> +#include <string> +#include <string_view> +#include <string_view> + +/** + * Run identity. + * + * There is none in the library today: outputs land in a directory named after + * the example, with `<field>_<step>.vtk` inside, so a rerun silently + * overwrites the one before it and nothing records what parameters produced + * what. A swarm makes that worse rather than better -- several workers write + * concurrently, and a result arriving for an unknown run has to be refusable. + * + * A run id is therefore the first thing the orchestrator mints and the thing + * every transfer names. It is sortable, unique, and safe as a directory name: + * + * 20261112T094501Z-a3f19c + * + * UTC so that two machines agree, second resolution because runs are not + * started faster than that by a human, and six hex digits of entropy so that + * two started in the same second by a script still differ. + */ +namespace kel { +namespace lbm { +namespace sch { + +using RunDescriptor = Struct< + Member<String, "run_id">, + Member<String, "name">, + Member<UInt64, "created_at_ms">, + Member<String, "schema_version">, + /** + * Whether halo exchange was on. False until milestone 3, and recorded + * rather than assumed: slices run with clamped edges until then, so the + * seams are wrong, and a stored result should say so rather than leave + * someone to mistake a seam artefact for a solver bug years later. + */ + Member<Bool, "halo_exchange">, + /// Opaque to everything here: whatever the admin endpoint was handed. + Member<String, "params_json"> +>; + +} // namespace sch + +namespace swarm { + +namespace impl { + +/** + * Civil date from a day count since 1970-01-01, by Howard Hinnant's algorithm. + * + * Deliberately not gmtime_r: this is pure arithmetic, so it needs no locale, + * no timezone database and no thread safety caveat, and it can be exercised + * directly in a test rather than through whatever the host libc happens to + * believe. It is also the same on a browser as on the orchestrator, which + * matters when both ends format or parse an id. + */ +struct civil_date { + int64_t year; + uint32_t month; ///< 1-12 + uint32_t day; ///< 1-31 +}; + +constexpr civil_date civil_from_days(int64_t z){ + z += 719468; + const int64_t era = (z >= 0 ? z : z - 146096) / 146097; + const uint64_t doe = static_cast<uint64_t>(z - era * 146097); + const uint64_t yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365; + const int64_t y = static_cast<int64_t>(yoe) + era * 400; + const uint64_t doy = doe - (365 * yoe + yoe / 4 - yoe / 100); + const uint64_t mp = (5 * doy + 2) / 153; + const uint64_t d = doy - (153 * mp + 2) / 5 + 1; + const uint64_t m = mp + (mp < 10 ? 3 : -9); + return civil_date{y + (m <= 2 ? 1 : 0), static_cast<uint32_t>(m), + static_cast<uint32_t>(d)}; +} + +inline void append_padded(std::string &out, uint64_t value, uint32_t width){ + char buffer[20]; + uint32_t written = 0u; + do { + buffer[written++] = static_cast<char>('0' + (value % 10u)); + value /= 10u; + } while(value > 0u and written < sizeof(buffer)); + + for(uint32_t i = written; i < width; ++i){ + out.push_back('0'); + } + for(uint32_t i = written; i > 0u; --i){ + out.push_back(buffer[i - 1u]); + } +} + +inline void append_hex(std::string &out, uint64_t value, uint32_t digits){ + static constexpr char table[] = "0123456789abcdef"; + for(uint32_t i = digits; i > 0u; --i){ + out.push_back(table[(value >> ((i - 1u) * 4u)) & 0xfu]); + } +} + +} // namespace impl + +/** + * Formats a run id. + * + * Takes the clock and the entropy rather than reading them, for the same + * reason the registry takes `now_ms`: a test can then pin both and assert the + * exact string, instead of matching a pattern and hoping. + * + * Only the low 24 bits of `entropy` are used. + */ +inline std::string make_run_id(uint64_t now_ms, uint64_t entropy){ + const int64_t seconds = static_cast<int64_t>(now_ms / 1000u); + const int64_t days = (seconds >= 0) ? (seconds / 86400) + : ((seconds - 86399) / 86400); + const uint64_t secs_of_day = static_cast<uint64_t>(seconds - days * 86400); + + const auto date = impl::civil_from_days(days); + + std::string out; + out.reserve(24u); + + impl::append_padded(out, static_cast<uint64_t>(date.year), 4u); + impl::append_padded(out, date.month, 2u); + impl::append_padded(out, date.day, 2u); + out.push_back('T'); + impl::append_padded(out, secs_of_day / 3600u, 2u); + impl::append_padded(out, (secs_of_day / 60u) % 60u, 2u); + impl::append_padded(out, secs_of_day % 60u, 2u); + out.push_back('Z'); + out.push_back('-'); + impl::append_hex(out, entropy, 6u); + + return out; +} + +/** + * Whether a string could have come from make_run_id. + * + * The sink uses a run id as a directory name, so this is also the check that + * keeps a hostile id from escaping the storage root -- there is no '/', no + * '.', and nothing but a fixed shape of digits and hex. + */ +inline bool is_run_id(std::string_view id){ + if(id.size() != 23u){ + return false; + } + + auto digit = [&](std::size_t i){ return id[i] >= '0' and id[i] <= '9'; }; + auto hex = [&](std::size_t i){ + return (id[i] >= '0' and id[i] <= '9') or (id[i] >= 'a' and id[i] <= 'f'); + }; + + for(std::size_t i = 0u; i < 8u; ++i){ + if(not digit(i)){ return false; } + } + if(id[8] != 'T'){ return false; } + for(std::size_t i = 9u; i < 15u; ++i){ + if(not digit(i)){ return false; } + } + if(id[15] != 'Z'){ return false; } + if(id[16] != '-'){ return false; } + for(std::size_t i = 17u; i < 23u; ++i){ + if(not hex(i)){ return false; } + } + + return true; +} + +} // namespace swarm + +namespace sch { + +using MsgRunStart = Envelope<Member<RunDescriptor, "run">>; +using MsgRunEnd = Envelope<Member<String, "run_id">, Member<String, "outcome">>; + +} // namespace sch + +namespace run_outcome { +inline constexpr std::string_view finished = "finished"; +inline constexpr std::string_view cancelled = "cancelled"; +inline constexpr std::string_view failed = "failed"; +} // namespace run_outcome + +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/signal.hpp b/modules/swarm/c++/signal.hpp new file mode 100644 index 0000000..e8d76bd --- /dev/null +++ b/modules/swarm/c++/signal.hpp @@ -0,0 +1,52 @@ +#pragma once + +#include <kel/lbm/abstract/schema.hpp> + +#include <string_view> + +/** + * WebRTC signalling, carried over the WebSocket that precedes the data channel. + * + * This is a different protocol from the control messages in message.hpp and + * deliberately so: signalling exists only to get a peer connection established, + * after which everything moves to the data channel. It lives here rather than + * in the orchestrator because both the browser worker and the native test + * worker have to speak it, and one definition is the only way they cannot + * disagree. + * + * The shapes mirror what a browser hands you, with one deliberate difference: + * an ICE candidate arrives from JS as {candidate, sdpMid, sdpMLineIndex} and is + * sent on as {type:"candidate", candidate, mid}. Normalising at the JS boundary + * keeps the wire uniform -- every message here is a struct with a "type" -- at + * the cost of three lines in the worker's transport glue. + */ +namespace kel { +namespace lbm { +namespace sch { + +/// Stage one of the same two stage decode the control protocol uses. +using SignalHeader = Struct<Member<String, "type">>; + +/// "offer" or "answer". +using SignalDescription = Struct< + Member<String, "type">, + Member<String, "sdp"> +>; + +/// "candidate". mid may be empty; libdatachannel treats that as unhinted. +using SignalCandidate = Struct< + Member<String, "type">, + Member<String, "candidate">, + Member<String, "mid"> +>; + +} // namespace sch + +namespace sig { +inline constexpr std::string_view offer = "offer"; +inline constexpr std::string_view answer = "answer"; +inline constexpr std::string_view candidate = "candidate"; +} // namespace sig + +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/c++/swarm.hpp b/modules/swarm/c++/swarm.hpp new file mode 100644 index 0000000..a7c066f --- /dev/null +++ b/modules/swarm/c++/swarm.hpp @@ -0,0 +1,11 @@ +#pragma once + +#include "capability.hpp" +#include "capacity.hpp" +#include "interpret.hpp" +#include "message.hpp" +#include "run.hpp" +#include "probe_search.hpp" +#include "registry.hpp" +#include "signal.hpp" +#include "wire.hpp" diff --git a/modules/swarm/c++/wire.hpp b/modules/swarm/c++/wire.hpp new file mode 100644 index 0000000..7c7c7d0 --- /dev/null +++ b/modules/swarm/c++/wire.hpp @@ -0,0 +1,119 @@ +#pragma once + +#include "message.hpp" + +#include <kel/lbm/abstract/data.hpp> +#include <kel/lbm/abstract/json.hpp> + +#include <string> +#include <string_view> + +/** + * Encoding and decoding control messages. + * + * Everything here runs the JSON codec in strict mode. That is not the codec's + * default, and the default is wrong for a wire: codec_config<enc::Json>::strict + * is false so that config files can state only their deviations, which means a + * worker sending "{}" would decode cleanly into a default constructed struct. + * A registration that silently becomes all zeroes is precisely the failure this + * protocol must not have, so strict is set explicitly on every wire codec. + * + * Strict only governs *missing* members. Unknown members are skipped by the + * Struct decoder, which is what makes the two stage decode below work and what + * lets a newer worker talk to an older orchestrator. + */ +namespace kel { +namespace lbm { +namespace swarm { + +namespace impl { +template <typename Schema> +codec<Schema, enc::Json> make_wire_codec(){ + codec_config<enc::Json> cfg; + cfg.strict = true; + // Control messages nest at most capability -> webgl2 -> feasible -> plan, + // so the default guard against pathological input is already generous. + return codec<Schema, enc::Json>{cfg}; +} +} // namespace impl + +/** + * Serialise a message to the text that goes on the data channel. + */ +template <typename Schema> +error_or<std::string> encode_message(const data<Schema> &msg){ + auto wire_codec = impl::make_wire_codec<Schema>(); + + data<Schema, enc::Json> out; + auto eov = wire_codec.encode(msg, out); + if(eov.is_error()){ + return std::move(eov.get_error()); + } + + return out.stl_string(); +} + +/** + * Decode text into a known message type. Fails if any member is absent. + */ +template <typename Schema> +error_or<data<Schema>> decode_message(std::string_view text){ + auto wire_codec = impl::make_wire_codec<Schema>(); + + data<Schema, enc::Json> in{text}; + data<Schema> out; + auto eov = wire_codec.decode(in, out); + if(eov.is_error()){ + return std::move(eov.get_error()); + } + + return out; +} + +/** + * Stage one: read just the common members so the caller learns which type to + * decode. The payload is skipped rather than parsed into anything, so this + * succeeds for every message type and fails only on genuinely malformed input + * or a message missing the common members. + */ +inline error_or<data<sch::MsgHeader>> peek_header(std::string_view text){ + return decode_message<sch::MsgHeader>(text); +} + +/** + * Fills in the members every message shares. Kept in one place so a message + * built by the orchestrator and one built by the worker cannot disagree about + * the shape of the envelope. + */ +template <typename Schema> +void set_envelope(data<Schema> &msg, std::string_view type, + std::string_view worker_id, uint64_t seq){ + msg.template get<"type">().set(std::string{type}); + msg.template get<"worker_id">().set(std::string{worker_id}); + msg.template get<"seq">().set(seq); +} + +/** + * Convenience for the common shape: build a message, stamp the envelope. + */ +template <typename Schema> +data<Schema> make_message(std::string_view type, std::string_view worker_id, + uint64_t seq){ + data<Schema> msg; + set_envelope(msg, type, worker_id, seq); + return msg; +} + +/// Reads the "type" of an already decoded header. +inline std::string_view header_type(const data<sch::MsgHeader> &hdr){ + return hdr.template get<"type">().stl_view(); +} + +/// Reads the "worker_id" of an already decoded header. +inline std::string_view header_worker_id(const data<sch::MsgHeader> &hdr){ + return hdr.template get<"worker_id">().stl_view(); +} + +} // namespace swarm +} // namespace lbm +} // namespace kel diff --git a/modules/swarm/tests/SConscript b/modules/swarm/tests/SConscript new file mode 100644 index 0000000..d1b381e --- /dev/null +++ b/modules/swarm/tests/SConscript @@ -0,0 +1,32 @@ +#!/bin/false + +import os +import os.path +import glob + + +Import('env') + +dir_path = Dir('.').abspath + +# Environment for base library +test_cases_env = env.Clone(); + +test_cases_env.Append(LIBS=['forstio-test']); + +test_cases_env.sources = sorted(glob.glob(dir_path + "/*.cpp")) +test_cases_env.headers = sorted(glob.glob(dir_path + "/*.hpp")) + +env.sources += test_cases_env.sources; +env.headers += test_cases_env.headers; + +objects_static = [] +test_cases_env.add_source_files(objects_static, test_cases_env.sources, shared=False); +test_cases_env.program = test_cases_env.Program('#bin/tests', [objects_static]); +# , env.library_static]); + +# Set Alias +env.Alias('test', test_cases_env.program); +env.Alias('check', test_cases_env.program); + +env.targets += ['test','check']; diff --git a/modules/swarm/tests/capacity.cpp b/modules/swarm/tests/capacity.cpp new file mode 100644 index 0000000..c269aa1 --- /dev/null +++ b/modules/swarm/tests/capacity.cpp @@ -0,0 +1,234 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/capacity.hpp" + +namespace { +using namespace kel::lbm::swarm; + +/** + * The packing arithmetic is small enough that the interesting thing to test is + * not that it computes, but that the ceilings it implies are the ones we think + * they are. These are compile time assertions on purpose: they are statements + * about which descriptors are usable, and the answer should not depend on + * running the test on a particular device. + */ + +SAW_TEST("Packing / planes and idle slots per descriptor"){ + // D1Q3, D2Q5, D2Q9, D3Q19, D3Q27. + static_assert(packing_math::planes(3u) == 1u, "D1Q3 needs one texture"); + static_assert(packing_math::planes(5u) == 2u, "D2Q5 needs two textures"); + static_assert(packing_math::planes(9u) == 3u, "D2Q9 needs three textures"); + static_assert(packing_math::planes(19u) == 5u, "D3Q19 needs five textures"); + static_assert(packing_math::planes(27u) == 7u, "D3Q27 needs seven textures"); + + static_assert(packing_math::idle_slots(3u) == 1u, "D1Q3 wastes one slot"); + static_assert(packing_math::idle_slots(5u) == 3u, "D2Q5 wastes three slots"); + static_assert(packing_math::idle_slots(9u) == 3u, "D2Q9 wastes three slots"); + static_assert(packing_math::idle_slots(19u) == 1u, "D3Q19 wastes one slot"); + static_assert(packing_math::idle_slots(27u) == 1u, "D3Q27 wastes one slot"); + + SAW_EXPECT(true, "static asserts carry this one"); +} + +SAW_TEST("Packing / slots are a partition of the texels"){ + // planes*4 is exactly Q plus the waste, for every Q. Cheap, but it is the + // invariant every slot table depends on. + for(uint64_t q = 1u; q <= 64u; ++q){ + const uint64_t total = packing_math::planes(q) * packing_math::slots_per_texel; + SAW_EXPECT(total == q + packing_math::idle_slots(q), + "planes*4 must be Q plus the idle slots"); + SAW_EXPECT(packing_math::idle_slots(q) < packing_math::slots_per_texel, + "Waste below a full texel, or a plane was over allocated"); + } +} + +/** + * The limit that decides whether a descriptor is usable at all. WebGL2 + * guarantees only four colour attachments, so the 3D descriptors cannot write + * their whole distribution in one pass on a conformant minimum spec device. + * Asserting it here means we learn it from a test rather than from a browser. + */ +SAW_TEST("Packing / single pass only reaches Q <= 16 at guaranteed limits"){ + constexpr uint64_t mrt = webgl2_guaranteed::max_draw_buffers; + + static_assert(packing_math::fits_single_pass(9u, mrt), + "D2Q9 must fit one pass on any conformant WebGL2"); + static_assert(packing_math::fits_single_pass(5u, mrt), "D2Q5 must fit"); + static_assert(packing_math::fits_single_pass(3u, mrt), "D1Q3 must fit"); + + static_assert(not packing_math::fits_single_pass(19u, mrt), + "D3Q19 must not claim a single pass at guaranteed limits"); + static_assert(not packing_math::fits_single_pass(27u, mrt), + "D3Q27 must not claim a single pass at guaranteed limits"); + + static_assert(packing_math::passes(19u, mrt) == 2u, "D3Q19 needs two passes"); + static_assert(packing_math::passes(27u, mrt) == 2u, "D3Q27 needs two passes"); + + // Sixteen is the boundary: four planes, four attachments. + static_assert(packing_math::fits_single_pass(16u, mrt), "Q=16 is the last that fits"); + static_assert(not packing_math::fits_single_pass(17u, mrt), "Q=17 must not fit"); + + SAW_EXPECT(packing_math::passes(9u, 0u) == 0u, + "A device reporting no draw buffers must not divide by zero"); +} + +SAW_TEST("Packing / stuffing aux fields into idle slots"){ + // D2Q9 has three idle slots, so a lone info flag rides along free... + static_assert(packing_math::aux_planes(9u, 1u, true) == 0u, + "One aux scalar must fit D2Q9's idle slots"); + // ...but the four fields a PSM run wants do not. + static_assert(packing_math::aux_planes(9u, 4u, true) == 1u, + "Four aux scalars must not fit three idle slots"); + // Unstuffed always pays for its own plane. + static_assert(packing_math::aux_planes(9u, 1u, false) == 1u, + "Unstuffed aux must take a plane of its own"); + + // D3Q19 and D3Q27 have exactly one idle slot, so info is free there too. + static_assert(packing_math::aux_planes(19u, 1u, true) == 0u, "D3Q19 stuffs info"); + static_assert(packing_math::aux_planes(27u, 1u, true) == 0u, "D3Q27 stuffs info"); + + SAW_EXPECT(true, "static asserts carry this one"); +} + +SAW_TEST("Packing / bytes per cell"){ + // D2Q9, double buffered, info stuffed: 2*3 textures * 16 bytes. + static_assert(packing_math::bytes_per_cell(9u, 2u, 1u, true) == 96u, + "D2Q9 stuffed must be 96 bytes per cell"); + // Unstuffed adds a plane: 2*3 + 1 textures. + static_assert(packing_math::bytes_per_cell(9u, 2u, 1u, false) == 112u, + "D2Q9 unstuffed must be 112 bytes per cell"); + static_assert(packing_math::bytes_per_cell(19u, 2u, 1u, true) == 160u, + "D3Q19 stuffed must be 160 bytes per cell"); + static_assert(packing_math::bytes_per_cell(27u, 2u, 1u, true) == 224u, + "D3Q27 stuffed must be 224 bytes per cell"); + + SAW_EXPECT(true, "static asserts carry this one"); +} + +SAW_TEST("Capacity / integer square root is exact"){ + static_assert(isqrt(0u) == 0u, "isqrt(0)"); + static_assert(isqrt(1u) == 1u, "isqrt(1)"); + static_assert(isqrt(2u) == 1u, "isqrt(2)"); + static_assert(isqrt(3u) == 1u, "isqrt(3)"); + static_assert(isqrt(4u) == 2u, "isqrt(4)"); + + // The property, not just the samples: isqrt(n)^2 <= n < (isqrt(n)+1)^2. + for(uint64_t n = 0u; n < 4096u; ++n){ + const uint64_t r = isqrt(n); + SAW_EXPECT(r * r <= n, "isqrt must not overshoot"); + SAW_EXPECT((r + 1u) * (r + 1u) > n, "isqrt must not undershoot"); + } + + // Exact squares near the top of the range, where a float sqrt would drift. + const uint64_t big = 3037000499u; + SAW_EXPECT(isqrt(big * big) == big, "isqrt must stay exact for large squares"); + SAW_EXPECT(isqrt(big * big - 1u) == big - 1u, "isqrt must round down"); +} + +SAW_TEST("Capacity / the texture bound is the squared usable edge"){ + // Ghost eats a ring off each side, so the edge is S - 2G. + static_assert(capacity_math::texture_bound_cells_2d(2048u, 0u) == 2048u * 2048u, + "No ghost means the full edge"); + static_assert(capacity_math::texture_bound_cells_2d(2048u, 1u) == 2046u * 2046u, + "A one cell ring costs two off the edge"); + + // A device whose texture dimension cannot even hold the ring has no room. + static_assert(capacity_math::texture_bound_cells_2d(2u, 1u) == 0u, + "An edge consumed entirely by ghost leaves nothing"); + + SAW_EXPECT(true, "static asserts carry this one"); +} + +/** + * The headline number: how much lattice a worker can actually hold. The point + * of the test is the relationship between the two bounds, since on real + * hardware the texture bound is roughly a hundred times looser than memory and + * a capacity model that used it would be badly wrong. + */ +SAW_TEST("Capacity / memory binds before texture size on real devices"){ + constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true); + static_assert(bpc == 96u, "D2Q9 stuffed"); + + // A typical desktop: 16384 max texture, 512MB of budget. + constexpr uint64_t desktop_tex = 16384u; + constexpr uint64_t budget = 512ull * 1024ull * 1024ull; + + constexpr uint64_t by_texture = capacity_math::texture_bound_cells_2d(desktop_tex, 0u); + constexpr uint64_t by_memory = capacity_math::cells_from_bytes(budget, bpc); + + static_assert(by_memory < by_texture, + "Memory has to be the binding constraint on a typical desktop"); + static_assert(by_texture / by_memory > 40u, + "The texture bound should be looser by a wide margin, not a hair"); + + constexpr uint64_t cells = capacity_math::max_cells_2d(budget, bpc, desktop_tex, 0u); + static_assert(cells == by_memory, "max_cells must take the tighter bound"); + + SAW_EXPECT(cells * bpc <= budget, "The answer has to fit the budget it came from"); +} + +SAW_TEST("Capacity / minimum spec can be texture bound instead"){ + constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true); + + // Guaranteed limits with a generous budget: now the texture dimension is + // what runs out first, which is a different thing to report upstream. + constexpr uint64_t tex = webgl2_guaranteed::max_texture_size; + constexpr uint64_t budget = 4ull * 1024ull * 1024ull * 1024ull; + + constexpr uint64_t by_texture = capacity_math::texture_bound_cells_2d(tex, 1u); + constexpr uint64_t by_memory = capacity_math::cells_from_bytes(budget, bpc); + + static_assert(by_texture < by_memory, "Texture size must bind at minimum spec"); + static_assert(capacity_math::max_cells_2d(budget, bpc, tex, 1u) == by_texture, + "max_cells must take the tighter bound here too"); + + SAW_EXPECT(true, "static asserts carry this one"); +} + +SAW_TEST("Capacity / a fitted domain always fits"){ + constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true); + + // Sweep budgets and aspect ratios; the invariant is that the answer never + // exceeds the cell count it was given, and never exceeds the texture edge. + const uint64_t aspects[][2] = {{1u,1u}, {4u,1u}, {1u,4u}, {16u,9u}, {2u,1u}}; + const uint64_t tex = 16384u; + const uint64_t ghost = 1u; + const uint64_t edge = tex - 2u * ghost; + + for(uint64_t mb = 1u; mb <= 2048u; mb *= 2u){ + const uint64_t budget = mb * 1024ull * 1024ull; + const uint64_t cells = capacity_math::max_cells_2d(budget, bpc, tex, ghost); + + for(const auto& a : aspects){ + const auto dom = capacity_math::fit_domain_2d(cells, a[0], a[1], tex, ghost); + + SAW_EXPECT(dom.cells() <= cells, + "A fitted domain must not exceed the measured capacity"); + SAW_EXPECT(dom.nx <= edge and dom.ny <= edge, + "A fitted domain must not exceed the texture edge"); + SAW_EXPECT(dom.nx > 0u and dom.ny > 0u, + "A non zero budget must yield a non empty domain"); + SAW_EXPECT(dom.cells() * bpc <= budget, + "The domain must fit the byte budget it was derived from"); + } + } +} + +SAW_TEST("Capacity / fitting respects the requested aspect"){ + // 4:1 on a square-ish budget should come out roughly four times as wide as + // it is tall. Exactness is not the claim -- flooring twice costs a little -- + // but the shape has to be recognisably what was asked for. + const auto dom = capacity_math::fit_domain_2d(1024u * 256u, 4u, 1u, 16384u, 0u); + + SAW_EXPECT(dom.nx > dom.ny, "A 4:1 request must be wider than tall"); + const uint64_t ratio_x100 = (dom.nx * 100u) / dom.ny; + SAW_EXPECT(ratio_x100 >= 380u and ratio_x100 <= 420u, + "A 4:1 request must land near 4:1"); + + // Degenerate inputs are answered, not asserted on. + const auto zero = capacity_math::fit_domain_2d(0u, 4u, 1u, 16384u, 0u); + SAW_EXPECT(zero.cells() == 0u, "No capacity means no domain"); + const auto bad = capacity_math::fit_domain_2d(1024u, 0u, 1u, 16384u, 0u); + SAW_EXPECT(bad.cells() == 0u, "A degenerate aspect must not divide by zero"); +} +} diff --git a/modules/swarm/tests/interpret.cpp b/modules/swarm/tests/interpret.cpp new file mode 100644 index 0000000..53374f1 --- /dev/null +++ b/modules/swarm/tests/interpret.cpp @@ -0,0 +1,133 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/interpret.hpp" + +#include <string> + +namespace { +namespace sch { +using namespace kel::lbm::sch; +} +using namespace kel::lbm; +using namespace kel::lbm::swarm; + +/** + * The orchestrator's webgl2 branch cannot be reached by the native worker, and + * reaching it with a real browser means a human in the loop. These cover the + * part of it that is pure: turning a reported capability into a capacity and a + * summary line. + */ + +data<sch::WebGl2Capability> make_gl(uint64_t safe_bytes, uint64_t max_tex, + bool float_render = true){ + data<sch::WebGl2Capability> gl; + gl.get<"limits">().get<"max_texture_size">().set( + static_cast<uint32_t>(max_tex)); + gl.get<"limits">().get<"max_draw_buffers">().set(8u); + gl.get<"budget">().get<"probed_bytes_safe">().set(safe_bytes); + gl.get<"features">().get<"color_buffer_float">().set(float_render); + return gl; +} + +data<sch::NativeCapability> make_native(uint64_t memory, uint32_t threads, + bool sycl = false){ + data<sch::NativeCapability> nat; + nat.get<"threads">().set(threads); + nat.get<"memory_bytes">().set(memory); + nat.get<"cpu">().set(std::string{"x86_64"}); + nat.get<"has_sycl">().set(sycl); + return nat; +} + +SAW_TEST("Interpret / the reference packing is D2Q9 double buffered"){ + static_assert(reference_bytes_per_cell() == 96u, + "Capacity figures are quoted in 96 byte D2Q9 cells"); + SAW_EXPECT(true, "static assert carries this one"); +} + +SAW_TEST("Interpret / a browser's capacity comes from its measured budget"){ + // 512MiB safe budget on a roomy device: memory binds, not texture size. + const auto gl = make_gl(512ull * 1024ull * 1024ull, 16384u); + const uint64_t cells = webgl2_capacity_cells(gl); + + SAW_EXPECT(cells == (512ull * 1024ull * 1024ull) / 96u, + "Capacity is the budget divided by the reference cell size"); + SAW_EXPECT(cells * 96u <= 512ull * 1024ull * 1024ull, + "and must fit the budget it came from"); +} + +SAW_TEST("Interpret / a small texture dimension binds before memory"){ + // Generous budget, minimum spec texture size: the texture bound wins. + const auto gl = make_gl(4ull * 1024ull * 1024ull * 1024ull, 2048u); + const uint64_t cells = webgl2_capacity_cells(gl); + + SAW_EXPECT(cells == 2048ull * 2048ull, + "The texture dimension is the binding constraint here"); +} + +SAW_TEST("Interpret / a device that measured nothing has no capacity"){ + // What a worker reports when the probe failed outright -- the case the + // node self test produces, and the one a browser produces on a device + // with no float render target. + const auto gl = make_gl(0u, 16384u, false); + SAW_EXPECT(webgl2_capacity_cells(gl) == 0u, + "No measured budget means no capacity, not a guess from the limits"); +} + +SAW_TEST("Interpret / the summary says when a device cannot render float"){ + const auto usable = make_gl(256ull * 1024ull * 1024ull, 16384u, true); + const std::string ok_line = webgl2_summary(usable); + SAW_EXPECT(ok_line.find("tex 16384") != std::string::npos, + "The summary names the texture limit"); + SAW_EXPECT(ok_line.find("256.0 MiB") != std::string::npos, + "and the budget, in units a human reads"); + SAW_EXPECT(ok_line.find("NO FLOAT RENDER") == std::string::npos, + "A usable device is not flagged"); + + const auto broken = make_gl(0u, 16384u, false); + SAW_EXPECT(webgl2_summary(broken).find("NO FLOAT RENDER") != std::string::npos, + "A device with no float render target is flagged loudly, since that " + "is the difference between slow and impossible"); +} + +SAW_TEST("Interpret / a native worker's capacity leaves room for the machine"){ + const auto nat = make_native(32ull * 1024ull * 1024ull * 1024ull, 16u); + const uint64_t cells = native_capacity_cells(nat); + + // A quarter of memory, because the rest of the machine exists. + SAW_EXPECT(cells == (32ull * 1024ull * 1024ull * 1024ull / 4u) / 96u, + "Native capacity is a quarter of memory in reference cells"); + SAW_EXPECT(cells * 96u * 4u <= 32ull * 1024ull * 1024ull * 1024ull, + "and stays well inside what the machine has"); +} + +SAW_TEST("Interpret / native and browser capacities are comparable"){ + // The point of quoting both in the same unit: a registry holding a mix of + // kinds can rank them against each other. + const auto gl = make_gl(2ull * 1024ull * 1024ull * 1024ull, 16384u); + const auto nat = make_native(8ull * 1024ull * 1024ull * 1024ull, 8u); + + const uint64_t browser_cells = webgl2_capacity_cells(gl); + const uint64_t native_cells = native_capacity_cells(nat); + + // 2GiB measured vs 8GiB/4 = 2GiB planned: the same, which is the check + // that one unit really is being used for both. + SAW_EXPECT(browser_cells == native_cells, + "Equivalent budgets must produce equal capacities across kinds"); +} + +SAW_TEST("Interpret / the native summary reports what a process can know"){ + const std::string plain = native_summary( + make_native(8ull * 1024ull * 1024ull * 1024ull, 4u)); + SAW_EXPECT(plain.find("4 threads") != std::string::npos, "thread count"); + SAW_EXPECT(plain.find("8.0 GiB") != std::string::npos, "memory"); + SAW_EXPECT(plain.find("x86_64") != std::string::npos, "architecture"); + SAW_EXPECT(plain.find("sycl") == std::string::npos, + "and does not claim sycl when there is none"); + + const std::string with_sycl = native_summary( + make_native(8ull * 1024ull * 1024ull * 1024ull, 4u, true)); + SAW_EXPECT(with_sycl.find("sycl") != std::string::npos, + "but says so when there is"); +} +} diff --git a/modules/swarm/tests/probe_search.cpp b/modules/swarm/tests/probe_search.cpp new file mode 100644 index 0000000..42f852b --- /dev/null +++ b/modules/swarm/tests/probe_search.cpp @@ -0,0 +1,202 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/capacity.hpp" +#include "../c++/probe_search.hpp" + +#include <string> + +namespace { +using namespace kel::lbm::swarm; + +/** + * Runs a search against a simulated device whose real capacity is `truth`, + * returning the outcome. This is the whole point of keeping the strategy apart + * from the GL calls: a device that would take a browser and several seconds to + * interrogate is a predicate here. + */ +struct probe_outcome { + uint64_t best; + uint64_t trials; + bool hit_ceiling; +}; + +probe_outcome run_against(uint64_t truth, allocation_search::config cfg = {}){ + allocation_search search{cfg}; + + while(not search.done()){ + search.report(search.candidate() <= truth); + } + + return probe_outcome{search.best_cells(), search.trials(), + search.hit_ceiling()}; +} + +SAW_TEST("Probe / never reports more than the device can do"){ + // The property that matters most. Over-reporting means the orchestrator + // hands out a domain that does not fit, and the worker fails at the point + // where it is least convenient. + const uint64_t truths[] = { + 65536u, 100000u, 1000000u, 2097152u, 5600000u, 12345678u, + 99999999u, 1u << 28, + }; + + for(uint64_t truth : truths){ + const auto out = run_against(truth); + SAW_EXPECT(out.best <= truth, + "A probe must never claim more than the device allows"); + } +} + +SAW_TEST("Probe / gets close to the real capacity"){ + // Within a quarter is plenty: the figure is a planning estimate against a + // budget that shifts as other tabs come and go. + const uint64_t truths[] = { + 200000u, 1000000u, 3000000u, 5600000u, 22000000u, + }; + + for(uint64_t truth : truths){ + const auto out = run_against(truth); + SAW_EXPECT(out.best * 4u >= truth * 3u, + std::string{"Probe landed too far below the truth for "} + + std::to_string(truth)); + } +} + +SAW_TEST("Probe / converges in a handful of trials"){ + // Doubling then bisecting should cost a dozen or so attempts even across + // three orders of magnitude of device. + allocation_search::config cfg; + + for(uint64_t truth = 65536u; truth < (1ull << 30); truth *= 3u){ + const auto out = run_against(truth, cfg); + SAW_EXPECT(out.trials <= cfg.max_trials, + "The backstop must hold"); + SAW_EXPECT(out.trials <= 20u, + std::string{"Too many trials for truth "} + std::to_string(truth)); + } +} + +SAW_TEST("Probe / a device that cannot do the opening attempt reports zero"){ + allocation_search::config cfg; + cfg.start_cells = 65536u; + + const auto out = run_against(1000u, cfg); + SAW_EXPECT(out.best == 0u, + "Failing the smallest attempt must report no capacity, not a guess"); + SAW_EXPECT(out.trials == 1u, "and must not keep trying"); +} + +SAW_TEST("Probe / the texture ceiling is reported, not confused with memory"){ + allocation_search::config cfg; + cfg.ceiling_cells = 1000000u; + + // Memory is effectively unlimited here, so the ceiling is what stops it. + const auto out = run_against(1ull << 40, cfg); + SAW_EXPECT(out.best == cfg.ceiling_cells, "It reaches the ceiling exactly"); + SAW_EXPECT(out.hit_ceiling, + "and says the texture dimension stopped it, not memory"); + + // Whereas a device that runs out of memory first must not claim the + // ceiling stopped it -- those are different things to report upstream. + const auto mem = run_against(300000u, cfg); + SAW_EXPECT(not mem.hit_ceiling, + "Running out of memory below the ceiling is not a ceiling hit"); + SAW_EXPECT(mem.best <= 300000u, "and still must not over-report"); +} + +SAW_TEST("Probe / a ceiling below the opening attempt is clamped"){ + allocation_search::config cfg; + cfg.start_cells = 65536u; + cfg.ceiling_cells = 1024u; + + allocation_search search{cfg}; + SAW_EXPECT(search.candidate() == 1024u, + "The first attempt must not exceed the ceiling"); + + const auto out = run_against(1ull << 30, cfg); + SAW_EXPECT(out.best == 1024u, "and the answer is the ceiling"); + SAW_EXPECT(out.hit_ceiling, "reported as such"); +} + +SAW_TEST("Probe / a zero ceiling means no capacity at all"){ + allocation_search::config cfg; + cfg.ceiling_cells = 0u; + cfg.start_cells = 0u; + + allocation_search search{cfg}; + SAW_EXPECT(search.done(), "Nothing to try means the search is already over"); + SAW_EXPECT(search.best_cells() == 0u, "and the answer is zero"); +} + +SAW_TEST("Probe / reporting after completion is ignored"){ + allocation_search search{allocation_search::config{}}; + while(not search.done()){ + search.report(false); + } + + const uint64_t trials = search.trials(); + search.report(true); + SAW_EXPECT(search.trials() == trials, + "A late answer must not restart a finished search"); + SAW_EXPECT(search.best_cells() == 0u, "nor change the result"); +} + +/** + * A device that answers inconsistently -- which a real one can, since memory + * pressure moves while you are measuring -- must still terminate. + */ +SAW_TEST("Probe / an unreliable device still terminates"){ + allocation_search::config cfg; + + // Alternating yes/no regardless of size. + { + allocation_search search{cfg}; + bool flip = true; + uint64_t guard = 0u; + while(not search.done()){ + search.report(flip); + flip = not flip; + SAW_EXPECT(++guard < 1000u, "The search must terminate"); + } + SAW_EXPECT(search.trials() <= cfg.max_trials, "within the backstop"); + } + + // Always yes, unbounded device: the doubling has to stop somewhere. + { + allocation_search search{cfg}; + uint64_t guard = 0u; + while(not search.done()){ + search.report(true); + SAW_EXPECT(++guard < 1000u, "Unbounded success must still terminate"); + } + SAW_EXPECT(search.trials() <= cfg.max_trials, "within the backstop"); + } +} + +/** + * The probe answers in cells; the orchestrator wants a domain. Checking the + * two compose means the number that comes off a device is usable as it stands. + */ +SAW_TEST("Probe / the measured capacity feeds the domain fitting"){ + constexpr uint64_t bpc = packing_math::bytes_per_cell(9u, 2u, 1u, true); + const uint64_t max_tex = 16384u; + + // A device good for about 512MB of lattice. + const uint64_t truth = capacity_math::cells_from_bytes( + 512ull * 1024ull * 1024ull, bpc); + + allocation_search::config cfg; + cfg.ceiling_cells = capacity_math::texture_bound_cells_2d(max_tex, 0u); + + const auto out = run_against(truth, cfg); + SAW_EXPECT(out.best <= truth, "Measured capacity must not exceed the truth"); + SAW_EXPECT(not out.hit_ceiling, + "Memory binds well before the texture dimension on a device like this"); + + const auto dom = capacity_math::fit_domain_2d(out.best, 4u, 1u, max_tex, 0u); + SAW_EXPECT(dom.cells() <= out.best, + "The fitted domain must fit what was actually measured"); + SAW_EXPECT(dom.cells() * bpc <= 512ull * 1024ull * 1024ull, + "and therefore fit in the memory the device really had"); +} +} diff --git a/modules/swarm/tests/registry.cpp b/modules/swarm/tests/registry.cpp new file mode 100644 index 0000000..45ebab3 --- /dev/null +++ b/modules/swarm/tests/registry.cpp @@ -0,0 +1,298 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/message.hpp" +#include "../c++/registry.hpp" + +#include <string> + +namespace { +namespace sch { +using namespace kel::lbm::sch; +} +using namespace kel::lbm; +using namespace kel::lbm::swarm; + +/** + * The registry takes `now_ms` at every entry point rather than reading a clock, + * so these tests drive a worker from healthy to dropped in microseconds. Doing + * this against a real connection would mean sleeping through several heartbeat + * intervals and hoping the timing held. + */ + +data<sch::WorkerLive> some_live(){ + data<sch::WorkerLive> live; + live.get<"state">().set(std::string{wstate::ready}); + live.get<"uptime_ms">().set(0u); + live.get<"steps_done">().set(0u); + live.get<"last_error">().set(std::string{""}); + return live; +} + +/** + * Registers one worker into an existing registry. Fills in place rather than + * returning one: registry holds a mutex, so it is neither copyable nor movable. + */ +void register_one(registry ®){ + reg.add_session("w1", 1000u); + reg.mark_registered("w1", "alpha", std::string{wkind::native}, 1000u, + "test worker", 1000u); +} + +worker_record only(const registry ®){ + auto snap = reg.snapshot(); + return snap.empty() ? worker_record{} : snap.front(); +} + +SAW_TEST("Registry / a session starts in signalling and is not pinged"){ + registry reg; + reg.add_session("w1", 100u); + + SAW_EXPECT(reg.size() == 1u, "The session is tracked"); + SAW_EXPECT(only(reg).state == worker_state::signalling, + "A fresh session has not said hello yet"); + + // Crucially the thresholds must not apply before a hello. A worker still + // negotiating is not unhealthy, and counting misses against it would drop + // it before it ever had a channel to answer on. + for(uint64_t i = 0u; i < 20u; ++i){ + auto result = reg.tick(200u + i); + SAW_EXPECT(result.to_ping.empty(), "A signalling session is not pinged"); + SAW_EXPECT(result.dropped.empty(), "A signalling session is not dropped"); + } + SAW_EXPECT(reg.size() == 1u, "It is still there after many ticks"); +} + +SAW_TEST("Registry / registration records the capability"){ + registry reg; + register_one(reg); + const auto rec = only(reg); + + SAW_EXPECT(rec.state == worker_state::registered, "hello moves it on"); + SAW_EXPECT(rec.worker_id == "alpha", "The self reported name is kept"); + SAW_EXPECT(rec.kind == wkind::native, "The kind is kept"); + SAW_EXPECT(rec.capacity_cells == 1000u, "The capacity is kept"); + SAW_EXPECT(rec.session_id == "w1", "Keyed on the assigned id"); +} + +SAW_TEST("Registry / registering an unknown session fails rather than creating one"){ + registry reg; + SAW_EXPECT(not reg.mark_registered("ghost", "a", "native", 1u, "", 1u), + "A hello from a session that has gone must not resurrect it"); + SAW_EXPECT(reg.size() == 0u, "and must not invent a record"); +} + +SAW_TEST("Registry / a ping is outstanding until its pong"){ + registry reg; + register_one(reg); + + auto t1 = reg.tick(2000u); + SAW_EXPECT(t1.to_ping.size() == 1u, "One worker, one ping"); + SAW_EXPECT(t1.to_ping.front().seq == 1u, "Sequences start at one"); + SAW_EXPECT(only(reg).outstanding_pings == 1u, "The ping is outstanding"); + + reg.record_pong("w1", 1u, 2000u, some_live(), 2020u); + SAW_EXPECT(only(reg).outstanding_pings == 0u, "The pong clears it"); + SAW_EXPECT(only(reg).pongs == 1u, "and is counted"); +} + +SAW_TEST("Registry / round trip is measured against our own clock"){ + registry reg; + register_one(reg); + + reg.tick(2000u); + // The worker echoes the timestamp we sent, so no clock agreement needed. + reg.record_pong("w1", 1u, 2000u, some_live(), 2040u); + SAW_EXPECT(only(reg).rtt_ewma_ms == 40.0, + "The first sample seeds the average exactly"); + + // Second sample at 80ms: 0.25*80 + 0.75*40 = 50. + reg.tick(3000u); + reg.record_pong("w1", 2u, 3000u, some_live(), 3080u); + const double rtt = only(reg).rtt_ewma_ms; + SAW_EXPECT(rtt > 49.9 and rtt < 50.1, "Smoothing weights the history"); +} + +SAW_TEST("Registry / a clock that goes backwards does not produce a negative rtt"){ + registry reg; + register_one(reg); + + reg.tick(2000u); + // Echoed timestamp later than now. Should clamp, not underflow into a + // huge positive via unsigned subtraction. + reg.record_pong("w1", 1u, 5000u, some_live(), 2000u); + SAW_EXPECT(only(reg).rtt_ewma_ms == 0.0, "A backwards clock reads as zero"); +} + +/** + * The transition that actually matters, and the one that is tedious to provoke + * against a live connection. + */ +SAW_TEST("Registry / stale then dropped, at the configured thresholds"){ + worker_thresholds limits; + limits.stale_after = 2u; + limits.drop_after = 4u; + + registry reg{limits}; + register_one(reg); + uint64_t t = 2000u; + + // Beat 1 and 2: outstanding climbs, still considered healthy. + auto b1 = reg.tick(t += 100u); + SAW_EXPECT(b1.newly_stale.empty(), "One miss is not yet doubtful"); + SAW_EXPECT(only(reg).state == worker_state::registered, "still registered"); + + auto b2 = reg.tick(t += 100u); + SAW_EXPECT(b2.newly_stale.empty(), "Two outstanding, threshold not crossed yet"); + + // Beat 3 sees outstanding == 2, which meets stale_after. + auto b3 = reg.tick(t += 100u); + SAW_EXPECT(b3.newly_stale.size() == 1u, "Crossing into stale is reported once"); + SAW_EXPECT(b3.newly_stale.front() == "w1", "and names the session"); + SAW_EXPECT(only(reg).state == worker_state::stale, "and is recorded"); + + // Reported once, not every beat afterwards -- otherwise the log fills up. + auto b4 = reg.tick(t += 100u); + SAW_EXPECT(b4.newly_stale.empty(), "Stale is announced once, not repeatedly"); + SAW_EXPECT(only(reg).state == worker_state::stale, "and it stays stale"); + + // Beat 5 sees outstanding == 4, which meets drop_after. + auto b5 = reg.tick(t += 100u); + SAW_EXPECT(b5.dropped.size() == 1u, "It is dropped at the threshold"); + SAW_EXPECT(b5.dropped.front().worker_id == "alpha", + "The dropped record is handed back so the caller can log it"); + SAW_EXPECT(reg.size() == 0u, "and removed from the registry"); + SAW_EXPECT(b5.to_ping.empty(), "A dropped session is not also pinged"); +} + +SAW_TEST("Registry / answering again clears stale"){ + worker_thresholds limits; + limits.stale_after = 2u; + limits.drop_after = 10u; + + registry reg{limits}; + register_one(reg); + uint64_t t = 2000u; + + reg.tick(t += 100u); + reg.tick(t += 100u); + auto b3 = reg.tick(t += 100u); + SAW_EXPECT(only(reg).state == worker_state::stale, "It went stale"); + + // The worker comes back, answering the ping that is actually outstanding. + reg.record_pong("w1", b3.to_ping.front().seq, t, some_live(), t + 5u); + + SAW_EXPECT(only(reg).state == worker_state::registered, + "Answering clears the doubt"); + SAW_EXPECT(only(reg).outstanding_pings == 0u, "and resets the miss count"); +} + +SAW_TEST("Registry / recovery does not silently restore readiness"){ + // Readiness is something only the worker can assert, so a recovered worker + // goes back to registered and has to say 'ready' again. + worker_thresholds limits; + limits.stale_after = 1u; + limits.drop_after = 10u; + + registry reg{limits}; + register_one(reg); + reg.mark_ready("w1", some_live(), 1500u); + SAW_EXPECT(only(reg).state == worker_state::ready, "It was ready"); + + reg.tick(2000u); + auto b2 = reg.tick(2100u); + SAW_EXPECT(only(reg).state == worker_state::stale, "Then it went quiet"); + + reg.record_pong("w1", b2.to_ping.front().seq, 2100u, some_live(), 2110u); + SAW_EXPECT(only(reg).state == worker_state::registered, + "Recovery must not reassert readiness on the worker's behalf"); +} + +/** + * A worker consistently one beat behind would otherwise look perfectly healthy: + * every tick adds a miss, every late pong clears it, and the miss count never + * reaches the threshold. + */ +SAW_TEST("Registry / a stale sequence pong does not clear the miss count"){ + registry reg; + register_one(reg); + + auto b1 = reg.tick(2000u); + const uint64_t old_seq = b1.to_ping.front().seq; + + reg.tick(2100u); + reg.tick(2200u); + SAW_EXPECT(only(reg).outstanding_pings == 3u, "Three pings outstanding"); + + // Answer the first one, long after it was superseded. + reg.record_pong("w1", old_seq, 2000u, some_live(), 2250u); + + SAW_EXPECT(only(reg).outstanding_pings == 3u, + "A pong for a superseded ping must not clear the misses"); + SAW_EXPECT(only(reg).pongs == 0u, "nor count as an answer"); + SAW_EXPECT(only(reg).last_seen_ms == 2250u, + "but it does prove the channel is alive"); +} + +SAW_TEST("Registry / removal returns the record once"){ + registry reg; + register_one(reg); + + auto gone = reg.remove("w1"); + SAW_EXPECT(gone.has_value(), "Removing returns what was removed"); + SAW_EXPECT(gone->worker_id == "alpha", "with its contents intact"); + SAW_EXPECT(reg.size() == 0u, "and empties the registry"); + + // Idempotent: several teardown paths converge on this and whichever + // arrives first should win without the others erroring. + SAW_EXPECT(not reg.remove("w1").has_value(), "A second removal is a no-op"); +} + +SAW_TEST("Registry / many workers are ticked independently"){ + worker_thresholds limits; + limits.stale_after = 2u; + limits.drop_after = 3u; + + registry reg{limits}; + for(uint64_t i = 0u; i < 5u; ++i){ + const std::string id = "w" + std::to_string(i); + reg.add_session(id, 1000u); + reg.mark_registered(id, "worker" + std::to_string(i), "native", + 1000u * i, "", 1000u); + } + + uint64_t t = 1000u; + for(int beat = 0; beat < 3; ++beat){ + auto result = reg.tick(t += 100u); + // w3 keeps answering; everyone else goes quiet. + for(const auto &target : result.to_ping){ + if(target.session_id == "w3"){ + reg.record_pong("w3", target.seq, t, some_live(), t + 1u); + } + } + } + + auto result = reg.tick(t += 100u); + SAW_EXPECT(result.dropped.size() == 4u, "The four silent workers are dropped"); + SAW_EXPECT(reg.size() == 1u, "The responsive one survives"); + SAW_EXPECT(only(reg).session_id == "w3", "and it is the right one"); +} + +SAW_TEST("Registry / the table renders without a worker and with one"){ + registry reg; + SAW_EXPECT(render_table(reg.snapshot(), 0u).find("(no workers)") + != std::string::npos, "An empty registry says so"); + + registry one; + register_one(one); + one.tick(2000u); + one.record_pong("w1", 1u, 2000u, some_live(), 2010u); + + const std::string table = render_table(one.snapshot(), 3000u); + SAW_EXPECT(table.find("alpha") != std::string::npos, "The worker is listed"); + SAW_EXPECT(table.find("native") != std::string::npos, "with its kind"); + SAW_EXPECT(table.find("10.0ms") != std::string::npos, "and its round trip"); + // 1000 cells renders as a bare count, not scaled. + SAW_EXPECT(table.find("1.0k") != std::string::npos, + "and a human readable capacity"); +} +} diff --git a/modules/swarm/tests/run.cpp b/modules/swarm/tests/run.cpp new file mode 100644 index 0000000..b7cd8f5 --- /dev/null +++ b/modules/swarm/tests/run.cpp @@ -0,0 +1,158 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/run.hpp" +#include "../c++/wire.hpp" + +#include <set> +#include <string> + +namespace { +namespace sch { +using namespace kel::lbm::sch; +} +using namespace kel::lbm; +using namespace kel::lbm::swarm; + +/// 2026-11-12T09:45:01Z, as milliseconds since the epoch. +constexpr uint64_t reference_ms = 1794476701000ull; + +SAW_TEST("Run / the id has the documented shape"){ + // Pinned exactly rather than pattern matched: make_run_id takes its clock + // and entropy, so the whole string is determined and a drift in either + // half should fail loudly. + const std::string id = make_run_id(reference_ms, 0xa3f19cull); + SAW_EXPECT(id == "20261112T094501Z-a3f19c", + std::string{"unexpected run id: "} + id); + SAW_EXPECT(id.size() == 23u, "and the fixed width the sink relies on"); +} + +SAW_TEST("Run / only the low 24 bits of entropy are used"){ + const std::string a = make_run_id(reference_ms, 0xffffffffffffffffull); + SAW_EXPECT(a == "20261112T094501Z-ffffff", "the top bits are discarded"); + + const std::string b = make_run_id(reference_ms, 0x0ull); + SAW_EXPECT(b == "20261112T094501Z-000000", "and zero pads rather than shortens"); +} + +SAW_TEST("Run / ids sort chronologically as plain strings"){ + // The point of the format: `ls` and a std::map give time order for free, + // with no parsing anywhere. + const std::string earlier = make_run_id(reference_ms, 0xffffffull); + const std::string later = make_run_id(reference_ms + 1000u, 0x000000ull); + + SAW_EXPECT(earlier < later, + "A later run must sort after an earlier one even with lower entropy"); + + // Across a month and a year boundary, where a naive format breaks. + SAW_EXPECT(make_run_id(reference_ms, 0u) + < make_run_id(reference_ms + 30ull * 86400000ull, 0u), + "and across a month"); +} + +SAW_TEST("Run / the civil date conversion handles the awkward cases"){ + using kel::lbm::swarm::impl::civil_from_days; + + // The epoch itself. + { + const auto d = civil_from_days(0); + SAW_EXPECT(d.year == 1970 and d.month == 1u and d.day == 1u, "epoch"); + } + // A leap day, which is where a hand-rolled conversion usually goes wrong. + { + const auto d = civil_from_days(19782); // 2024-02-29 + SAW_EXPECT(d.year == 2024 and d.month == 2u and d.day == 29u, + "2024 is a leap year and the 29th exists"); + } + // 2000 was a leap year despite being a century. + { + const auto d = civil_from_days(11016); // 2000-02-29 + SAW_EXPECT(d.year == 2000 and d.month == 2u and d.day == 29u, + "the 400 year rule"); + } + // The day after the 2024 leap day, so an off-by-one shows. + { + const auto d = civil_from_days(19783); + SAW_EXPECT(d.year == 2024 and d.month == 3u and d.day == 1u, "march 1st"); + } +} + +SAW_TEST("Run / midnight and the last second of a day format correctly"){ + // 2026-11-12T00:00:00Z + const uint64_t midnight = (reference_ms / 86400000ull) * 86400000ull; + SAW_EXPECT(make_run_id(midnight, 0u) == "20261112T000000Z-000000", + "midnight is all zeroes, not blank"); + + SAW_EXPECT(make_run_id(midnight + 86399000ull, 0u) + == "20261112T235959Z-000000", "and the last second is 235959"); + + // One more second rolls the date rather than producing 24:00:00. + SAW_EXPECT(make_run_id(midnight + 86400000ull, 0u) + == "20261113T000000Z-000000", "which rolls into the next day"); +} + +/** + * The sink uses a run id as a directory name, so this is the check that stops + * a hostile id escaping the storage root. + */ +SAW_TEST("Run / validation rejects anything that is not the exact shape"){ + SAW_EXPECT(is_run_id(make_run_id(reference_ms, 0xabcdefull)), + "what make_run_id produces must validate"); + + const char *bad[] = { + "", + "20261112T094501Z", // no entropy + "20261112T094501Z-a3f19", // one short + "20261112T094501Z-a3f19cd", // one long + "20261112t094501Z-a3f19c", // lowercase separator + "20261112T094501Z-A3F19C", // uppercase hex + "20261112T094501Z-a3f19g", // 'g' is not hex + "2026111 T094501Z-a3f19c", // space + "../../etc/passwd000000Z-a3f19c", // the reason this function exists + "20261112T094501Z/a3f19c", // a separator that is a path one + }; + + for(const char *id : bad){ + SAW_EXPECT(not is_run_id(id), + std::string{"must be rejected: "} + id); + } +} + +SAW_TEST("Run / distinct entropy gives distinct ids within one second"){ + std::set<std::string> seen; + for(uint64_t e = 0u; e < 512u; ++e){ + seen.insert(make_run_id(reference_ms, e)); + } + SAW_EXPECT(seen.size() == 512u, + "Two runs started in the same second must not collide"); +} + +SAW_TEST("Run / a run descriptor round trips on the wire"){ + auto start = make_message<sch::MsgRunStart>(msg::run_start, "orch", 0u); + + auto &run = start.get<"run">(); + run.get<"run_id">().set(make_run_id(reference_ms, 0xa3f19cull)); + run.get<"name">().set(std::string{"poiseuille 1024x256"}); + run.get<"created_at_ms">().set(reference_ms); + run.get<"schema_version">().set(std::string{schema_version}); + run.get<"halo_exchange">().set(false); + run.get<"params_json">().set(std::string{R"({"nx":1024,"ny":256})"}); + + auto eo_text = encode_message<sch::MsgRunStart>(start); + SAW_EXPECT(not eo_text.is_error(), "a run start encodes"); + + auto eo_hdr = peek_header(eo_text.get_value()); + SAW_EXPECT(not eo_hdr.is_error(), "and routes"); + SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::run_start, "as a run start"); + + auto eo_back = decode_message<sch::MsgRunStart>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "and decodes"); + + const auto &back = eo_back.get_value().get<"run">(); + SAW_EXPECT(back.get<"run_id">().stl_view() == "20261112T094501Z-a3f19c", + "the id survives"); + SAW_EXPECT(not back.get<"halo_exchange">().get(), + "and the record that the seams were clamped survives with it"); + SAW_EXPECT(back.get<"params_json">().stl_view() == R"({"nx":1024,"ny":256})", + "the opaque params survive being nested inside JSON"); +} +} diff --git a/modules/swarm/tests/signal.cpp b/modules/swarm/tests/signal.cpp new file mode 100644 index 0000000..fc12193 --- /dev/null +++ b/modules/swarm/tests/signal.cpp @@ -0,0 +1,82 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/signal.hpp" +#include "../c++/wire.hpp" + +namespace { +namespace sch { +using namespace kel::lbm::sch; +} +using namespace kel::lbm; +using namespace kel::lbm::swarm; + +SAW_TEST("Signal / an offer round trips"){ + data<sch::SignalDescription> desc; + desc.get<"type">().set(std::string{sig::offer}); + desc.get<"sdp">().set(std::string{"v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\n"}); + + auto eo_text = encode_message<sch::SignalDescription>(desc); + SAW_EXPECT(not eo_text.is_error(), "An offer must encode"); + + auto eo_back = decode_message<sch::SignalDescription>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "An offer must decode"); + SAW_EXPECT(eo_back.get_value().get<"type">().stl_view() == sig::offer, + "type survives"); + // SDP is multi-line and full of characters JSON has to escape; that it + // comes back byte for byte is the only interesting property here. + SAW_EXPECT(eo_back.get_value().get<"sdp">().stl_view() + == "v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\n", + "SDP must survive escaping unchanged"); +} + +SAW_TEST("Signal / a candidate round trips"){ + data<sch::SignalCandidate> cand; + cand.get<"type">().set(std::string{sig::candidate}); + cand.get<"candidate">().set(std::string{"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"}); + cand.get<"mid">().set(std::string{"0"}); + + auto eo_text = encode_message<sch::SignalCandidate>(cand); + SAW_EXPECT(not eo_text.is_error(), "A candidate must encode"); + + auto eo_back = decode_message<sch::SignalCandidate>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "A candidate must decode"); + SAW_EXPECT(eo_back.get_value().get<"mid">().stl_view() == "0", "mid survives"); +} + +SAW_TEST("Signal / the header routes without knowing the payload"){ + data<sch::SignalDescription> desc; + desc.get<"type">().set(std::string{sig::answer}); + desc.get<"sdp">().set(std::string{"v=0"}); + auto eo_text = encode_message<sch::SignalDescription>(desc); + SAW_EXPECT(not eo_text.is_error(), "encodes"); + + auto eo_hdr = decode_message<sch::SignalHeader>(eo_text.get_value()); + SAW_EXPECT(not eo_hdr.is_error(), "A header read must skip the sdp"); + SAW_EXPECT(eo_hdr.get_value().get<"type">().stl_view() == sig::answer, + "Header reports answer"); +} + +SAW_TEST("Signal / an empty mid is carried rather than dropped"){ + // libdatachannel accepts an unhinted candidate, so the empty string has to + // survive the round trip as an empty string and not become a decode error. + data<sch::SignalCandidate> cand; + cand.get<"type">().set(std::string{sig::candidate}); + cand.get<"candidate">().set(std::string{"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"}); + cand.get<"mid">().set(std::string{""}); + + auto eo_text = encode_message<sch::SignalCandidate>(cand); + SAW_EXPECT(not eo_text.is_error(), "encodes"); + auto eo_back = decode_message<sch::SignalCandidate>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "An empty mid must still decode"); + SAW_EXPECT(eo_back.get_value().get<"mid">().stl_view().empty(), + "An empty mid stays empty"); +} + +SAW_TEST("Signal / a candidate missing its mid is rejected"){ + // Strictness applies here too: a signalling message that lost a member in + // transit should fail loudly rather than add a candidate with no mid. + auto eo = decode_message<sch::SignalCandidate>( + R"({"type":"candidate","candidate":"candidate:1 1 UDP 100 10.0.0.1 5000 typ host"})"); + SAW_EXPECT(eo.is_error(), "A missing mid must be an error"); +} +} diff --git a/modules/swarm/tests/wire.cpp b/modules/swarm/tests/wire.cpp new file mode 100644 index 0000000..5238619 --- /dev/null +++ b/modules/swarm/tests/wire.cpp @@ -0,0 +1,381 @@ +#include <forstio/test/suite.hpp> + +#include "../c++/wire.hpp" + +#include <string> + +namespace { +namespace sch { +using namespace kel::lbm::sch; +} +using namespace kel::lbm; +using namespace kel::lbm::swarm; + +/** + * Builds a filled-in live block. Every member is set, because the wire codecs + * run strict and a half built message is exactly what these tests are trying + * to catch elsewhere. + */ +data<sch::WorkerLive> make_live(){ + data<sch::WorkerLive> live; + live.get<"state">().set(std::string{wstate::ready}); + live.get<"uptime_ms">().set(1234u); + live.get<"steps_done">().set(42u); + live.get<"last_error">().set(std::string{""}); + return live; +} + +SAW_TEST("Wire / pong round trips unchanged"){ + auto msg = make_message<sch::MsgPong>(msg::pong, "worker-7", 19u); + msg.get<"sent_at_ms">().set(1000u); + msg.get<"worker_now_ms">().set(2000u); + msg.get<"live">() = make_live(); + + auto eo_text = encode_message<sch::MsgPong>(msg); + SAW_EXPECT(not eo_text.is_error(), "Encoding a complete message must succeed"); + const std::string text = eo_text.get_value(); + + auto eo_back = decode_message<sch::MsgPong>(text); + SAW_EXPECT(not eo_back.is_error(), "Decoding our own output must succeed"); + auto& back = eo_back.get_value(); + + SAW_EXPECT(back.get<"type">().stl_view() == msg::pong, "type survives"); + SAW_EXPECT(back.get<"worker_id">().stl_view() == "worker-7", "worker_id survives"); + SAW_EXPECT(back.get<"seq">().get() == 19u, "seq survives"); + SAW_EXPECT(back.get<"sent_at_ms">().get() == 1000u, "echoed timestamp survives"); + SAW_EXPECT(back.get<"worker_now_ms">().get() == 2000u, "worker clock survives"); + SAW_EXPECT(back.get<"live">().get<"steps_done">().get() == 42u, + "Nested struct members survive"); + SAW_EXPECT(back.get<"live">().get<"state">().stl_view() == wstate::ready, + "Nested strings survive"); +} + +SAW_TEST("Wire / welcome and ping round trip"){ + auto wel = make_message<sch::MsgWelcome>(msg::welcome, "worker-1", 0u); + wel.get<"heartbeat_ms">().set(2000u); + wel.get<"schema_version">().set(std::string{schema_version}); + + auto eo_text = encode_message<sch::MsgWelcome>(wel); + SAW_EXPECT(not eo_text.is_error(), "welcome encodes"); + auto eo_back = decode_message<sch::MsgWelcome>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "welcome decodes"); + SAW_EXPECT(eo_back.get_value().get<"heartbeat_ms">().get() == 2000u, + "heartbeat survives"); + + auto png = make_message<sch::MsgPing>(msg::ping, "worker-1", 5u); + png.get<"sent_at_ms">().set(999u); + auto eo_ptext = encode_message<sch::MsgPing>(png); + SAW_EXPECT(not eo_ptext.is_error(), "ping encodes"); + auto eo_pback = decode_message<sch::MsgPing>(eo_ptext.get_value()); + SAW_EXPECT(not eo_pback.is_error(), "ping decodes"); + SAW_EXPECT(eo_pback.get_value().get<"sent_at_ms">().get() == 999u, + "ping timestamp survives"); +} + +/** + * The two stage decode is the whole reason this protocol works without a + * tagged union: reading the header out of a full message has to succeed for + * every message type, skipping whatever payload it does not know about. + */ +SAW_TEST("Wire / the header can be read out of any message"){ + auto png = make_message<sch::MsgPing>(msg::ping, "w-a", 1u); + png.get<"sent_at_ms">().set(7u); + auto eo_png = encode_message<sch::MsgPing>(png); + SAW_EXPECT(not eo_png.is_error(), "ping encodes"); + + auto eo_hdr = peek_header(eo_png.get_value()); + SAW_EXPECT(not eo_hdr.is_error(), + "Reading a header out of a ping must skip the payload, not fail"); + SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::ping, "Header reports ping"); + SAW_EXPECT(header_worker_id(eo_hdr.get_value()) == "w-a", "Header reports the id"); + + auto pong = make_message<sch::MsgPong>(msg::pong, "w-b", 2u); + pong.get<"sent_at_ms">().set(1u); + pong.get<"worker_now_ms">().set(2u); + pong.get<"live">() = make_live(); + auto eo_pong = encode_message<sch::MsgPong>(pong); + SAW_EXPECT(not eo_pong.is_error(), "pong encodes"); + + auto eo_hdr2 = peek_header(eo_pong.get_value()); + SAW_EXPECT(not eo_hdr2.is_error(), + "A nested struct payload must also be skippable"); + SAW_EXPECT(header_type(eo_hdr2.get_value()) == msg::pong, "Header reports pong"); + SAW_EXPECT(header_worker_id(eo_hdr2.get_value()) == "w-b", "Header reports the id"); +} + +/** + * The failure this protocol must not have. codec_config<enc::Json>::strict + * defaults to false so that config files can omit their defaults; on a wire + * that would let a worker send "{}" and have it decode into a silently zeroed + * registration. + */ +SAW_TEST("Wire / an empty object is rejected, not defaulted"){ + auto eo = decode_message<sch::MsgPing>("{}"); + SAW_EXPECT(eo.is_error(), + "An empty object must not decode into a default constructed message"); +} + +SAW_TEST("Wire / a missing member is rejected at every nesting depth"){ + // Top level: seq absent. + { + auto eo = decode_message<sch::MsgPing>( + R"({"type":"ping","worker_id":"w","sent_at_ms":1})"); + SAW_EXPECT(eo.is_error(), "A missing top level member must fail"); + } + // One level down: live is present but incomplete. This is the case that + // matters most, since strictness has to reach into nested structs or a + // half filled capability would register cleanly. + { + auto eo = decode_message<sch::MsgPong>( + R"({"type":"pong","worker_id":"w","seq":1,"sent_at_ms":1,)" + R"("worker_now_ms":2,"live":{"state":"ready"}})"); + SAW_EXPECT(eo.is_error(), "A missing nested member must fail"); + } + // And the complete form of the same message must still pass, so the test + // above is not just rejecting everything. + { + auto eo = decode_message<sch::MsgPong>( + R"({"type":"pong","worker_id":"w","seq":1,"sent_at_ms":1,)" + R"("worker_now_ms":2,"live":{"state":"ready","uptime_ms":0,)" + R"("steps_done":0,"last_error":""}})"); + SAW_EXPECT(not eo.is_error(), "The complete message must still decode"); + } +} + +/** + * Forward compatibility in the direction that works: a newer worker sending + * members an older orchestrator has never heard of still registers. + */ +SAW_TEST("Wire / unknown members are skipped"){ + auto eo = decode_message<sch::MsgPing>( + R"({"type":"ping","worker_id":"w","seq":3,"sent_at_ms":8,)" + R"("future_field":{"nested":[1,2,3]},"another":"x"})"); + SAW_EXPECT(not eo.is_error(), + "A newer sender's extra members must be skipped, not rejected"); + SAW_EXPECT(eo.get_value().get<"seq">().get() == 3u, "Known members still land"); + SAW_EXPECT(eo.get_value().get<"sent_at_ms">().get() == 8u, "and keep their values"); +} + +SAW_TEST("Wire / malformed input errors rather than defaulting"){ + const char* bad[] = { + "", + "{", + R"({"type":"ping","worker_id":"w","seq":1,"sent_at_ms":1)", // truncated + R"({"type":"ping","worker_id":"w","seq":1,"sent_at_ms":1}})", // trailing + R"({"type":"ping","worker_id":"w","seq":"not a number","sent_at_ms":1})", + "[1,2,3]", + "null", + }; + + for(const char* text : bad){ + auto eo = decode_message<sch::MsgPing>(text); + SAW_EXPECT(eo.is_error(), std::string{"Malformed input must error: "} + text); + } +} + +/** + * The capability envelope is the largest thing on the wire and the one whose + * shape has to survive being read by a process built from different source. + */ +SAW_TEST("Wire / hello carries a capability round trip"){ + auto hello = make_message<sch::MsgHelloWebGl2>(msg::hello, "worker-9", 0u); + + auto& cap = hello.get<"capability">(); + cap.get<"worker_id">().set(std::string{"worker-9"}); + cap.get<"kind">().set(std::string{wkind::webgl2}); + cap.get<"schema_version">().set(std::string{schema_version}); + cap.get<"reported_at_ms">().set(1700000000000u); + cap.get<"user_agent">().set(std::string{"test-agent"}); + + auto& gl = cap.get<"webgl2">(); + + auto& lim = gl.get<"limits">(); + lim.get<"max_texture_size">().set(16384u); + lim.get<"max_3d_texture_size">().set(2048u); + lim.get<"max_array_texture_layers">().set(2048u); + lim.get<"max_draw_buffers">().set(8u); + lim.get<"max_color_attachments">().set(8u); + lim.get<"max_texture_image_units">().set(16u); + lim.get<"max_combined_texture_image_units">().set(32u); + lim.get<"max_renderbuffer_size">().set(16384u); + lim.get<"max_fragment_uniform_vectors">().set(224u); + lim.get<"max_viewport_dims">().at({{0u}}).set(16384u); + lim.get<"max_viewport_dims">().at({{1u}}).set(16384u); + + auto& feat = gl.get<"features">(); + feat.get<"webgl2">().set(true); + feat.get<"offscreen_canvas">().set(true); + feat.get<"color_buffer_float">().set(true); + feat.get<"color_buffer_half_float">().set(true); + feat.get<"texture_float_linear">().set(false); + feat.get<"float_blend">().set(false); + feat.get<"parallel_shader_compile">().set(true); + feat.get<"disjoint_timer_query">().set(false); + + auto& bud = gl.get<"budget">(); + bud.get<"probed_bytes_max">().set(536870912u); + bud.get<"probed_bytes_safe">().set(322122547u); + bud.get<"probe_trials">().set(14u); + bud.get<"context_lost_during_probe">().set(false); + bud.get<"probe_hit_texture_size_bound">().set(false); + bud.get<"safety_factor">().set(0.6f); + + // One feasible plan, enough to prove the array of nested structs survives. + { + data<sch::PackingPlan> plan; + plan.get<"layout">().set(std::string{"plain2d"}); + plan.get<"aux_mode">().set(std::string{"stuffed"}); + plan.get<"d">().set(2u); + plan.get<"q">().set(9u); + plan.get<"ghost">().set(0u); + plan.get<"storage_bits">().set(32u); + plan.get<"slots_per_texel">().set(4u); + plan.get<"textures_df">().set(3u); + plan.get<"textures_aux">().set(0u); + plan.get<"states">().set(2u); + plan.get<"passes">().set(1u); + plan.get<"idle_slots">().set(3u); + plan.get<"domain">().at({{0u}}).set(1024u); + plan.get<"domain">().at({{1u}}).set(256u); + plan.get<"domain">().at({{2u}}).set(1u); + plan.get<"tiles">().at({{0u}}).set(1u); + plan.get<"tiles">().at({{1u}}).set(1u); + plan.get<"tiles_pow2">().set(true); + plan.get<"texture_size">().at({{0u}}).set(1024u); + plan.get<"texture_size">().at({{1u}}).set(256u); + plan.get<"bytes_total">().set(1024u * 256u * 96u); + plan.get<"bytes_useful">().set(1024u * 256u * 96u); + + for(uint64_t i = 0u; i < 9u; ++i){ + auto eo = plan.get<"slot_tex_of_q">().add(data<sch::UInt8>{static_cast<uint8_t>(i / 4u)}); + SAW_EXPECT(not eo.is_error(), "slot_tex_of_q grows"); + auto eo2 = plan.get<"slot_cmp_of_q">().add(data<sch::UInt8>{static_cast<uint8_t>(i % 4u)}); + SAW_EXPECT(not eo2.is_error(), "slot_cmp_of_q grows"); + } + auto eo3 = plan.get<"slot_tex_of_aux">().add(data<sch::UInt8>{2u}); + SAW_EXPECT(not eo3.is_error(), "slot_tex_of_aux grows"); + auto eo4 = plan.get<"slot_cmp_of_aux">().add(data<sch::UInt8>{1u}); + SAW_EXPECT(not eo4.is_error(), "slot_cmp_of_aux grows"); + auto eo5 = plan.get<"aux_names">().add(data<sch::String>{std::string{"info"}}); + SAW_EXPECT(not eo5.is_error(), "aux_names grows"); + + auto eo6 = gl.get<"feasible">().add(std::move(plan)); + SAW_EXPECT(not eo6.is_error(), "feasible grows"); + } + + auto eo_text = encode_message<sch::MsgHelloWebGl2>(hello); + SAW_EXPECT(not eo_text.is_error(), "A complete capability must encode"); + + // The header has to be readable out of the biggest message we have. + auto eo_hdr = peek_header(eo_text.get_value()); + SAW_EXPECT(not eo_hdr.is_error(), "The header must survive a large payload"); + SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::hello, "Header reports hello"); + + // Routing pass: the common fields alone are enough to learn the kind, and + // the webgl2 section is skipped because it is not named here. + auto eo_route = decode_message<sch::MsgHello>(eo_text.get_value()); + SAW_EXPECT(not eo_route.is_error(), "The routing decode must succeed"); + SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view() + == wkind::webgl2, "The routing decode must report the kind"); + + auto eo_back = decode_message<sch::MsgHelloWebGl2>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "A complete capability must decode"); + auto& back = eo_back.get_value().get<"capability">(); + + SAW_EXPECT(back.get<"kind">().stl_view() == wkind::webgl2, "kind survives"); + SAW_EXPECT(back.get<"webgl2">().get<"limits">().get<"max_texture_size">().get() + == 16384u, "Deeply nested integers survive"); + SAW_EXPECT(back.get<"webgl2">().get<"features">().get<"color_buffer_float">().get(), + "Booleans survive"); + SAW_EXPECT(back.get<"webgl2">().get<"budget">().get<"probe_trials">().get() == 14u, + "Budget survives"); + + auto& feasible = back.get<"webgl2">().get<"feasible">(); + SAW_EXPECT(feasible.meta().flat_at(0u).get() == 1u, "One plan came back"); + auto& plan_back = feasible.at({{0u}}); + SAW_EXPECT(plan_back.get<"q">().get() == 9u, "Plan Q survives"); + SAW_EXPECT(plan_back.get<"layout">().stl_view() == "plain2d", "Plan layout survives"); + SAW_EXPECT(plan_back.get<"slot_tex_of_q">().meta().flat_at(0u).get() == 9u, + "The slot table keeps its length"); + SAW_EXPECT(plan_back.get<"slot_tex_of_q">().at({{8u}}).get() == 2u, + "Direction 8 lives in texture 2"); + SAW_EXPECT(plan_back.get<"slot_cmp_of_q">().at({{8u}}).get() == 0u, + "Direction 8 lives in channel 0"); + SAW_EXPECT(plan_back.get<"aux_names">().at({{0u}}).stl_view() == "info", + "Arrays of strings survive"); +} + +/** + * A worker of a kind we do not know about still has to be readable far enough + * to find out that we do not know about it. This is the envelope earning its + * keep. + */ +SAW_TEST("Wire / an unknown worker kind is still routable"){ + const char* text = + R"({"type":"hello","worker_id":"w-x","seq":0,)" + R"("capability":{"worker_id":"w-x","kind":"webgpu","schema_version":"1",)" + R"("reported_at_ms":1,"user_agent":"a","webgpu":{"whatever":true}}})"; + + auto eo_hdr = peek_header(text); + SAW_EXPECT(not eo_hdr.is_error(), + "An unknown backend section must not stop the header decoding"); + SAW_EXPECT(header_type(eo_hdr.get_value()) == msg::hello, "Still a hello"); + SAW_EXPECT(header_worker_id(eo_hdr.get_value()) == "w-x", "Still identifiable"); + + // The routing decode succeeds and names the kind, which is exactly what it + // is for: an unusable worker is still an identifiable worker. + auto eo_route = decode_message<sch::MsgHello>(text); + SAW_EXPECT(not eo_route.is_error(), + "The common fields of an unknown kind must still decode"); + SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view() + == "webgpu", "The orchestrator learns which kind it cannot use"); + + // Decoding it as a webgl2 hello must fail, because "webgl2" is absent -- + // that is the orchestrator learning it cannot use this worker, which is a + // different and better outcome than a zeroed capability. + auto eo_full = decode_message<sch::MsgHelloWebGl2>(text); + SAW_EXPECT(eo_full.is_error(), + "A webgl2 decode of a webgpu worker must fail rather than zero fill"); +} +/** + * Native workers are a worker kind, not a test fixture, so the same routing has + * to work for them -- and crucially a native hello must not be obliged to carry + * a texture budget it has no way to measure. + */ +SAW_TEST("Wire / a native worker registers without a webgl section"){ + auto hello = make_message<sch::MsgHelloNative>(msg::hello, "n-1", 0u); + + auto& cap = hello.get<"capability">(); + cap.get<"worker_id">().set(std::string{"n-1"}); + cap.get<"kind">().set(std::string{wkind::native}); + cap.get<"schema_version">().set(std::string{schema_version}); + cap.get<"reported_at_ms">().set(1700000000000u); + cap.get<"user_agent">().set(std::string{"kel-lbm-worker-native"}); + + auto& nat = cap.get<"native">(); + nat.get<"threads">().set(16u); + nat.get<"memory_bytes">().set(34359738368u); + nat.get<"cpu">().set(std::string{"x86_64"}); + nat.get<"has_sycl">().set(false); + + auto eo_text = encode_message<sch::MsgHelloNative>(hello); + SAW_EXPECT(not eo_text.is_error(), "A native hello must encode"); + + // Routes the same way a browser does. + auto eo_route = decode_message<sch::MsgHello>(eo_text.get_value()); + SAW_EXPECT(not eo_route.is_error(), "A native hello must route"); + SAW_EXPECT(eo_route.get_value().get<"capability">().get<"kind">().stl_view() + == wkind::native, "Routing reports native"); + + auto eo_back = decode_message<sch::MsgHelloNative>(eo_text.get_value()); + SAW_EXPECT(not eo_back.is_error(), "A native hello must decode"); + SAW_EXPECT(eo_back.get_value().get<"capability">().get<"native">() + .get<"threads">().get() == 16u, "Thread count survives"); + + // And the point of the restructure: this text has no webgl2 section at all, + // so a decode that demands one has to fail rather than zero fill. + auto eo_wrong = decode_message<sch::MsgHelloWebGl2>(eo_text.get_value()); + SAW_EXPECT(eo_wrong.is_error(), + "A native worker must not decode as a webgl2 one"); +} +} |
