Gleam and Erlang OTP: Typed Actor Framework vs. External gen_server Wrappers

Direct recommendation

Use Gleam’s native gleam/otp actors for any supervision tree or stateful component whose behaviour is already covered by the library; reserve @external wrappers for Erlang OTP features that gleam/otp does not expose (e.g., low‑level handle_info with arbitrary terms, custom sys‑proc handling, or legacy gen_server callbacks).

Why this works

The gleam/otp layer gives compile‑time typed message contracts and integrates with Gleam’s type system, while still being supervised by the BEAM. When a required OTP behaviour is missing from the library, the only way to access it is through an Erlang module, which must be called via @external. In that case you lose static guarantees, so you must validate data at the boundary.

Steps to balance and validate

1. Audit the OTP features you need (supervisor specs, child specs, timeouts, handle_info, etc.).
2. If the feature exists in gleam/otp, implement it as a Gleam actor.
3. If not, create a thin Erlang gen_server module and wrap its public API with @external.
4. Define a Gleam opaque type for each datum that crosses the boundary (e.g., type ExternalPayload = ExternalPayload(InternalErlangTerm)).
5. Write encoder (ExternalPayload -> ErlangTerm) and decoder (ErlangTerm -> Result(ExternalPayload, String)) functions, using pattern matching or a schema library like gleam_schema to reject malformed terms.
6. In the @external call site, decode incoming terms before using them, and encode outgoing terms before sending them.
7. Unit‑test the decoder with random or malformed Erlang terms (using gleam_check or expect) to ensure it returns Error instead of panicking.
8. Run the application under a test supervisor and inject unexpected terms to confirm that the supervision strategy isolates the faulty component.

If you are unsure whether a particular OTP callback (e.g., a custom handle_info that processes unexpected messages) is available in gleam/otp, let me know which specific feature you need so I can confirm whether a gleam/otp actor suffices or an @external wrapper is required.