imanhodjaev / pumba

Pumba helps you

1. To fetch user agent strings for different browsers,
2. Keep in-memory state,
3. Randomly fetch any user agent,
4. Profit - Hakuna Matata 🦄

Use cases 🔮

You might want to use Pumba

1. To simulate real user agent when requesting website or resource,
2. To use in tandem with crawlers to randomly swap user agent strings,
3. Build REST API or any API on top of it or expose as a service,
4. Many other use cases I'm not aware (open issue to share one).

Installation 💾

If available in Hex, the package can be installed by adding pumba to your list of dependencies in mix.exs and if needed please add to application list to start:

def deps do
  [
    {:pumba, "~> 0.0.2"}
  ]
end

Usage 🧠

Load user agents

To load user agent strings for a given browser you need to call

iex> Pumba.load("Firefox")
:ok

Get random user agent

To load user agent strings for a given browser you need to call

iex> Pumba.random()
Mozilla/5.0 (X11; Linux ppc64le; rv:75.0) Gecko/20100101 Firefox/75.0

Check if user agents loaded

iex> Pumba.ready?("Firefox")
true

Get user agents for browser

iex> Pumba.get("Firefox")
[
  "Mozilla/5.0 (X11; Linux ppc64le; rv:75.0) Gecko/20100101 Firefox/75.0",
  ...
]

Set custom client

Default client fetches user agents from http://www.useragentstring.com.

There are two ways to set custom client first is via config second is overriding manually

Configuration

config :pumba,
  client: MyAwesomeClient

Runtime

iex> Pumba.set_client(MyAwesomeClient)

Create custom client

If you want to have your own client then it should implement Pumba.Client behaviour.

User agents storage

Storage is a GenServer which has the following state and lives at Pumba.UserAgents

%{
  client: Pumba.Client.DefaultClient,
  browsers: %{},
  names: []
}

Where browsers is a map with key as browser name and the list user agents as it's value, names is a list of loaded browsers using which we later can randomly pick browser and return a random user agent.

browsers contains %Pumba.Result{} record which keeps total count of user agents and indexed map with user agent strings for fast lookups.

Get current state

To get the latest state you can use Pumba.all/0 function.

Documentation 📜

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/pumba.

Assets 💄

https://www.flickr.com/photos/15622979@N07/4329873905