feat(ffi): Initial C API for hyper

Author: seanmonstar

.github/workflows/CI.yml

@@ -16,6 +16,7 @@ jobs:
       - style
       - test
       - features
+      - ffi
       - doc
     steps:
       - run: exit 0
@@ -111,7 +112,53 @@ jobs:
         run: cargo install cargo-hack
 
       - name: check --each-feature
-        run: cargo hack check --each-feature -Z avoid-dev-deps
+        run: cargo hack check --each-feature --skip ffi -Z avoid-dev-deps
+
+  ffi:
+    name: Test C API (FFI)
+    needs: [style]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v1
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+
+      - name: Install cbindgen
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: cbindgen
+
+      - name: Build FFI
+        uses: actions-rs/cargo@v1
+        env:
+          RUSTFLAGS: --cfg hyper_unstable_ffi
+        with:
+          command: build
+          args: --features client,http1,http2,ffi
+
+      # TODO: re-enable check once figuring out how to get it working in CI
+      # - name: Verify cbindgen
+      #   run: ./capi/gen_header.sh --verify
+
+      - name: Make Examples
+        run: cd capi/examples && make client
+
+      - name: Run FFI unit tests
+        uses: actions-rs/cargo@v1
+        env:
+          RUSTFLAGS: --cfg hyper_unstable_ffi
+        with:
+          command: test
+          args: --features full,ffi --lib
 
   doc:
     name: Build docs

.gitignore

@@ -1,2 +1,2 @@
-/target
-/Cargo.lock
+target
+Cargo.lock

Cargo.toml

@@ -19,6 +19,9 @@ include = [
   #"build.rs",
 ]
 
+[lib]
+crate-type = ["lib", "staticlib", "cdylib"]
+
 [dependencies]
 bytes = "1"
 futures-core = { version = "0.3", default-features = false }
@@ -38,6 +41,7 @@ want = "0.3"
 
 # Optional
 
+libc = { version = "0.2", optional = true }
 socket2 = { version = "0.3.16", optional = true }
 
 [dev-dependencies]
@@ -94,7 +98,6 @@ server = []
 stream = []
 
 # Tokio support
-
 runtime = [
     "tcp",
     "tokio/rt",
@@ -106,6 +109,9 @@ tcp = [
     "tokio/time",
 ]
 
+# C-API support (currently unstable (no semver))
+ffi = ["libc"]
+
 # internal features used in CI
 nightly = []
 __internal_happy_eyeballs_tests = []

capi/README.md

@@ -0,0 +1,17 @@
+# C API for hyper
+
+This provides auxiliary pieces for a C API to use the hyper library.
+
+## Unstable
+
+The C API of hyper is currently **unstable**, which means it's not part of the semver contract as the rest of the Rust API is.
+
+Because of that, it's only accessible if `--cfg hyper_unstable_ffi` is passed to `rustc` when compiling. The easiest way to do that is setting the `RUSTFLAGS` environment variable.
+
+## Building
+
+The C API is part of the Rust library, but isn't compiled by default. Using `cargo`, it can be compiled with the following command:
+
+```
+RUSTFLAGS="--cfg hyper_unstable_ffi" cargo build --features client,http1,http2,ffi
+```

capi/cbindgen.toml

@@ -0,0 +1,14 @@
+language = "C"
+include_guard = "_HYPER_H"
+no_includes = true
+sys_includes = ["stdint.h", "stddef.h"]
+cpp_compat = true
+documentation_style = "c"
+
+[parse.expand]
+crates = ["hyper-capi"]
+
+[export.rename]
+"Exec" = "hyper_executor"
+"Io" = "hyper_io"
+"Task" = "hyper_task"

capi/examples/Makefile

@@ -0,0 +1,22 @@
+#
+# Build the example client
+#
+
+TARGET = client
+
+OBJS = client.o
+
+RPATH=$(PWD)/../../target/debug
+CFLAGS = -I../include
+LDFLAGS = -L$(RPATH) -Wl,-rpath,$(RPATH)
+LIBS = -lhyper
+
+$(TARGET): $(OBJS)
+	$(CC) -o $(TARGET) $(OBJS) $(LDFLAGS) $(LIBS)
+
+upload: upload.o
+	$(CC) -o upload upload.o $(LDFLAGS) $(LIBS)
+
+clean:
+	rm -f $(OBJS) $(TARGET)
+	rm -f upload upload.o