distribute v3.0.0

Typed distributed messaging for Gleam on the BEAM.

Core: TypedName, Codec, GlobalSubject, gen_statem actors, :global registry.
103 tests, 0 warnings.

Author: lupodevelop

.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27.0"
+          gleam-version: "1.6.1"
+      - run: gleam deps download
+      - run: gleam test
+      - run: gleam format --check src test

.gitignore

@@ -0,0 +1,7 @@
+*.beam
+*.ez
+/build
+erl_crash.dump
+**/build
+*.log
+

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## v3.0.0 — 2026-02-11
+
+### ⚠️ Breaking — Complete rewrite
+
+v3 is a ground-up rewrite with a much smaller API surface. If you used v2, see the migration notes below.
+
+### What changed
+
+- **Removed** crypto, discovery, settings, groups, monitoring, connection pool,
+  retry, and all other modules outside the core scope.
+- **Removed** `whereis_global(name, encoder, decoder)` — replaced by
+  `registry.lookup(typed_name)` with compile-time type safety.
+- **Added** `TypedName(msg)` — an opaque type that binds a name string to an
+  encoder/decoder pair. Registration and lookup share the same `msg` type
+  parameter, enforced at compile time.
+- **Changed** all actor functions (`start`, `start_registered`,
+  `start_supervised`, `pool`) to accept `TypedName` instead of separate
+  name + encoder + decoder arguments.
+- **Changed** `distribute.register` and `distribute.lookup` to accept
+  `TypedName` instead of raw name strings.
+- **Changed** all distributed workers to be real OTP `gen_statem` behaviours
+  via `gleam/otp/actor`, instead of custom receive loops.
+- **Changed** registry to use binary names with `:global` — zero atom
+  creation, no atom table exhaustion risk.
+- **Fixed** shared `Nil` tag across all `GlobalSubject` — each now gets a
+  unique or deterministic tag.
+- **Fixed** race condition in `start_supervised` — orphaned actors are killed
+  on registration failure.
+- **Added** `Codec(a)` type — bundles encoder, decoder, and sized decoder.
+  Shorthand constructors: `int()`, `string()`, `float()`, `bool()`,
+  `bitarray()`, `nil()`, `list()`.
+- **Added** `codec.map(c, wrap, unwrap)` — derive a codec for a custom type
+  from an existing one.
+- **Added** `codec.nil()` — codec for `Nil`, for actors without payload.
+- **Added** `composite.option(c)`, `composite.tuple2(a, b)`,
+  `composite.tuple3(a, b, c)` — bundled `Codec` versions of composite codecs.
+- **Added** `registry.named(name, codec)` — shorter `TypedName` constructor
+  that takes a `Codec` instead of separate encoder + decoder.
+
+### What survived
+
+- `distribute/codec` — binary serialization
+- `distribute/cluster` — node management
+- `distribute/global` — `GlobalSubject(msg)`
+- `distribute/registry` — global name registration (now with `TypedName`)
+- `distribute/receiver` — message reception and actor wrappers
+- `distribute/actor` — actor lifecycle and supervision
+- `distribute` — facade module.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lupodevelop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,106 @@
+# distribute
+
+<p align="center">
+  <img src="assets/img/distribute.png" alt="distribute logo" width="200" />
+</p>
+
+A Gleam library for sending typed messages between nodes on the BEAM.
+
+[![Package Version](https://img.shields.io/hexpm/v/distribute)](https://hex.pm/packages/distribute)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/distribute/)
+
+## Why
+
+Erlang gives you distribution for free, but when you use it from Gleam you
+lose type information at the node boundary. The BEAM's distribution protocol
+sends raw terms.  `distribute` wraps the moving parts (`:global`, `net_kernel`,
+`Subject`) behind binary codecs so the compiler can catch the obvious mistakes
+before your messages go over the wire. ("Typed" here means checked at
+encode/decode boundaries not a shared type system across nodes.)
+
+It won't protect you from everything (see _Honest caveats_ below), but it
+makes the common path less error-prone.
+
+## How it works
+
+You define a `TypedName(msg)` that bundles a name string with a codec
+(encoder + decoder).  Use the same `TypedName` to register an actor and to
+look it up the compiler makes sure both sides agree on the `msg` type.
+
+Under the hood every actor is a regular `gen_statem` started through
+`gleam/otp/actor`, so `observer`, `sys:get_status` and supervision trees work
+as usual.
+
+## Quick start
+
+```sh
+gleam add distribute
+```
+
+```gleam
+import distribute
+import distribute/codec
+import distribute/registry
+import distribute/receiver
+
+pub fn main() {
+  // start a node
+  let assert Ok(Nil) = distribute.start("myapp@127.0.0.1", "secret")
+
+  // define the protocol — name + codec, shared across the codebase
+  let greeter = registry.named("greeter", codec.string())
+
+  // start a named actor and register it globally
+  let assert Ok(gs) = distribute.start_actor(greeter, Nil, fn(msg, _state) {
+    io.println("Got: " <> msg)
+    receiver.Continue(Nil)
+  })
+  let assert Ok(Nil) = distribute.register(greeter, gs)
+
+  // from any node: look up by the same TypedName and send
+  let assert Ok(remote) = distribute.lookup(greeter)
+  let assert Ok(Nil) = distribute.send(remote, "Hello, cluster!")
+}
+```
+
+## Modules
+
+| Module | What it does |
+|--------|-------------|
+| `distribute` | Facade — start, connect, send, lookup |
+| `distribute/actor` | Named actor lifecycle, supervision, pools |
+| `distribute/cluster` | Node start/connect/ping |
+| `distribute/codec` | Binary encoder/decoder for primitives |
+| `distribute/codec/composite` | Option, Result, Tuple codecs |
+| `distribute/codec/tagged` | Tagged messages with version checks |
+| `distribute/global` | `GlobalSubject(msg)` — typed wrapper around `Subject(BitArray)` |
+| `distribute/registry` | `TypedName(msg)`, global registration and lookup |
+| `distribute/receiver` | Message reception, OTP actor loops |
+
+## Honest caveats
+
+**What the types catch:**
+- Within one codebase, `TypedName` and `GlobalSubject` prevent you from mixing
+  up message types at compile time.
+
+**What they don't catch:**
+- Two separate projects using different codecs for the same name.  The codec
+  will reject the message at runtime, not at compile time.
+- Erlang code sending raw terms to a `distribute` actor.  Same story — runtime
+  rejection, no compile-time help.
+- The BEAM doesn't carry Gleam types across nodes.  `distribute` validates via
+  binary codecs, which is the best you can do, but it's not the same as a
+  shared type system.
+
+**Subject construction:** Gleam's `Subject` is opaque.  To build one from a
+remote PID and a deterministic tag (which is how registry lookup works), I
+construct the `{subject, Pid, Tag}` tuple in our own Erlang FFI
+([one function](src/distribute_ffi_utils.erl)).  If `gleam_erlang` changes the
+representation, that's the one place to update.
+
+## Development
+
+```sh
+gleam test         
+gleam docs build   
+```

assets/img/distribute.png

@@ -0,0 +1,19 @@
+name = "distribute"
+version = "3.0.0"
+description = "Typed distributed messaging for Gleam on the BEAM."
+licences = ["MIT"]
+repository = { type = "github", user = "lupodevelop", repo = "distribute" }
+links = [
+  { title = "GitHub", href = "https://github.com/lupodevelop/distribute" },
+]
+gleam = ">= 1.4.0"
+
+target = "erlang"
+
+[dependencies]
+gleam_stdlib = ">= 0.44.0 and < 2.0.0"
+gleam_erlang = ">= 0.5.0 and < 2.0.0"
+gleam_otp = ">= 0.1.0 and < 2.0.0"
+
+[dev-dependencies]
+gleeunit = ">= 1.0.0 and < 2.0.0"

gleam.toml

@@ -0,0 +1,15 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "gleam_erlang", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "1124AD3AA21143E5AF0FC5CF3D9529F6DB8CA03E43A55711B60B6B7B3874375C" },
+  { name = "gleam_otp", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "BA6A294E295E428EC1562DC1C11EA7530DCB981E8359134BEABC8493B7B2258E" },
+  { name = "gleam_stdlib", version = "0.67.1", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "6CE3E4189A8B8EC2F73AB61A2FBDE49F159D6C9C61C49E3B3082E439F260D3D0" },
+  { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" },
+]
+
+[requirements]
+gleam_erlang = { version = ">= 0.5.0 and < 2.0.0" }
+gleam_otp = { version = ">= 0.1.0 and < 2.0.0" }
+gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
+gleeunit = { version = ">= 1.0.0 and < 2.0.0" }

manifest.toml

@@ -0,0 +1,82 @@
+-module(cluster_ffi).
+-export([start_node/2, connect/1, nodes/0, self_node/0, ping/1,
+         is_ok_atom/1, get_error_reason/1, is_true/1, is_ignored/1]).
+
+-import(distribute_ffi_utils, [to_atom_safe/1]).
+
+%% Start a distributed BEAM node.
+%% Node names are created via binary_to_atom since they MUST be new atoms.
+%% Input is validated (max 512 bytes, no null bytes) before creation.
+start_node(Name, Cookie) ->
+    NameAtom = to_atom_force(Name),
+    Type = case string:tokens(atom_to_list(NameAtom), "@") of
+        [_, Host] ->
+            case lists:member($., Host) of
+                true -> longnames;
+                false -> shortnames
+            end;
+        _ -> shortnames
+    end,
+    try
+        net_kernel:start([NameAtom, Type]),
+        erlang:set_cookie(node(), to_atom_force(Cookie)),
+        ok
+    catch
+        Class:Reason ->
+            {error, iolist_to_binary(io_lib:format("~p:~p", [Class, Reason]))}
+    end.
+
+connect(Node) ->
+    case to_atom_safe(Node) of
+        {ok, A} ->
+            case net_kernel:connect_node(A) of
+                true -> true;
+                false -> false;
+                ignored -> ignored
+            end;
+        _ -> false
+    end.
+
+nodes() ->
+    [atom_to_binary(N, utf8) || N <- erlang:nodes()].
+
+self_node() ->
+    atom_to_binary(node(), utf8).
+
+ping(Node) ->
+    case to_atom_safe(Node) of
+        {ok, A} ->
+            case net_adm:ping(A) of
+                pong -> true;
+                _ -> false
+            end;
+        _ -> false
+    end.
+
+%% Helpers for Gleam FFI result classification (delegate to shared utils)
+is_ok_atom(V) -> distribute_ffi_utils:is_ok_atom(V).
+get_error_reason(V) -> distribute_ffi_utils:get_error_reason(V).
+
+is_true(true) -> true;
+is_true(_) -> false.
+
+is_ignored(ignored) -> true;
+is_ignored(_) -> false.
+
+%% Internal: create atom for node names/cookies (validated input only).
+to_atom_force(Bin) when is_binary(Bin) ->
+    case is_valid_node_input(Bin) of
+        true -> binary_to_atom(Bin, utf8);
+        false ->
+            try binary_to_existing_atom(Bin, utf8)
+            catch _:_ -> binary_to_atom(Bin, utf8)
+            end
+    end;
+to_atom_force(Bin) when is_list(Bin) ->
+    to_atom_force(list_to_binary(Bin));
+to_atom_force(Atom) when is_atom(Atom) ->
+    Atom.
+
+is_valid_node_input(Bin) when is_binary(Bin) ->
+    byte_size(Bin) =< 512 andalso
+    binary:match(Bin, <<"\0">>) =:= nomatch.