internetdata_cowboy (internetdata_cowboy v1.0.1)

View Source

The official Cowboy middleware for the InternetData API.

It looks up the visitor behind each request - where they are, which network they come from, and whether it is a VPN, a proxy, Tor or a hosting server - and puts the answer on the request, where your handlers can read it with lookup/1. Blocking is opt-in.

Build the core once, at startup, and name this module in the middleware chain:

  {ok, Core} = internetdata_cowboy:core(#{api_key => os:getenv("INTERNETDATA_API_KEY")}),
  Dispatch = cowboy_router:compile([{'_', [{"/", my_handler, []}]}]),
  cowboy:start_clear(http, [{port, 8080}], #{
      env => #{dispatch => Dispatch, internetdata => Core},
      middlewares => [cowboy_router, internetdata_cowboy, cowboy_handler]
  }).

AFTER cowboy_router, so a skip can look at the matched route, and BEFORE cowboy_handler, so a blocked request never reaches one.

The framework-agnostic half lives in internetdata_middleware. Elixir's Plug.Cowboy runs the same chain, so this works there through protocol_options.

Summary

Functions

Build the core, refusing a condition that constrains nothing.

The Cowboy middleware callback. You do not call this yourself.

What the middleware found out about this visitor.

Types

options/0

-type options() ::
          #{on_blocked => fun((cowboy_req:req(), internetdata_middleware:lookup()) -> cowboy_req:req()),
            skip => fun((cowboy_req:req()) -> boolean()),
            _ => _}.

Functions

core(Options)

-spec core(options()) -> {ok, map()} | {error, term()}.

Build the core, refusing a condition that constrains nothing.

Do this ONCE, at startup, and put the result in the protocol env: it owns the HTTP client and the answer cache, and one per request would mean neither ever helps.

execute(Req, Env)

The Cowboy middleware callback. You do not call this yourself.

lookup(Req)

-spec lookup(cowboy_req:req()) -> internetdata_middleware:lookup() | undefined.

What the middleware found out about this visitor.

undefined when the middleware did not run for this route, or when skip claimed the request.