{"id":22785959,"url":"https://github.com/simonwaldherr/harp","last_synced_at":"2025-04-13T11:51:14.644Z","repository":{"id":172308041,"uuid":"649103469","full_name":"SimonWaldherr/HARP","owner":"SimonWaldherr","description":"HARP - the Golang HTTP AutoRegister Reverse Proxy","archived":false,"fork":false,"pushed_at":"2025-03-03T23:03:00.000Z","size":387,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T03:01:33.134Z","etag":null,"topics":["cache","golang","grpc","grpc-client","grpc-server","help-wanted","http","http-proxy","inverse-proxy","proxy","proxy-server","reverse-proxy","web-proxy"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SimonWaldherr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-03T19:39:53.000Z","updated_at":"2025-03-03T23:09:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e0907cc-eae0-471b-9dbe-ca78588ca6c4","html_url":"https://github.com/SimonWaldherr/HARP","commit_stats":null,"previous_names":["simonwaldherr/harp"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonWaldherr%2FHARP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonWaldherr%2FHARP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonWaldherr%2FHARP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonWaldherr%2FHARP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimonWaldherr","download_url":"https://codeload.github.com/SimonWaldherr/HARP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248710438,"owners_count":21149188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","golang","grpc","grpc-client","grpc-server","help-wanted","http","http-proxy","inverse-proxy","proxy","proxy-server","reverse-proxy","web-proxy"],"created_at":"2024-12-11T23:08:32.696Z","updated_at":"2025-04-13T11:51:14.639Z","avatar_url":"https://github.com/SimonWaldherr.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HARP – HTTP Autoregister Reverse Proxy (gRPC Edition)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/SimonWaldherr/HARP)](https://goreportcard.com/report/github.com/SimonWaldherr/HARP)\n[![Build](https://github.com/SimonWaldherr/HARP/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/SimonWaldherr/HARP/actions/workflows/go.yml)\n[![License: GPL](https://img.shields.io/badge/license-GPL-blue.svg)](./LICENSE)\n\nHARP is a dynamic reverse proxy designed to expose backend applications (even those hidden behind NAT or firewalls) to the Internet without directly exposing them. Backends connect via gRPC, register their HTTP endpoints, and receive forwarded HTTP requests. The proxy now supports a structured configuration for per‑route authentication and includes a helper to easily wrap existing web‑applications.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [How It Works](#how-it-works)\n- [Sequence Diagram](#sequence-diagram)\n- [Installation \u0026 Usage](#installation--usage)\n- [Configuration](#configuration)\n- [Examples](#examples)\n- [Using the Web Handler Wrapper](#using-the-web-handler-wrapper)\n- [License](#license)\n\n---\n\n## Overview\n\nHARP allows your internal servers (or devices like Raspberry Pis) to securely expose HTTP endpoints by connecting to a publicly hosted proxy. The backends register via gRPC using a per‑route authentication mechanism defined in the configuration. Existing web‑applications can be integrated easily using the provided handler wrapper.\n\n---\n\n## Architecture\n\n- **Proxy Server:**  \n  Runs both a gRPC server (for backend registration and messaging) and an HTTP/HTTPS/HTTP3 server (for client requests).  \n  - Reads configuration from `config.json`.\n  - Uses a structured list of allowed registrations to enforce per‑route authentication.\n  - Implements caching (in‑memory or disk‑based).\n\n- **Backend Applications:**  \n  Connect to the proxy via gRPC, register their available routes, and handle forwarded HTTP requests.  \n  A helper is provided so that existing net/http–based web applications can be wrapped with minimal changes.\n\n---\n\n## How It Works\n\n1. **Backend Registration:**  \n   A backend connects to the proxy’s gRPC server and sends a registration message with its available routes and a key.  \n   The proxy checks each route against the allowed registrations defined in the configuration file. Only routes whose path matches a configured regex and whose key is correct are accepted.\n\n2. **Request Forwarding:**  \n   When the proxy receives an HTTP request, it looks up a matching registered route and forwards the request via gRPC.\n\n3. **Response Relay \u0026 Caching:**  \n   The backend processes the request and returns a response via gRPC, which the proxy relays to the client. Responses may also be cached.\n\n---\n\n## Sequence Diagram\n\n```mermaid\nsequenceDiagram\n    participant Client as Client\n    participant Proxy as HARP Proxy\n    participant GRPC as gRPC Server\n    participant Backend as Backend Service\n    participant Cache as Cache Store\n\n    Client-\u003e\u003eProxy: HTTP Request (domain/path)\n    Proxy-\u003e\u003eCache: Check for Cached Response\n    alt Cache Hit\n        Cache--\u003e\u003eProxy: Cached Response\n        Proxy-\u003e\u003eClient: Return Cached Response\n    else Cache Miss\n        Proxy-\u003e\u003eGRPC: Forward HTTP Request (gRPC message)\n        GRPC-\u003e\u003eBackend: Dispatch request via bidirectional stream\n        Backend-\u003e\u003eGRPC: Process request \u0026 return HTTP Response\n        GRPC-\u003e\u003eProxy: Return HTTP Response over gRPC stream\n        Proxy-\u003e\u003eCache: Store response (if cacheable)\n        Proxy-\u003e\u003eClient: Relay HTTP Response\n    end\n\n    note over Backend,Proxy: Backend registration occurs on startup\u003cbr/\u003ewith per‑route authentication.\n```\n\n---\n\n## Installation \u0026 Usage\n\n### Prerequisites\n\n- [Go](https://golang.org) (v1.16 or later)\n- [protoc](https://grpc.io/docs/protoc-installation/) (for regenerating proto code if needed)\n- (Optional) QUIC-Go for HTTP/3 support\n\n### Build \u0026 Run\n\n1. **Configuration:**  \n   Adjust the settings in `config.json` as required. Note the new `allowedRegistration` section which defines allowed route regexes and their corresponding keys.\n\n2. **Build the Proxy:**  \n   ```bash\n   go build -o bin/harp-proxy proxy.go\n   ```\n\n3. **Run the Proxy:**  \n   ```bash\n   ./bin/harp-proxy -config config.json\n   ```\n\n4. **Run a Backend Example:**  \n   For example, in `demos/simple-go`:\n   ```bash\n   go run app.go -proxy localhost:50051\n   ```\n\n---\n\n## Configuration\n\nThe `config.json` file controls the proxy behavior. Key settings include:\n\n- **Ports \u0026 TLS:**  \n  - `grpcPort`, `httpPort`, `http3Port`\n  - TLS settings for gRPC and HTTPS/HTTP3\n\n- **Caching:**  \n  - `enableCache`, `cacheType` (`memory` or `disk`), `cacheTTL`\n\n- **Allowed Registrations:**  \n  A list of objects defining allowed registration rules. For example:\n  ```json\n  \"allowedRegistration\": [\n    { \"route\": \"/foobar/.*$\", \"key\": \"secret1\" },\n    { \"route\": \"/lorem/.*$\",  \"key\": \"ipsum-key\" },\n    { \"route\": \"/.*$\",       \"key\": \"master-key\" }\n  ]\n  ```\n  When a backend registers, each of its routes is checked against these rules. Only routes matching a rule with the correct key are accepted.\n\n- **Logging:**  \n  Set via `logLevel` (e.g. DEBUG, INFO).\n\n---\n\n## Examples\n\nThe **demos/** folder includes several backend examples:\n\n1. **Simple Go Application (demos/simple-go):**  \n   Registers a `/test` route and responds with a greeting.\n\n2. **Multi‑Service Application (demos/multi-service-go):**  \n   Registers multiple routes (e.g. math operations, hello, joke) and dispatches based on URL.\n\n3. **Wrapper Example (demos/static-wrapper-go):**  \n   Uses the HARP handler wrapper to directly integrate an existing net/http–based web application.\n\n4. **complex-harp-server:**  \n   A more complex example with multiple routes.\n\n---\n\n## Using the Web Handler Wrapper\n\nThe new helper in `harp/handler.go` (the `BackendServer` type and its `ListenAndServeHarp()` method) lets you wrap an existing `http.Handler` so that your web application can be exposed via HARP with minimal changes. \n\n---\n\n## License\n\nHARP is released under the GPL License. See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwaldherr%2Fharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonwaldherr%2Fharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwaldherr%2Fharp/lists"}