publish to crates.io

Cargo.toml

@@ -9,12 +9,17 @@ name = "ngx"
 version = "0.3.0-beta"
 edition = "2021"
 autoexamples = false
+categories = ["api-bindings", "network-programming"]
+description = "FFI bindings to NGINX"
+repository = "https://github.com/nginxinc/ngx-rust"
+homepage = "https://github.com/nginxinc/ngx-rust"
 license = "Apache-2.0"
+keywords = ["nginx", "module", "sys"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-nginx-sys = { path = "nginx-sys"}
+nginx-sys = { path = "nginx-sys", version = "0.1"}
 
 [build-dependencies]
 bindgen = "0.64.0"
@@ -23,3 +28,6 @@ duct = "0.13.6"
 ureq = { version = "2.6.2", features = ["tls"] }
 flate2 = "1.0.25"
 tar = "0.4.38"
+
+[badges]
+maintenance = { status = "experimental" }

README.md

@@ -1,4 +1,6 @@
 [![Rust](https://github.com/nginxinc/ngx-rust/actions/workflows/ci.yaml/badge.svg)](https://github.com/nginxinc/ngx-rust/actions/workflows/ci.yaml)
+[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)[![crates.io](https://img.shields.io/crates/v/ngx.svg)](https://crates.io/crates/ngx)
+
 
 ## Project status
 This project is still a work in progress and not production ready.
@@ -12,8 +14,7 @@ In short, this SDK allows writing NGINX modules using the Rust language.
 
 ## Build
 
-NGINX modules can be build against a particular version of NGINX. The following environment variables can be used to
-specify particular version of NGINX or an NGINX dependency:
+NGINX modules can be built against a particular version of NGINX. The following environment variables can be used to specify a particular version of NGINX or an NGINX dependency:
 
 * `ZLIB_VERSION` (default 1.2.13) -
 * `PCRE2_VERSION` (default 10.42)

examples/README.md

@@ -1,14 +1,65 @@
+- [Examples](#examples)
+  - [CURL](#curl)
+  - [AWSSIG](#awssig)
+  - [HTTPORIGDST  - NGINX Destination IP recovery module for HTTP](#httporigdst----nginx-destination-ip-recovery-module-for-http)
+    - [Dependencies](#dependencies)
+    - [Example Configuration](#example-configuration)
+      - [HTTP](#http)
+    - [Embedded Variables](#embedded-variables)
+    - [Usage](#usage)
+    - [Caveats](#caveats)
+
+
 # Examples
+This crate provides a couple of example using [ngx](https://crates.io/crates/ngx) crate:
+
+- [awssig.rs](./awssig.rs) - An example of NGINX dynamic module that can sign GET request using AWS Signature v4.
+- [curl](./curl.rs) - An example of the Access Phase NGINX dynamic module that blocks HTTP requests if `user-agent` header starts with `curl`.
+- [httporigdst](./httporigdst.rs) - A dynamic module recovers the original IP address and port number of the destination packet.
+
+To build all these examples simply run:
+
+```
+cargo build --package=examples --examples
+```
+
+
+## CURL
+
+This module demonstrates how to create a minimal dynamic module with `http_request_handler`, that checks for User-Agent headers and returns status code 403 if UA starts with `curl`, if a module is disabled then uses `core::Status::NGX_DECLINED` to indicate the operation is rejected, for example, because it is disabled in the configuration (`curl off`). Additionally, it demonstrates how to write a defective parser.
+
+An example of nginx configuration file that uses that module can be found at [curl.conf](./curl.conf).
 
-## NGINX Destination IP recovery module for HTTP
+How to build and run in a [Docker](../Dockerfile) container curl example:
+```
+# build all dynamic modules examples and specify NGINX version to use
+docker buildx build --build-arg NGX_VERSION=1.23.3 -t ngx-rust .
+
+# start NGINX using curl.conf module example:
+docker run --rm -d  -p 8000:8000 ngx-rust nginx -c examples/curl.conf
+
+# test it - you should see 403 Forbidden
+curl http://127.0.0.1:8000 -v -H "user-agent: curl"
+
+
+# test it - you should see 404 Not Found
+curl http://127.0.0.1:8000 -v -H "user-agent: foo"
+```
 
-This dynamic module recovers original IP address and port number of the destination packet. It is useful, for example, with container sidecars where all outgoing traffic is redirected to a separate container with iptables before reaching the target.
+## AWSSIG
+
+This module uses [NGX_HTTP_PRECONTENT_PHASE](https://nginx.org/en/docs/dev/development_guide.html#http_phases) and provides examples, of how to use external dependency and manipulate HTTP headers before sending client requests upstream.
+
+An example of nginx configuration file that uses that module can be found at [awssig.conf](./awssig.conf).
+
+## HTTPORIGDST  - NGINX Destination IP recovery module for HTTP
+
+This dynamic module recovers the original IP address and port number of the destination packet. It is useful, for example, with container sidecars where all outgoing traffic is redirected to a separate container with iptables before reaching the target.
 
 This module can only be built with the "linux" feature enabled, and will only successfully build on a Linux OS.
 
 ### Dependencies
-
-This modules uses the Rust crate libc and Linux **getsockopt** socket API.
+This module uses the Rust crate libc and Linux **getsockopt** socket API.
 
 ### Example Configuration
 #### HTTP

nginx-sys/Cargo.toml

@@ -2,15 +2,20 @@
 name = "nginx-sys"
 version = "0.1.0"
 edition = "2021"
+categories = ["external-ffi-bindings"]
+description = "FFI bindings to NGINX"
+repository = "https://github.com/nginxinc/ngx-rust"
+homepage = "https://github.com/nginxinc/ngx-rust"
 license = "Apache-2.0"
+keywords = ["nginx", "ffi", "sys"]
 
 [lib]
-crate-type = ["staticlib","rlib"]
+crate-type = ["staticlib", "rlib"]
 
 [dependencies]
 
 [build-dependencies]
-bindgen = "0.64.0"
+bindgen = "0.65.0"
 which = "4.4.0"
 duct = "0.13.6"
 ureq = { version = "2.6.2", features = ["tls"] }