baseplate.clients.requests

Requests is a library for making HTTP requests. Baseplate provides two wrappers for Requests: the “external” client is suitable for communication with third party, potentially untrusted, services; the “internal” client is suitable for talking to first-party services and automatically includes trace and edge context data in requests. Baseplate uses Advocate to prevent the external client from talking to internal services and vice versa.

New in version 1.4.

Example

To integrate requests with your application, add the appropriate client declaration to your context configuration:

baseplate.configure_context(
   {
      ...
      # see above for when to use which of these
      "foo": ExternalRequestsClient(),
      "bar": InternalRequestsClient(),
      ...
   }
)

configure it in your application’s configuration file:

[app:main]

...

# optional: the number of connections to cache
foo.pool_connections = 10

# optional: the maximum number of connections to keep in the pool
foo.pool_maxsize = 10

# optional: how many times to retry DNS/connection attempts
# (not data requests)
foo.max_retries = 0

# optional: whether or not to block waiting for connections
# from the pool
foo.pool_block = false

# optional: address filter configuration, see
# http_adapter_from_config for all options
foo.filter.ip_allowlist = 1.2.3.0/24

...

and then use the attached Session-like object in request:

def my_method(request):
    request.foo.get("http://html5zombo.com")

Configuration

class baseplate.clients.requests.ExternalRequestsClient(**kwargs)[source]

Configure a Requests client for use with external HTTP services.

Requests made with this client will not include trace context and edge context. This client is suitable for use with third party or untrusted services.

This is meant to be used with baseplate.Baseplate.configure_context().

See http_adapter_from_config() for available configuration settings.

class baseplate.clients.requests.InternalRequestsClient(**kwargs)[source]

Configure a Requests client for use with internal Baseplate HTTP services.

Requests made with this client will include trace context and edge context. This client should only be used to speak to trusted internal services. URLs that resolve to public addresses will be rejected. It is not possible to override the Advocate address validator used by this client.

Warning

Requesting user-specified URLs with this client could lead to Server-Side Request Forgery. Ensure that you only request trusted URLs e.g. hard-coded or from a local configuration file.

This is meant to be used with baseplate.Baseplate.configure_context().

See http_adapter_from_config() for available configuration settings.

baseplate.clients.requests.http_adapter_from_config(app_config, prefix, **kwargs)[source]

Make an HTTPAdapter from a configuration dictionary.

The keys useful to http_adapter_from_config() should be prefixed, e.g. http.pool_connections, http.max_retries, etc. The prefix argument specifies the prefix used. Each key is mapped to a corresponding keyword argument on the HTTPAdapter constructor.

Supported keys:

  • pool_connections: The number of connections to cache (default: 10).

  • pool_maxsize: The maximum number of connections to keep in the pool (default: 10).

  • max_retries: How many times to retry DNS lookups or connection attempts, but never sending data (default: 0).

  • pool_block: Whether the connection pool will block when trying to get a connection (default: false).

Additionally, the rules for Advocate’s address filtering can be configured with the filter sub-keys:

  • filter.ip_allowlist: A comma-delimited list of IP addresses (1.2.3.4)

    or CIDR-notation (1.2.3.0/24) ranges that the client can always connect to (default: anything not on the local network).

  • filter.ip_denylist: A comma-delimited list of IP addresses or

    CIDR-notation ranges the client may never connect to (default: the local network).

  • filter.port_allowlist: A comma-delimited list of TCP port numbers

    that the client can connect to (default: 80, 8080, 443, 8443, 8000).

  • filter.port_denylist: A comma-delimited list of TCP port numbers that

    the client may never connect to (default: none).

  • filter.hostname_denylist: A comma-delimited list of hostnames that

    the client may never connect to (default: none).

  • filter.allow_ipv6: Should the client be allowed to connect to IPv6

    hosts? (default: false, note: IPv6 is tricky to apply filtering rules comprehensively to).

Return type

HTTPAdapter

Classes

class baseplate.clients.requests.BaseplateSession(adapter, name, span)[source]

A proxy for requests.Session.

Requests sent with this client will be instrumented automatically.

delete(url, **kwargs)[source]

Send a DELETE request.

See requests.request() for valid keyword arguments.

Return type

Response

get(url, **kwargs)[source]

Send a GET request.

See requests.request() for valid keyword arguments.

Return type

Response

head(url, **kwargs)[source]

Send a HEAD request.

See requests.request() for valid keyword arguments.

Return type

Response

options(url, **kwargs)[source]

Send an OPTIONS request.

See requests.request() for valid keyword arguments.

Return type

Response

patch(url, **kwargs)[source]

Send a PATCH request.

See requests.request() for valid keyword arguments.

Return type

Response

post(url, **kwargs)[source]

Send a POST request.

See requests.request() for valid keyword arguments.

Return type

Response

put(url, **kwargs)[source]

Send a PUT request.

See requests.request() for valid keyword arguments.

Return type

Response

prepare_request(request)[source]

Construct a PreparedRequest for later use.

The prepared request can be stored or manipulated and then used with send().

Return type

PreparedRequest

request(method, url, **kwargs)[source]

Send a request.

Parameters
  • method (str) – The HTTP method of the request, e.g. GET, PUT, etc.

  • url (Union[str, bytes]) – The URL to send the request to.

See requests.request() for valid keyword arguments.

Return type

Response

send(request, **kwargs)[source]

Send a PreparedRequest.

Return type

Response

class baseplate.clients.requests.RequestsContextFactory(adapter, session_cls)[source]

Requests client context factory.

This factory will attach a BaseplateSession to an attribute on the RequestContext. When HTTP requests are sent via this session, they will use connections from the provided HTTPAdapter connection pools and automatically record diagnostic information.

Note that though the connection pool is shared across calls, a new Session is created for each request so that cookies and other state are not accidentally shared between requests. If you do want to persist state, you will need to do it in your application.

Parameters
make_object_for_context(name, span)[source]

Return an object that can be added to the context object.

Parameters
  • name (str) – The name assigned to this object on the context.

  • span (Span) – The current span this object is being made for.

Return type

BaseplateSession