# HopGate Architecture / HopGate 아키텍처 이 문서는 HopGate 시스템의 전체 구조를 설명합니다. (ko) This document describes the overall architecture of the HopGate system. (en) --- ## 1. Overview / 전체 개요 - HopGate는 공인 서버와 여러 프라이빗 네트워크 클라이언트 사이에서 HTTP(S) 트래픽을 터널링하는 게이트웨이입니다. (ko) - HopGate is a gateway that tunnels HTTP(S) traffic between a public server and multiple private-network clients. (en) - 서버는 80/443 포트를 점유하고, ACME(Let's Encrypt 등)로 TLS 인증서를 자동 발급/갱신합니다. (ko) - The server listens on ports 80/443 and automatically issues/renews TLS certificates using ACME (e.g. Let's Encrypt). (en) - 클라이언트는 DTLS를 통해 서버에 연결되고, 서버가 전달한 HTTP 요청을 로컬 서비스(127.0.0.1:PORT)에 대신 보내고 응답을 다시 서버로 전달합니다. (ko) - Clients connect to the server via DTLS, forward HTTP requests to local services (127.0.0.1:PORT), and send the responses back to the server. (en) - 관리 Plane(REST API)을 통해 도메인 등록/해제 및 클라이언트 API Key 발급을 수행합니다. (ko) - An admin plane (REST API) is used to register/unregister domains and issue client API keys. (en) --- ## 2. Directory Layout / 디렉터리 레이아웃 ```text . ├── cmd/ │ ├── server/ # server binary entrypoint │ └── client/ # client binary entrypoint ├── internal/ │ ├── config/ # shared configuration loader │ ├── acme/ # ACME certificate management │ ├── dtls/ # DTLS abstraction & implementation │ ├── proxy/ # HTTP proxy / tunneling core │ ├── protocol/ # server-client message protocol │ ├── admin/ # admin plane HTTP handlers │ └── logging/ # structured logging utilities ├── ent/ │ └── schema/ # ent schema definitions (e.g. Domain) └── pkg/ └── util/ # reusable helpers (optional) ``` --- ### 2.1 `cmd/` - [`cmd/server/main.go`](cmd/server/main.go) — 서버 실행 엔트리 포인트. 서버 설정 로딩, ACME/TLS 초기화, HTTP/HTTPS/DTLS 리스너 시작을 담당합니다. (ko) - [`cmd/server/main.go`](cmd/server/main.go) — Server entrypoint. Loads configuration, initializes ACME/TLS, and starts HTTP/HTTPS/DTLS listeners. (en) - [`cmd/client/main.go`](cmd/client/main.go) — 클라이언트 실행 엔트리 포인트. 설정 로딩, DTLS 연결 및 핸드셰이크, 로컬 서비스 프록시 루프를 담당합니다. (ko) - [`cmd/client/main.go`](cmd/client/main.go) — Client entrypoint. Loads configuration, performs DTLS connection and handshake, and runs the local proxy loop. (en) --- ### 2.2 `internal/config` - 서버와 클라이언트가 공통으로 사용하는 설정 스키마 및 `.env`/환경 변수 로더를 제공합니다. (ko) - Provides shared config structs for server and client, plus `.env`/environment variable loaders. (en) - 주요 구조체 / Main structs: (ko/en) - `ServerConfig` — HTTP/HTTPS/DTLS 리스닝 주소, 도메인/프록시 도메인, Debug 플래그, 로그 설정. (ko) - `ServerConfig` — HTTP/HTTPS/DTLS listen addresses, main/proxy domains, debug flag, logging config. (en) - `ClientConfig` — 서버 주소, 도메인, 클라이언트 API Key, local_target, Debug 플래그, 로그 설정. (ko) - `ClientConfig` — server address, domain, client API key, local_target, debug flag, logging config. (en) --- ### 2.3 `internal/acme` - ACME(예: Let's Encrypt) 클라이언트 래퍼 및 인증서 매니저를 구현하는 패키지입니다. (ko) - Package that will wrap an ACME client (e.g. Let's Encrypt) and manage certificates. (en) - 역할 / Responsibilities: (ko/en) - 메인 도메인 및 프록시 서브도메인용 TLS 인증서 발급/갱신. (ko) - Issue/renew TLS certificates for main and proxy domains. (en) - HTTP-01 / TLS-ALPN-01 챌린지 처리 훅 제공. (ko) - Provide hooks for HTTP-01 / TLS-ALPN-01 challenges. (en) - HTTPS/DTLS 리스너에 사용할 `*tls.Config` 제공. (ko) - Provide `*tls.Config` for HTTPS/DTLS listeners. (en) --- ### 2.4 `internal/dtls` - DTLS 통신을 추상화하고, pion/dtls 기반 구현 및 핸드셰이크 로직을 포함합니다. (ko) - Abstracts DTLS communication and includes a pion/dtls-based implementation plus handshake logic. (en) - 주요 요소 / Main elements: (ko/en) - `Session`, `Server`, `Client` 인터페이스 — DTLS 위의 스트림과 서버/클라이언트를 추상화. (ko) - `Session`, `Server`, `Client` interfaces — abstract streams and server/client roles over DTLS. (en) - `NewPionServer`, `NewPionClient` — pion/dtls 를 사용하는 실제 구현. (ko) - `NewPionServer`, `NewPionClient` — concrete implementations using pion/dtls. (en) - `PerformServerHandshake`, `PerformClientHandshake` — 도메인 + 클라이언트 API Key 기반 애플리케이션 레벨 핸드셰이크. (ko) - `PerformServerHandshake`, `PerformClientHandshake` — application-level handshake based on domain + client API key. (en) - `NewSelfSignedLocalhostConfig` — 디버그용 localhost self-signed TLS 설정을 생성. (ko) - `NewSelfSignedLocalhostConfig` — generates a debug-only localhost self-signed TLS config. (en) --- ### 2.5 `internal/protocol` - 서버와 클라이언트가 DTLS 위에서 주고받는 HTTP 요청/응답 메시지 포맷을 정의합니다. (ko) - Defines HTTP request/response message formats exchanged over DTLS between server and clients. (en) - 요청 메시지 / Request message: (ko/en) - `RequestID`, `ClientID`, `ServiceName`, `Method`, `URL`, `Header`, `Body`. (ko/en) - 응답 메시지 / Response message: (ko/en) - `RequestID`, `Status`, `Header`, `Body`, `Error`. (ko/en) - 인코딩은 초기에는 JSON을 사용하고, 필요 시 MsgPack/Protobuf 등으로 확장 가능합니다. (ko) - Encoding starts with JSON and may be extended to MsgPack/Protobuf later. (en) --- ### 2.6 `internal/proxy` - HTTP Reverse Proxy 및 클라이언트 측 로컬 프록시 코어 로직을 담당합니다. (ko) - Contains the core logic for the HTTP reverse proxy on the server and the local proxy on the client. (en) #### 서버 측 역할 / Server-side role - 공인 HTTPS 엔드포인트에서 들어오는 요청을 수신합니다. (ko) - Receive incoming requests on the public HTTPS endpoint. (en) - 도메인/패스 규칙에 따라 적절한 클라이언트와 서비스로 매핑합니다. (ko) - Map requests to appropriate clients and services based on domain/path rules. (en) - 요청을 `protocol.Request` 로 직렬화하여 DTLS 세션을 통해 클라이언트로 전송합니다. (ko) - Serialize the request as `protocol.Request` and send it over a DTLS session to the client. (en) - 클라이언트로부터 받은 `protocol.Response` 를 HTTP 응답으로 복원하여 외부 사용자에게 반환합니다. (ko) - Deserialize `protocol.Response` from the client and return it as an HTTP response to the external user. (en) #### 클라이언트 측 역할 / Client-side role - DTLS 채널을 통해 서버가 내려보낸 `protocol.Request` 를 수신합니다. (ko) - Receive `protocol.Request` objects sent by the server over DTLS. (en) - 로컬 HTTP 서비스(예: 127.0.0.1:8080)에 요청을 전달하고 응답을 수신합니다. (ko) - Forward these requests to local HTTP services (e.g. 127.0.0.1:8080) and collect responses. (en) - 응답을 `protocol.Response` 로 직렬화하여 DTLS 채널을 통해 서버로 전송합니다. (ko) - Serialize responses as `protocol.Response` and send them back to the server over DTLS. (en) --- ### 2.7 `internal/logging` - Loki/Grafana 스택에 적합한 구조적 JSON 로깅 인터페이스를 제공합니다. (ko) - Provides a structured JSON logging interface compatible with the Loki/Grafana stack. (en) - 공통 필드 (예: component, request_id, client_id, domain 등)를 포함한 Logger 를 제공합니다. (ko) - Offers a Logger that includes common fields (e.g., component, request_id, client_id, domain). (en) --- ### 2.8 `ent/schema` - `Domain` 등 엔티티에 대한 ent 스키마를 정의합니다. (ko) - Defines ent schemas for entities such as `Domain`. (en) - Domain 엔티티는 다음 정보를 포함합니다: (ko) - The Domain entity contains the following fields: (en) - UUID `id` — 기본 키 / primary key. (ko/en) - `domain` — FQDN (예: app.example.com). (ko/en) - `client_api_key` — 클라이언트 인증용 64자 키. (ko/en) - `memo` — 관리자 메모. (ko/en) - `created_at`, `updated_at` — 감사용 타임스탬프. (ko/en) --- ### 2.9 `pkg/util` (optional) - 재사용 가능한 헬퍼 함수/유틸리티를 둘 수 있는 선택적 패키지입니다. (ko) - Optional package for reusable helpers and utilities. (en) --- ## 3. Request Flow Summary / 요청 흐름 요약 1. 외부 사용자가 `https://proxy.example.com/service-a/path` 로 HTTPS 요청을 보냅니다. (ko) An external user sends an HTTPS request to `https://proxy.example.com/service-a/path`. (en) 2. HopGate 서버의 HTTPS 리스너가 요청을 수신합니다. (ko) The HTTPS listener on the HopGate server receives the request. (en) 3. `proxy` 레이어가 도메인과 경로를 기반으로 이 요청을 처리할 클라이언트(예: client-1)와 해당 로컬 서비스(`service-a`)를 결정합니다. (ko) The `proxy` layer decides which client (e.g., client-1) and which local service (`service-a`) should handle the request, based on domain and path. (en) 4. 서버는 요청을 `protocol.Request` 구조로 직렬화하고, `dtls.Session` 을 통해 선택된 클라이언트로 전송합니다. (ko) The server serializes the request into a `protocol.Request` and sends it to the selected client over a `dtls.Session`. (en) 5. 클라이언트의 `proxy` 레이어는 `protocol.Request` 를 수신하고, 로컬 서비스(예: 127.0.0.1:8080)에 HTTP 요청을 수행합니다. (ko) The client’s `proxy` layer receives the `protocol.Request` and performs an HTTP request to a local service (e.g., 127.0.0.1:8080). (en) 6. 클라이언트는 로컬 서비스로부터 HTTP 응답을 수신하고, 이를 `protocol.Response` 로 직렬화하여 DTLS 채널을 통해 서버로 다시 전송합니다. (ko) The client receives the HTTP response from the local service, serializes it as a `protocol.Response`, and sends it back to the server over DTLS. (en) 7. 서버는 `protocol.Response` 를 디코딩하여 원래의 HTTPS 요청에 대한 HTTP 응답으로 변환한 뒤, 외부 사용자에게 반환합니다. (ko) The server decodes the `protocol.Response`, converts it back into an HTTP response, and returns it to the original external user. (en) ![architecture.jpeg](images/architecture.jpeg) --- ## 4. Next Steps / 다음 단계 - 위 아키텍처를 기반으로 디렉터리와 엔트리 포인트를 생성/정리합니다. (ko) - Use this architecture to create/organize directories and entrypoints. (en) - `internal/config` 에 필요한 설정 필드와 `.env` 로더를 확장합니다. (ko) - Extend `internal/config` with required config fields and `.env` loaders. (en) - `internal/acme` 에 ACME 클라이언트(certmagic 또는 lego 등)를 연결해 TLS 인증서 발급/갱신을 구현합니다. (ko) - Wire an ACME client (certmagic, lego, etc.) into `internal/acme` to implement TLS certificate issuance/renewal. (en) - `internal/dtls` 에서 pion/dtls 기반 DTLS 전송 계층 및 핸드셰이크를 안정화합니다. (ko) - Stabilize the pion/dtls-based DTLS transport and handshake logic in `internal/dtls`. (en) - `internal/protocol` 과 `internal/proxy` 를 통해 실제 HTTP 터널링을 구현하고, 라우팅 규칙을 구성합니다. (ko) - Implement real HTTP tunneling and routing rules via `internal/protocol` and `internal/proxy`. (en) - `internal/admin` + `ent` + PostgreSQL 을 사용해 Domain 등록/해제 및 클라이언트 API Key 발급을 완성합니다. (ko) - Complete domain registration/unregistration and client API key issuing using `internal/admin` + `ent` + PostgreSQL. (en) - 로깅/메트릭을 Prometheus + Loki + Grafana 스택과 연동하여 운영 가시성을 확보합니다. (ko) - Integrate logging/metrics with the Prometheus + Loki + Grafana stack to gain operational visibility. (en)