Changelog

Copy Markdown View Source

All notable changes to bloccs are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[0.2.0] — 2026-06-05

Added

  • Introspection API — a read-only window into running networks, the foundation an observability dashboard (bloccs_web) reads. All additive.
    • Bloccs.Introspect — list_networks/0 (summaries), network/1 (a normalized Bloccs.Introspect.Network with nodes, ports, effects, edges, per-node concurrency, supervision strategy, and exposed ports), producers/1, and producer_state/1.
    • Bloccs.Introspect.glyph/1 — the canonical notation glyph for a node manifest (:source, :sink, :split, :batch, :join, :throttle, :delay, :node_effect, :node), so the notation stays a property of the library rather than being reinvented by each viewer.
    • Bloccs.Discovery — boot-time registration of running networks in a new Bloccs.NetworkRegistry, so tools enumerate live networks in O(1) without scanning the supervision tree. Entries are owned by each network's supervisor and clean up automatically when it stops or crashes. The generated supervisor now calls Bloccs.Discovery.register/2 from init/1 — recompile networks built with an older bloccs (mix bloccs.compile) to make them discoverable.
    • Bloccs.Producer.stats/1 — a safe, typed snapshot of a producer's queue (size, buffer, blocked, pending_demand, utilization) via a bounded GenStage call, so observers never reach in with :sys.get_state.
    • The generated supervisor gained __bloccs_introspect__/0 (topology + node→impl
      • supervision + exposed ports) feeding the API above.

0.1.1 — 2026-06-05

Changed

  • Docs: dropped the README Status and "Out of scope" sections (the roadmap now lives in GitHub Projects), corrected the License note to plain MIT (no Pro call-out), and refreshed the post-publish wording now that bloccs is on Hex.

0.1.0 — 2026-06-05

First public release.

Added

  • Manifest formats — TOML node manifests (.bloccs, one node per file) and network manifests, parsed into typed structs (Bloccs.Manifest.*) by Bloccs.Parser.
  • Validator — Bloccs.Validator enforces declared ports, end-to-end edge schema matching, DAG-only topology (cycle detection), effect declaration, and well-formed pure_core/effect_shell function refs.
  • use Bloccs.Node — compile-time parse + validate of a node's manifest, @after_compile arity check of the contract functions, and an AST-walk warning on use of undeclared effects.
  • Code generator — Bloccs.Compiler emits a Broadway supervision tree as real .ex source under _build/<env>/bloccs_generated/<network>/ (debuggable, PR-reviewable), one pipeline module per node plus a supervisor.
  • Runtime contracts, wired into the generated handle_message: retry (constant/linear/exponential back-off, matched on failure reason), timeout_ms (bounded task per attempt), idempotency (atomic in-flight reservation by key), bounded-buffer back-pressure (producer parks the caller, never drops), and :telemetry spans.
  • Effect capability model — pure core + effect shell split; four effect axes (http, db, time, random); declared axes bind to real adapters, undeclared axes bind to a denied-capability stub that raises. Mock adapters by default; real Bloccs.Effects.HTTP.Req and Bloccs.Effects.DB.Ecto behind a config switch, with :req/Ecto as optional deps.
  • Flow primitives — :drop (filter) and {:emit, [{port, payload}, …]} (split / multi-emit) effect-shell return shapes alongside the single {:emit, port, payload}; merge (several edges into one in-port); [batch] windows (size / timeout_ms) reduced by pure_core; [join] correlating two or more distinct typed in-ports by a key (on) — each in-port compiles to its own pipeline; partials past timeout_ms dead-letter; [rate] throttle and [delay] time-shift via the Broadway producer. A filtered message emits [:bloccs, :node, :dropped].
  • Subgraph composition — a [nodes] entry may use a network manifest; the parser flattens it into namespaced leaf nodes at parse time.
  • Trace + coverage — Bloccs.Trace records a run from telemetry to a .bloccs-trace; mix bloccs.coverage reports real structural coverage (in-ports, out-ports, edges reached) live (--message) or from a loaded trace (--trace).
  • CLI — mix bloccs.new, mix bloccs.validate, mix bloccs.compile, mix bloccs.run (with --message, --port, --trace), mix bloccs.coverage.
  • Examples — a graded ladder: examples/tour (core concepts, mock effects), examples/events (the flagship webhook processor — branching, fan-out, retry, timeout, idempotency, coverage), and examples/real_backend (real HTTP to a local stub + real SQLite).
  • Guides — core concepts, getting started, manifest reference, architecture, and effect adapters.

Known limitations

  • Cyclic networks are out of scope (DAG-only); feedback loops need a deadlock-safe edge mode still on the roadmap.