Merge pull request #33 from litencatt/do-not-assign-reserved-port-numbers

Do not assign reserved port numbers

Author: harakeishi

README.md

@@ -88,19 +88,25 @@ gopose up --port-range 9000-9999
 gopose up --port-range 8000-8999,9000-9999
 ```
 
-#### Exclusion Settings
+#### Reserved Ports Configuration
 
 ```bash
-# Exclude specific services
-gopose up --exclude-services redis,postgres
+# Reserve specific ports (will never be assigned even if unused)
+# Use configuration file for persistent settings
+```
 
-# Exclude privileged ports
-gopose up --exclude-privileged
+You can reserve specific ports in `.gopose.yaml` to prevent them from being assigned:
 
-# Exclude reserved ports
-gopose up --exclude-ports 8080,8443,9000
+```yaml
+port:
+  reserved: [8080, 8443, 9000, 9090]  # These ports will never be assigned
 ```
 
+**Important**: Reserved ports are guaranteed to be skipped during port allocation, regardless of whether they are currently in use or not. This is useful for:
+- Preventing conflicts with services you plan to start later
+- Reserving ports for manual debugging or testing
+- Avoiding specific ports that may be used by other tools or services
+
 #### Output and Logging Settings
 
 ```bash
@@ -129,6 +135,8 @@ port:
   range:
     start: 8000
     end: 9999
+  # Reserved ports: These ports will NEVER be assigned, even if they are not in use
+  # Useful for preventing conflicts with services you plan to start later
   reserved: [8080, 8443, 9000, 9090]
   exclude_privileged: true
 
@@ -152,6 +160,16 @@ resolver:
   port_proximity: true
 ```
 
+#### Configuration Priority
+
+Configuration settings are applied in the following order (later values override earlier ones):
+
+1. Default configuration (built-in)
+2. Configuration file (`.gopose.yaml`)
+3. CLI options (e.g., `--port-range`)
+
+**Note**: Reserved ports from the configuration file are always preserved, even when using CLI options to override the port range.
+
 ### Output Example
 
 ```
@@ -241,6 +259,62 @@ time=2025-06-10T23:31:03.780+09:00 level=INFO msg="Docker Composeを実行" comp
 Attaching to web-1
 ```
 
+## Reserved Ports
+
+The `reserved` configuration allows you to specify ports that should never be assigned by gopose, regardless of whether they are currently in use.
+
+### Use Cases
+
+- **Future services**: Reserve ports for services you plan to start later
+- **Manual debugging**: Keep specific ports available for manual testing
+- **External tools**: Avoid conflicts with ports used by other development tools
+- **Consistency**: Ensure certain ports remain free across different environments
+
+### Example Configuration
+
+```yaml
+# .gopose.yaml
+port:
+  range:
+    start: 8000
+    end: 8100
+  reserved:
+    - 8080  # Reserved for main application
+    - 8443  # Reserved for HTTPS proxy
+    - 9000  # Reserved for debugging
+    - 9090  # Reserved for monitoring tools
+  exclude_privileged: true
+```
+
+### Behavior
+
+With the above configuration:
+- If gopose needs to assign ports for Docker Compose services with conflicts on ports 80 and 443
+- It will skip ports 8080, 8443, 9000, and 9090 (even if they are not in use)
+- Available ports like 8000-8079, 8081-8442, 8444-8999, 9001-9089, 9091-8100 will be considered
+- For example, ports 8000, 8001, etc. might be assigned instead
+
+### Testing Reserved Ports
+
+You can verify that reserved ports are working correctly:
+
+```bash
+# Create a test configuration
+cat > .gopose.yaml << EOF
+port:
+  range:
+    start: 8000
+    end: 8100
+  reserved: [8000, 8001, 8002, 8050]
+EOF
+
+# Run gopose - it will skip the reserved ports
+gopose up --dry-run
+
+# Check the generated compose.override.yml
+# You should see ports starting from 8003 (skipping 8000-8002)
+```
+
 ## Network Conflict Avoidance
 
 gopose automatically detects subnet conflicts with existing Docker networks and assigns safe alternative subnets.

README_JA.md

@@ -88,19 +88,25 @@ gopose up --port-range 9000-9999
 gopose up --port-range 8000-8999,9000-9999
 ```
 
-#### 除外設定
+#### 予約ポート設定
 
 ```bash
-# 特定のサービスを除外
-gopose up --exclude-services redis,postgres
+# 特定のポートを予約（未使用でも割り当てられません）
+# 永続的な設定には設定ファイルを使用します
+```
 
-# 特権ポートを除外
-gopose up --exclude-privileged
+`.gopose.yaml`で特定のポートを予約して、割り当てられないようにできます：
 
-# 予約ポートを除外
-gopose up --exclude-ports 8080,8443,9000
+```yaml
+port:
+  reserved: [8080, 8443, 9000, 9090]  # これらのポートは絶対に割り当てられません
 ```
 
+**重要**: 予約ポートは、現在使用中かどうかに関わらず、ポート割り当て時に確実にスキップされます。これは以下の用途に便利です：
+- 後で起動する予定のサービスとの衝突を防ぐ
+- 手動でのデバッグやテスト用にポートを確保
+- 他のツールやサービスが使用する可能性のある特定のポートを避ける
+
 #### 出力とログ設定
 
 ```bash
@@ -129,6 +135,8 @@ port:
   range:
     start: 8000
     end: 9999
+  # 予約ポート: これらのポートは未使用でも絶対に割り当てられません
+  # 後で起動する予定のサービスとの衝突を防ぐのに便利です
   reserved: [8080, 8443, 9000, 9090]
   exclude_privileged: true
 
@@ -152,6 +160,16 @@ resolver:
   port_proximity: true
 ```
 
+#### 設定の優先順位
+
+設定は以下の順序で適用されます（後のものが優先されます）：
+
+1. デフォルト設定（組み込み）
+2. 設定ファイル（`.gopose.yaml`）
+3. CLIオプション（例：`--port-range`）
+
+**注意**: 設定ファイルの予約ポートは、CLIオプションでポート範囲を上書きしても常に保持されます。
+
 ### 出力例
 
 ```
@@ -241,6 +259,62 @@ time=2025-06-10T23:31:03.780+09:00 level=INFO msg="Docker Composeを実行" comp
 Attaching to web-1
 ```
 
+## 予約ポート機能
+
+`reserved`設定を使用すると、現在使用中かどうかに関わらず、goposeが絶対に割り当ててはいけないポートを指定できます。
+
+### ユースケース
+
+- **将来のサービス**: 後で起動する予定のサービス用にポートを予約
+- **手動デバッグ**: 手動テスト用に特定のポートを利用可能な状態に保つ
+- **外部ツール**: 他の開発ツールが使用するポートとの衝突を回避
+- **一貫性**: 異なる環境間で特定のポートを確実に空けておく
+
+### 設定例
+
+```yaml
+# .gopose.yaml
+port:
+  range:
+    start: 8000
+    end: 8100
+  reserved:
+    - 8080  # メインアプリケーション用に予約
+    - 8443  # HTTPSプロキシ用に予約
+    - 9000  # デバッグ用に予約
+    - 9090  # 監視ツール用に予約
+  exclude_privileged: true
+```
+
+### 動作
+
+上記の設定では：
+- goposeがポート80と443で衝突があるDocker Composeサービスにポートを割り当てる必要がある場合
+- ポート8080、8443、9000、9090は（未使用であっても）スキップされます
+- 8000-8079、8081-8442、8444-8999、9001-9089、9091-8100などの利用可能なポートが検討されます
+- 例えば、8000、8001などのポートが割り当てられる可能性があります
+
+### 予約ポートのテスト
+
+予約ポートが正しく動作していることを確認できます：
+
+```bash
+# テスト用設定を作成
+cat > .gopose.yaml << EOF
+port:
+  range:
+    start: 8000
+    end: 8100
+  reserved: [8000, 8001, 8002, 8050]
+EOF
+
+# goposeを実行 - 予約ポートがスキップされます
+gopose up --dry-run
+
+# 生成されたcompose.override.ymlを確認
+# 8003から始まるポートが表示されるはずです（8000-8002はスキップ）
+```
+
 ## ネットワーク衝突回避機能
 
 goposeは既存のDockerネットワークとのサブネット衝突を自動検出し、安全な代替サブネットを割り当てます。

cmd/up.go

@@ -62,18 +62,19 @@ func parsePortRange(portRangeStr string) (types.PortRange, error) {
 	return types.PortRange{Start: start, End: end}, nil
 }
 
-// createPortConfig はCLIオプションからポート設定を作成します。
-func createPortConfig(portRangeStr string) (types.PortConfig, error) {
-	portRange, err := parsePortRange(portRangeStr)
-	if err != nil {
-		return types.PortConfig{}, err
+// createPortConfig はCLIオプションと設定ファイルからポート設定を作成します。
+// baseConfigをベースとして、portRangeStrが指定されている場合のみ範囲を上書きします。
+func createPortConfig(portRangeStr string, baseConfig types.PortConfig) (types.PortConfig, error) {
+	// CLIでポート範囲が指定されている場合のみ上書き
+	if portRangeStr != "" {
+		portRange, err := parsePortRange(portRangeStr)
+		if err != nil {
+			return types.PortConfig{}, err
+		}
+		baseConfig.Range = portRange
 	}
 
-	return types.PortConfig{
-		Range:             portRange,
-		Reserved:          []int{}, // 予約済みポートは空で開始
-		ExcludePrivileged: true,    // 特権ポートは除外
-	}, nil
+	return baseConfig, nil
 }
 
 // detectWorktreeProjectName は現在の git ワークツリーのトップレベルディレクトリ名を
@@ -144,8 +145,8 @@ var upCmd = &cobra.Command{
 			return fmt.Errorf("ロガーの初期化に失敗しました: %w", err)
 		}
 
-		// ポート範囲の解析
-		portConfig, err := createPortConfig(portRange)
+		// ポート設定の作成（設定ファイルの値をベースに、CLIオプションで上書き）
+		portConfig, err := createPortConfig(portRange, cfg.GetPort())
 		if err != nil {
 			return fmt.Errorf("ポート範囲の解析に失敗しました: %w", err)
 		}
@@ -165,7 +166,8 @@ var upCmd = &cobra.Command{
 			types.Field{Key: "output_file", Value: outputFile},
 			types.Field{Key: "project_name", Value: composeProjectName},
 			types.Field{Key: "strategy", Value: strategy},
-			types.Field{Key: "port_range", Value: fmt.Sprintf("%d-%d", portConfig.Range.Start, portConfig.Range.End)})
+			types.Field{Key: "port_range", Value: fmt.Sprintf("%d-%d", portConfig.Range.Start, portConfig.Range.End)},
+			types.Field{Key: "reserved_ports", Value: portConfig.Reserved})
 
 		// Docker Composeファイルの自動検出（指定されていない場合）
 		if filePath == "" || filePath == "compose.yml" {