Wiki.EventStreams (mediawiki_client v0.5.3)

View Source

This module reads from the real-time stream of server-sent events annotating actions such as editing or patrolling as they happen across Wikimedia projects.

For more about the public wiki streams and their format, see EventStreams on Wikitech

Examples

Listen for page creation, expose as a GenStage.stream and print a few:

{:ok, pid} = Wiki.EventStreams.start_link(streams: "page-create")
Wiki.EventStreams.stream(pid) |> Stream.take(1) |> Enum.to_list

Combine multiple feeds as one stream,

{:ok, pid} = Wiki.EventStreams.start_link(streams: ["revision-create", "page-create"])
Wiki.EventStreams.stream(pid)
|> Stream.take(6)
|> Enum.to_list

TODO

  • Track the restart ID, disconnect from the feed at some maximum queue size. Reconnect as demand resumes. Application-lifetime or permanent storage for the restart ID tracking, for consumers that need an at-least-once guarantee.

Summary

Types

  • :adapter - Override the HTTP adapter.
  • :endpoint - Override the default endpoint URL.
  • :stream_to - Optional application which will receive the events, otherwise they go to the process starting the EventStream.
  • :streams - One or more atoms with the stream names to subscribe to.
  • :user_agent - Custom user-agent header string

Functions

Return a list of currently available streams.

Start a supervisor tree to receive and relay server-side events.

Indefinitely capture subscribed events and relay them as a Stream.

Types

client_option()

@type client_option() ::
  {:adapter, module()}
  | {:endpoint, binary()}
  | {:stream_to, GenServer.server()}
  | {:streams, atom() | [atom()]}
  | {:user_agent, binary()}

client_options()

@type client_options() :: [client_option()]
  • :adapter - Override the HTTP adapter.
  • :endpoint - Override the default endpoint URL.
  • :stream_to - Optional application which will receive the events, otherwise they go to the process starting the EventStream.
  • :streams - One or more atoms with the stream names to subscribe to.
  • :user_agent - Custom user-agent header string

Functions

available_streams(opts \\ [])

@spec available_streams(keyword()) :: [{name :: binary(), description :: binary()}]

Return a list of currently available streams.

Note that the matching is intentionally fragile, on the assumption that the caller is interested in uncovering new routes (eg. a future "v3" or new route patterns) immediately.

Arguments

  • options - Keyword list,
    • {:adapter, module} - Override HTTPoison adapter.
    • {:endpoint, url} - Override default endpoint.

start_link(args)

@spec start_link(client_options()) :: GenServer.on_start()

Start a supervisor tree to receive and relay server-side events.

Arguments

  • options - Keyword list,
    • {:adapter, module} - Override HTTPoison adapter.
    • {:endpoint, url} - Override default endpoint.
    • {:send_to, pid | module} - Instead of using the built-in streaming relay, send the events directly to your own process.

    • {:streams, atom | [atom]} - Select which streams to listen to. An updated list can be found here. Required.

stream(pid, options \\ [])

@spec stream(pid(), client_options()) :: Enumerable.t()

Indefinitely capture subscribed events and relay them as a Stream.