feat: add support for the PROXY protocol

cmd/outline-ss-server/config.go

@@ -0,0 +1,143 @@
+// Copyright 2024 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/url"
+	"os"
+
+	"github.com/Jigsaw-Code/outline-ss-server/service"
+	"gopkg.in/yaml.v2"
+)
+
+type Service struct {
+	Listeners []Listener
+	Keys      []Key
+}
+
+type ListenerType string
+
+const (
+	listenerTypeDirect ListenerType = "direct"
+	listenerTypeProxy  ListenerType = "proxy_protocol"
+)
+
+type Listener struct {
+	Type    ListenerType
+	Address string
+}
+
+type Key struct {
+	ID     string
+	Cipher string
+	Secret string
+}
+
+type LegacyKeyService struct {
+	Key  `yaml:",inline"`
+	Port int
+}
+
+type Config struct {
+	Services []Service
+
+	// Deprecated: `keys` exists for backward compatibility. Prefer to configure
+	// using the newer `services` format.
+	Keys []LegacyKeyService
+}
+
+// readConfig attempts to read a config from a filename and parses it as a [Config].
+func readConfig(filename string) (*Config, error) {
+	config := Config{}
+	configData, err := os.ReadFile(filename)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read config: %w", err)
+	}
+	err = yaml.Unmarshal(configData, &config)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+	return &config, nil
+}
+
+// validateListener asserts that a listener URI conforms to the expected format.
+func validateListener(u *url.URL) error {
+	if u.Opaque != "" {
+		return errors.New("URI cannot have an opaque part")
+	}
+	if u.User != nil {
+		return errors.New("URI cannot have an userdata part")
+	}
+	if u.RawQuery != "" || u.ForceQuery {
+		return errors.New("URI cannot have a query part")
+	}
+	if u.Fragment != "" {
+		return errors.New("URI cannot have a fragement")
+	}
+	if u.Path != "" && u.Path != "/" {
+		return errors.New("URI path not allowed")
+	}
+	return nil
+}
+
+// newListener creates a new listener from a URL-style address specification.
+//
+// Example addresses:
+//
+//	tcp4://127.0.0.1:8000
+//	udp://127.0.0.1:9000
+func newListener(addr string) (io.Closer, error) {
+	u, err := url.Parse(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	switch u.Scheme {
+	case "tcp", "tcp4", "tcp6":
+		if err := validateListener(u); err != nil {
+			return nil, fmt.Errorf("invalid listener `%s`: %v", u, err)
+		}
+		return net.Listen(u.Scheme, u.Host)
+	case "udp", "udp4", "udp6":
+		if err := validateListener(u); err != nil {
+			return nil, fmt.Errorf("invalid listener `%s`: %v", u, err)
+		}
+		return net.ListenPacket(u.Scheme, u.Host)
+	default:
+		return nil, fmt.Errorf("unsupported protocol: %s", u.Scheme)
+	}
+}
+
+// Listen creates a new listener based on a given [Listener] config.
+func Listen(config Listener) (io.Closer, error) {
+	listener, err := newListener(config.Address)
+	if err != nil {
+		return nil, err
+	}
+	switch ln := listener.(type) {
+	case net.Listener:
+		streamListener := &service.StreamListener{Listener: ln}
+		if config.Type == listenerTypeProxy {
+			return &service.ProxyListener{StreamListener: *streamListener}, err
+		}
+		return streamListener, err
+	default:
+		return listener, err
+	}
+}

cmd/outline-ss-server/config_example.deprecated.yml

@@ -0,0 +1,15 @@
+keys:
+  - id: user-0
+    port: 9000
+    cipher: chacha20-ietf-poly1305
+    secret: Secret0
+
+  - id: user-1
+    port: 9000
+    cipher: chacha20-ietf-poly1305
+    secret: Secret1
+
+  - id: user-2
+    port: 9001
+    cipher: chacha20-ietf-poly1305
+    secret: Secret2

cmd/outline-ss-server/config_example.yml

@@ -1,15 +1,27 @@
-keys:
-  - id: user-0
-    port: 9000
-    cipher: chacha20-ietf-poly1305
-    secret: Secret0
+services:
+  - listeners:
+      - type: direct
+        address: "tcp://[::]:9000"
+      - type: direct
+        address: "udp://[::]:9000"
+      - type: proxy_protocol
+        address: "tcp://[::]:9010"
+      - type: proxy_protocol
+        address: "udp://[::]:9010"
+    keys:
+        - id: user-0
+          cipher: chacha20-ietf-poly1305
+          secret: Secret0
+        - id: user-1
+          cipher: chacha20-ietf-poly1305
+          secret: Secret1
 
-  - id: user-1
-    port: 9000
-    cipher: chacha20-ietf-poly1305
-    secret: Secret1
-
-  - id: user-2
-    port: 9001
-    cipher: chacha20-ietf-poly1305
-    secret: Secret2
+  - listeners:
+      - type: direct
+        address: "tcp://[::]:9001"
+      - type: direct
+        address: "udp://[::]:9001"
+    keys:
+        - id: user-2
+          cipher: chacha20-ietf-poly1305
+          secret: Secret2

cmd/outline-ss-server/config_test.go

@@ -0,0 +1,103 @@
+// Copyright 2024 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestReadConfig(t *testing.T) {
+	config, err := readConfig("./config_example.yml")
+
+	require.NoError(t, err)
+	expected := Config{
+		Services: []Service{
+			Service{
+				Listeners: []Listener{
+					Listener{Type: listenerTypeDirect, Address: "tcp://[::]:9000"},
+					Listener{Type: listenerTypeDirect, Address: "udp://[::]:9000"},
+					Listener{Type: listenerTypeProxy, Address: "tcp://[::]:9010"},
+					Listener{Type: listenerTypeProxy, Address: "udp://[::]:9010"},
+				},
+				Keys: []Key{
+					Key{"user-0", "chacha20-ietf-poly1305", "Secret0"},
+					Key{"user-1", "chacha20-ietf-poly1305", "Secret1"},
+				},
+			},
+			Service{
+				Listeners: []Listener{
+					Listener{Type: listenerTypeDirect, Address: "tcp://[::]:9001"},
+					Listener{Type: listenerTypeDirect, Address: "udp://[::]:9001"},
+				},
+				Keys: []Key{
+					Key{"user-2", "chacha20-ietf-poly1305", "Secret2"},
+				},
+			},
+		},
+	}
+	require.Equal(t, expected, *config)
+}
+
+func TestReadConfigParsesDeprecatedFormat(t *testing.T) {
+	config, err := readConfig("./config_example.deprecated.yml")
+
+	require.NoError(t, err)
+	expected := Config{
+		Keys: []LegacyKeyService{
+			LegacyKeyService{
+				Key:  Key{ID: "user-0", Cipher: "chacha20-ietf-poly1305", Secret: "Secret0"},
+				Port: 9000,
+			},
+			LegacyKeyService{
+				Key:  Key{ID: "user-1", Cipher: "chacha20-ietf-poly1305", Secret: "Secret1"},
+				Port: 9000,
+			},
+			LegacyKeyService{
+				Key:  Key{ID: "user-2", Cipher: "chacha20-ietf-poly1305", Secret: "Secret2"},
+				Port: 9001,
+			},
+		},
+	}
+	require.Equal(t, expected, *config)
+}
+
+func TestReadConfigFromEmptyFile(t *testing.T) {
+	file, _ := os.CreateTemp("", "empty.yaml")
+
+	config, err := readConfig(file.Name())
+
+	require.NoError(t, err)
+	require.ElementsMatch(t, Config{}, config)
+}
+
+func TestReadConfigFromNonExistingFileFails(t *testing.T) {
+	config, err := readConfig("./foo")
+
+	require.Error(t, err)
+	require.ElementsMatch(t, nil, config)
+}
+
+func TestReadConfigFromIncorrectFormatFails(t *testing.T) {
+	file, _ := os.CreateTemp("", "empty.yaml")
+	file.WriteString("foo")
+
+	config, err := readConfig(file.Name())
+
+	require.Error(t, err)
+	require.ElementsMatch(t, Config{}, config)
+}