DOCSEARCHbyAlgolia
Submit Docs

Repose RESTful Proxy Service Engine

repository·master·Indexed 43 days ago

https://github.com/rackerlabs/repose

An open-source RESTful proxy service engine for building reusable software component stacks for API processing. Repose enables the implementation of Enterprise Integration Patterns (EIP) in a scalable, stateless manner. It features a variety of built-in filters and services for rate limiting, authentication (Keystone v2, OpenStack v3), API validation, translation, and HTTP logging via SLF4J.

Tokens
72.9K
Snippets
173
Records
296
Agent score
56%

What's inside Repose

  1. What is Repose?

    master

    Repose is a REstful PrOxy Service Engine designed to build stacks of reusable software components for common API processing tasks. It acts as a proxy that allows services to implement Enterprise Integration Patterns (EIP).

    Key characteristics include:

    • Statelessness: Designed for high scalability.
    • Standalone Execution: Can run as a Linux service (Valve) or directly via a JAR file.
    • Extensibility: Supports built-in filters and services, and allows for the creation of custom components.
    • Deployment Flexibility: Can be run on the same server as the service, on a different server, or horizontally scaled across multiple servers.

  3. Overview of Repose Services

    master

    Repose provides a suite of specialized services to handle core infrastructure concerns. These services allow for data consumption, storage, communication, observability, and security. Key service categories include:

    • Data & Storage: Atom Feed Consumption, Datastores.
    • Communication: HTTP Client, HTTP Logging.
    • Observability: Logging, Metrics, OpenTracing, URI Redaction.
    • System Health & Maintenance: Health Check, Phone Home.

  5. Choose a Datastore implementation

    master

    Repose provides three datastore implementations depending on your deployment needs:

    1. Local Datastore (local/default): Enabled by default. Stores data in the local cache of each node. Data is not shared between nodes (e.g., rate limiting limits are tracked per-node).
    2. Distributed Datastore (distributed/hash-ring): Enables a shared hash-ring object store across a cluster of Repose nodes. Provides consistency across participating nodes.
    3. Remote Datastore (distributed/remote): Allows isolated or dynamic Repose instances (like those in OpenShift) to connect to a single static Repose instance's object store.

    To use Distributed or Remote datastores, you must add the corresponding service to your System Model configuration.

    <!-- Example: Enabling Distributed Datastore in System Model -->
<system-model xmlns="http://docs.openrepose.org/repose/system-model/v2.0">
  <services>
    <service name="dist-datastore"/>
  </services>
</system-model>

  6. Use the URI Normalization Filter

    master

    The uri-normalization filter standardizes HTTP request URIs to optimize information flow and prevent cache busting. It performs two primary functions:

    1. Query Parameter Normalization: Whitelisting specific keys and alphabetizing the parameter list.
    2. Media Type Translation: Converting URI extensions (e.g., .json) into Accept header values and removing the extension from the URI.

    Key Details:

    • Name: uri-normalization
    • Bundle: repose-filter-bundle
    • Placement: It is recommended to place this filter near the top of the filter chain so that requests are normalized before being processed by other filters.
    • Side Effects: It may create or modify the Accept request header. It does not modify the request or response body, nor does it modify the response status code.

  7. Repose filesystem directory layout

    master

    After installing a Repose package, the following directory structure is used to manage artifacts, configuration, logs, and services. Understanding this layout is essential for configuring the system, troubleshooting via logs, or managing the service lifecycle.

    | Artifacts & Deployment

    • /usr/share/repose/filters: Contains all EAR files and artifacts used by Repose.
    • /var/repose: The working directory for artifacts used during runtime.
    • /usr/share/repose/repose.jar: The main Valve JAR file used to start the service.

    | Configuration

    • /etc/repose: Contains the XML configuration files that determine system behavior.
    • /etc/repose/examples: Contains example XML configuration files (note: these are for reference only and do not affect runtime behavior).

    | Logs & Services

    • /var/log/repose: Location of system and HTTP logs.
    • /lib/systemd/system/repose.service: The SystemD service unit file for managing the service.
    • /etc/init.d/repose: (Deprecated) The legacy service script for System V or Upstart.

  8. Use the Scripting Filter for custom request/response processing

    master

    The scripting filter allows you to execute custom logic using various scripting languages to perform arbitrary processing on requests and responses. It is part of the repose-filter-bundle and was released in v8.0.0.0.

    Supported Languages

    • Groovy
    • Javascript
    • Python (via Jython)

    All supported languages are currently compilable, which ensures high performance.

    Configuration

    The filter is configured via an XML element <scripting> within your configuration files. You must specify the language attribute to select your scripting engine.

    Important: Passing the Request/Response

    You must call filterChain.doFilter(request, response) at the end of your script. If you do not invoke this method, the filter will stop the chain, and the request will never reach the origin service or any subsequent filters.

    <scripting xmlns="http://docs.openrepose.org/repose/scripting/v1.0" language="groovy">
    // Your script here
    filterChain.doFilter(request, response)
</scripting>

  9. What is the API Validator filter?

    master

    The api-validator filter validates incoming requests against a configured Web Application Description Language (WADL) file. It ensures that requests conform to the expected URI structure, HTTP methods, and required headers. Additionally, it can validate request body content against an XML Schema Definition (XSD) or JSON Schema referenced within the WADL.

    This filter is typically placed early in the filter chain, immediately after authentication filters, to reject invalid requests before they reach the origin service.

  10. What is Repose and how does it work?

    master

    Repose is an open-source, RESTful middleware platform that acts as a pseudo-transparent reverse proxy. It sits between clients and origin services to process incoming requests through a series of extensible filters.

    Core Workflow

    1. Client Request: A client sends a request to Repose.
    2. Filter Processing: Repose passes the request through a series of filters (e.g., authentication, rate limiting, request modification).
    3. Origin Service: The adjusted request is forwarded to the origin service.
    4. Response: The response from the origin service is passed back through filters (if configured) and returned to the client.

    Key Features

    • Extensibility: Use customizable filters for tasks like translation, rate limiting, and RBAC.
    • Dynamic Configuration: Many configurations can be tweaked on the fly without restarting the Repose instance.
    • Scalability: Supports distributed data stores to exchange cached information across multiple nodes, providing fault tolerance and high performance.

  11. Understand how Repose loads and reloads configuration

    master

    Repose automatically reads configuration files during startup and monitors them for updates.

    • Update Frequency: Configuration files are checked for updates every 15 seconds. This interval is fixed and cannot be configured or manually triggered.
    • Error Handling: If a configuration file becomes invalid, Repose will continue using the last known good configuration. If the error occurs during initial startup, Repose will return a 503 error until the configuration is corrected.
    • Environment Variables: Updating an environment variable will not trigger a configuration reload. To apply changes to environment variables, you must restart Repose.

  12. How key-space addressing works in Distributed Datastore

    master

    The Distributed Datastore uses MD5 hashing to distribute keys across the cluster.

    Internal Client Behavior: When using the internal Repose Java cache client, keys are obscured. The client stores only the MD5 hash of the key, represented as a 128-bit UUID.

    External Client Behavior: If you are accessing the datastore from an external application, you must manually hash the key using MD5 before sending the request. If you do not hash the key, the object will be stored under the literal string value of the key provided, which will not match the internal client's lookup logic.

    Example Transformation:

    • Original Key: object-key
    • MD5 Hash: cd26615a30a3cdce02e3a834fed5711a
    • UUID (used in URL): cecda330-5a61-26cd-1a71-d5fe34a8e302
    <!-- External GET request example -->
GET /powerapi/dist-datastore/objects/cecda330-5a61-26cd-1a71-d5fe34a8e302