Electric.Client.ShapeState (Electric Client v0.9.1)

View Source

State for polling a shape.

This struct holds the state needed between polling requests, including:

  • The shape handle and offset for resuming
  • Schema and value mapper for parsing responses
  • Tag tracking data for generating synthetic deletes from move-out events

Usage

# Create initial state
state = ShapeState.new()

# Poll for changes
{:ok, messages, new_state} = Client.poll(client, shape, state)

# State can also be created from a ResumeMessage (interop with stream API)
state = ShapeState.from_resume(resume_message)

Summary

Types

t()

Functions

clear_stale_retry(state)

Clear stale retry state after a successful response.

enter_stale_retry(state)

Enter stale retry mode by setting a cache buster and incrementing the retry count.

from_resume(resume)

Create polling state from a ResumeMessage.

generate_cache_buster()

Generate a random cache buster string.

new(opts \\ [])

Create a new initial polling state.

reset(state, shape_handle)

Reset polling state for a new shape handle, preserving schema and value mapper.

to_resume(state)

Convert polling state to a ResumeMessage for use with the streaming API.

Types

t()

@type t() :: %Electric.Client.ShapeState{
  key_data: %{optional(term()) => %{tags: MapSet.t(), msg: term()}},
  next_cursor: binary() | nil,
  offset: Electric.Client.Offset.t(),
  schema: Electric.Client.schema() | nil,
  shape_handle: Electric.Client.shape_handle() | nil,
  stale_cache_buster: String.t() | nil,
  stale_cache_retry_count: non_neg_integer(),
  tag_to_keys: %{optional(term()) => MapSet.t()},
  up_to_date?: boolean(),
  value_mapper_fun: Electric.Client.ValueMapper.mapper_fun() | nil
}

Functions

clear_stale_retry(state)

@spec clear_stale_retry(t()) :: t()

Clear stale retry state after a successful response.

Called when we receive a fresh (non-stale) response from the server.

enter_stale_retry(state)

@spec enter_stale_retry(t()) :: t()

Enter stale retry mode by setting a cache buster and incrementing the retry count.

Called when a stale CDN response is detected - the server returns an expired handle that matches our cached expired handle.

from_resume(resume)

@spec from_resume(Electric.Client.Message.ResumeMessage.t()) :: t()

Create polling state from a ResumeMessage.

This allows interop between the streaming and polling APIs - you can use live: false to get a ResumeMessage from a stream, then continue polling from that point.

generate_cache_buster()

@spec generate_cache_buster() :: String.t()

Generate a random cache buster string.

Uses 8 random bytes encoded as hex (16 characters).

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new initial polling state.

Options

  • :shape_handle - Optional shape handle to resume from
  • :offset - Optional offset to resume from (default: before_all)
  • :schema - Optional schema for value mapping

reset(state, shape_handle)

@spec reset(t(), Electric.Client.shape_handle()) :: t()

Reset polling state for a new shape handle, preserving schema and value mapper.

Used when a 409 (must-refetch) response is received — the shape handle changes but the schema remains the same.

to_resume(state)

@spec to_resume(t()) :: Electric.Client.Message.ResumeMessage.t()

Convert polling state to a ResumeMessage for use with the streaming API.