PcapFileEx.Flows.DecoderMatcher (pcap_file_ex v0.5.5)

View Source

Matcher and invoker for custom flow decoders.

Evaluates decoder specifications against match context and invokes matching decoders in order. Handles :skip fall-through and terminal errors.

Summary

Types

eval_result()

Result of decoder evaluation.

Functions

find_and_invoke(decoders, ctx, payload)

Find and invoke matching decoders for the given context and payload.

invoke_decoder(decoder, ctx, payload)

Invoke a decoder with the given context and payload.

matches?(matcher, ctx)

Check if a matcher matches the given context.

process_result(arg1)

Process the result from find_and_invoke into the final stored value.

Types

eval_result()

@type eval_result() :: {:ok, term()} | {:error, term()} | :skip

Result of decoder evaluation.

  • {:ok, term} - Decoder succeeded, to be wrapped as {:custom, term}
  • {:error, term} - Decoder failed (terminal), to be stored as {:decode_error, term}
  • :skip - No decoder matched or all returned :skip

Functions

find_and_invoke(decoders, ctx, payload)

@spec find_and_invoke(
  [PcapFileEx.Flows.Decoder.decoder_spec()],
  PcapFileEx.Flows.Decoder.match_context(),
  binary()
) :: eval_result()

Find and invoke matching decoders for the given context and payload.

Evaluates decoders in order. If a decoder returns :skip, continues to the next matching decoder. If a decoder returns {:error, reason}, stops immediately (terminal). Returns :skip if no decoder matches or all skip.

Parameters

  • decoders - List of decoder specifications
  • ctx - Match context with protocol, direction, and other metadata
  • payload - Binary payload to decode

Returns

  • {:ok, decoded} - A decoder succeeded
  • {:error, reason} - A decoder failed (terminal)
  • :skip - No decoder matched or all returned :skip

invoke_decoder(decoder, ctx, payload)

@spec invoke_decoder(
  PcapFileEx.Flows.Decoder.decoder_fn() | module(),
  PcapFileEx.Flows.Decoder.match_context(),
  binary()
) :: PcapFileEx.Flows.Decoder.decode_result()

Invoke a decoder with the given context and payload.

Handles:

  • Arity-1 functions: decoder.(payload), wraps result
  • Arity-2 functions: decoder.(ctx, payload), expects decode_result()
  • Modules: module.decode(ctx, payload), expects decode_result()

Exceptions are caught and returned as {:error, %{exception: e, stacktrace: st}}.

matches?(matcher, ctx)

@spec matches?(
  PcapFileEx.Flows.Decoder.matcher(),
  PcapFileEx.Flows.Decoder.match_context()
) ::
  boolean()

Check if a matcher matches the given context.

Map Matchers

All specified criteria must match:

  • :scope - Exact match
  • :port - Integer, Range, or list of integers
  • :content_type - String (exact), Regex, or list of strings
  • :content_id - String (exact) or Regex
  • :method - String or list of strings
  • :path - String (exact) or Regex

Function Matchers

Function receives the full context and returns boolean. Exceptions are caught and treated as no match.

process_result(arg1)

@spec process_result(eval_result()) ::
  {:custom, term()} | {:decode_error, term()} | :binary_fallback

Process the result from find_and_invoke into the final stored value.

Returns

  • {:custom, term} - Decoder succeeded
  • {:decode_error, reason} - Decoder failed
  • :binary_fallback - No decoder matched (caller should use {:binary, payload} or nil)