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)[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