hop-gate/ARCHITECTURE.md

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 / 디렉터리 레이아웃

.
├── 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 — 서버 실행 엔트리 포인트. 서버 설정 로딩, ACME/TLS 초기화, HTTP/HTTPS/DTLS 리스너 시작을 담당합니다. (ko)

• cmd/server/main.go — Server entrypoint. Loads configuration, initializes ACME/TLS, and starts HTTP/HTTPS/DTLS listeners. (en)

• cmd/client/main.go — 클라이언트 실행 엔트리 포인트. 설정 로딩, DTLS 연결 및 핸드셰이크, 로컬 서비스 프록시 루프를 담당합니다. (ko)

• 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)

2. An external user sends an HTTPS request to https://proxy.example.com/service-a/path. (en)

3. HopGate 서버의 HTTPS 리스너가 요청을 수신합니다. (ko)

4. The HTTPS listener on the HopGate server receives the request. (en)

5. proxy 레이어가 도메인과 경로를 기반으로 이 요청을 처리할 클라이언트(예: client-1)와 해당 로컬 서비스(service-a)를 결정합니다. (ko)

6. 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)

7. 서버는 요청을 protocol.Request 구조로 직렬화하고, dtls.Session 을 통해 선택된 클라이언트로 전송합니다. (ko)

8. The server serializes the request into a protocol.Request and sends it to the selected client over a dtls.Session. (en)

9. 클라이언트의 proxy 레이어는 protocol.Request 를 수신하고, 로컬 서비스(예: 127.0.0.1:8080)에 HTTP 요청을 수행합니다. (ko)

10. 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)

11. 클라이언트는 로컬 서비스로부터 HTTP 응답을 수신하고, 이를 protocol.Response 로 직렬화하여 DTLS 채널을 통해 서버로 다시 전송합니다. (ko)

12. 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)

13. 서버는 protocol.Response 를 디코딩하여 원래의 HTTPS 요청에 대한 HTTP 응답으로 변환한 뒤, 외부 사용자에게 반환합니다. (ko)

14. The server decodes the protocol.Response, converts it back into an HTTP response, and returns it to the original external user. (en)

---

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)