macula_response behaviour (macula v9.3.0)

View Source

Behaviour for supervised RPC responses.

advertise/5 on the raw SDK takes a bare handler fun invoked in a transient process spawned per inbound CALL (see the internal macula_station_link advertise/5 — "Handlers run in a transient process spawned per CALL"). This module gives that transient process a proper shape: each inbound call starts one supervised macula_response child (under a simple_one_for_one factory this module owns), threading state through Module:init/1 and Module:handle_request/2, and publishing rpc.received_v1 / rpc.replied_v1 mesh facts around the request. This is the provider-side counterpart to macula_request.

A crashing Module:handle_request/2 kills the response child; that composes with the SDK's own crash mapping unchanged, since gen_server:call/3 against a dead callee raises the same way a crashing bare handler fun already does.

Example

   -module(math_service).
   -behaviour(macula_response).
   -export([init/1, handle_request/2]).
  
   init(_Args) -> {ok, []}.
  
   handle_request(#{a := A, b := B}, State) ->
       {reply, #{result => A + B}, State}.
   {ok, _Sup} = macula_response:advertise(Pool, Realm,
       <<"math.add_v1">>, math_service, []).

Summary

Callbacks

handle_request/2
init/1
terminate/2

Functions

advertise(Pool, Realm, Procedure, Module, Args)

Advertise Procedure on Pool/Realm. Starts a private factory supervisor for per-request response children and registers a dispatch handler with macula:advertise/5. Returns the supervisor pid so the caller can supervise it (or ignore it).

advertise(Pool, Realm, Procedure, Module, Args, Opts)

As advertise/5. Opts may include announce (default true) and auth (forwarded to macula:advertise/5).

unadvertise(Pool, Realm, Procedure)

Stop advertising. Does not stop the factory supervisor returned by advertise/5,6 — callers that want to tear it down should exit(Sup, shutdown) themselves.

Callbacks

handle_request/2

-callback handle_request(Payload :: term(), State :: term()) ->
                            {reply, Reply :: term(), NewState :: term()} |
                            {error, Reason :: term(), NewState :: term()}.

init/1

-callback init(Args :: term()) -> {ok, State :: term()} | {stop, Reason :: term()}.

terminate/2

(optional) 
-callback terminate(Reason :: term(), State :: term()) -> any().

Functions

advertise(Pool, Realm, Procedure, Module, Args)

-spec advertise(macula:pool(), macula:realm(), macula:procedure(), module(), term()) ->
                   {ok, pid()} | {error, term()}.

Advertise Procedure on Pool/Realm. Starts a private factory supervisor for per-request response children and registers a dispatch handler with macula:advertise/5. Returns the supervisor pid so the caller can supervise it (or ignore it).

advertise(Pool, Realm, Procedure, Module, Args, Opts)

-spec advertise(macula:pool(), macula:realm(), macula:procedure(), module(), term(), map()) ->
                   {ok, pid()} | {error, term()}.

As advertise/5. Opts may include announce (default true) and auth (forwarded to macula:advertise/5).

unadvertise(Pool, Realm, Procedure)

-spec unadvertise(macula:pool(), macula:realm(), macula:procedure()) -> ok.

Stop advertising. Does not stop the factory supervisor returned by advertise/5,6 — callers that want to tear it down should exit(Sup, shutdown) themselves.