Pyrox API Documentation¶
pyrox Module¶
pyrox.http.model Module¶
- class pyrox.http.model.HttpHeader(name)[source]¶
Bases: object
Defines the fields for a HTTP header
- Attributes:
- name A bytearray or string value representing the field-name of
- the header.
- class pyrox.http.model.HttpMessage(version='1.1')[source]¶
Bases: object
Parent class for requests and responses. Many of the elements in the messages share common structures.
- Attributes:
- headers A dictionary of the headers currently stored in this
- HTTP message.
- version A bytearray or string value representing the major-minor
- version of the HttpMessage.
- local_data The local_data variable is a dictionary that may be
- used as a holding place for data that other filters may then access and utilize. Setting entries in this dictionary does not modify the HTTP model in anyway.
- get_header(name)[source]¶
Returns the header that matches the name via case-insensitive matching. Unlike the header function, if the header does not exist then a None result is returned.
- header(name)[source]¶
Returns the header that matches the name via case-insensitive matching. If the header does not exist, a new header is created, attached to the message and returned. If the header already exists, then it is returned.
- remove_header(name)[source]¶
Removes the header that matches the name via case-insensitive matching. If the header exists, it is removed and a result of True is returned. If the header does not exist then a result of False is returned.
- class pyrox.http.model.HttpRequest[source]¶
Bases: pyrox.http.model.HttpMessage
HttpRequest defines the HTTP request attributes that will be available to a HttpFilter.
- Attributes:
- method A bytearray or string value representing the request’s
- method verb.
- url A bytearray or string value representing the requests’
- uri path including the query and fragment string.
- class pyrox.http.model.HttpResponse[source]¶
Bases: pyrox.http.model.HttpMessage
HttpResponse defines the HTTP response attributes that will be available to a HttpFilter.
- Attributes:
- status A string representing the response’s status code and
- potentially its human readable component delimited by a single space.
pyrox.filtering.pipeline Module¶
- class pyrox.filtering.pipeline.FilterAction(kind=0, payload=None)[source]¶
Bases: object
A filter action allows us to tell upstream controls what the filter has decided as the next course of action. Certain filter actions may include a response object for serialization out to the client in the case where the action enforces a rejection.
- Attributes:
- kind An integer value representing the kind of action this
- object is intended to communicate.
payload An argument to be passed on to the consumer of this action.
- class pyrox.filtering.pipeline.HttpFilter[source]¶
Bases: object
HttpFilter is a marker class that may be utilized for dynamic gathering of filter logic.
- class pyrox.filtering.pipeline.HttpFilterPipeline[source]¶
Bases: object
The filter pipeline represents a series of filters. This pipeline currently serves bidirectional filtering (request and response). This chain will have the request head and response head events passed through it during the lifecycle of a client request. Each request is assigned a new copy of the chain, meaning that state may not be shared between requests during the lifetime of the filter chain or its filters.
Parameters: chain – A list of HttpFilter objects organized to act as a pipeline with element 0 being the first to receive events.
- pyrox.filtering.pipeline.consume()[source]¶
Consumes the event and does not allow any further downstream filters to see it. This effectively halts execution of the filter chain but leaves the request to pass through the proxy.
- pyrox.filtering.pipeline.handles_request_body(request_func)[source]¶
This function decorator may be used to mark a method as usable for intercepting request body content.
handles_request_body will intercept the HTTP content in chunks as it arrives. This method, like others in the filter class may return a FilterAction.
- pyrox.filtering.pipeline.handles_request_head(request_func)[source]¶
This function decorator may be used to mark a method as usable for intercepting request head content.
handles_request_head will accept an HttpRequest object and implement the logic that will define the FilterActions to be applied to the request
- pyrox.filtering.pipeline.handles_response_body(request_func)[source]¶
This function decorator may be used to mark a method as usable for intercepting response body content.
handles_response_body will intercept the HTTP content in chunks as they arrives. This method, like others in the filter class, may return a FilterAction.
- pyrox.filtering.pipeline.handles_response_head(request_func)[source]¶
This function decorator may be used to mark a method as usable for intercepting response head content.
handles_response_head will accept an HttpResponse object and implement the logic that will define the FilterActions to be applied to the request
- pyrox.filtering.pipeline.next()[source]¶
Passes the current http event down the filter chain. This allows for downstream filters a chance to process the event.
- pyrox.filtering.pipeline.reject(response=None)[source]¶
Rejects the request that this event is related to. Rejection may happen during on_request and on_response. The associated response parameter becomes the response the client should expect to see. If a response parameter is not provided then the function will default to the configured default response.
Parameters: response – the response object to reply to the client with
- pyrox.filtering.pipeline.reply(response, src)[source]¶
A special type of rejection that implies willful handling of a request. This call may optionally include a stream or a data blob to take the place of the response content body.
Parameters: response – the response object to reply to the client with
- pyrox.filtering.pipeline.route(upstream_target)[source]¶
Routes the request that this event is related to. Usage of this method will halt execution of the filter pipeline and begin streaming the request to the specified upstream target. This method is invalid for handling an upstream response.
Parameters: upstream_target – the URI string of the upstream target to route to.
pyrox.server.config Module¶
- class pyrox.server.config.CoreConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Pyrox core configuration section.
# Core section [core]
- bind_host[source]¶
Returns the host and port the proxy is expected to bind to when accepting connections. This option defaults to localhost:8080 if left unset.
bind_host = localhost:8080
- enable_profiling[source]¶
Returns a boolean value representing whether or not Pyrox should use a special single-process start up and run sequence so that code may be profiled. If unset, this defaults to False.
NOTE: If enabled, the number of processess Pyrox will be allowed to spin up will be limited to 1
enable_profiling = True
- plugin_paths[source]¶
Returns a list of directories to plug into when attempting to resolve the names of pipeline filters. This option may be a single directory or a comma delimited list of directories.
# Any of the below are acceptable plugin_paths = /usr/share/project/python plugin_paths = /usr/share/project/python,/usr/share/other/python plugin_paths = /opt/pyrox/stock, /opt/pyrox/contrib
- class pyrox.server.config.LoggingConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Pyrox logging configuration section.
# Logging section [logging]
- console[source]¶
Returns a boolean representing whether or not Pyrox should write to stdout for logging purposes. This value may be either True of False. If unset this value defaults to False.
console = True
- class pyrox.server.config.PipelineConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Pyrox pipeline configuration section.
# Pipeline section [pipeline]
Configuring a pipeline requires the admin to first configure aliases to each filter referenced. This is done by adding a named configuration option to this section that does not match “upstream” or “downstream.” Filter aliases must point to a class or function that returns a filter instance with the expected entry points.
After the filter aliases are specified, they may be then organized in comma delimited lists and assigned to either the “upstream” option for filters that should receive upstream events or the “downstream” option for filters that should receive downstream events.
In the context of Pyrox, upstream events originate from the requesting client also known as the request. Downstream events originate from the origin service (the upstream request target) and is also known as the response.
[pipeline] filter_1 = myfilters.upstream.Filter1 filter_2 = myfilters.upstream.Filter2 filter_3 = myfilters.downstream.Filter3 upstream = filter_1, filter_2 downstream = filter_3
- downstream[source]¶
Returns the list of filters configured to handle downstream events. This configuration option must be a comma delimited list of filter aliases. If left unset this option defaults to an empty tuple.
downstream = filter_3
- upstream[source]¶
Returns the list of filters configured to handle upstream events. This configuration option must be a comma delimited list of filter aliases. If left unset this option defaults to an empty list.
upstream = filter_1, filter_2
- use_singletons[source]¶
Returns a boolean value representing whether or not Pyrox should reuse filter instances for up and downstream aliases. This means, effectively, that a filter specified in both pipelines will maintain its state for the request and response lifecycle. If left unset this option defaults to false.
use_singletons = True
- class pyrox.server.config.RoutingConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Pyrox routing configuration section.
# Routing section [routing]
- upstream_hosts[source]¶
Returns a list of downstream hosts to proxy requests to. This may be set to either a single valid URL string or a comma delimited list of valid URI strings. This option defaults to http://localhost:80 if left unset.
upstream_hosts = http://host:port, https://host:port
- class pyrox.server.config.SSLConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Portal configuration section ‘ssl’
- class pyrox.server.config.TemplatesConfiguration(cfg, defaults=None)[source]¶
Bases: pyrox.util.config.ConfigurationPart
Class mapping for the Pyrox teplates configuration section.
# Templates section [templates]
pyrox.util.config Module¶
- class pyrox.util.config.ConfigurationPart(cfg, defaults=None)[source]¶
Bases: object
A configuration part is an OO abstraction for a ConfigParser that allows for ease of documentation and usage of configuration options. All subclasses of ConfigurationPart must follow a naming convention. A configuration part subclass must start with the name of its section. This must then be followed by the word “Configuration.” This convention results in subclasses with names similar to: CoreConfiguration and LoggingConfiguration.
A configuration part subclass will have its section set to the lowercase name of the subclass sans the word such that a subclass with the name, “LoggingConfiguration” will reference the ConfigParser section “logging” when looking up options.