Threadline.OperatorSurface.Exports.FilterParams (Threadline v0.5.0)

Copy Markdown View Source

Parses a string-keyed URL params map into a keyword list ready for Threadline.Query.validate_timeline_filters!/1.

Used by both Threadline.OperatorSurface.Live.TimelineLive (LV-side) and Threadline.OperatorSurface.Controllers.ExportController (HTTP-side) so the two surfaces share one parser — guaranteeing the EXPO-05 byte-equality parity test holds for every input edge case (RESEARCH §"Pitfall 3").

Allowed URL keys

from, to, table, actor_kind, actor_id, correlation_id

Mapping to filter keys:

  • from/to — ISO-8601 datetime-local (16-char form YYYY-MM-DDTHH:MM is padded to :00Z; 19-char form YYYY-MM-DDTHH:MM:SS is padded to Z).
  • table — passed through verbatim.
  • actor_kind + actor_id — collapsed to a single actor_ref: %Threadline.Semantics.ActorRef{} keyword. actor_kind=anonymous strips actor_id. Other kinds require both fields.
  • correlation_id — passed through verbatim.

Atom safety

actor_kind is converted to an atom via String.to_existing_atom/1 — never via the unsafe variant that creates fresh atoms from arbitrary strings. The atom table (16 MiB default) is shared process-wide; unfiltered HTTP input could otherwise be used to fill it (RESEARCH §"Pitfall 11").

Summary

Functions

filters_raw_from_params(params)

Returns a string-keyed %{key => value} map suitable for re-rendering the filter form on URL paste. Mirrors the actor_kind=anonymous strip-id normalization so the form echoes the canonical (post-strip) URL.

parse(params)

Parses a string-keyed map of URL params into either a validated keyword list ready for Threadline.Query.validate_timeline_filters!/1 (success) or an {:error, message} tuple (failure — invalid datetime, unknown actor kind, or missing actor id).

Functions

filters_raw_from_params(params)

@spec filters_raw_from_params(map()) :: %{required(String.t()) => String.t()}

Returns a string-keyed %{key => value} map suitable for re-rendering the filter form on URL paste. Mirrors the actor_kind=anonymous strip-id normalization so the form echoes the canonical (post-strip) URL.

parse(params)

@spec parse(map()) :: {:ok, keyword()} | {:error, String.t()}

Parses a string-keyed map of URL params into either a validated keyword list ready for Threadline.Query.validate_timeline_filters!/1 (success) or an {:error, message} tuple (failure — invalid datetime, unknown actor kind, or missing actor id).

Returns {:ok, []} for an empty input map (no filters supplied).