dalbodeule/hop-gate
1
0
Fork 0
mirror of https://github.com/dalbodeule/hop-gate.git synced 2026-09-21 08:11:06 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs: align architecture and API docs with Go 1.27 ingress support

Browse Source 
- document HTTP/1.1, HTTP/2, and HTTP/3 ingress
- describe SSE streaming and timeout behavior
- document HTTP/2 and HTTP/3 Extended CONNECT
- update yamux stream and deployment architecture
- document Go 1.27 and UDP HTTP/3 requirements
This commit is contained in:
dalbodeule
2026-09-04 16:58:14 +09:00
parent fe1018469d
commit ebd8463c19
11 changed files with 668 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API.md
+37
View File
@@ -1,5 +1,38 @@
# HopGate API
## Public Ingress
Registered domains are served by the public listeners configured on the server.
The same request is forwarded to the client's `HOP_CLIENT_LOCAL_TARGET`.
| Protocol | Port | Supported behavior |
| --- | --- | --- |
| HTTP/1.1 | TCP `HOP_SERVER_HTTP_LISTEN` / `HOP_SERVER_HTTPS_LISTEN` | HTTP, SSE, WebSocket Upgrade |
| HTTP/2 | TCP `HOP_SERVER_HTTPS_LISTEN` | HTTP, SSE, WebSocket Extended CONNECT |
| HTTP/3 | UDP `HOP_SERVER_HTTPS_LISTEN` | HTTP, SSE, WebSocket Extended CONNECT |
HTTP/3 is announced to HTTP/1.1 and HTTP/2 clients with `Alt-Svc`. HTTP/2
Extended CONNECT requires `GODEBUG=http2xconnect=1` when starting the server.
### SSE
SSE is detected when the request `Accept` header contains `text/event-stream`.
The response is streamed without buffering and bypasses the normal proxy
timeout. The upstream should send standard SSE records separated by a blank
line, for example:
```text
data: hello
```
### WebSocket
HTTP/1.1 WebSocket uses `Upgrade: websocket`. HTTP/2 and HTTP/3 use Extended
CONNECT with `:protocol=websocket`. The local service may remain an ordinary
HTTP/1.1 WebSocket server; HopGate translates the Extended CONNECT handshake
before relaying the raw bidirectional payload.
## Admin API
Admin endpoints are served under `/api/v1/admin/` on `HOP_SERVER_DOMAIN` and
@@ -19,3 +52,7 @@ to `:7443`. The client connects to that address with
Required client settings are `HOP_CLIENT_SERVER_ADDR`, `HOP_CLIENT_DOMAIN`,
`HOP_CLIENT_API_KEY`, `HOP_CLIENT_LOCAL_TARGET`, and `HOP_CLIENT_DEBUG`.
The tunnel is TLS over TCP with yamux multiplexing. The client only needs an
outbound TCP connection to the tunnel listener; public HTTP/3 traffic terminates
at the server and does not require QUIC support in the client.