http-handle 0.0.4

# -----------------------------------------------------------------------------
# HTTP Handle - A fast and lightweight Rust library for handling HTTP requests
# and responses.
# -----------------------------------------------------------------------------

[package]
# General project metadata
name = "http-handle"                        # The name of the library
version = "0.0.4"                           # Current version of the crate
authors = ["HTTP Handle Contributors"]      # Library contributors (auto-generated if not defined)
edition = "2024"                            # Rust edition
rust-version = "1.88.0"                     # Minimum supported Rust version
license = "AGPL-3.0-only"                   # Project license
description = """
A fast and lightweight Rust library for handling HTTP requests and responses.
"""                                         # Short library description
homepage = "https://http-handle.com/"       # Project's homepage URL
documentation = "https://http-handle.com/documentation/index.html" # Documentation URL
repository = "https://github.com/sebastienrousseau/http-handle"    # Repository URL
readme = "README.md"                        # Path to the README file
build = "build.rs"                          # Path to the build script (optional if used)

# -----------------------------------------------------------------------------
# Dependencies
# -----------------------------------------------------------------------------
[dependencies]
# Required dependencies for building and running the project.
thiserror = "2.0"                           # Error handling library for defining custom errors
serde = { version = "1.0", features = ["derive"] } # Serialization/deserialization with derive features
serde_json = "1.0"                          # JSON support with Serde
log = "0.4"                                 # Logging facade for Rust
env_logger = { version = "0.11", optional = true } # Optional logging with environment variable support
euxis-commons = { version = "0.0.2", default-features = false, features = ["error", "logging", "time"] }
ctrlc = "3.4"                               # Signal handling for graceful shutdown
regex = "1.11"                              # Runtime custom language pattern support
tokio = { version = "1.44", optional = true, default-features = false, features = ["rt", "sync", "time", "macros", "net", "fs", "io-util"] } # Async runtime support
tracing = { version = "0.1", optional = true }     # Structured logging
tracing-subscriber = { version = "0.3", optional = true, features = ["fmt", "env-filter"] } # Tracing subscriber
h2 = { version = "0.4", optional = true }          # HTTP/2 protocol support
http = { version = "1.3", optional = true }        # HTTP type definitions for h2
bytes = { version = "1.10", optional = true }      # Zero-copy byte buffers for h2 body frames
libc = { version = "0.2", optional = true }        # Unix sendfile support
notify = { version = "8.2", optional = true }      # Config hot-reload file watcher
arc-swap = { version = "1.7", optional = true }    # Lock-free hot config swaps
toml = { version = "1.0", optional = true }        # Profile config loading

# -----------------------------------------------------------------------------
# Library Configuration
# -----------------------------------------------------------------------------
[lib]
# Library-specific configurations.
name = "http_handle"                        # Name of the library
path = "src/lib.rs"                         # Path to the library’s main file

# -----------------------------------------------------------------------------
# Build Dependencies
# -----------------------------------------------------------------------------
[build-dependencies]
# Dependencies for the build script, used for pre-compilation tasks.
version_check = "0.9"                       # Ensures that a compatible Rust version is used

# -----------------------------------------------------------------------------
# Development Dependencies
# -----------------------------------------------------------------------------
[dev-dependencies]
# Dependencies required for testing and development.
tempfile = "3.13"                            # Temporary file creation for tests
assert_fs = "1.1"                           # File system assertion library for tests
predicates = "3.1"                          # Predicate assertions for test conditions
criterion = "0.8"                           # Benchmarking library to test performance
proptest = "1.6"                            # Property-based testing

# -----------------------------------------------------------------------------
# Examples
# -----------------------------------------------------------------------------
[[example]]
# Example code demonstrating the library in use.
name = "basic_server"                       # Name of the example
path = "examples/basic_server.rs"           # Path to the example file

[[example]]
# Example code demonstrating error handling.
name = "error_example"                      # Name of the example
path = "examples/error_example.rs"          # Path to the example file

[[example]]
# Example code demonstrating the library as a library.
name = "full_demo"                          # Name of the example
path = "examples/full_demo.rs"              # Path to the example file

[[example]]
# Legacy library example preserved from earlier revisions.
name = "lib_example_legacy"                 # Name of the example
path = "examples/lib_example_legacy.rs"     # Path to the example file

[[example]]
# Example code demonstrating request handling.
name = "request_example"                   # Name of the example
path = "examples/request_example.rs"       # Path to the example file

[[example]]
# Example code demonstrating response handling.
name = "response_example"                  # Name of the example
path = "examples/response_example.rs"      # Path to the example file

[[example]]
# Example code demonstrating server handling.
name = "server_example"                    # Name of the example
path = "examples/server_example.rs"        # Path to the example file

[[example]]
# Example code demonstrating graceful shutdown.
name = "graceful_shutdown_example"         # Name of the example
path = "examples/graceful_shutdown_example.rs" # Path to the example file

[[example]]
# Example code demonstrating ServerBuilder pattern usage.
name = "server_builder_example"            # Name of the example
path = "examples/server_builder_example.rs" # Path to the example file

[[example]]
# Example code demonstrating language detection with custom patterns.
name = "feature_language_detection"        # Name of the example
path = "examples/feature_language_detection.rs" # Path to the example file

[[example]]
# Example code demonstrating concurrent batch processing.
name = "feature_batch_processing"          # Name of the example
path = "examples/feature_batch_processing.rs" # Path to the example file
required-features = ["batch"]              # Only build when batch is enabled

[[example]]
# Example code demonstrating chunked file streaming.
name = "feature_streaming_chunks"          # Name of the example
path = "examples/feature_streaming_chunks.rs" # Path to the example file
required-features = ["streaming"]          # Only build when streaming is enabled

[[example]]
# Example code demonstrating optimized lookup helpers.
name = "feature_optimized_lookups"         # Name of the example
path = "examples/feature_optimized_lookups.rs" # Path to the example file
required-features = ["optimized"]          # Only build when optimized is enabled

[[example]]
# Example code demonstrating observability initialization.
name = "feature_observability"             # Name of the example
path = "examples/feature_observability.rs" # Path to the example file
required-features = ["observability"]      # Only build when observability is enabled

[[example]]
# Example code demonstrating async runtime helper.
name = "feature_async_runtime"             # Name of the example
path = "examples/feature_async_runtime.rs" # Path to the example file
required-features = ["async"]              # Only build when async is enabled

[[example]]
# Example code demonstrating async server startup.
name = "feature_async_server"              # Name of the example
path = "examples/feature_async_server.rs"  # Path to the example file
required-features = ["async"]              # Only build when async is enabled

[[example]]
# Example code demonstrating HTTP/2 server startup.
name = "feature_http2_server"              # Name of the example
path = "examples/feature_http2_server.rs"  # Path to the example file
required-features = ["http2"]              # Only build when HTTP/2 is enabled

[[example]]
# Example code demonstrating HTTP/3 ALPN profile and fallback policy.
name = "feature_http3_profile"             # Name of the example
path = "examples/feature_http3_profile.rs" # Path to the example file
required-features = ["http3-profile"]      # Only build when HTTP/3 profile is enabled

[[example]]
# Example code demonstrating distributed rate limiting adapters.
name = "feature_distributed_rate_limit"    # Name of the example
path = "examples/feature_distributed_rate_limit.rs" # Path to the example file
required-features = ["distributed-rate-limit"] # Only build when distributed rate limiting is enabled

[[example]]
# Example code demonstrating tenant isolation and secret providers.
name = "feature_tenant_isolation"          # Name of the example
path = "examples/feature_tenant_isolation.rs" # Path to the example file
required-features = ["multi-tenant"]       # Only build when multi-tenant isolation is enabled

[[example]]
# Example code demonstrating runtime auto-tuning.
name = "feature_runtime_autotune"          # Name of the example
path = "examples/feature_runtime_autotune.rs" # Path to the example file
required-features = ["autotune"]           # Only build when autotune is enabled

[[example]]
# Example code demonstrating enterprise authorization policies.
name = "feature_enterprise_authorization"  # Name of the example
path = "examples/feature_enterprise_authorization.rs" # Path to the example file
required-features = ["enterprise"]         # Only build when enterprise is enabled

[[example]]
# Example code demonstrating practical server policy configuration.
name = "scenario_server_policies"          # Name of the example
path = "examples/scenario_server_policies.rs" # Path to the example file

[[example]]
# Benchmark target binary for external load tools.
name = "benchmark_target"                  # Name of the example
path = "examples/benchmark_target.rs"      # Path to the example file

# -----------------------------------------------------------------------------
# Criterion Benchmark
# -----------------------------------------------------------------------------
[[bench]]
# Benchmarking configuration for performance testing.
name = "server_benchmark"                   # Name of the benchmark
harness = false                             # Disable the default benchmark harness (used by Criterion)

[profile.bench]
# Profile used when running benchmarks.
debug = true                                # Include debug symbols for better diagnostics

# -----------------------------------------------------------------------------
# Features
# -----------------------------------------------------------------------------
[features]
# Optional features that can be enabled or disabled.
default = []                                # No default features enabled
async = ["dep:tokio"]                       # Async runtime and hardened blocking helper
batch = []                                  # Concurrent batch processing APIs
streaming = []                              # Chunked streaming APIs
optimized = []                              # Zero-cost optimized lookups
observability = ["dep:tracing", "dep:tracing-subscriber"] # Structured tracing/observability
http2 = ["dep:tokio", "dep:h2", "dep:http", "dep:bytes"] # HTTP/2 server foundation (h2c)
high-perf = ["dep:tokio", "dep:libc"]      # Async-first serving with backpressure and sendfile fast path
tls = []                                    # TLS and mTLS configuration primitives
auth = []                                   # Auth middleware (API key + JWT parsing hook)
config = ["dep:notify", "dep:arc-swap", "dep:toml"] # Runtime profiles + hot reload
enterprise = ["tls", "auth", "config", "observability"] # Enterprise-ready integrations
http3-profile = []                          # HTTP/3 production profile and ALPN fallback helpers
distributed-rate-limit = []                 # Distributed rate-limit backends and adapters
multi-tenant = []                           # Tenant-isolated config and secret providers
autotune = ["high-perf"]                    # Runtime auto-tuning for host resource profiles

# -----------------------------------------------------------------------------
# Documentation Configuration
# -----------------------------------------------------------------------------
[package.metadata.docs.rs]
# Settings for building and hosting documentation on docs.rs.
all-features = true                         # Build documentation with all features enabled
rustdoc-args = ["--cfg", "docsrs"]          # Arguments passed to `rustdoc` when building the documentation
targets = ["x86_64-apple-darwin", "x86_64-unknown-linux-gnu"] # Publish docs metadata for macOS + Linux

# -----------------------------------------------------------------------------
# Linting Configuration
# -----------------------------------------------------------------------------
[lints.rust]
# Linting rules for the project.

## Warnings
missing_copy_implementations = "warn"       # Warn if types can implement `Copy` but don’t
missing_docs = "deny"                       # Deny if public items lack documentation
unstable_features = "warn"                  # Warn on the usage of unstable features
unused_extern_crates = "warn"               # Warn about unused external crates
unused_results = "warn"                     # Warn if a result type is unused (e.g., errors ignored)

## Allowances
bare_trait_objects = "allow"                # Allow bare trait objects (e.g., `Box<dyn Trait>`)
elided_lifetimes_in_paths = "allow"         # Allow lifetimes to be elided in paths
non_camel_case_types = "allow"              # Allow non-camel-case types
non_upper_case_globals = "allow"            # Allow non-uppercase global variables
trivial_bounds = "allow"                    # Allow trivial bounds in trait definitions
unsafe_code = "allow"                       # Allow the usage of unsafe code blocks

## Forbidden
missing_debug_implementations = "forbid"    # Forbid missing `Debug` implementations
non_ascii_idents = "forbid"                 # Forbid non-ASCII identifiers
unreachable_pub = "forbid"                  # Forbid unreachable `pub` items

## Denials
dead_code = "deny"                          # Deny unused, dead code in the project
deprecated_in_future = "deny"               # Deny code that will be deprecated in the future
ellipsis_inclusive_range_patterns = "deny"  # Deny usage of inclusive ranges in match patterns (`...`)
explicit_outlives_requirements = "deny"     # Deny unnecessary lifetime outlives requirements
future_incompatible = { level = "deny", priority = -1 } # Handle future compatibility issues
keyword_idents = { level = "deny", priority = -1 }      # Deny usage of keywords as identifiers
macro_use_extern_crate = "deny"             # Deny macro use of `extern crate`
meta_variable_misuse = "deny"               # Deny misuse of meta variables in macros
noop_method_call = "deny"                   # Deny method calls that have no effect
rust_2018_idioms = { level = "deny", priority = -1 }    # Enforce Rust 2018 idioms
rust_2021_compatibility = { level = "deny", priority = -1 } # Enforce Rust 2021 compatibility
rust_2024_compatibility = { level = "deny", priority = -1 } # Enforce Rust 2024 compatibility
single_use_lifetimes = "deny"               # Deny lifetimes that are used only once
trivial_casts = "deny"                      # Deny trivial casts (e.g., `as` when unnecessary)
trivial_numeric_casts = "deny"              # Deny trivial numeric casts (e.g., `i32` to `i64`)
unused = { level = "deny", priority = -1 }  # Deny unused code, variables, etc.
unused_features = "deny"                    # Deny unused features
unused_import_braces = "deny"               # Deny unnecessary braces around imports
unused_labels = "deny"                      # Deny unused labels in loops
unused_lifetimes = "deny"                   # Deny unused lifetimes
unused_macro_rules = "deny"                 # Deny unused macros
unused_qualifications = "deny"              # Deny unnecessary type qualifications
variant_size_differences = "deny"           # Deny enum variants with significant size differences

# -----------------------------------------------------------------------------
# Clippy Configuration
# -----------------------------------------------------------------------------
[package.metadata.clippy]
# Clippy lint configuration for enhanced code analysis.
warn-lints = [
    "clippy::all",                          # Warn on all common Clippy lints
    "clippy::pedantic",                     # Enable pedantic lints for stricter checking
    "clippy::cargo",                        # Enable lints specific to cargo
    "clippy::nursery",                      # Enable lints from Clippy’s nursery (experimental)
]

# -----------------------------------------------------------------------------
# Profiles
# -----------------------------------------------------------------------------
[profile.dev]
# Development profile configuration for fast builds and debugging.
codegen-units = 256                         # Increase codegen units for faster compilation
debug = true                                # Enable debugging symbols
debug-assertions = true                     # Enable debug assertions
incremental = true                          # Enable incremental compilation
lto = false                                 # Disable link-time optimization for development
opt-level = 0                               # No optimizations in development
overflow-checks = true                      # Enable overflow checks for arithmetic operations
panic = 'unwind'                            # Enable unwinding for panics (useful in development)
rpath = false                               # Disable rpath generation
strip = false                               # Do not strip symbols in development builds

[profile.release]
# Release profile configuration for optimized builds.
codegen-units = 1                           # Reduce codegen units for better performance
debug = false                               # Disable debug symbols in release builds
debug-assertions = false                    # Disable debug assertions
incremental = false                         # Disable incremental compilation for optimal binary size
lto = true                                  # Enable link-time optimization for smaller and faster binaries
opt-level = "s"                             # Optimize for binary size
overflow-checks = false                     # Disable overflow checks for performance
panic = "abort"                             # Use abort on panic for minimal overhead
rpath = false                               # Disable rpath generation
strip = "symbols"                           # Strip symbols for smaller binary size

[profile.test]
# Test profile configuration for debugging and development.
codegen-units = 256                         # Increase codegen units for faster test builds
debug = true                                # Enable debugging symbols for test builds
debug-assertions = true                     # Enable debug assertions for tests
incremental = true                          # Enable incremental compilation for tests
lto = false                                 # Disable link-time optimization during testing
opt-level = 0                               # No optimizations in test builds
overflow-checks = true                      # Enable overflow checks for tests
rpath = false                               # Disable rpath generation
strip = false                               # Do not strip symbols in test builds