Parse rustls.h to generate an API docs website

.github/workflows/docs.yaml

@@ -0,0 +1,59 @@
+name: documentation
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 18 * * *'
+
+jobs:
+  generate:
+    name: Generate API documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+
+      - name: Install zola
+        uses: taiki-e/install-action@v2
+        with:
+          tool: [email protected] # Matched to rustls repo
+
+      - name: Generate API JSON data
+        run:
+          cargo run --bin docgen > website/static/api.json
+
+      - name: Generate site pages
+        run: |
+          cd website && zola build --output-dir ../target/website/
+
+      - name: Package and upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./target/website/
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    if: github.repository == 'rustls/rustls-ffi'
+    needs: generate
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test.yaml

@@ -130,10 +130,12 @@ jobs:
           ! nm build/tests/server | grep '__asan_init'
 
       - name: Run ECH connect test
-        if: matrix.crypto == 'aws-lc-rs' # No HPKE in ring
+        # No HPKE in ring, tools package w/ ech-fetch util needs higher MSRV.
+        if: matrix.crypto == 'aws-lc-rs' && matrix.rust != '1.73'
         run: |
-          cmake --build build --target ech-test > ech-test.log
-          grep 'sni=encrypted' ech-test.log
+          cmake --build build --target ech-test |
+            tee ech-test.log |
+            grep 'sni=encrypted'
 
       # Our integration tests rely on a built-in provider being enabled.
       # Double-check the library/unit tests work without any providers to
@@ -251,9 +253,11 @@ jobs:
         run: cmake --build build --config "${{matrix.config}}" --target integration-test
 
       - name: Run ECH connect test
-        if: matrix.crypto == 'aws-lc-rs' # No HPKE in ring
+        # No HPKE in ring, tools package w/ ech-fetch util needs higher MSRV.
+        if: matrix.crypto == 'aws-lc-rs' && matrix.rust != '1.73'
         run: |
-          cmake --build build --target ech-test > ech-test.log
+          cmake --build build --target ech-test | Tee-Object -FilePath ech-test.log
+          Get-Content ech-test.log
           grep 'sni=encrypted' ech-test.log
 
   ensure-header-updated:

.gitignore

@@ -4,3 +4,5 @@ librustls/cmake-build*
 .idea
 .venv
 .vs
+/website/static/api.json
+/website/public

Cargo.toml

@@ -8,7 +8,6 @@ members = [
 
 default-members = [
     "librustls",
-    "tools"
 ]
 resolver = "2"
 
@@ -23,3 +22,7 @@ regex = "1.9.6"
 toml = { version = "0.6.0", default-features = false, features = ["parse"] }
 hickory-resolver = { version = "=0.25.0-alpha.4", features = ["dns-over-https-rustls", "webpki-roots"] }
 tokio = { version = "1.42.0", features = ["io-util", "macros", "net", "rt"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tree-sitter = "0.23" # TODO(@cpu): handle breaking API changes for 0.24
+tree-sitter-c = "0.23"

librustls/cmake/rust.cmake

@@ -91,7 +91,7 @@ endif()
 add_custom_command(
     TARGET ech-test
     POST_BUILD
-    COMMAND cargo run --manifest-path=../Cargo.toml --bin ech_fetch
+    COMMAND cargo run --manifest-path=../tools/Cargo.toml --bin ech_fetch
     COMMAND
         ${CMAKE_COMMAND} -E env RUSTLS_PLATFORM_VERIFIER=1 ${CMAKE_COMMAND} -E
         env ECH_CONFIG_LIST="research.cloudflare.com.ech.configs.bin"

librustls/src/client.rs

@@ -570,6 +570,7 @@ pub struct rustls_verify_server_cert_params<'a> {
 #[allow(non_camel_case_types)]
 pub type rustls_verify_server_cert_user_data = *mut libc::c_void;
 
+/// A callback that is invoked to verify a server certificate.
 // According to the nomicon https://doc.rust-lang.org/nomicon/ffi.html#the-nullable-pointer-optimization):
 // > Option<extern "C" fn(c_int) -> c_int> is a correct way to represent a
 // > nullable function pointer using the C ABI (corresponding to the C type int (*)(int)).

librustls/src/connection.rs

@@ -93,6 +93,7 @@ impl std::ops::DerefMut for Connection {
 }
 
 box_castable! {
+    /// A C representation of a Rustls `Connection`.
     pub struct rustls_connection(Connection);
 }
 
@@ -288,6 +289,7 @@ impl rustls_connection {
         }
     }
 
+    /// Returns a `rustls_handshake_kind` describing the `rustls_connection`.
     #[no_mangle]
     pub extern "C" fn rustls_connection_handshake_kind(
         conn: *const rustls_connection,

librustls/src/error.rs

@@ -46,6 +46,7 @@ macro_rules! u32_enum_builder {
 }
 
 u32_enum_builder! {
+    /// Numeric error codes returned from rustls-ffi API functions.
     EnumName: rustls_result;
     EnumDefault: InvalidParameter;
     EnumVal{
@@ -242,6 +243,7 @@ impl rustls_result {
         }
     }
 
+    /// Returns true if the `result` is a certificate related error.
     #[no_mangle]
     pub extern "C" fn rustls_result_is_cert_error(result: c_uint) -> bool {
         use rustls_result::*;

librustls/src/log.rs

@@ -42,6 +42,10 @@ pub(crate) fn ensure_log_registered() {
     log::set_max_level(log::LevelFilter::Debug)
 }
 
+/// Numeric representation of a log level.
+///
+/// Passed as a field of the `rustls_log_params` passed to a log callback.
+/// Use with `rustls_log_level_str` to convert to a string label.
 pub type rustls_log_level = usize;
 
 /// Return a rustls_str containing the stringified version of a log level.
@@ -58,12 +62,16 @@ pub extern "C" fn rustls_log_level_str(level: rustls_log_level) -> rustls_str<'s
     rustls_str::from_str_unchecked(s)
 }
 
+/// Parameter structure passed to a `rustls_log_callback`.
 #[repr(C)]
 pub struct rustls_log_params<'a> {
+    /// The log level the message was logged at.
     pub level: rustls_log_level,
+    /// The message that was logged.
     pub message: rustls_str<'a>,
 }
 
+/// A callback that is invoked for messages logged by rustls.
 #[allow(non_camel_case_types)]
 pub type rustls_log_callback =
     Option<unsafe extern "C" fn(userdata: *mut c_void, params: *const rustls_log_params)>;

librustls/src/rustls.h

@@ -42,6 +42,9 @@ typedef enum rustls_handshake_kind {
   RUSTLS_HANDSHAKE_KIND_RESUMED = 3,
 } rustls_handshake_kind;
 
+/**
+ * Numeric error codes returned from rustls-ffi API functions.
+ */
 enum rustls_result {
   RUSTLS_RESULT_OK = 7000,
   RUSTLS_RESULT_IO = 7001,
@@ -272,6 +275,9 @@ typedef struct rustls_client_config rustls_client_config;
  */
 typedef struct rustls_client_config_builder rustls_client_config_builder;
 
+/**
+ * A C representation of a Rustls `Connection`.
+ */
 typedef struct rustls_connection rustls_connection;
 
 /**
@@ -550,6 +556,9 @@ typedef struct rustls_verify_server_cert_params {
   struct rustls_slice_bytes ocsp_response;
 } rustls_verify_server_cert_params;
 
+/**
+ * A callback that is invoked to verify a server certificate.
+ */
 typedef uint32_t (*rustls_verify_server_cert_callback)(rustls_verify_server_cert_user_data userdata,
                                                        const struct rustls_verify_server_cert_params *params);
 
@@ -575,13 +584,31 @@ typedef void (*rustls_keylog_log_callback)(struct rustls_str label,
  */
 typedef int (*rustls_keylog_will_log_callback)(struct rustls_str label);
 
+/**
+ * Numeric representation of a log level.
+ *
+ * Passed as a field of the `rustls_log_params` passed to a log callback.
+ * Use with `rustls_log_level_str` to convert to a string label.
+ */
 typedef size_t rustls_log_level;
 
+/**
+ * Parameter structure passed to a `rustls_log_callback`.
+ */
 typedef struct rustls_log_params {
+  /**
+   * The log level the message was logged at.
+   */
   rustls_log_level level;
+  /**
+   * The message that was logged.
+   */
   struct rustls_str message;
 } rustls_log_params;
 
+/**
+ * A callback that is invoked for messages logged by rustls.
+ */
 typedef void (*rustls_log_callback)(void *userdata, const struct rustls_log_params *params);
 
 /**
@@ -1666,6 +1693,9 @@ bool rustls_connection_wants_write(const struct rustls_connection *conn);
  */
 bool rustls_connection_is_handshaking(const struct rustls_connection *conn);
 
+/**
+ * Returns a `rustls_handshake_kind` describing the `rustls_connection`.
+ */
 enum rustls_handshake_kind rustls_connection_handshake_kind(const struct rustls_connection *conn);
 
 /**
@@ -2128,6 +2158,9 @@ struct rustls_str rustls_handshake_kind_str(enum rustls_handshake_kind kind);
  */
 void rustls_error(unsigned int result, char *buf, size_t len, size_t *out_n);
 
+/**
+ * Returns true if the `result` is a certificate related error.
+ */
 bool rustls_result_is_cert_error(unsigned int result);
 
 /**

tools/Cargo.toml

@@ -8,7 +8,7 @@ publish = false
 rustls = { workspace = true }
 hickory-resolver = { workspace = true }
 tokio = { workspace = true }
-
-[[bin]]
-name = "ech_fetch"
-path = "src/ech_fetch.rs"
+serde = { workspace = true }
+serde_json = { workspace = true }
+tree-sitter = { workspace = true }
+tree-sitter-c = { workspace = true }