Architecture Guide
Membrane API Gateway is composed of several components. Because the components are described by an interface, the implementations can be exchanged and Membrane's behavior can be modified and extended. The runtime configuration of the components and their connections is defined by a Spring configuration file. Using the plan described in this file, Membrane Service Proxy's components are assembled during startup. You can see the main building blocks in figure 1.
Figure1:
A Handler waits for incoming HTTP requests. After the arrival of a request, a new Exchange object is created and passed to the Transport, a global chain of interceptors. Each interceptor can read and manipulate the HTTP request associated with each Exchange object that flows through it. The last interceptor is - in the standard setup of Membrane Service Proxy - an instance of HttpClientInterceptor, which sends the HTTP request to its destination outside of the Service Proxy.
The HttpClientInterceptor then associates the HTTP response with the Exchange object and sends the Exchange object off on its way back through the chain of interceptors.
Sub-chains, Proxies and User Feature
As on a global scale, the desired behaviour is very similar for each request, Membrane has a global interceptor chain, which is the same for all requests. This chain is called the transport chain.
Distinct behavior for different requests is implemented using the User Feature Interceptor. The userFeature interceptor is - in the standard setup - part of the transport chain. It passes flow control on to a sub-chain of interceptors. This chain - as opposed to the global chain - can be different for two requests. The subchain is selected based on one of the request's properties (path, host, port, etc.).
The subchain is managed by a proxy object. A proxy consists of two things: It defines criteria which requests should be handled by it (a filter) and a list of what should be done with it (the sub-chain of interceptors).
Membrane selects the first proxy defined in its configuration file matching the request.
Components
Exchange
An exchange object is a pair of one HTTP request and one HTTP response.
Interceptor
An interceptor can read and modify the Exchange object as well as its HTTP request and HTTP response objects.
Interceptor Chain
A chain of interceptors is simply a list of interceptors with associated flow control: During request handling in the chain, each interceptor can decide whether the exchange should be passed on down or return back up. (Details.)
Transport
The Transport defines a global chain of interceptors. This chain controls the global flow of every Exchange handled by Membrane Service Proxy.
Handler
A Handler waits for incoming HTTP requests. When a new request arrives, it creates an Exchange for the request. The Exchange is then passed on to the Transport chain. When the Transport chain completes, the Handler sends the response back to the caller.
Filter
A filter is a set of criteria for a HTTP request. A request has to meet all the criteria for the filter to match.
Target
A target is a URL or a hostname with an optional port.
Proxy
A proxy is the combination 1. a filter, 2. a target and 3. a chain of interceptors.
Proxies are the central components of Membrane Service Proxy.
For all HTTP requests matching their filter criteria, a proxy defines how to modify the request, and where to forward it. (Note that both modifying and forwarding are optional.)
Rule Matching
The Rule Matching interceptor selects the proxy for a request. The first proxy whose criteria are matched by the request is chosen.
Dispatching
The Dispatching interceptor adjusts a HTTP request for forwarding: It sets the Exchange's destination based on its proxy's target.
User Feature
The User Feauter Interceptor passes flow control for an Exchange object on to the chain of interceptors defined its proxy.
HttpClient
The HTTP Client Interceptor forwards the request to its exchange's destination. The HTTP response is then associated with the Exchange and the flow direction is reversed.