Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (40 loc) · 2.95 KB

CONTRIBUTING.md

File metadata and controls

56 lines (40 loc) · 2.95 KB

Contributing to sōzu

Thank you for your interest in sōzu, you're very welcome here!

This is a young project, and things are still a bit in flux, so there are a lot of opportunities to learn and have a great impact on the project. We marked some issues as easy for first contributors, please check them out!

Communication

Most of the discussion around the project happens in the issues, so please check the list there.

Navigating the source

The proxy is designed to have a minimal core that you drive through external tooling. The Cargo workspace ships four crates:

  • lib is the event loop handling network communication and parsing. Workers are small wrappers around this.
  • bin is the main executable, providing a master/workers multiprocess architecture and exposing a unix socket to receive configuration changes. It also contains the command-line interface.
  • command is a library wrapping the communication protocol of the unix socket. You'd typically use it to make tools to drive the proxy.
  • e2e is the integration test harness that spawns real workers plus mock clients and backends.

The fuzz/ crate (cargo-fuzz targets fuzz_frame_parser, fuzz_hpack_decoder) lives outside the Cargo workspace and is built with cargo +nightly fuzz from inside fuzz/.

The easiest way to contribute would be to work on the command-line interface (bin/src/ctl/) or on external tools using the command library. lib can be complex since you need familiarity with the event loop handling, but the parsers and protocols are well separated. bin is mostly plumbing to handle command-line options, supervise workers, and dispatch orders from the socket.

Debugging

If the bug or feature you are exploring is linked to the HTTP or TLS implementation, you can reuse directly the code of one of the examples, they allow you to use the proxy without the overhead of the worker system.

Otherwise, the proxy uses the log crate and follows the RUST_LOG environment variable convention, so you can precisely trace what happens.

Copyright assignment

We (Clever Cloud) will ask you to sign a copyright assignment agreement before accepting your code into the project. In short, the agreement allows us to change the license of the project (currently in AGPL 3) if needed. You can of course keep using the published version of sōzu with your contribution as AGPL 3.

We ask this because we might run an internal fork of sōzu on our infrastructure with changes that make no sense for public use.

Copyright assignment is handled through the CLA assistant bot, which will ask you in a pull request to accept the agreement.