distribute v3.0.0

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.14.0"
+      - 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,41 @@
+# Changelog
+
+## v3.0.0 — 2026-02-11
+
+Ground-up rewrite. Smaller API, proper OTP actors, compile-time type safety
+via `TypedName(msg)`. Not compatible with v2.
+
+### Removed
+
+Everything outside the core: crypto, discovery, settings, groups, monitoring,
+connection pool, retry. Also removed `whereis_global(name, encoder, decoder)`.
+
+### Changed
+
+- Actors are real `gen_statem` via `gleam/otp/actor` — `observer`,
+  `sys:get_status`, supervision trees all work.
+- Registry uses binary names with `:global`. No atoms created, no atom
+  table exhaustion.
+- `start`, `start_registered`, `start_supervised`, `pool` all take
+  `TypedName` instead of separate name + encoder + decoder.
+- `register` and `lookup` take `TypedName`. The compiler enforces that
+  both sides use the same `msg` type.
+- Each `GlobalSubject` gets a unique or deterministic tag (was shared
+  `Nil` in v2 — caused message mixing).
+- Orphaned actors are killed on registration failure in `start_supervised`.
+
+### Added
+
+- `TypedName(msg)` — opaque type binding a name to an encoder/decoder pair.
+- `Codec(a)` — bundles encoder + decoder + sized decoder. Shorthand
+  constructors: `int()`, `string()`, `float()`, `bool()`, `bitarray()`,
+  `nil()`, `list(c)`.
+- `codec.map(c, wrap, unwrap)` — derive a codec for a custom type.
+- `codec.subject()` — serialize a `Subject(BitArray)` for cross-node
+  request/response.
+- `global.call(target, make_request, response_decoder, timeout)` —
+  synchronous request/response across nodes.
+- `global.reply(reply_to, response, encoder)` — send a response back.
+- `composite.option(c)`, `composite.result(ok, err)`,
+  `composite.tuple2(a, b)`, `composite.tuple3(a, b, c)`.
+- `registry.named(name, codec)` — short form of `typed_name`.

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,154 @@
+# distribute
+
+<p align="center">
+  <img src="assets/img/distribute.png" alt="distribute logo" width="200" />
+</p>
+
+Typed distributed messaging for Gleam 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/)
+
+## What this is
+
+Erlang already gives you distribution, but from Gleam you lose type info at
+the node boundary — everything crosses the wire as raw terms. `distribute`
+puts binary codecs in front of `:global` and `Subject` so the compiler can
+catch mismatches before messages leave the process.
+
+"Typed" here means checked at encode/decode boundaries. There is no shared
+type system across nodes — the BEAM doesn't work that way.
+
+## Install
+
+```sh
+gleam add distribute
+```
+
+## Usage
+
+### Fire-and-forget
+
+Define a `TypedName(msg)` that pairs a name with a codec, then use it on
+both sides. The compiler won't let you register a `String` actor and look
+it up as `Int`.
+
+```gleam
+import distribute
+import distribute/codec
+import distribute/registry
+import distribute/receiver
+
+// one TypedName, shared across the codebase
+let greeter = registry.named("greeter", codec.string())
+
+// start + register
+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
+let assert Ok(remote) = distribute.lookup(greeter)
+let assert Ok(Nil) = distribute.send(remote, "hello")
+```
+
+### Request / response
+
+Include a reply `Subject(BitArray)` in your message type and use
+`codec.subject()` to serialize it. The `Subject` carries node info, so
+replies route back across nodes automatically.
+
+```gleam
+import distribute/codec
+import distribute/global
+import distribute/receiver
+import gleam/erlang/process
+
+type CounterMsg {
+  Inc(Int)
+  Get(reply: process.Subject(BitArray))
+}
+
+// handler side
+fn handle(msg, state) {
+  case msg {
+    Inc(n) -> receiver.Continue(state + n)
+    Get(reply) -> {
+      let _ = global.reply(reply, state, codec.int_encoder())
+      receiver.Continue(state)
+    }
+  }
+}
+
+// caller side
+let assert Ok(count) = global.call(counter, Get, codec.int_decoder(), 5000)
+```
+
+`global.call` creates a temporary subject, sends the request, waits for
+the response, decodes it. Same idea as `gen_server:call`.
+
+### Codecs
+
+Primitives: `codec.int()`, `codec.string()`, `codec.float()`, `codec.bool()`,
+`codec.bitarray()`, `codec.nil()`.
+
+Composites: `codec.list(c)`, `codec.subject()`, `codec.map(c, wrap, unwrap)`,
+`composite.option(c)`, `composite.result(ok, err)`,
+`composite.tuple2(a, b)`, `composite.tuple3(a, b, c)`.
+
+For your own types, use `codec.map`:
+
+```gleam
+type UserId { UserId(Int) }
+
+let user_id_codec = codec.map(codec.int(), UserId, fn(uid) {
+  let UserId(n) = uid
+  n
+})
+```
+
+Gleam has no derive macros or reflection, so codecs for complex types
+are manual. The combinators handle the serialization — you just wire
+the fields together.
+
+## Modules
+
+| Module | Does |
+|--------|------|
+| `distribute` | Facade — start node, connect, send, lookup |
+| `distribute/actor` | Named actors, supervision, pools |
+| `distribute/cluster` | `net_kernel` start/connect/ping |
+| `distribute/codec` | Binary codecs for primitives + `subject()` |
+| `distribute/codec/composite` | Option, Result, Tuple codecs |
+| `distribute/codec/tagged` | Tagged messages with version field |
+| `distribute/global` | `GlobalSubject(msg)`, `call`, `reply` |
+| `distribute/registry` | `TypedName(msg)`, `:global` registration |
+| `distribute/receiver` | Typed receive, OTP actor wrappers |
+
+## Caveats
+
+**What the types catch** — within one codebase, `TypedName` and
+`GlobalSubject` prevent mixing up message types at compile time.
+
+**What they don't** — two separate codebases using different codecs for
+the same name. The codec will reject the binary at runtime, not at compile
+time. Same for Erlang code sending raw terms to a `distribute` actor.
+
+**Subject construction** — Gleam's `Subject` is opaque. To build one from
+a remote PID and a deterministic tag (how registry lookup works), we
+construct the `{subject, Pid, Tag}` tuple in
+[one Erlang function](src/distribute_ffi_utils.erl). If `gleam_erlang`
+changes the internal representation, that single function needs updating.
+
+**No auto-derive** — Gleam doesn't have macros. Complex message codecs
+are manual. The combinators (`map`, `list`, `option`, `tuple2`, etc.)
+keep it manageable, but it's not zero-boilerplate.
+
+## Development
+
+```sh
+gleam test
+gleam docs build
+```

assets/img/distribute.png

@@ -0,0 +1,18 @@
+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" },
+]
+
+target = "erlang"
+
+[dependencies]
+gleam_stdlib = ">= 0.60.0 and < 2.0.0"
+gleam_erlang = ">= 1.0.0 and < 2.0.0"
+gleam_otp = ">= 1.0.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.68.1", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "F7FAEBD8EF260664E86A46C8DBA23508D1D11BB3BCC6EE1B89B3BC3E5C83FF1E" },
+  { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" },
+]
+
+[requirements]
+gleam_erlang = { version = ">= 1.0.0 and < 2.0.0" }
+gleam_otp = { version = ">= 1.0.0 and < 2.0.0" }
+gleam_stdlib = { version = ">= 0.60.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.