w-henderson/humphrey

📡 A Performance-Focused, Dependency-Free Web Server with WebSockets and JSON.

👋 Hi there, I'm William

I'm a Computer Science student at the University of Cambridge with a passion for solving problems by developing efficient, robust and maintainable software, built with performance in mind. I thrive on projects where every millisecond counts, and I find immense satisfaction in delivering performant and reliable solutions across diverse domains, from systems development to web applications, back-end infrastructure to mobile apps.

Please visit my portfolio and blog for more information.

💬 Contact Me

If you want to get in touch, feel free to use any of the platforms below!

• Message me on Twitter
• Message me on LinkedIn
• Send me an email

humphrey's Issues

Allow for a default configuration location in an environment variable

This could be useful when running humphrey in a directory to serve it. The variable could potentially be called HUMPHREY_CONF.

Add `Host` header filtering for requests

It can be useful to run effectively different apps on one port, accessed from different domains. For example, Cloudflare hosts many web applications on fewer IP addresses, and the server knows what to do according to the Host header.

Proposed syntax:

let local_subapp = SubApp::new()
    .with_route("/different_route", local_handler);

let production_subapp = SubApp::new()
    .with_route("/different_route", production_handler);

let app = App::new()
    .with_route("/", home_handler)
    .with_host("localhost", local_subapp)
    .with_host("*", production_subapp)

with_route called on the main app adds a host-independent handler. Sub-app handlers take precedence over host-independent handlers, no matter the order they are specified in. In this example, when requesting "/", the program should first check production_subapp for a "/" handler, then fall back to the main app to find home_handler.

Add a basic WebSocket implementation

This would require the creation of an entirely new crate called humphrey-ws. Ideally the dependency-free nature of Humphrey would be maintained, which would require following things to be completed:

• #29
• #30
• #31
• #33

The MDN documentation for WebSocket servers may be useful.

Implement base64 encoding and decoding

RFC 4648

Refactor configuration to be more like Nginx

The current configuration only allows for one configuration for the server, whereas Nginx allows different settings for different routes. The configuration system needs to be completely rewritten to allow for a similar thing.

Possible New Configuration Example

server {
    address = "0.0.0.0"
    port = 80

    route /proxy/* {
        proxy = "http://127.0.0.1:8000"
    }

    route /* {
        directory = "/var/www"
    }
}

Implement chunked transfer encoding for proxy

This is necessary when parsing a response from the target server.

Add configuration options for different hosts

Use the new functionality from #41 to allow for host-level configuration.

Proposed syntax:

server {
    address "0.0.0.0"
    port    80
    threads 32

    # quotes are optional in host name
    host "localhost" {
        route /app/* {
            directory "/var/www/dev"
        }
    }

    host "*.example.com" {
        route /app/* {
            directory "/var/www/prod"
        }
    }

    # routes on the base server are applied to all hosts
    route / {
        redirect "/app/"
    }
}

Thread panics when calling `Address::from_headers`

When parsing proxy addresses in humphrey/src/http/address.rs, the following section of code can panic:

let mut proxies: Vec<IpAddr> = forwarded
    .split(',')
    .map(|s| IpAddr::from_str(s).unwrap()) // panics
    .collect();

This happens when the X-Forwarded-For header contains something other than a comma-separated list of IP addresses.

Add an `include` statement to the configuration format

This would import another .conf file into the place of the include statement. For example:

humphrey.conf

server {
    ...

    include "plugins.conf"
}

plugins.conf

plugins {
    some_plugin {
        ...
    }
}

Expanded server.conf

server {
    ...

    plugins {
        some_plugin {
            ...
        }
    }
}

Add support for CORS and the OPTIONS method

Currently, Humphrey does not allow cross-origin resource sharing and rejects the OPTIONS method. This should be changed, and the app given a with_cors(true | false) method.

Add timeout for keep-alive requests

Currently, there is no timeout for keep-alive requests which can cause a deadlock of the thread pool.

Default Server configuration is broken

The defaults set in default.rs are completely incorrect and need to be fixed.

Implement HTTP proxy

The current proxy implementation simply forwards every byte to the target address. A spec-compliant proxy needs to be implemented allowing for HTTP request forwarding with the X-Forwarded-For header.

Make the WebSocket proxy route-dependent

Use the functionality from #39 to allow WebSocket proxying to different targets on different routes.

Proposed syntax:

server {
    address "0.0.0.0"
    port    80
    threads 32

    route /ws {
        websocket "localhost:1234"
    }

    route /chat {
        websocket "localhost:5678"
    }
}

Add a path-aware route concept to the `App`

This would effectively allow users to define handlers which are aware of the endpoint to which they are attached. This could then be used for the serve_dir built-in handler and remove the need for the strip_prefix.

Implement the WebSocket protocol

RFC 6455

Improve stability of Humphrey WebSocket

(basically just get rid of some unwraps which can in very rare cases panic)

Develop a first-party advanced analytics plugin

This should complement the current logging system by having its own configuration, and logging a variety of data to a CSV file.

Proposed Changes for Server 0.3

After #38 is completed, these changes will need to be added into Humphrey Server.

• #46
• #47

Improve `App::new` documentation

Clarify in the documentation that App::new requires Default to be implemented for the generic type State and that App::with_state should be used in cases where this is not possible.

Fix high CPU usage on async WebSocket

This is likely due to the suspicious polling implementation.

Add some kind of non-blocking feature for WebSockets

This would be required for things like listening for messages and being able to broadcast at the same time.

Make the generic type `State` default to `()`

Make the generic type State have a default value of () so it does not need to be specified.

Allow Core to be used as a client

With optional TLS according to the feature.

Add same site cookie configuration to Core

This should use an enum.

Reduce boilerplate code required for cookies

This would involve specific methods for getting cookies from requests and setting cookies on responses. It would probably require at least a partial rewrite of the cookie system.

Add comma-separated matchers to route configuration

Current:

route /example/* {
    directory "/var/www"
}

route /example {
    directory "/var/www"
}

Proposed:

route /example/*,/example {
    directory "/var/www"
}

Update examples to reflect new API

Implement the `Read + Write` traits for `WebsocketStream`

This would read and write binary data to the stream, automatically wrapping and unwrapping into frames as required.

Make the WebSocket handler route-dependent

Currently, only one WebSocket handler can be set for the entire app. This should be changed so different routes can have different WebSocket handlers.

Current syntax:

let app = App::new()
    .with_websocket_handler(some_handler);

Proposed syntax:

let app = App::new()
    .with_websocket_handler("/chat_ws", some_handler)
    .with_websocket_handler("/*", default_handler);

`index.php` returns 404 Not Found in PHP plugin

This is due to the recent optimisation requiring PHP files to end with .php. Some workaround needs to be found which will still be fast but actually work.

Write tests for WebSocket implementation

Implement `Into<Response>` for a number of types

Some simple convenience implementations should be added for types such as String and Vec<u8>, allowing a simple 200 OK response to be automatically generated using some_string.into() instead of Response::new(StatusCode::OK, some_string).

Add a static content handler

Add some kind of first-party static content handler function to automatically serve static content within a directory, using the try_find_path function.

Add TLS guide and example code

This should be done before the next release.

Better integrate JSON with Core and WebSocket

This would involve adding From implementations for automatically serializing JSON for transport in Responses and WebSocket Messages, as well as adding correct headers for the former.

Update examples for new release

Thread panics when getting peer address

In the client_handler function of humphrey/src/app.rs, the following line can panic.

let addr = stream.peer_addr().unwrap();

This is because the stream can become disconnected before the request is processed, which could happen as a result of high load or just becoming disconnected immediately after connecting.

Implement a monitoring feature

This would allow consumers of the Humphrey crate to monitor its internal performance and activity. This could then be integrated into Server in order to improve logging.

crates.io version bump request

https://docs.rs/humphrey_ws/latest/humphrey_ws/handler/fn.async_websocket_handler.html
This example doesn't compile when pulling from crates.io. I suspect it's just that crates.io needs a minor bump with

Humphrey/humphrey-ws/Cargo.toml

Line 17 in 3a5d2b5

humphrey = { version = "^0.7.0", path = "../humphrey" }

? I think humphrey-auth and humprey-server might also need a version bump.

Thank you very much for this project, this is exactly what I was looking for! I can dig deeper if it's not just a simple minor version bump.

Fails to compile with the following dependencies with no lock-file:

[dependencies]
humphrey = "^0.7.0"
humphrey_ws = "^0.5"

but it does work from a local clone of master:

humphrey = { path = "../Humphrey/humphrey" }
humphrey_ws = { path = "../Humphrey/humphrey-ws" }

error:

error[E0277]: expected a `Fn<(humphrey::http::Request, humphrey::stream::Stream, Arc<_>)>` closure, found `impl Fn(humphrey::http::request::Request, humphrey::stream::Stream, Arc<_>)`
   --> src/main.rs:14:38
    |
14  |         .with_websocket_route("/ws", async_websocket_handler(websocket_app.connect_hook().unwrap()));
    |          --------------------        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected an `Fn<(humphrey::http::Request, humphrey::stream::Stream, Arc<_>)>` closure, found `impl Fn(humphrey::http::request::Request, humphrey::stream::Stream, Arc<_>)`
    |          |
    |          required by a bound introduced by this call
    |
    = help: the trait `Fn<(humphrey::http::Request, humphrey::stream::Stream, Arc<_>)>` is not implemented for `impl Fn(humphrey::http::request::Request, humphrey::stream::Stream, Arc<_>)`
    = note: expected a closure with arguments `(humphrey::http::request::Request, humphrey::stream::Stream, Arc<_>)`
               found a closure with arguments `(humphrey::http::Request, humphrey::stream::Stream, Arc<_>)`
    = note: required for `impl Fn(humphrey::http::request::Request, humphrey::stream::Stream, Arc<_>)` to implement `humphrey::app::WebsocketHandler<_>`
note: required by a bound in `App::<State>::with_websocket_route`
   --> /home/grinkers/.cargo/registry/src/index.crates.io-6f17d22bba15001f/humphrey-0.7.0/src/app.rs:364:12
    |
362 |     pub fn with_websocket_route<T>(mut self, route: &str, handler: T) -> Self
    |            -------------------- required by a bound in this associated function
363 |     where
364 |         T: WebsocketHandler<State> + 'static,
    |            ^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `App::<State>::with_websocket_route`
    ```

Fix bug with malformed empty responses

When requesting a route which serves zero bytes of content, the browser will hang indefinitely while the app believes it has finished serving the request.

Minimal reproducible example:

use humphrey::App;
use humphrey::http::{Request, Response, StatusCode};

fn main() {
    let app: App<()> = App::new()
        .with_stateless_route("/", home);
    app.run("0.0.0.0:80").unwrap();
}

fn home(request: Request) -> Response {
    Response::new(StatusCode::OK, "", &request)
}

Implement SHA-1 hashing

RFC 3174

Add a percent-encoding utility function

This would be useful in a number of places, for example in parsing URIs.

Make `Response` creation more concise

Move current Response::new function to Response::default and have the new new function take in StatusCode, bytes and Request as parameters and perform all the compatibility fixes behind the scenes.

Proposed Changes for Core 0.3

A number of aspects of the Humphrey Core API still leave a lot to be desired. This issue outlines and discusses these potential changes which will be released in v0.3.

• #39
• #40
• #41
• #42
• #43

Write a "Getting Started" guide

This needs to be linked in the README. This would replace the book branch so should cover a decent amount of content (#25). The book branch should be deleted when done.

Humphrey Core 0.2 Roadmap

Humphrey Core 0.2 will include a number of breaking API changes to improve the user experience as well as adding new features to more easily support different use-cases.

Proposed Additions

• #14
• #15
• #16

Proposed Changes

• #17
• #18
• #19

Move `try_find_path` to the core crate.

Add a handler called `redirect` which returns a 301 response

This would be in the handlers module of the humphrey crate.

Make `Connection` header handling managed by the app

Currently, every response must finish with with_request_compatibility(&request) in order to correctly reflect the Connection header of the request. This also sets the correct HTTP version for 1.0 and 1.1.

This should be brought into the app's main handler loop and automatically done on every response, except those with the Connection handler already set, for example if a connection is to be closed despite the client requesting it to be kept alive.