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. Theprefix
argument specifies the prefix used. Each key is mapped to a corresponding keyword argument on theHTTPAdapter
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 orCIDR-notation ranges the client may never connect to (default: the local network).
filter.port_allowlist
: A comma-delimited list of TCP port numbersthat the client can connect to (default: 80, 8080, 443, 8443, 8000).
filter.port_denylist
: A comma-delimited list of TCP port numbers thatthe client may never connect to (default: none).
filter.hostname_denylist
: A comma-delimited list of hostnames thatthe client may never connect to (default: none).
filter.allow_ipv6
: Should the client be allowed to connect to IPv6hosts? (default: false, note: IPv6 is tricky to apply filtering rules comprehensively to).
- Return type
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
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 theRequestContext
. When HTTP requests are sent via this session, they will use connections from the providedHTTPAdapter
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
adapter (
HTTPAdapter
) – A transport adapter for making HTTP requests. Seehttp_adapter_from_config()
.session_cls (
Type
[BaseplateSession
]) – The type for the actual session object to put on the request context.