9.1.0.0 | Architecture | System Model

This version of the docs is a work in progress. If you don’t see what you are looking for check the legacy wiki.

The Repose system-model.cfg.xml is the main configuration file for Repose. It outlines the deployment layout and behavior for Repose. Repose must be aware of this in order to configure itself and correctly coordinate routing if necessary. Additionally, the system model lets Repose know where the other Repose nodes reside. Using this information, Repose can coordinate its own clustering to share data among nodes that share common filters.

Model Definitions

Endpoint: An endpoint is a special type of destination. An endpoint destination can specify an exact node to which requests can be routed. This element can contain protocol, hostname, root-path, and port elements that are used in constructing a route. If the endpoint is within the same container as Repose, protocol, hostname and port are not specified.
Destinations: An enumeration of eligible routes to which HTTP messages can be forwarded. These are listed in the destinations section of the system model. If a destination is requested that is not listed in this section, a "service not available" code is returned. The destination selected for routing is determined during processing (e.g., by the Destination Router Filter) with the default destination being used if no other destination was selected.
Filter: An HTTP message interceptor that provides a specific piece of business functionality. A filter contains a Repose specific named reference.
Filters (Filter Chain): A sequence of filters that will intercept and process the request and/ord response. The request will be processed in order starting from the topmost filter in the sequence down to the bottom. The response will be processed in order starting from the bottommost filter in the sequence up to the top.
Node: A named reference that may be used to locate a network endpoint. The hostname may be the human readable, string representation of an IPv4 or IPv6 address or a named reference that an IPv4 or IPv6 address.
Service: A service is any served REST API bound to a TCP/IP address and port. A service is considered served and available so long as it is addressable and accessible to a separate processes (local or remote).
Services: A sequence of services that will be loaded into the servlet context to be available for filters.

Configuration

This section is only meant to explain certain quirks of the system model, and to provide a link to the comprehensive configuration schema. Other aspects of configuration will be explained through examples. See: Repose Deployment Scenarios

Since port numbers below 1024 are privileged, Repose typically can not connect directly to them. There are several ways to go about getting around this, but one of the most generally accepted ways is to execute the following commands with root privilege (e.g., sudo):

/sbin/iptables -t nat -I PREROUTING -p tcp --dport  80 -j REDIRECT --to-port 8080
/sbin/iptables -t nat -I PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

Schema

Repose Deployment Scenarios

Simple Pass-Through Proxy

system-model.cfg.xml

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <nodes>
    <node id="repose_node1" (1)
          hostname="localhost" (2)
          http-port="8080"/> (3)
  </nodes>

  <filters/> (4)

  <services/> (5)

  <destinations>
    <endpoint id="open_repose" (6)
              protocol="http" (7)
              hostname="openrepose.org" (8)
              root-path="/" (9)
              port="80" (10)
              default="true"/> (11)
  </destinations>
</system-model>

1	Defines a new Repose node with an ID that must be unique across all defined nodes in the list.
2	Defines the hostname of the Repose node. If set to localhost, any physical node will match and run the Repose node.
3	Defines the port for the node to listen on.
4	Defines a sequence of filters to run. In this case, no filters are being used.
5	Defines a set of services to run. In this case, no services are being used.
6	Defines a new endpoint with an ID that must be unique across all defined endpoints in the destinations list. There must be exactly one default destination endpoint.
7	Defines the endpoint’s protocol. If the protocol is not specified, then internal dispatch is assumed.
8	Defines the endpoint’s host name. If not specified, localhost is assumed.
9	Defines the endpoint’s base path. This will be used in building the URI/path for connecting to the service. Any additional URI info will be appended to this.
10	Defines the endpoint’s port. If not specified (or 0), internal dispatch is assumed.
11	Specifies whether or not this is the default destination endpoint. The default destination endpoint will be responsible for handling all traffic that is not explicitly routed to a different destination endpoint.

Filter Activation Determination

system-model.cfg.xml

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <nodes>
    <node id="repose_node" hostname="localhost" http-port="8080"/> (1)
  </nodes>

  <filters> (2)
    <filter name="ip-user"> (3)
        <and> (4)
          <methods value="GET HEAD POST PUT"/> (5)
          <or> (6)
            <header name="foo"/> (7)
            <header name="bar" value="BaZ"/> (8)
          </or>
          <not> (9)
            <uri regex="^/v1/[^/]+/[^/]+/public/?"/> (10)
          </not>
        </and>
    </filter>
  </filters>

  <services/> (11)

  <destinations>
    <endpoint id="origin_service" protocol="http" port="80" default="true"/> (12)
  </destinations>
</system-model>

1	Defines a new Repose node.
2	Defines a sequence of filters to run.
3	Defines the IP User Filter should be used.
4	Defines a boolean `AND` operator where all direct sub-elements must evaluate to `true`.
5	Defines the space separated list of case sensitive methods to check the current request against.
6	Defines a boolean `OR` operator where at least one direct sub-element must evaluate to `true`.
7	Defines that a header named `foo` (case insensitive) must be defined.
8	Defines that a header named `bar` (case insensitive) must be defined and have a value of `BaZ` (case sensitive).
9	Defines a boolean `NOT` operator that negates the result of the single direct sub-element’s evaluation.
10	Defines the Java regular expression the URI must match. This particular one requires that it has exactly four total path segments, the first path segment must be `v1`, the fourth path segment is `public`, and the trailing slash is optional. Example: `/v1/two/three/public`
11	Defines a set of services to run. In this case, no services are being used.
12	Defines the required one default endpoint.

Streaming Request Body to the Origin Service

Streaming a request body to the origin service is accomplished by using the chunked transfer encoding.

system-model.cfg.xml

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <nodes>
    <node id="repose_node" hostname="localhost" http-port="8080"/>
  </nodes>

  <filters/>

  <destinations>
    <endpoint id="origin_service" default="true" protocol="http" port="80"
              chunked-encoding="auto"/> (1)
  </destinations>
</system-model>

1 Determines whether or not the request body should be chunked when forwarded to the origin service. If set to true, the request body will always be transferred chunked encoded. If set to false, the request body will never be transferred chunked encoded. If set to auto, the request body will only be transferred chunked encoded if the original request to Repose was transferred chunked encoded.
Default: true

If the origin service does not support the chunked transfer-encoding (e.g., WSGI), it can be turned off easily. Simply set the chunked-encoding attribute to false.

Setting the chunked-encoding attribute to false may cause Repose to read and temporarily buffer the request body content. This will cause some performance degradation as request body is no longer always streamed through. It is recommended that users leave this value as true unless their service does not support chunked encoding.

Header Encoding

If headers got added to the request while processing through Repose that contain characters that are valid by the HTTP spec this allows them to be encoded before being sent to the origin service.

system-model.cfg.xml

<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <nodes>
    <node id="repose_node" hostname="localhost" http-port="8080"/>
  </nodes>

  <filters/>

  <destinations url-encode-headers="x-header-1,x-header-2"> (1)
    <endpoint id="origin_service" default="true" protocol="http" port="80"
              chunked-encoding="auto"/>
  </destinations>
</system-model>

1	This is a comma separated list of all the headers that should be URL Encoded. Default: empty

Nova-API Localhost Deployment

IN PROGRESS

Health Check Passthrough

IN PROGRESS