network

Documentation

Overview

Package network hosts `olares-cli settings network`. Mirrors the SPA's Settings -> Network page (Reverse Proxy, FRP, External Network, SSL, Hosts File). The wire formats here come from two backends:

1. user-service /api/network.controller.ts → BFL endpoints under /bfl/settings/v1alpha1/... Some handlers (`/api/reverse-proxy`, `/api/external-network`, `/api/launcher-public-domain-access-policy`) forward `data.data` verbatim to the client, leaving the BFL envelope intact. Others (`/api/frp-servers`) wrap with `returnSucceed(...)` — also a BFL-shaped envelope. Either way, the CLI sees a uniform {code, message, data} response and uses doGetEnvelope.

2. user-service /api/terminusd.controller.ts → /system/* on the olaresd daemon. Same outer BFL envelope (returnSucceed of the daemon's data.data).

We deliberately keep a per-area common.go (matching settings/me, settings/users, settings/apps, settings/vpn) instead of pulling a shared package — each area's response decoder can drift independently without leaking abstractions across areas.

Package network implements the `olares-cli settings network` subtree (Settings -> Network). Backed by user-service's bfl/network.controller.ts for reverse-proxy / FRP / external-network / SSL, plus terminusd.controller.ts for the hosts-file slice.

Index

• func NewExternalNetworkCommand(f *cmdutil.Factory) *cobra.Command
• func NewFRPCommand(f *cmdutil.Factory) *cobra.Command
• func NewHostsFileCommand(f *cmdutil.Factory) *cobra.Command
• func NewNetworkCommand(f *cmdutil.Factory) *cobra.Command
• func NewReverseProxyCommand(f *cmdutil.Factory) *cobra.Command
• func NewSSLCommand(f *cmdutil.Factory) *cobra.Command
• type Doer
• type Format

Functions

func NewExternalNetworkCommand

func NewExternalNetworkCommand(f *cmdutil.Factory) *cobra.Command

`olares-cli settings network external-network ...`

Backed by user-service's /api/external-network, which forwards /bfl/settings/v1alpha1/external-network. The body is BFL's ExternalNetworkSwitchView:

{
  "spec":   { "disabled": <bool> },
  "status": { "phase": "...", "message": "...", "updatedAt": "RFC3339" }
}

Only the read verb is in scope today; the matching write requires a JWS-signed device-id header on the BFL side and is owner-only.

func NewFRPCommand

func NewFRPCommand(f *cmdutil.Factory) *cobra.Command

`olares-cli settings network frp ...`

Backed by user-service's /api/frp-servers, which proxies the upstream Olares-tunnel registry (FRP_LIST_URL/servers). The wire shape is a BFL envelope wrapping an array of `{name, host}`:

{ "code": 0, "message": "success", "data": [{"name":"...", "host":"..."}, ...] }

Only `list` is in scope here; the v2 endpoint (POST /api/frp-servers-v2) is locale/userName-aware and the SPA only uses it to drive a select dropdown — there's no stable scripting use case for it yet.

func NewHostsFileCommand

func NewHostsFileCommand(f *cmdutil.Factory) *cobra.Command

`olares-cli settings network hosts-file ...`

Backed by user-service's /api/system/hosts-file, which proxies the olaresd daemon's /system/hosts-file. The wire shape (after returnSucceed wraps the daemon body) is a BFL envelope around an array of `{ip, host}`:

{ "code": 0, "message": "success", "data": [{"ip":"...", "host":"..."}, ...] }

The daemon side is JWS-signed: when the SPA hits this endpoint it also passes an X-Signature header; without one, user-service falls back to the access token (see olaresd/utils.ts). The CLI sends only X-Authorization, so this verb works as long as olaresd accepts authorization-header callers — if a future release tightens that, we'll have to surface a JWS-signing path here.

func NewNetworkCommand

func NewNetworkCommand(f *cmdutil.Factory) *cobra.Command

NewNetworkCommand returns the `settings network` parent: read-only inspection of every sub-area plus the reverse-proxy mode write. The remaining mutating endpoints require a JWS-signed device-id header the CLI doesn't yet produce, so they're out of scope today.

func NewReverseProxyCommand

func NewReverseProxyCommand(f *cmdutil.Factory) *cobra.Command

`olares-cli settings network reverse-proxy ...`

Backed by user-service's /api/reverse-proxy, which forwards /bfl/settings/v1alpha1/reverse-proxy. The shape is BFL's ReverseProxyConfig embedding FRPConfig:

{
  "frp_server": "...", "frp_port": 7000,
  "frp_auth_method": "token", "frp_auth_token": "***",
  "ip": "1.2.3.4",
  "enable_cloudflare_tunnel": false,
  "enable_frp": true,
  "external_network_off": false   // owner-only flag, surface only
}

`set --mode <mode>` writes the same struct back, with field-level overrides for FRP / public-IP modes.

func NewSSLCommand

func NewSSLCommand(f *cmdutil.Factory) *cobra.Command

`olares-cli settings network ssl ...`

Backed by user-service's /api/ssl/task-state, which forwards /bfl/settings/v1alpha1/ssl/task-state. The body is a BFL envelope around `{state: <int>}`. The state code maps as the SPA does it (see Mobile/connect/activate/CheckNetwork.vue):

1  Pending
2  Running
3  Failed
4  Succeeded
5  CheckL4Proxy
6  CheckFrpAgent
7  GenerateCert
8  ConfigureIngressHTTPs
9  CheckTunnel

Types

type Doer

type Doer interface {
	DoJSON(ctx context.Context, method, path string, body, out interface{}) error
}

Doer is the smallest contract verbs need from the underlying HTTP client. *whoami.HTTPClient satisfies it; tests can supply a fake.

type Format

type Format string

const (
	FormatTable Format = "table"
	FormatJSON  Format = "json"
)