HSBC’s open source reverse proxy for modern web applications

In this blog post, we’ll explore what Cranker is, how you can start using it, and some practical use cases, such as safely exposing your home application on the internet.

In the fast-paced world of software development, deploying applications quickly and securely is crucial. HSBC has open-sourced a powerful tool called Cranker, a load-balancing reverse proxy designed to simplify the deployment of HTTP services.

What is Cranker?

Cranker is a unique reverse proxy that stands out due to its innovative approach to service connectivity. Unlike traditional load balancers, Cranker allows each service to connect to the proxy via a “connector” using a WebSocket. This means that services are self-configuring: the router automatically knows the location and availability of a service through its active WebSocket connection.

Key features of Cranker

• Self-configuring services: Services connect to the router, eliminating the need for manual configuration when new services are added, or existing ones are upgraded.
• Secure deployment: Services can be deployed on private networks without exposing incoming TCP ports, enhancing security.
• Flexible and scalable: Ideal for fast-moving teams that need to deploy frequently without central configuration. Any language or framework supporting HTTP can be used as a service.

Cranker architecture: Router and connector

Cranker consists of two parts: the Cranker router and the Cranker connector. Let’s build our Cranker in 15 minutes and register a service onto it.

Coding part one: Building your own Cranker router

The Cranker router is responsible for handling incoming client requests and managing connections with services. To set up a Cranker router, you’ll need the mu-cranker-router library along with mu-server. Here’s a basic example of how to set these up using Java:

Step 1: Add the necessary dependencies to your project

<dependency>
    <groupid>com.hsbc.cranker</groupid>
    <artifactid>mu-cranker-router</artifactid>
    <version>2.0.8</version>
</dependency>
<dependency>
    <groupid>io.muserver</groupid>
    <artifactid>mu-server</artifactid>
    <version>2.4.6</version>
</dependency>

Step 2: Write code to create two mu-server instances (one for accepting client traffic, one for accepting service registration), using the handlers from the mu-cranker-router plugin

public static void main(String[] args) {

    // Use the mucranker library to create a router object - this creates handlers
    CrankerRouter router = CrankerRouterBuilder.crankerRouter()
        .start();

    // Start a server which will listen to connector registrations on a websocket
    MuServer registrationServer = MuServerBuilder.muServer()
        .withHttpsPort(8444)
        .addHandler(router.createRegistrationHandler())
        .start();

    // Start the server that clients will send HTTP requests to
    MuServer httpServer = MuServerBuilder.muServer()
        .withHttpsPort(8443)
        .addHandler(router.createHttpHandler())
        .start();

    System.out.println("Cranker is available at " + httpServer.uri() +
                       " with registration at " + registrationServer.uri());
}

With these 30+ lines of code, you’ll have a high-performing Cranker router.

Coding part two: Registering the service with Cranker connector

The Cranker connector is a lightweight library that allows your service to connect to the Cranker router. It requires JDK11 or later and has no external dependencies. To integrate the Cranker connector into your service, follow these steps:

Step 1: Add the dependencies

Include the cranker-connector library in your project:

<dependency>
    <groupid>com.hsbc.cranker</groupid>
    <artifactid>cranker-connector</artifactid>
    <version>RELEASE</version>
</dependency>

Step 2: Start your web server

Use your preferred framework to start a web server. This server will only be accessed locally, so binding to localhost is recommended for security.

Step 3: Configure the connector to register your service with the Cranker router

Cranker uses a path-prefix (also called a route) as a key for load-balancing client requests.

// For example, your HTTP server starts on http://localhost:8080
// and the RESTful APIs are under a certain prefix, e.g.:
// /path-prefix/api/v1/users
// /path-prefix/api/v1/orders
// 'path-prefix' is what we call a 'route' for this service
URI targetServiceUri = startedWebServerUri();

CrankerConnector connector = CrankerConnectorBuilder.connector()
    // Router registration URL
    .withRouterLookupByDNS(URI.create("wss://my-router.example.org:8444"))
    // The route
    .withRoute("path-prefix")
    // Target service URL, e.g. http://localhost:8080
    .withTarget(targetServiceUri)
    .start();

Use case: Exposing a home application safely on the internet

One practical use case for Cranker is securely exposing a home application to the internet. By using Cranker, you can deploy your application on a private network, ensuring that no incoming TCP ports are open to the outside world.

The application connects to the Cranker router (which runs on the public network) via a WebSocket, allowing secure and efficient communication. This setup reduces the risk of unauthorised access by eliminating the need to open ports on your home network. You can quickly deploy and update services without manual configuration, making it easier to add more services as your needs grow.

Conclusion

Cranker is a powerful tool for developers looking to streamline their deployment processes while maintaining high security standards. Whether you’re managing a large-scale enterprise system or a personal project, Cranker offers the flexibility and security needed to succeed in today’s fast-paced development environment.

We encourage you to explore Cranker further by visiting the repo below and trying out the example. Happy coding!

GitHub repository for Cranker router (opens in new window)

GitHub repository for Cranker connector (opens in new window)