Malla.Plugins.Request behaviour (malla v0.0.1-rc.1)

Copy Markdown View Source

Server-side plugin for handling incoming requests via the Malla request protocol.

This plugin defines the malla_request/3 callback that is invoked when a remote service makes a request using Malla.Request.request/4. It provides the default implementation that creates tracing spans, checks service status, executes the target function, and normalizes responses.

Plugins can override this callback to add cross-cutting concerns like authentication, rate limiting, validation, and logging.

Callback

Default Implementation

The default malla_request/3:

  1. Checks if service is running (returns error if not)
  2. Creates "request-in" span (child of caller's "request-out" span)
  3. Calls the target function with provided arguments
  4. Normalizes response via Malla.Status.public/1
  5. Emits [:malla, :request, :in] telemetry event
  6. Returns standardized response

Plugin Interception

Override malla_request/3 to intercept requests:

defmodule AuthPlugin do
  use Malla.Plugin

  defcb malla_request(fun, args, opts) do
    case verify_auth_token(opts[:auth_token]) do
      {:ok, user_id} ->
        # Add user_id to opts and continue
        {:cont, [fun, args, Keyword.put(opts, :user_id, user_id)]}

      {:error, _reason} ->
        {:error, :unauthorized}
    end
  end
end

Response Protocol

Functions called via the request protocol must return:

  • :ok | :created - Success without data

  • {:ok | :created, map | list} - Success with data

  • {:error, term} - Error (normalized via Malla.Status)
  • {:status, term} - Custom status (normalized via Malla.Status)

Callback Chain

When a request arrives:

malla_request/3 call
├─ ValidationPlugin.malla_request/3
├─ AuthPlugin.malla_request/3
├─ RateLimitPlugin.malla_request/3
└─ Default implementation
   ├─ Check service status
   ├─ Create "request-in" span
   ├─ Call target function
   ├─ Normalize response
   └─ Emit telemetry

Telemetry

Emits [:malla, :request, :in] events with:

  • Measurements: :counter, :duration
  • Metadata: :op, :result, plus standard fields

For Complete Documentation

See the Request Handling guide for comprehensive examples including:

  • Authentication plugins
  • Rate limiting plugins
  • Validation plugins
  • Composing multiple plugins
  • Conditional plugin logic
  • Testing strategies

See Also

Summary

Callbacks

malla_request(atom, list, keyword)

Default implementation for incoming requests.

Callbacks

malla_request(atom, list, keyword)

(optional) 
@callback malla_request(atom(), list(), keyword()) ::
  {:ok | :created, map()}
  | {:error | :status, Malla.Status.t()}
  | {:error, :malla_service_not_available}
  | {:error, {:malla_rpc_error, any()}}

Default implementation for incoming requests.

  • First it checks if service is running, returning {:error, :malla_service_not_available} in that case
  • It tries to use base span_id in option base_span_id