Skip to content

Latest commit

 

History

History
176 lines (133 loc) · 7.87 KB

README.md

File metadata and controls

176 lines (133 loc) · 7.87 KB
Raw

janus

Build Status

Janus is an implementation of the Distributed Aggregation Protocol (DAP) specification. Currently it supports VDAFs with trivial aggregation parameters only, e.g. Prio3. VDAFs with nontrivial aggregation parameters (e.g. Mastic) are not yet supported.

Janus is currently in active development.

Draft versions and release branches

The main branch is under continuous development and will usually be partway between DAP drafts. Janus uses stable release branches to maintain implementations of different DAP draft versions. Rust crates and container images with versions x.y.z are released from a corresponding release/x.y branch.

Git branch Draft version Conforms to protocol? Status
release/0.1 draft-ietf-ppm-dap-01 Yes Unmaintained as of December 7, 2022
release/0.2 draft-ietf-ppm-dap-02 Yes Unmaintained as of July 13, 2023
release/0.3 draft-ietf-ppm-dap-03 Yes Unmaintained as of February 6, 2023
release/0.4 draft-ietf-ppm-dap-04 Yes Unmaintained as of May 24, 2023
release/0.subscriber-01 draft-ietf-ppm-dap-02 plus extensions No Unmaintained as of November 1, 2023
release/0.5 draft-ietf-ppm-dap-04 Yes Unmaintained as of June 24, 2024
release/0.6 draft-ietf-ppm-dap-07 Yes, with errata Unmaintained as of June 24, 2024
release/0.7 draft-ietf-ppm-dap-09 Yes, with errata Supported
main draft-ietf-ppm-dap-13 Not yet (under development) Supported

Note that not every DAP draft has been implemented.

draft-ietf-ppm-dap-07 errata

There is a bug in Janus' release/0.6 branch wherein PrepareResp messages are incorrectly encoded, making Janus incompatible with other DAP Aggregator implementations.

See issue #2466 for details.

draft-ietf-ppm-dap-09 errata

Janus' release/0.7 branch contains the following issues which cause it to skew from the behavior specified in the DAP specification:

  • When acting as a Leader aggregator, Janus responds to successful upload requests with an HTTP 200 OK status rather than an HTTP 201 Created status. The suggested workaround is for clients to accept any HTTP status code in the 2xx range as success. See issue #3483 for details.

Versioning and Stability

Janus follows semantic versioning. Because we are at major version 0, we increment the minor version number for breaking changes, and increment the patch version for new features and backwards-compatible bug fixes.

What is considered a breaking change depends on the crate. The following crates are stable on their Rust API:

  • janus_collector
  • janus_client
  • janus_messages

janus_core is published to crates.io, but has no stability guarantees. It should not be depended on directly. If you find yourself needing to depend on it directly while using any other Janus crates, open a bug report.

The following crates are stable on their external configuration, CLI arguments, and HTTP API. Their Rust API may arbitrarily change and should not be depended on. They are not published to crates.io.

  • janus_aggregator
  • janus_tools

Any other crates not mentioned have no stability guarantees whatsoever.

Building

To build Janus, execute cargo build.

Container image

To build container images, run docker buildx bake --load. This will produce images tagged janus_aggregator, janus_garbage_collector, janus_aggregation_job_creator, janus_aggregation_job_driver, janus_collection_job_driver, janus_cli, janus_db_migrator, janus_interop_client, janus_interop_aggregator, and janus_interop_collector by default.

Pre-built container images are available at us-west2-docker.pkg.dev/divviup-artifacts-public/janus.

Minimum Supported Rust Version (MSRV)

We support the latest stable version of Rust, at time of release, and the two preceding minor versions.

Running tests

Tests require that docker and kind be installed on the machine running the tests and in the PATH of the test-runner's environment. The docker daemon must be running. CI tests currently use kind 0.20.0 and the corresponding Kubernetes 1.26 node image (kindest/node:v1.26.6@sha256:6e2d8b28a5b601defe327b98bd1c2d1930b49e5d8c512e1895099e4504007adb). Using the same versions for local development is recommended.

To run Janus tests, execute cargo test. To run tests on Docker images, execute cargo xtask test-docker.

Note that podman is not an acceptable substitute for docker. There are subtle incompatibilities between the two that will cause tests to fail.

inotify limits

If you experience issues with tests using Kind on Linux, you may need to adjust inotify sysctls. Both systemd and Kubernetes inside each Kind node make use of inotify. When combined with other services and desktop applications, they may exhaust per-user limits.

Deploying Janus

See the documentation on deploying Janus for details about its configuration and operation.

Cargo features

janus_core has the following features available.

  • database: Enables implementations of postgres_types::ToSql and postgres_types::FromSql on janus_core::Interval.
  • test-util: Enables miscellaneous test-only APIs. This should not be used outside of tests, and any such APIs do not carry any stability guarantees.

janus_aggregator has the following features available.

  • otlp: Enables OTLP exporter support for both metrics and tracing. See the metrics and tracing documentation for configuration instructions.
  • prometheus: Enables a Prometheus metrics exporter; see the documentation for configuration instructions.
  • test-util: Enables miscellaneous test-only APIs. This should not be used outside of tests, and any such APIs do not carry any stability guarantees.
  • tokio-console: Enables a tracing subscriber and server to support tokio-console. See the documentation for configuration instructions.