Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: for the plan.

Jump to: navigation, search

Gyrex/Concepts/Http Applications

The OSGi HTTP service allows registering servlets and resources which can then be accessed over HTTP. Gyrex makes heavy use of the OSGi HTTP service. All offered services are made available over HTTP. Additionally, an admin interface will be provided which can also be accessed over HTTP(S). In order to support good flexibility and scalable operation the concept of HTTP applications was created. This article describes the concept.

HTTP Applications

Gyrex allows the definition of HTTP applications. Applications may be defined programmatically using an OSGi service or in a declarative way using the Equinox extension registry to support lazy loading of applications and their resources.

Technically speaking, a HTTP application is a collection of servlets and resources. The main advantage compared to dealing with the OSGi HTTP Service directly is that Gyrex HTTP applications define their own URL space. Thus, servlets and resources are not mounted directly into the global namespace but into the namespace of the application.

Applications operate in a tenant-specific context. A separate instances of an application will be created per context. This allows operating multiple versions of the same application in parallel. For example, each tenant can run its own version and a tenant can also run different instances to allow concepts like staging/production.

Mount Points

Gyrex offers applications which run in a tenant-specific context. Thus, multiple instances of the same application may be running. Each instance may expose differences in its behavior and functionality depending on the context it is running in. When a HTTP request is received the platform must be able to quickly detect (a) the application and (b) the context. In order to achieve this, the concept of mounts will be used.

A mount is the binding of an URL to an application instance. The URL typically consists of a protocol, domain name, port and a path (eg. Path and port may be optional. If no path is provided, the "root" path (i.e. "/") will be used. If no specific port is provided, it will accept all ports. Everything below a mount point is intended to be controlled by the application. The allowed URL protocols are http and https.

An application typically consists of two mount points – a confidential and a non-confidential mount point. The confidential mount point guarantees that data be transmitted so as to prevent other entities from observing the contents of the transmission.

Gyrex will analyze incoming HTTP requests to read the protocol, domain name, port and the path for discovering the application instance bound to a specific context. The path matching will happen after domain matching. A prefix matching is applied following the behavior of the HTTP Service specification.

For domain names, a suffix matching will be applied. This allows to capture requests to sub-domains. The longest matching domain wins. For example, an application mount to "" will also receive requests to the "" sub-domain if there is no other application mounted to that sub-domain.

A network operator must ensure that all requests targeted at a HTTP application instance will reach the Gyrex cluster. A network operator must also ensure that confidential guarantees are preserved when routing the request to the Gyrex cluster.

HTTP Integration

HTTP Headers

Gyrex may support HTTP headers which allow to specify the original incoming URL if any system in front of Gyrex does not allow passing the original request. The following headers shall be supported.

  • X-Gyrex-OriginalURL
  • X-Gyrex-ClientIP
  • X-Gyrex-Key

X-Gyrex-OriginalURL .. the original, complete URL.

X-Gyrex-ClientIP .. the IP address of the client.

X-Gyrex-Key .. the key which identifies the source submitting the HTTP header. If no key or an invalid key is provided, Gyrex may reject the request or ignore the headers.

HTTP Service Scenarios

Gyrex will support the following HTTP Service scenarios.

  • Single HTTP Service
  • Multiple HTTP Services

Single HTTP Service .. a single HTTP Service instance is running and receiving all requests (eg. Servlet Bridge or single Jetty instance).

Multiple HTTP Services .. multiple HTTP Service instances are running and each instance is receiving a specific set of requests (eg. HTTPS for different domains). Typically, this scenario may be used to provide better encapsulation between different contexts.

In both scenarios a single request handling servlet is registered with the service instance. The request handler is registered at the root alias. It is also assumed that the service may be used exclusively by Gyrex. However, this assumption is not strictly enforced.

Gyrex may support the administration/configuration of HTTP Services using very specific service implementations (eg. the Equinox Jetty based HTTP Service). It may also possible to offer a very deep integration with HTTP containers for best performance. However, it’s out of scope of this document to describe such implementation details.


The main issue with TLS/SSL is that it requires a channel (separate IP/port combination) for each domain. This makes administration not easier. Only recommendations can be given at this time. For example, to make things easier wildcard certificates may be used. But this topic is more related to service administration and may not even touch the platform if a third-party system (eg. SSL Accelerator proxy) is placed in front of Gyrex to handle the issue. However, Gyrex will support the integration with those systems to assist network operators with the operation in those environments.

HTTP Session

The final goal is to provide complete session isolation between applications. An extensible session manager will allow to provide application specific session handling. For example, one application may want to persist session state into a repository. Another application may not need sessions at all for scalability purposes.

Copyright © Eclipse Foundation, Inc. All Rights Reserved.