diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 537c267..ff602e3 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -118,7 +118,9 @@ "Bash(go run:*)", "Bash(git commit -m \"$(cat <<''EOF''\nFix NIP-11 fetch URL scheme conversion for non-proxied relays\n\n- Convert wss:// to https:// and ws:// to http:// before fetching NIP-11\n documents, fixing failures for users not using HTTPS upgrade proxies\n- The fetchNIP11 function was using WebSocket URLs directly for HTTP\n requests, causing scheme mismatch errors\n\nπŸ€– Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Opus 4.5 \nEOF\n)\")", "Bash(/tmp/orly help:*)", - "Bash(git commit -m \"$(cat <<''EOF''\nAdd ORLY_POLICY_PATH for custom policy file location\n\n- Add ORLY_POLICY_PATH environment variable to configure custom policy\n file path, overriding the default ~/.config/ORLY/policy.json location\n- Enforce ABSOLUTE paths only - relay panics on startup if relative path\n is provided, preventing common misconfiguration errors\n- Update PolicyManager to store and expose configPath for hot-reload saves\n- Add ConfigPath() method to P struct delegating to internal PolicyManager\n- Update NewWithManager() signature to accept optional custom path parameter\n- Add BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md with issue submission\n guidelines requiring environment details, reproduction steps, and logs\n- Update README.md with system requirements (500MB minimum memory) and\n link to bug report protocol\n- Update CLAUDE.md and README.md documentation for new ORLY_POLICY_PATH\n\nFiles modified:\n- app/config/config.go: Add PolicyPath config field\n- pkg/policy/policy.go: Add configPath storage and validation\n- app/handle-policy-config.go: Use policyManager.ConfigPath()\n- app/main.go: Pass cfg.PolicyPath to NewWithManager\n- pkg/policy/*_test.go: Update test calls with new parameter\n- BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md: New file\n- README.md, CLAUDE.md: Documentation updates\n\nπŸ€– Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Opus 4.5 \nEOF\n)\")" + "Bash(git commit -m \"$(cat <<''EOF''\nAdd ORLY_POLICY_PATH for custom policy file location\n\n- Add ORLY_POLICY_PATH environment variable to configure custom policy\n file path, overriding the default ~/.config/ORLY/policy.json location\n- Enforce ABSOLUTE paths only - relay panics on startup if relative path\n is provided, preventing common misconfiguration errors\n- Update PolicyManager to store and expose configPath for hot-reload saves\n- Add ConfigPath() method to P struct delegating to internal PolicyManager\n- Update NewWithManager() signature to accept optional custom path parameter\n- Add BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md with issue submission\n guidelines requiring environment details, reproduction steps, and logs\n- Update README.md with system requirements (500MB minimum memory) and\n link to bug report protocol\n- Update CLAUDE.md and README.md documentation for new ORLY_POLICY_PATH\n\nFiles modified:\n- app/config/config.go: Add PolicyPath config field\n- pkg/policy/policy.go: Add configPath storage and validation\n- app/handle-policy-config.go: Use policyManager.ConfigPath()\n- app/main.go: Pass cfg.PolicyPath to NewWithManager\n- pkg/policy/*_test.go: Update test calls with new parameter\n- BUG_REPORTS_AND_FEATURE_REQUEST_PROTOCOL.md: New file\n- README.md, CLAUDE.md: Documentation updates\n\nπŸ€– Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Opus 4.5 \nEOF\n)\")", + "Bash(mkdir:*)", + "Bash(ssh:*)" ], "deny": [], "ask": [] diff --git a/.gitea/issue_template/bug_report.yaml b/.gitea/issue_template/bug_report.yaml new file mode 100644 index 0000000..3ce0060 --- /dev/null +++ b/.gitea/issue_template/bug_report.yaml @@ -0,0 +1,118 @@ +name: Bug Report +about: Report a bug or unexpected behavior in ORLY relay +title: "[BUG] " +labels: + - bug +body: + - type: markdown + attributes: + value: | + ## Bug Report Guidelines + + Thank you for taking the time to report a bug. Please fill out the form below to help us understand and reproduce the issue. + + **Before submitting:** + - Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates + - Check the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration guidance + - Ensure you're running a recent version of ORLY + + - type: input + id: version + attributes: + label: ORLY Version + description: Run `./orly version` to get the version + placeholder: "v0.35.4" + validations: + required: true + + - type: dropdown + id: database + attributes: + label: Database Backend + description: Which database backend are you using? + options: + - Badger (default) + - Neo4j + - WasmDB + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of the bug + placeholder: Describe what happened and what you expected to happen + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Detailed steps to reproduce the behavior + placeholder: | + 1. Start relay with `./orly` + 2. Connect with client X + 3. Perform action Y + 4. Observe error Z + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant Logs + description: | + Include relevant log output. Set `ORLY_LOG_LEVEL=debug` or `trace` for more detail. + This will be automatically formatted as code. + render: shell + + - type: textarea + id: config + attributes: + label: Configuration + description: | + Relevant environment variables or configuration (redact sensitive values). + This will be automatically formatted as code. + render: shell + placeholder: | + ORLY_ACL_MODE=follows + ORLY_POLICY_ENABLED=true + ORLY_DB_TYPE=badger + + - type: textarea + id: environment + attributes: + label: Environment + description: Operating system, Go version, etc. + placeholder: | + OS: Linux 6.8.0 + Go: 1.25.3 + Architecture: amd64 + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other context, screenshots, or information that might help + + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: I have searched existing issues and this is not a duplicate + required: true + - label: I have included version information + required: true + - label: I have included steps to reproduce the issue + required: true diff --git a/.gitea/issue_template/config.yaml b/.gitea/issue_template/config.yaml new file mode 100644 index 0000000..af9d3a9 --- /dev/null +++ b/.gitea/issue_template/config.yaml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation + url: https://git.mleku.dev/mleku/next.orly.dev + about: Check the repository documentation before opening an issue + - name: Nostr Protocol (NIPs) + url: https://github.com/nostr-protocol/nips + about: For questions about Nostr protocol specifications diff --git a/.gitea/issue_template/feature_request.yaml b/.gitea/issue_template/feature_request.yaml new file mode 100644 index 0000000..81936e9 --- /dev/null +++ b/.gitea/issue_template/feature_request.yaml @@ -0,0 +1,118 @@ +name: Feature Request +about: Suggest a new feature or enhancement for ORLY relay +title: "[FEATURE] " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + ## Feature Request Guidelines + + Thank you for suggesting a feature. Please provide as much detail as possible to help us understand your proposal. + + **Before submitting:** + - Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates + - Check if this is covered by an existing [NIP](https://github.com/nostr-protocol/nips) + - Review the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for current capabilities + + - type: dropdown + id: category + attributes: + label: Feature Category + description: What area of ORLY does this feature relate to? + options: + - Protocol (NIP implementation) + - Database / Storage + - Performance / Optimization + - Policy / Access Control + - Web UI / Admin Interface + - Deployment / Operations + - API / Integration + - Documentation + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: | + What problem does this feature solve? Is this related to a frustration you have? + A clear problem statement helps us understand the motivation. + placeholder: "I'm always frustrated when..." + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: | + Describe the solution you'd like. Be specific about expected behavior. + placeholder: "I would like ORLY to..." + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: | + Describe any alternative solutions or workarounds you've considered. + placeholder: "I've tried X but it doesn't work because..." + + - type: input + id: nip + attributes: + label: Related NIP + description: If this relates to a Nostr Implementation Possibility, provide the NIP number + placeholder: "NIP-XX" + + - type: dropdown + id: impact + attributes: + label: Scope of Impact + description: How significant is this feature? + options: + - Minor enhancement (small quality-of-life improvement) + - Moderate feature (adds useful capability) + - Major feature (significant new functionality) + - Breaking change (requires migration or config changes) + validations: + required: true + + - type: dropdown + id: contribution + attributes: + label: Willingness to Contribute + description: Would you be willing to help implement this feature? + options: + - "Yes, I can submit a PR" + - "Yes, I can help with testing" + - "No, but I can provide more details" + - "No" + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional Context + description: | + Any other context, mockups, examples, or references that help explain the feature. + + For protocol features, include example event structures or message flows if applicable. + + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: I have searched existing issues and this is not a duplicate + required: true + - label: I have described the problem this feature solves + required: true + - label: I have checked if this relates to an existing NIP + required: false diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml new file mode 100644 index 0000000..5ce9479 --- /dev/null +++ b/.github/workflows/ci.yaml @@ -0,0 +1,53 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Download libsecp256k1 + run: | + wget -q https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/libsecp256k1.so -O libsecp256k1.so + chmod +x libsecp256k1.so + + - name: Run tests + run: | + export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$(pwd)" + CGO_ENABLED=0 go test ./... + + - name: Build binary + run: | + CGO_ENABLED=0 go build -o orly . + ./orly version + + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Check go mod tidy + run: | + go mod tidy + git diff --exit-code go.mod go.sum + + - name: Run go vet + run: CGO_ENABLED=0 go vet ./... diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..c7b65be --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,154 @@ +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + include: + - goos: linux + goarch: amd64 + platform: linux-amd64 + ext: "" + lib: libsecp256k1.so + - goos: linux + goarch: arm64 + platform: linux-arm64 + ext: "" + lib: libsecp256k1.so + - goos: darwin + goarch: amd64 + platform: darwin-amd64 + ext: "" + lib: libsecp256k1.dylib + - goos: darwin + goarch: arm64 + platform: darwin-arm64 + ext: "" + lib: libsecp256k1.dylib + - goos: windows + goarch: amd64 + platform: windows-amd64 + ext: ".exe" + lib: libsecp256k1.dll + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install bun + run: | + curl -fsSL https://bun.sh/install | bash + echo "$HOME/.bun/bin" >> $GITHUB_PATH + + - name: Build Web UI + run: | + cd app/web + $HOME/.bun/bin/bun install + $HOME/.bun/bin/bun run build + + - name: Get version + id: version + run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT + + - name: Build binary + env: + CGO_ENABLED: 0 + GOOS: ${{ matrix.goos }} + GOARCH: ${{ matrix.goarch }} + run: | + VERSION=${{ steps.version.outputs.version }} + OUTPUT="orly-${VERSION}-${{ matrix.platform }}${{ matrix.ext }}" + go build -ldflags "-s -w -X main.version=${VERSION}" -o ${OUTPUT} . + sha256sum ${OUTPUT} > ${OUTPUT}.sha256 + + - name: Download runtime library + run: | + VERSION=${{ steps.version.outputs.version }} + LIB="${{ matrix.lib }}" + wget -q "https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/${LIB}" -O "${LIB}" || true + if [ -f "${LIB}" ]; then + sha256sum "${LIB}" > "${LIB}.sha256" + fi + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: orly-${{ matrix.platform }} + path: | + orly-* + libsecp256k1* + + release: + needs: build + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Get version + id: version + run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT + + - name: Download all artifacts + uses: actions/download-artifact@v4 + with: + path: artifacts + merge-multiple: true + + - name: Create combined checksums + run: | + cd artifacts + cat *.sha256 | sort -k2 > SHA256SUMS.txt + rm -f *.sha256 + + - name: List release files + run: ls -la artifacts/ + + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + name: ORLY ${{ steps.version.outputs.version }} + body: | + ## ORLY ${{ steps.version.outputs.version }} + + ### Downloads + + Download the appropriate binary for your platform. The `libsecp256k1` library is optional but recommended for better cryptographic performance. + + ### Installation + + 1. Download the binary for your platform + 2. (Optional) Download the corresponding `libsecp256k1` library + 3. Place both files in the same directory + 4. Make the binary executable: `chmod +x orly-*` + 5. Run: `./orly-*-linux-amd64` (or your platform's binary) + + ### Verify Downloads + + ```bash + sha256sum -c SHA256SUMS.txt + ``` + + ### Configuration + + See the [repository documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration options. + files: | + artifacts/* + draft: false + prerelease: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5895457 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to ORLY + +Thank you for your interest in contributing to ORLY! This document outlines the process for reporting bugs, requesting features, and submitting contributions. + +**Canonical Repository:** https://git.mleku.dev/mleku/next.orly.dev + +## Issue Reporting Policy + +### Before Opening an Issue + +1. **Search existing issues** to avoid duplicates +2. **Check the documentation** in the repository +3. **Verify your version** - run `./orly version` and ensure you're on a recent release +4. **Review the CLAUDE.md** file for configuration guidance + +### Bug Reports + +Use the **Bug Report** template when reporting unexpected behavior. A good bug report includes: + +- **Version information** - exact ORLY version from `./orly version` +- **Database backend** - Badger, Neo4j, or WasmDB +- **Clear description** - what happened vs. what you expected +- **Reproduction steps** - detailed steps to trigger the bug +- **Logs** - relevant log output (use `ORLY_LOG_LEVEL=debug` or `trace`) +- **Configuration** - relevant environment variables (redact secrets) + +#### Log Levels for Debugging + +```bash +export ORLY_LOG_LEVEL=trace # Most verbose +export ORLY_LOG_LEVEL=debug # Development debugging +export ORLY_LOG_LEVEL=info # Default +``` + +### Feature Requests + +Use the **Feature Request** template when suggesting new functionality. A good feature request includes: + +- **Problem statement** - what problem does this solve? +- **Proposed solution** - specific description of desired behavior +- **Alternatives considered** - workarounds you've tried +- **Related NIP** - if this implements a Nostr protocol specification +- **Impact assessment** - is this a minor tweak or major change? + +#### Feature Categories + +- **Protocol** - NIP implementations and Nostr protocol features +- **Database** - Storage backends, indexing, query optimization +- **Performance** - Caching, SIMD operations, memory optimization +- **Policy** - Access control, event filtering, validation +- **Web UI** - Admin interface improvements +- **Operations** - Deployment, monitoring, systemd integration + +## Code Contributions + +### Development Setup + +```bash +# Clone the repository +git clone https://git.mleku.dev/mleku/next.orly.dev.git +cd next.orly.dev + +# Build +CGO_ENABLED=0 go build -o orly + +# Run tests +./scripts/test.sh + +# Build with web UI +./scripts/update-embedded-web.sh +``` + +### Pull Request Guidelines + +1. **One feature/fix per PR** - keep changes focused +2. **Write tests** - for new functionality and bug fixes +3. **Follow existing patterns** - match the code style of surrounding code +4. **Update documentation** - if your change affects configuration or behavior +5. **Test your changes** - run `./scripts/test.sh` before submitting + +### Commit Message Format + +``` +Short summary (72 chars max, imperative mood) + +- Bullet point describing change 1 +- Bullet point describing change 2 + +Files modified: +- path/to/file1.go: Description of change +- path/to/file2.go: Description of change +``` + +## Communication + +- **Issues:** https://git.mleku.dev/mleku/next.orly.dev/issues +- **Documentation:** https://git.mleku.dev/mleku/next.orly.dev + +## License + +By contributing to ORLY, you agree that your contributions will be licensed under the same license as the project. diff --git a/docs/plans/DECENTRALIZE_NOSTR.md b/docs/plans/DECENTRALIZE_NOSTR.md new file mode 100644 index 0000000..8b29121 --- /dev/null +++ b/docs/plans/DECENTRALIZE_NOSTR.md @@ -0,0 +1,325 @@ +# ORLY Expansion Plan: Documentation, Installer, Tray, and WireGuard + +## Overview + +Expand ORLY from a relay binary into a complete ecosystem for personal Nostr relay deployment, with: +1. **Textbook-style README** - Progressive documentation from novice to expert +2. **GUI Installer** - Wails-based setup wizard (Linux + macOS) +3. **System Tray** - Service monitoring and control +4. **WireGuard Client** - Embedded tunnel for NAT traversal +5. **Proxy Server** - Self-hostable AND managed service option + +--- + +## Architecture + +``` + USER SYSTEMS +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ orly-setup β”‚ β”‚ orly β”‚ β”‚ orly --tray β”‚ β”‚ +β”‚ β”‚ (Installer) β”‚ β”‚ (Relay) β”‚ β”‚ (Systray) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ generates β”‚ serves β”‚ monitors β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ~/.config/ β”‚ β”‚ :3334 WS/HTTPβ”‚ β”‚ /api/admin/* β”‚ β”‚ +β”‚ β”‚ systemd svc β”‚ β”‚ + WG tunnel β”‚ β”‚ status/ctrl β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ pkg/tunnel/ β”‚ β”‚ +β”‚ β”‚ WireGuard β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ WG Tunnel (UDP :51820) + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PROXY SERVER β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ WG Server │───▢│ Nostr Auth │───▢│ Public Proxy β”‚ β”‚ +β”‚ β”‚ :51820 β”‚ β”‚ (npub-based) β”‚ β”‚ Egress β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## Package Structure + +``` +next.orly.dev/ +β”œβ”€β”€ cmd/ +β”‚ β”œβ”€β”€ orly-setup/ # NEW: Wails installer +β”‚ β”‚ β”œβ”€β”€ main.go +β”‚ β”‚ β”œβ”€β”€ app.go # Backend logic +β”‚ β”‚ β”œβ”€β”€ frontend/ # Svelte wizard UI +β”‚ β”‚ β”‚ └── src/steps/ # Welcome, Config, Install, Complete +β”‚ β”‚ └── install/ +β”‚ β”‚ β”œβ”€β”€ preflight.go # Dependency checks +β”‚ β”‚ β”œβ”€β”€ systemd.go # Service creation +β”‚ β”‚ └── verify.go # Post-install checks +β”‚ β”‚ +β”‚ └── proxy-server/ # NEW: WireGuard proxy +β”‚ β”œβ”€β”€ main.go +β”‚ β”œβ”€β”€ server.go # WG server +β”‚ β”œβ”€β”€ auth.go # Nostr auth +β”‚ └── registry.go # User management +β”‚ +β”œβ”€β”€ pkg/ +β”‚ β”œβ”€β”€ tunnel/ # NEW: Embedded WG client +β”‚ β”‚ β”œβ”€β”€ tunnel.go # Main interface +β”‚ β”‚ β”œβ”€β”€ client.go # wireguard-go wrapper +β”‚ β”‚ β”œβ”€β”€ reconnect.go # Auto-reconnect +β”‚ β”‚ └── health.go # Connection health +β”‚ β”‚ +β”‚ β”œβ”€β”€ tray/ # NEW: System tray +β”‚ β”‚ β”œβ”€β”€ tray.go # Platform abstraction +β”‚ β”‚ β”œβ”€β”€ tray_linux.go # Linux implementation +β”‚ β”‚ β”œβ”€β”€ tray_darwin.go # macOS implementation +β”‚ β”‚ └── menu.go # Menu construction +β”‚ β”‚ +β”‚ β”œβ”€β”€ admin/ # NEW: Admin HTTP API +β”‚ β”‚ β”œβ”€β”€ api.go # Router +β”‚ β”‚ β”œβ”€β”€ status.go # GET /api/admin/status +β”‚ β”‚ β”œβ”€β”€ control.go # POST /api/admin/start|stop|restart +β”‚ β”‚ └── logs.go # GET /api/admin/logs (SSE) +β”‚ β”‚ +β”‚ └── interfaces/ +β”‚ β”œβ”€β”€ tunnel/tunnel.go # Tunnel interface +β”‚ β”œβ”€β”€ tray/tray.go # Tray interface +β”‚ └── admin/admin.go # Admin API interface +β”‚ +└── docs/ + └── README.adoc # NEW: Textbook-style docs +``` + +--- + +## Implementation Phases + +### Phase 1: Documentation Foundation +**Files to create/modify:** +- `README.adoc` - New textbook-style documentation +- `docs/` - Reorganize scattered docs + +**README Structure (Textbook Style):** +``` +Chapter 1: Quick Start (5-minute setup) +Chapter 2: Installation (platform-specific) +Chapter 3: Configuration (all env vars) +Chapter 4: Operations (systemd, monitoring) +Chapter 5: Security (TLS, ACLs, policy) +Chapter 6: Advanced (Neo4j, clustering, WoT) +Chapter 7: Architecture (internals) +Appendices: Reference tables, troubleshooting +``` + +### Phase 2: Admin API +**Files to create:** +- `pkg/admin/api.go` - Router and middleware +- `pkg/admin/status.go` - Status endpoint +- `pkg/admin/control.go` - Start/stop/restart +- `pkg/admin/logs.go` - Log streaming via SSE +- `pkg/interfaces/admin/admin.go` - Interface definition + +**Files to modify:** +- `app/server.go` - Register `/api/admin/*` routes +- `app/config/config.go` - Add admin API config + +**Endpoints:** +``` +GET /api/admin/status - Relay status, uptime, connections +POST /api/admin/start - Start relay (when in tray mode) +POST /api/admin/stop - Graceful shutdown +POST /api/admin/restart - Graceful restart +GET /api/admin/logs - SSE log stream +``` + +### Phase 3: System Tray +**Files to create:** +- `pkg/tray/tray.go` - Platform abstraction +- `pkg/tray/tray_linux.go` - Linux (dbus/appindicator) +- `pkg/tray/tray_darwin.go` - macOS (NSStatusBar) +- `pkg/tray/menu.go` - Menu construction +- `pkg/interfaces/tray/tray.go` - Interface + +**Files to modify:** +- `main.go` - Add `--tray` flag handling +- `app/config/config.go` - Add tray config + +**Features:** +- Status icon (green/yellow/red) +- Start/Stop/Restart menu items +- Open Web UI (launches browser) +- View Logs submenu +- Auto-start on login toggle + +### Phase 4: Installer GUI (Wails) +**Files to create:** +- `cmd/orly-setup/main.go` - Wails entry point +- `cmd/orly-setup/app.go` - Backend methods +- `cmd/orly-setup/frontend/` - Svelte wizard +- `cmd/orly-setup/install/preflight.go` - Dependency checks +- `cmd/orly-setup/install/systemd.go` - Service creation +- `cmd/orly-setup/install/config.go` - Config generation +- `cmd/orly-setup/install/verify.go` - Post-install checks +- `scripts/build-installer.sh` - Build script + +**Wizard Steps:** +1. Welcome - Introduction, license +2. Preflight - Check Go, disk, ports +3. Configuration - Port, data dir, TLS domains +4. Admin Setup - Generate or import admin keys +5. Database - Choose Badger or Neo4j +6. WireGuard (optional) - Tunnel config +7. Installation - Create service, start relay +8. Complete - Verify and show status + +### Phase 5: WireGuard Client +**Files to create:** +- `pkg/tunnel/tunnel.go` - Main interface +- `pkg/tunnel/client.go` - wireguard-go wrapper +- `pkg/tunnel/config.go` - WG configuration +- `pkg/tunnel/reconnect.go` - Auto-reconnect logic +- `pkg/tunnel/health.go` - Health monitoring +- `pkg/tunnel/handoff.go` - Graceful restart +- `pkg/interfaces/tunnel/tunnel.go` - Interface + +**Files to modify:** +- `app/config/config.go` - Add WG config fields +- `app/main.go` - Initialize tunnel on startup +- `main.go` - Tunnel lifecycle management + +**Config additions:** +```go +WGEnabled bool `env:"ORLY_WG_ENABLED" default:"false"` +WGServer string `env:"ORLY_WG_SERVER"` +WGPrivateKey string `env:"ORLY_WG_PRIVATE_KEY"` +WGServerPubKey string `env:"ORLY_WG_PUBLIC_KEY"` +WGKeepalive int `env:"ORLY_WG_KEEPALIVE" default:"25"` +WGMTU int `env:"ORLY_WG_MTU" default:"1280"` +WGReconnect bool `env:"ORLY_WG_RECONNECT" default:"true"` +``` + +### Phase 6: Proxy Server +**Files to create:** +- `cmd/proxy-server/main.go` - Entry point +- `cmd/proxy-server/server.go` - WG server management +- `cmd/proxy-server/auth.go` - Nostr-based auth +- `cmd/proxy-server/registry.go` - User/relay registry +- `cmd/proxy-server/bandwidth.go` - Traffic monitoring +- `cmd/proxy-server/config.go` - Server configuration + +**Features:** +- WireGuard server (wireguard-go) +- Nostr event-based authentication (NIP-98 style) +- User registration via signed events +- Relay discovery and assignment +- Bandwidth monitoring and quotas +- Multi-tenant isolation + +--- + +## Key Interfaces + +### Tunnel Interface +```go +type Tunnel interface { + Connect(ctx context.Context) error + Disconnect() error + Status() TunnelStatus + Handoff() (*HandoffState, error) + Resume(state *HandoffState) error +} +``` + +### Admin API Interface +```go +type AdminAPI interface { + Status() (*RelayStatus, error) + Start() error + Stop() error + Restart() error + Logs(ctx context.Context, lines int) (<-chan LogEntry, error) +} +``` + +### Tray Interface +```go +type TrayApp interface { + Run() error + Quit() + UpdateStatus(status StatusLevel, tooltip string) + ShowNotification(title, message string) +} +``` + +--- + +## Dependencies to Add + +```go +// go.mod additions +require ( + github.com/wailsapp/wails/v2 v2.x.x // Installer GUI + golang.zx2c4.com/wireguard v0.x.x // WireGuard client + github.com/getlantern/systray v1.x.x // System tray (or fyne.io/systray) +) +``` + +--- + +## Build Commands + +```bash +# Standard relay build (unchanged) +CGO_ENABLED=0 go build -o orly + +# Relay with tray support +CGO_ENABLED=0 go build -tags tray -o orly + +# Installer GUI +cd cmd/orly-setup && wails build -platform linux/amd64,darwin/amd64 + +# Proxy server +CGO_ENABLED=0 go build -o orly-proxy ./cmd/proxy-server + +# All platforms +./scripts/build-all.sh +``` + +--- + +## Critical Files Reference + +| File | Purpose | +|------|---------| +| `app/config/config.go` | Add WG, tray, admin API config | +| `app/server.go` | Register admin API routes | +| `main.go` | Add --tray flag, WG initialization | +| `scripts/deploy.sh` | Pattern for installer service creation | +| `app/web/src/App.svelte` | Pattern for installer UI | + +--- + +## Backward Compatibility + +- Main `orly` binary behavior unchanged without flags +- All new features opt-in via environment variables +- WireGuard gracefully degrades if connection fails +- Tray mode only activates with `--tray` flag +- Admin API can be disabled via `ORLY_ADMIN_API_ENABLED=false` + +--- + +## Success Criteria + +1. New user can install via GUI wizard in < 5 minutes +2. README guides user from zero to running relay +3. System tray provides one-click relay management +4. WireGuard tunnel auto-connects and reconnects +5. Proxy server enables home relay exposure without port forwarding +6. All existing functionality preserved diff --git a/pkg/version/version b/pkg/version/version index 9a71172..56facb1 100644 --- a/pkg/version/version +++ b/pkg/version/version @@ -1 +1 @@ -v0.35.4 +v0.35.5