Skip to content
ziozzangPublic

About

Programmable L4/L7 gateway. high performance zero-trust cluster backbone

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

Hangang

Documentation · Quick start · Release notes · 한국어

Ingress usage, scenarios and live qualification.

An HTTP, TCP, and UDP gateway with enterprise-class lifecycle controls, isolated Lua policies, and a built-in management console.

Hangang brings reverse proxying, load balancing, TLS certificate management, access policies, and traffic visibility into one Rust binary. Configure routes in the browser or through the API, inspect live traffic, and extend request handling with Lua—without deploying a separate console service. The console supports English and Korean; this README and the English guides are the reference documentation.

Zero-trust backbone

Hangang integrates with the decision backbone through native hangang-guard support. hopae manages users and principals; guard manages IP/network controls and risk decisions, with room for broader policy contexts. A guard allow never replaces Hangang route authentication. Per-request remote decisions are the default;1–5second caching is optional.

From laptop to enterprise deployment

Develop and demonstrate on macOS Intel or Apple Silicon, then deploy the same configuration model on Linux x86-64 or ARM64. The native build matrix covers all four targets. Linux remains the reference for supervised upgrades, syscall-isolated Lua, and IPVS DSR. macOS offers ordinary gateway execution with explicit limitations; trusted development Lua requires --allow-unsandboxed-lua. Native Windows binaries are not available; use a Linux environment such as WSL2. See platform support and release targets for qualification requirements and limits.

Why Hangang

  • One place to operate HTTP and TCP. Manage routes, listeners, backend members, certificates, and activation from the embedded console. The same server exposes a documented management API and OpenAPI specification. See console coverage.
  • Customize policy with a separate failure boundary. Lua runs in replaceable child processes with memory, instruction, and wall-time limits. The built-in editor offers syntax highlighting and API completion. Worker saturation rejects the request rather than silently skipping its policy. See architecture and Lua editing.
  • Transform streaming traffic as well as ordinary bodies. Apply native JSON/XML/text operations or Lua transforms. Whole-document processing uses bounded buffering; line, NDJSON, and SSE modes work on complete records. Ordinary bodies stream by default, and WebSocket upgrades become tunnels. See transformations.
  • Change configuration while serving traffic. File watching and revision-checked API updates prepare candidates before publication. Invalid candidates leave the working configuration in place. Under local-file configuration authority, named members support draining and maintenance; connection behavior follows the policy being changed. See publication and member lifecycle.
  • See what is happening without adding a dashboard service. Live console views combine status, metrics, recent HTTP metadata, and active/recent TCP connections. Prometheus endpoints support external monitoring. Recording filters and bounded history control what the gateway retains. See HTTP history and TCP history.
  • Keep routing and security policy together. Combine host glob/regex matching and priorities with JWT, workload mTLS, protected-resource rules, country/language filters, and per-route outbound DNS, SOCKS5, and TLS policy. See routing, access control, and outbound connections.
  • Relay datagrams when the deployment boundary permits it. UDP routes preserve datagram boundaries and pin each client flow to a literal backend. The quic mode is opaque passthrough: it does not terminate HTTP/3, inspect SNI, or support connection migration. UDP routes use local-file configuration only and cannot participate in supervised/hot restart; see UDP and QUIC relays.
  • Use a separately scoped direct-routing companion. hangang-dsr installs and removes explicitly listed IPv4 Linux IPVS services for networks that already provide VIP ownership, ARP handling, and direct return. See IPVS DSR for its limits.

Enterprise-class service continuity

Change configuration, replace a serving process, and activate a signed binary while keeping the gateway's listening sockets in place. Hangang combines live configuration with a readiness-gated supervisor handoff, so planned maintenance can preserve ongoing traffic instead of requiring a stop/start cycle.

Change Continuity mechanism Operating conditions
Live configuration Prepare and validate a candidate before publication; retain the working configuration on preparation failure; new traffic uses the new snapshot. No process restart is required. Security-policy changes may deliberately close affected streams; persistence and local activation are distinct outcomes.
Supervised restart Transfer existing listener descriptors and the runtime snapshot; wait for the replacement to report READY before draining the old generation. Unix --supervised mode; trigger with SIGHUP or the authenticated restart API. Existing responses and tunnels remain with the old generation during drain.
Signed binary upgrade Verify the release, run version/configuration preflight, atomically replace the executable, then use the same readiness-gated handoff. Failed pre-readiness replacement invokes binary rollback and resumes the old worker. Explicit update source and signing key; writable install directory with hard-link/rename support. Rollback requires working local storage.

This is the concrete meaning of enterprise-class lifecycle controls here: live change, listener continuity, bounded draining, and a defined recovery path. The default drain budget is 30 seconds, configurable with --drain-seconds; connections exceeding it can close. Policy revocation can also terminate streams intentionally. The read-only Compose template uses container replacement and does not inherit in-process upgrade continuity; uninterrupted image rollout needs an appropriate multi-instance deployment.

See configuration publication, upgrade and recovery semantics, and reproducible lifecycle checks. These mechanisms support planned maintenance; they do not constitute a blanket zero-downtime SLA for host failures or every upgrade path.

Enterprise controls, integrated

Our goal is to surpass the operational experience of commercial enterprise gateways by making advanced controls coherent, inspectable, and practical to run. Hangang brings capabilities commonly expected from enterprise gateways into its MIT-licensed codebase. Today, its clearest advantage is their integration: routing, policy editing, traffic views, and management APIs share one application and configuration model.

Operational requirement Implemented in Hangang Scope to understand
Identity-aware access JWT verification, HTTP/TCP workload mTLS, protected-resource rules, administrator/viewer accounts Workload identity and local accounts are supported; this is not a centralized enterprise identity platform. Access model
Auditable administration Transactional local account audit, recording filters, configuration operation history, SQL commit receipts Coverage is operation-specific; traffic history is separate from durable audit. Account audit, configuration history
Controlled configuration changes Revision checks, candidate preparation, durable operation tracking, SQL receipt lookup A committed configuration does not prove that every instance has activated it. Publication, SQL receipts
Service continuity Backend health checks, serving/draining/maintenance states, supervised process replacement, signed updates Named-member lifecycle controls require local-file authority and are rejected by shared stores; connection continuity depends on the policy change and deployment mode. Lifecycle, updates
Operational visibility Live console views, Prometheus metrics, bounded connection/request history, authenticated remote observations Remote observation is read-only; it is not fleet rollout control. Fleet observations
Policy customization Bounded native transforms, isolated Lua workers, syntax highlighting and API completion Lua and body limits are explicit; a rejected or interrupted stream cannot recall bytes already forwarded. Transforms, Lua capacity

These are implemented capabilities, not a claim of complete enterprise-product parity. The project aims to improve on commercial products where integration and operator control matter; universal performance, availability, and compliance claims require separate evidence.

How it compares

Hangang is especially useful when you want interactive gateway administration, HTTP/TCP traffic handling, and custom Lua policy in one deployable application. The table compares operating models, not throughput or complete feature parity. Other products can cover overlapping use cases through their own modules, plugins, and editions.

Product Documented approach Why choose Hangang for this use case?
Hangang One binary embeds HTTP/TCP routing, local-file UDP/QUIC passthrough, an English/Korean management console, revision-checked configuration, and isolated Lua workers. A compact, self-hosted gateway stack with browser administration, policy customization, and scoped datagram relay in one application.
Caddy Automatic HTTPS and a JSON administration API; extensions use its module system. Choose Hangang when the embedded route-management console, TCP administration, and Lua policy editor are central to your workflow.
Kong Gateway Services, Routes, Consumers, and plugins organize API policy; Kong Manager provides administration. Choose Hangang when its native policies fit your requirements and you prefer a local-file starting point with process-isolated Lua and an embedded console.
Traefik Proxy Providers discover dynamic configuration, including Docker label-based routing. Choose Hangang when direct route editing, custom Lua, and request/record transformations are more central than provider-driven configuration.
HAProxy Its Lua API extends a non-blocking load balancer and requires scripts to respect that execution model. Choose Hangang when you want process-isolated Lua workers and an integrated policy editor alongside gateway management.

Comparison sources reviewed on 2026-09-22. Product editions and configuration affect availability. These are deployment tradeoffs, not a claim that Hangang is universally faster or replaces every enterprise capability. UDP/QUIC relay is local-file only and has no supervised/hot restart handoff; administrator accounts remain instance-local, and fleet observation is read-only. Review architecture and scale-out semantics before a migration.

Quick start

This local example demonstrates a working proxy, a Lua rejection rule, and the management console. You need Git, Rust 1.96 or newer, a C compiler, protoc (protobuf compiler), Python 3, OpenSSL, and curl. Node.js is only needed when developing the console; its built assets are already included.

Linux amd64 binaries and SHA256SUMS are available in the v0.2.1 release. The archive contains Hangang and its companion tools; verify it with sha256sum -c SHA256SUMS before extracting. The steps below build from source.

Read the example configuration guide for field-by-field explanations, runtime changes, and troubleshooting.

1. Build

git clone https://github.com/ziozzang/hangang.git
cd hangang
cargo build --locked

2. Start a demo backend

In a separate terminal, serve a temporary directory containing only the demo page:

HANGANG_DEMO_BACKEND="$(mktemp -d)"
printf 'Hello through Hangang!\n' > "$HANGANG_DEMO_BACKEND/index.html"
python3 -m http.server 8081 --bind 127.0.0.1 --directory "$HANGANG_DEMO_BACKEND"

3. Start Hangang

From the repository root in your first terminal:

On macOS, append --allow-unsandboxed-lua to both Hangang commands below to run this trusted Lua example. This development option does not provide Linux syscall isolation; see macOS limits.

umask 077
export HANGANG_DEMO_DIR="$(python3 -c 'import os,tempfile; print(os.path.realpath(tempfile.mkdtemp()))')"
cp examples/hangang.json "$HANGANG_DEMO_DIR/hangang.json"
openssl rand -hex 32 > "$HANGANG_DEMO_DIR/admin-token"
export HANGANG_ADMIN_TOKEN="$(cat "$HANGANG_DEMO_DIR/admin-token")"
./target/debug/hangang --check --config "$HANGANG_DEMO_DIR/hangang.json"
./target/debug/hangang --config "$HANGANG_DEMO_DIR/hangang.json"

The example forwards / to the backend on port 8081. Its Lua rule rejects requests carrying X-Block: yes. The proxy binds to 127.0.0.1:8080; management binds to 127.0.0.1:9000. Both remain local to your machine.

4. Verify and open the console

In another terminal:

curl --fail http://127.0.0.1:8080/
# Hello through Hangang!

curl -s -o /dev/null -w '%{http_code}\n' -H 'X-Block: yes' http://127.0.0.1:8080/
# 403

Open http://127.0.0.1:9000/ui/. Create the first administrator using the setup token saved in $HANGANG_DEMO_DIR/admin-token, a username, and a new password of at least 12 bytes. Read the token with a local editor; its directory is the value created in step 3, not a variable shared automatically with other terminals. Keep it private: it remains a break-glass administrator credential after account creation.

Open the HTTP route editor to inspect the Lua policy, then send more requests while watching the dashboard. --check validates configuration and Lua without starting listeners. To stop the demo, press Ctrl+C in the gateway and backend terminals. The temporary state remains available for inspection; restarting with the same config path preserves the local administrator database.

What you can build next

Need Included capability Guide
Serve several domains and ports Host patterns, priorities, canonical redirects, named HTTP/HTTPS listeners Matching, listeners
Automate certificate renewal ACME HTTP-01 and DNS-01; Cloudflare or authenticated DNS webhook; ZeroSSL EAB ACME
Protect application services JWT verification, workload mTLS, protected HTTP resources JWT, mTLS, resource policy
Reduce repeated backend work Response caching with configurable memory and disk policy Caching
Adapt payloads and streams Native JSON/XML/text transformations and bounded Lua body transforms Transformations
Discover container workloads Docker endpoints and Kubernetes Ingress reconciliation Docker, Kubernetes
Coordinate several instances Shared configuration via SQLite, PostgreSQL, or Redis, with documented consistency boundaries Scale-out
Deploy and operate Compose templates, administrator accounts, signed updates, account audit Deployment, accounts, updates, audit

For deployment beyond a local demo, start with the Compose guide or Kubernetes guide. Supply private credentials, persistent state, and the documented management-listener protection. The documentation index covers feature-specific setup and limitations; OpenAPI defines management endpoints and configuration objects.

Project information and updates

hangang --about
hangang --check-update

--about displays the version, repository, and author, Jioh Jung jung@jioh.net. --check-update queries the latest stable GitHub release without installing it. For automatic signed installation with readiness-gated process replacement, configure --supervised --update-github and a trusted public key as described in updates. Downloads still require a valid Ed25519 signature; release metadata or checksums alone do not authorize installation.

Development

make check       # Rust formatting and Clippy
make test        # Rust tests and local integration scenarios
make test-web    # Console and browser tests
make check-docs  # Staged documentation and publication checks

Some integration targets need Docker or additional dependencies. See development and documentation conventions. Hangang is licensed under MIT.

Trusted Guard/Hopae menus and native Hopae transport: console integration.

Pumgye native authorization and matrix · 한국어

Independent Pumgye authority documents native decision transport and delegated policy administration.

Native service request enforcement

The auth.native_resource option, published in 0.3.5, binds the final upstream target and entity to actual Hopae/Pumgye/Sumunjang decisions over mTLS gRPC. Exact signed static artifacts passed the backed-up four-server Kubernetes/browser fixture and are internally deployed. Existing operating receipt resources remain unconfigured; positive native enforcement is qualified in owned fixtures. See the cross-component qualification record.

The current source additionally retains the exact activated snapshot for native requests, rather than relying solely on a numeric configuration revision. A new snapshot with even an identical revision retires pending native authentication, entity preparation and authority calls, upstream admission and guarded bodies. Checks compare retained Arc identities without SQL or per-frame configuration serialization. This conservative fence also retires requests on unrelated snapshot replacement, consistent with the existing native revision fence. It is a local owner fence, not a distributed route lease, signed permit or replay ledger.

flowchart LR
  N0["Existing authentication"]
  N1["Transform and compose backend URI"]
  N2["Bound complete entity"]
  N3["Hopae receipt"]
  N4["Pumgye live identity and network decision"]
  N5["Final configuration and local revision fences"]
  N6["HTTP upstream"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6
  N4 --> S["Sumunjang network owner"]
  S --> N4
  N4 -. "issuer validation" .-> N3
Loading

Native requests also retain a bounded process-local route reference while the authority phase and upstream admission are pending. It captures the actual route runtime, trusted ingress client IP, snapshot, final absolute URI, method and prepared digest. Opaque random references expire after one second; cancellation removes them and a fresh registry never inherits them. The gateway caps registrations at 128 globally, uses 16 lock shards and checks route membership through a snapshot-built index. It copies neither request entities nor credential fields; owner snapshots stay shared and no request-time SQL is performed. The current source uses these references for local final-admission checks and adds a separate mandatory-mTLS route observation server library. Its independent contract crate contains no policy logic. Server replies derive client IP/service/resource/action from native owners; request fields cannot supply classification or an allow verdict. The server is started with --route-owner-config, including validation, shutdown and supervised socket handover. This mode sends the actual native reference and destination digest to route-aware Pumgye, which checks the configured mTLS owner before and after evaluation. Missing route-observation acknowledgement fails closed, including a legacy authority. Signed permission, projection and replay consumption remain separate work.

0.3.11 candidate

The candidate release contract describes context-aware Pumgye policy administration, unchanged native/runtime boundaries and required artifact/API-server/adoption gates. This is preparation, not an operating rollout.

About

Programmable L4/L7 gateway. high performance zero-trust cluster backbone

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages