feat: fix agents.md
gosunuts committed
Feb 27, 2026 at 14:52 UTC
9a589a48ff0169923be5227db05983d41c55d4f1
7 files changed
+26
-23
AGENTS.md
+24
-21
@@ -35,19 +35,21 @@ Frontend dev:
35
Portal is a relay network that connects Apps (service publishers) and Clients (service consumers) through a central relay server without decrypting payloads.
36
37
Core components:
38
-- Relay server: `cmd/relay-server` (HTTP + TCP relay, admin UI serving)
39
-- Relay core logic: `portal/` (lease manager, connection handlers, forwarding)
40
-- Crypto + protocols: `portal/core/`
38
+- Relay server: `cmd/relay-server` (HTTP API/admin + SNI router)
39
+- Relay core logic: `portal/` (lease manager, reverse connection hub, forwarding)
40
+- SNI router package: `portal/sni/`
41
- SDK for Apps: `sdk/`
42
- Tunnel client: `cmd/portal-tunnel/` (exposes local services)
43
- Admin frontend: `cmd/relay-server/frontend/` (built into `cmd/relay-server/dist/app`)
44
45
## Connection Flow (High Level)
46
47
-1. App registers a Lease with the relay (identity, ALPN, metadata).
48
-2. Client requests connection by Lease ID or name.
49
-3. Relay routes TLS connection by SNI to the appropriate tunnel backend.
50
-4. TLS provides end-to-end encryption (relay does not decrypt).
47
+1. App/Tunnel registers a Lease with relay via `/sdk/register` (name, metadata, TLS mode, reverse token).
48
+2. Tunnel maintains reverse WebSocket workers to relay via `/sdk/connect`.
49
+3. Client traffic enters relay:
50
+ - TLS traffic on SNI port is routed by SNI.
51
+ - Non-TLS traffic can use HTTP proxy mode.
52
+4. Relay acquires a reverse tunnel connection and forwards bytes end-to-end.
53
54
## Key Terms
55
@@ -58,8 +60,9 @@ Core components:
60
61
## Where to Look
62
61
-- `cmd/relay-server/` (entrypoint and HTTP/WS relay)
62
-- `portal/` (core relay logic)
63
+- `cmd/relay-server/` (entrypoint, HTTP APIs, SNI callback wiring)
64
+- `portal/reverse_hub.go` (reverse WebSocket connection pool)
65
+- `portal/sni/` (SNI parser/router)
66
- `sdk/` (App integration)
67
- `cmd/portal-tunnel/` (tunnel client)
68
- `docs/architecture.md` and `docs/glossary.md`
@@ -77,29 +80,29 @@ Portal uses environment variables for domain and TLS configuration:
80
| `SNI_PORT` | SNI router port (default `:443`) |
81
| `ADMIN_SECRET_KEY` | Admin auth key (auto-generated if unset) |
82
80
-### ACME Certificate Management
81
-
82
-For TLS passthrough with automatic certificates:
83
+### Tunnel Environment Variables
84
85
| Variable | Description |
86
|----------|-------------|
86
-| `ACME_DNS_PROVIDER` | `cloudflare` or `route53` |
87
-| `ACME_EMAIL` | Email for ACME registration |
88
-| `CLOUDFLARE_API_TOKEN` | Cloudflare API token (if using cloudflare) |
87
+| `RELAYS` | Relay API URLs for tunnel client (comma-separated) |
88
+| `TLS_MODE` | `no-tls`, `self`, or `keyless` |
89
+| `TLS_CERT_FILE` | Self TLS certificate chain path (self mode only) |
90
+| `TLS_KEY_FILE` | Self TLS private key path (self mode only) |
91
92
### Domain Derivation
93
94
- Service URL: `{name}.{base_domain}` (e.g., `myapp.example.com`)
95
- Base domain extracted from `PORTAL_URL` via `extractBaseDomain()` in `cmd/relay-server/utils.go`
94
-- SNI routes registered in `portal/utils/sni/router.go`
96
+- SNI routes registered in `portal/sni/router.go`
97
98
### TLS Modes
99
98
-1. **HTTP Proxy**: No TLS, relay proxies HTTP to tunnel
99
-2. **TLS Passthrough**: Relay routes TLS by SNI to tunnel backend
100
- - Tunnel client sends CSR to relay
101
- - Relay issues certificate via ACME DNS-01
102
- - End-to-end TLS encryption
100
+1. **`no-tls`**: HTTP proxy mode for development.
101
+2. **`self`**: Tunnel uses locally provided certificate and key (`TLS_CERT_FILE` + `TLS_KEY_FILE`).
102
+3. **`keyless`**: Tunnel uses SDK keyless mode with auto defaults.
103
+ - Keyless signer endpoint defaults to relay URL unless explicitly overridden in SDK options.
104
+ - Certificate chain/root trust are auto-discovered by SDK from signer endpoint when not explicitly provided.
105
+ - Auto-discovery requires an HTTPS signer endpoint.
106
107
See `docs/portal-deploy-guide.md` for full deployment documentation.
108
cmd/relay-server/main.go
+1
-1
@@ -16,7 +16,7 @@ import (
16
17
"gosuda.org/portal/cmd/relay-server/manager"
18
"gosuda.org/portal/portal"
19
- "gosuda.org/portal/portal/utils/sni"
19
+ "gosuda.org/portal/portal/sni"
20
)
21
22
var (
portal/relay.go
+1
-1
@@ -10,7 +10,7 @@ import (
10
11
"github.com/rs/zerolog/log"
12
13
- "gosuda.org/portal/portal/utils/sni"
13
+ "gosuda.org/portal/portal/sni"
14
)
15
16
type RelayServer struct {