feat: update CI workflow, enhance README and architecture documentation, and refine development guide
gosunuts committed
Feb 24, 2026 at 19:01 UTC
bf9ad7241f9f13104377eab2d7143cfdbdf31cce
5 files changed
+140
-248
.github/workflows/ci.yml
+3
-76
@@ -4,12 +4,12 @@ on:
4
pull_request:
5
branches: [main]
6
push:
7
- branches: ["*"]
7
+ branches: [main]
8
workflow_dispatch:
9
10
jobs:
11
test:
12
- name: Test
12
+ name: Test & Build
13
runs-on: ubuntu-latest
14
15
steps:
@@ -29,23 +29,7 @@ jobs:
29
run: go vet ./...
30
31
- name: Run tests
32
- run: go test -v -race -coverprofile=coverage.out ./...
33
-
34
- lint:
35
- name: Lint
36
- runs-on: ubuntu-latest
37
- steps:
38
- - name: Checkout code
39
- uses: actions/checkout@v5
40
-
41
- - name: Set up Go
42
- uses: actions/setup-go@v6
43
- with:
44
- go-version: "stable"
45
- check-latest: true
46
-
47
- - name: Download dependencies
48
- run: go mod download
32
+ run: go test -v -race ./...
33
34
- name: Install golangci-lint
35
run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
@@ -53,62 +37,5 @@ jobs:
37
- name: Run golangci-lint
38
run: golangci-lint run
39
56
- security:
57
- name: Security
58
- runs-on: ubuntu-latest
59
- steps:
60
- - name: Checkout code
61
- uses: actions/checkout@v5
62
-
63
- - name: Set up Go
64
- uses: actions/setup-go@v6
65
- with:
66
- go-version: "stable"
67
- check-latest: true
68
-
69
- - name: Download dependencies
70
- run: go mod download
71
-
72
- - name: Install govulncheck
73
- run: go install golang.org/x/vuln/cmd/govulncheck@latest
74
-
75
- - name: Run govulncheck
76
- run: govulncheck ./...
77
-
78
- build:
79
- name: Build
80
- runs-on: ubuntu-latest
81
-
82
- steps:
83
- - name: Checkout code
84
- uses: actions/checkout@v5
85
-
86
- - name: Set up Go
87
- uses: actions/setup-go@v6
88
- with:
89
- go-version: "stable"
90
- check-latest: true
91
-
92
- - name: Download dependencies
93
- run: go mod download
94
-
95
- - name: Install build dependencies
96
- run: |
97
- sudo apt-get update
98
- sudo apt-get install -y binaryen
99
-
40
- name: Build all components
41
run: make build
102
-
103
- - name: Upload artifacts
104
- uses: actions/upload-artifact@v4
105
- with:
106
- name: portal-binaries
107
- path: bin/
108
-
109
- - name: Build Docker image
110
- uses: docker/build-push-action@v6
111
- with:
112
- context: .
113
- push: false
114
- tags: portal:latest
CLAUDE.md
deleted
-1
@@ -1 +0,0 @@
1
-AGENTS.md
\ No newline at end of file
README.md
+32
-39
@@ -4,17 +4,7 @@
4
<img src="/portal.jpg" alt="Portal logo" width="540" />
5
</p>
6
7
-Portal is a permissionless, open hosting network that transforms your local project into a public web endpoint. [See more.](https://gosuda.org/portal/)
8
-
9
-## Table of Contents
10
-
11
-- [Overview](#overview)
12
-- [Features](#features)
13
-- [Quick Start](#quick-start)
14
-- [Architecture](#architecture)
15
-- [Contributing](#contributing)
16
-- [License](#license)
17
-
7
+Portal is a permissionless, open hosting network that transforms your local project into a public web endpoint. [Learn more.](https://gosuda.org/portal/)
8
## Overview
9
10
Portal connects local applications to web users through a secure relay layer.
@@ -23,55 +13,59 @@ This enables developers to publish local services globally without managing serv
13
14
## Features
15
26
-- 🔄 **Connection Relay**: Connects clients behind NAT or firewalls through the Portal network.
27
-- 🔐 **End-to-End Encryption**: Fully encrypted client-to-client communication, including browser sessions via a WASM-based Service Worker proxy.
28
-- 🕊️ **Permissionless Hosting**: Anyone can open or choose their own Portal — no approval, no central authority.
16
+- 🔄 **Connection Relay**: Connects clients behind NAT or firewalls through the Portal network
17
+- 🔐 **End-to-End Encryption**: Fully encrypted client-to-client communication via RDSEC protocol
18
+- 🕊️ **Permissionless Hosting**: Anyone can run their own Portal — no approval needed
19
- 🚀 **High Performance**: Multiplexed connections using yamux
30
-- ⚙️ **Simple Setup**: Build and bootstrap apps quickly using the Portal SDK or Tunnel client.
20
+- ⚙️ **Simple Setup**: Quick start with Tunnel client or Go SDK
21
22
## Quick Start
33
-You can run **Portal** to host relay services, or run **App** to publish your own application through portal.
23
35
-### Running the Portal Network
36
-Run Portal with Docker Compose:
24
+### Run Portal Relay
25
26
```bash
39
-# 1. Start services
27
+# Start with Docker Compose
28
docker compose up
29
42
-# 2. Open in browser
43
-http://localhost:4017
44
-
45
-# 3. Access admin panel at http://localhost:4017/admin
46
-# If ADMIN_SECRET_KEY is not set, a random key will be auto-generated and shown in logs
47
-# To use your own key:
30
+# Access at http://localhost:4017
31
+# Admin panel at http://localhost:4017/admin
32
+# Auto-generated admin key shown in logs, or set your own:
33
ADMIN_SECRET_KEY=your-secret-key docker compose up
34
```
35
51
-For a public deployment guide (DNS, TLS, reverse proxy), see [docs/portal-deploy-guide.md](docs/portal-deploy-guide.md).
36
+For production deployment (DNS, TLS, reverse proxy), see [docs/portal-deploy-guide.md](docs/portal-deploy-guide.md).
37
53
-### Running a Portal App using Tunnel
38
+### Expose Local Service via Tunnel
39
40
```bash
56
-# 1. Start your local service
57
-
58
-# 2. Run the tunnel client to expose
59
-## If you use it in windows
41
+# Windows PowerShell
42
$env:HOST="localhost:3000"; $env:NAME="myapp"; irm http://localhost:4017/tunnel | iex
61
-## Else
43
+
44
+# macOS/Linux
45
curl -fsSL http://localhost:4017/tunnel | HOST=localhost:3000 NAME=myapp sh
46
```
47
65
-### Running a Portal App using the SDK
66
-See [portal-toys](https://github.com/gosuda/portal-toys)
48
+### Use Go SDK
49
+
50
+```go
51
+import "gosuda.org/portal/sdk"
52
+
53
+client, _ := sdk.NewClient(sdk.WithBootstrapServers([]string{"http://localhost:4017"}))
54
+listener, _ := client.Listen("myapp")
55
+http.Serve(listener, handler)
56
+```
57
+
58
+See [portal-toys](https://github.com/gosuda/portal-toys) for more examples.
59
60
## Architecture
61
70
-For a detailed overview of system components and data flow, see the [architecture documentation](docs/architecture.md).
62
+- **Relay Server**: HTTP/WebSocket relay, admin UI, lease management
63
+- **SDK**: Go library for native app integration
64
+- **Tunnel**: CLI client for exposing local services without code changes
65
+- **WebClient**: WASM-based browser client (served by relay)
66
72
-## Glossary
67
+For details, see [docs/architecture.md](docs/architecture.md).
68
74
-If you need Portal-specific terminology, check the [Portal glossary](docs/glossary.md)
69
## Contributing
70
71
We welcome contributions from the community!
@@ -84,7 +78,6 @@ Before getting started, please check the [development guide](docs/development.md
78
3. Commit your changes (`git commit -m 'Add amazing feature'`)
79
4. Push to the branch (`git push origin feature/amazing-feature`)
80
5. Open a Pull Request
87
-
81
## License
82
90
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
83
+MIT License — see [LICENSE](LICENSE)
docs/architecture.md
+53
-87
@@ -1,99 +1,65 @@
1
-
1
# Architecture
2
4
-## System Architecture
5
-
6
-```mermaid
7
-graph TB
8
- subgraph "Client A"
9
- CA[Client A]
10
- CA --> CA_ID[Identity: Ed25519]
11
- CA --> CA_LEASE[Lease Manager]
12
- end
13
-
14
- subgraph "Client B"
15
- CB[Client B]
16
- CB --> CB_ID[Identity: Ed25519]
17
- CB --> CB_LEASE[Lease Manager]
18
- end
19
-
20
- subgraph "Relay Server"
21
- RS[Relay Server]
22
- RS --> RS_ID[Server Identity]
23
- RS --> LM[Lease Manager]
24
- RS --> CM[Connection Manager]
25
- RS --> FH[Forwarding Handler]
26
- end
27
-
28
- CA -.->|1. Register Lease| RS
29
- CB -.->|2. Register Lease| RS
30
- CB -.->|3. Request Connection| RS
31
- RS -.->|4. Forward Request| CA
32
- CA -.->|5. Accept Connection| RS
33
- RS -.->|6. Establish E2EE| CB
34
-
35
- CA <-->|7. Encrypted Data| CB
36
-```
3
+## Overview
4
38
-## Component Architecture
39
-
40
-```mermaid
41
-graph LR
42
- subgraph "Client Components"
43
- C[RelayClient]
44
- C --> H[Handshaker]
45
- C --> LM[LeaseManager]
46
- C --> SC[SecureConnection]
47
- end
48
-
49
- subgraph "Server Components"
50
- S[RelayServer]
51
- S --> LH[LeaseHandler]
52
- S --> CH[ConnectionHandler]
53
- S --> FH[ForwardingHandler]
54
- S --> LM2[LeaseManager]
55
- end
56
-
57
- subgraph "Crypto Operations"
58
- CO[CryptoOps]
59
- CO --> CRED[Credential]
60
- CO --> SIG[Signature]
61
- CO --> E2EE[End-to-End Encryption]
62
- end
63
-
64
- C <-->|Protocol Messages| S
65
- H --> CO
66
- SC --> CO
67
- LH --> LM2
68
- CH --> FH
5
+Portal connects local applications to web users through a secure relay layer with end-to-end encryption.
6
+
7
+```
8
+┌─────────────┐ ┌──────────────┐ ┌─────────────┐
9
+│ Browser │◄────►│ Relay Server │◄────►│ App/Tunnel │
10
+│ (WASM SW) │ WS │ (:4017) │ WS │ (SDK/CLI) │
11
+└─────────────┘ └──────────────┘ └─────────────┘
12
+ │
13
+ ▼
14
+ ┌──────────────┐
15
+ │ Local HTTP │
16
+ │ (:3000 etc) │
17
+ └──────────────┘
18
```
19
71
-## Connection Flow
20
+## Components
21
+
22
+### Relay Server (`cmd/relay-server`)
23
+
24
+- **HTTP Server**: Static files, admin UI, API endpoints
25
+- **WebSocket Relay**: `/api/connect` for reverse tunnel connections
26
+- **Lease Manager**: Registration, TTL, banning
27
+- **SNI Router**: TLS passthrough routing
28
+
29
+### SDK (`sdk/`)
30
73
-```mermaid
74
-sequenceDiagram
75
- participant C1 as Client 1
76
- participant RS as Relay Server
77
- participant C2 as Client 2
31
+- **Client**: Bootstrap, health checks, reconnection
32
+- **Listener**: `net.Listener` implementation over WebSocket
33
+- **Types**: Shared API types (`RegisterRequest`, `Metadata`, etc.)
34
79
- Note over C1,C2: Lease Registration Phase
80
- C1->>RS: Register Lease (Identity, ALPN)
81
- RS->>C1: Lease Confirmation
35
+### Tunnel (`cmd/portal-tunnel`)
36
83
- C2->>RS: Register Lease (Identity, ALPN)
84
- RS->>C2: Lease Confirmation
37
+- TCP proxy between relay and local service
38
+- No code changes required to expose existing services
39
86
- Note over C1,C2: Connection Establishment Phase
87
- C2->>RS: Request Connection (to Client 1)
88
- RS->>C1: Forward Connection Request
89
- C1->>RS: Accept Connection
90
- RS->>C2: Connection Accepted
40
+### WebClient (`cmd/webclient`)
41
92
- Note over C1,C2: Secure Handshake Phase
93
- C2->>C1: X25519 Handshake (via relay)
94
- C1->>C2: X25519 Response (via relay)
42
+- WASM-based Service Worker proxy
43
+- Runs in browser for E2EE communication
44
96
- Note over C1,C2: End-to-End Encrypted Communication
97
- C2->>C1: Encrypted Data (ChaCha20-Poly1305)
98
- C1->>C2: Encrypted Data (ChaCha20-Poly1305)
45
+## Connection Flow
46
+
47
+1. **Register**: App/Tunnel → Relay (`POST /api/register`)
48
+2. **Reverse Connect**: App/Tunnel ← Relay (`WS /api/connect`)
49
+3. **Client Request**: Browser → Relay (`GET *.localhost:4017`)
50
+4. **Proxy**: Relay ↔ App/Tunnel ↔ Local Service
51
+
52
+## Security
53
+
54
+- **RDSEC**: X25519 key exchange + ChaCha20-Poly1305 encryption
55
+- **Tokens**: Per-lease reverse connection tokens
56
+- **SNI Routing**: TLS passthrough without termination
57
+
58
+## Protocol Stack
59
+
60
+```
61
+HTTP/WebSocket
62
+ └── yamux (multiplexing)
63
+ └── RDSEC (E2EE)
64
+ └── Application Data
65
```
docs/development.md
+52
-45
@@ -1,45 +1,52 @@
1
-# Development Principles and Operational Guide
2
-
3
-This document defines the core principles and operational scope of the Portal project.
4
-It aims to prevent unnecessary feature expansion or direction drift, and to maintain a consistent user experience.
5
-
6
----
7
-
8
-## 1. Usability Invariance Principle
9
-Portal developers must ensure that any new feature does not alter existing usability.
10
-A "change in usability" includes, but is not limited to:
11
-
12
-- Modifications to the Portal usage flow
13
-- Changes to the deployment or configuration process
14
-- Alterations to the SDK development environment
15
-- Increases in codebase complexity
16
-- Any similar impacts that may affect the user experience
17
-
18
----
19
-
20
-## 2. Prior Agreement for Changes
21
-If a feature impacts usability, the proposer must provide a clear written rationale and obtain prior agreement from the team before proceeding.
22
-
23
-- A merge is permitted only when at least one reviewer (other than the proposer) approves the change.
24
-
25
----
26
-
27
-
28
-## 3. Testing and Quality Assurance
29
-Unfinished or experimental features must not be merged directly into the main branch.
30
-All new features must be fully tested and verified in a personal branch before merging.
31
-
32
----
33
-
34
-## 4. Project Philosophy and Scope
35
-Portal serves as a relay layer that allows individuals to publicly expose locally running services, with built-in end-to-end encryption.
36
-
37
-- When proposing new features, include sufficient justification and follow the agreement process described above.
38
-- Approved features must be documented and tracked in the project roadmap.
39
-
40
----
41
-
42
-## 5. Principles for Resolving Disagreements
43
-If differences of opinion arise, resolve them through constructive discussion and consensus.
44
-
45
----
1
+# Development Guide
2
+
3
+## Quick Start
4
+
5
+```bash
6
+# Clone and build
7
+git clone https://github.com/gosuda/portal.git
8
+cd portal
9
+make build
10
+
11
+# Run tests
12
+make test
13
+
14
+# Run relay server locally
15
+make run
16
+```
17
+
18
+## Project Structure
19
+
20
+```
21
+cmd/
22
+ relay-server/ # Relay server entrypoint
23
+ portal-tunnel/ # Tunnel CLI client
24
+ demo-app/ # Demo application
25
+ webclient/ # WASM browser client
26
+portal/ # Core relay logic
27
+sdk/ # Go SDK for apps
28
+utils/ # Shared utilities
29
+```
30
+
31
+## Key Commands
32
+
33
+| Command | Description |
34
+|---------|-------------|
35
+| `make build` | Build all components |
36
+| `make test` | Run tests with race detector |
37
+| `make lint` | Run golangci-lint |
38
+| `make fmt` | Format code |
39
+| `make run` | Run relay server |
40
+
41
+## Guidelines
42
+
43
+1. **No breaking changes** to existing workflows without team discussion
44
+2. **Test before merging** — all features must be verified in a branch
45
+3. **Follow existing patterns** — check similar code before adding new features
46
+4. **Run linters** before committing: `make fmt && make lint`
47
+
48
+## Architecture Decisions
49
+
50
+- **E2EE**: RDSEC protocol (X25519 + ChaCha20-Poly1305)
51
+- **Multiplexing**: yamux over WebSocket
52
+- **No CGO**: pure Go for cross-platform builds