Add Plugin API v3.6.0 config reload support

Implement the Config Reload request/response pair from Plugin API v3.6.0
(Launcher v2.19.0), allowing the Launcher to request plugins to reload
their configuration at runtime without restarting.

Wire protocol:
- Message type 202 for both request and response
- Response includes errorType (enum) and errorMessage (string)
- Non-streaming request-response pattern

SDK changes:
- Add ConfigReloadErrorType enum with Unknown/None/Load/Validate/Save
- Add ConfigReloadRequest/ConfigReloadResponse protocol types
- Add ConfigReloadablePlugin optional interface (ReloadConfig method)
- Add ConfigReloadError type for classified error reporting
- Auto-respond with success for plugins that don't implement the interface
- Export RequestFromJSON for test access to protocol deserialization

Testing:
- Protocol serialization/deserialization tests
- Handler dispatch tests (not implemented, success, typed error,
  plain error, wrapped error)
- ConfigReloadErrorType.String() tests
- Mock ResponseWriter support for config reload

Documentation:
- Update version references (v3.5 → v3.6) across docs
- Add configuration reloading section to GUIDE.md
- Update CHANGELOG.md with feature description

Author: dmortondev

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Go SDK for building Launcher plugins that integrate job schedulers (Slurm, Kubernetes, PBS, cloud platforms, etc.) with Posit Workbench and Posit Connect. Implements Launcher Plugin API v3.5.0.
+Go SDK for building Launcher plugins that integrate job schedulers (Slurm, Kubernetes, PBS, cloud platforms, etc.) with Posit Workbench and Posit Connect. Implements Launcher Plugin API v3.6.0.
 
 **Language:** Go 1.24+
 **License:** MIT

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Plugin API 3.6.0**: Config reload support. The Launcher can now request plugins to reload configuration at runtime without restarting.
+  - `ConfigReloadablePlugin` optional interface in `launcher` package — plugins implement `ReloadConfig(ctx context.Context) error` to handle reload requests
+  - `ConfigReloadError` type for classified reload failures (Load, Validate, Save)
+  - `ConfigReloadErrorType` enum in `api` package with `String()` method
+  - Plugins that do not implement `ConfigReloadablePlugin` automatically send a success response
+  - `MockResponseWriter.WriteConfigReload` and `ConfigReloadResult` in `plugintest` for testing reload implementations
+- Protocol support for config reload request/response (message type 202) in `internal/protocol`
+- Exported `protocol.RequestFromJSON` for use in handler tests
+- Unit tests for `internal/protocol` and `launcher` packages
+
 ### Changed
 - **BREAKING**: `cache.NewJobCache` no longer accepts a `dir` parameter. The SDK now defaults to in-memory caching, which aligns with how Launcher plugins are expected to work: the scheduler owns job state, and plugins populate the cache during `Bootstrap()` and keep it in sync via periodic polling.
 - **BREAKING**: Add `context.Context` as the first parameter to all non-streaming `Plugin` methods (`SubmitJob`, `GetJob`, `GetJobs`, `ControlJob`, `GetJobNetwork`, `ClusterInfo`) and extension interfaces (`Bootstrap`, `GetClusters`). Streaming methods already accepted context.

README.md

@@ -22,7 +22,7 @@ The Launcher Go SDK provides a complete framework for building plugins that conn
 - Conformance testing - Automated behavioral tests that verify your plugin against Posit product contracts
 - Testing utilities - Mock response writers, job builders, and assertion helpers
 - Comprehensive examples - In-memory example and scheduler design guide
-- Type-safe API - Strongly typed interfaces matching the Launcher Plugin API v3.5
+- Type-safe API - Strongly typed interfaces matching the Launcher Plugin API v3.6
 
 ## Quick start
 
@@ -182,7 +182,7 @@ func TestSubmitJob(t *testing.T) {
 
 ## API version
 
-This SDK implements **Launcher Plugin API v3.5.0**.
+This SDK implements **Launcher Plugin API v3.6.0**.
 
 ## Stability
 

api/types.go

@@ -835,7 +835,41 @@ type Version struct {
 
 // APIVersion is the Launcher plugin API version supported by the types defined
 // in this package.
-var APIVersion = Version{Major: 3, Minor: 5, Patch: 0}
+var APIVersion = Version{Major: 3, Minor: 6, Patch: 0}
+
+// ConfigReloadErrorType classifies config reload errors.
+type ConfigReloadErrorType int
+
+const (
+	// ReloadErrorUnknown indicates an unclassified reload error.
+	ReloadErrorUnknown ConfigReloadErrorType = -1
+	// ReloadErrorNone indicates the reload succeeded.
+	ReloadErrorNone ConfigReloadErrorType = 0
+	// ReloadErrorLoad indicates an error loading configuration files.
+	ReloadErrorLoad ConfigReloadErrorType = 1
+	// ReloadErrorValidate indicates a validation error in the configuration.
+	ReloadErrorValidate ConfigReloadErrorType = 2
+	// ReloadErrorSave indicates an error saving configuration state.
+	ReloadErrorSave ConfigReloadErrorType = 3
+)
+
+// String returns a human-readable description of the error type.
+func (e ConfigReloadErrorType) String() string {
+	switch e {
+	case ReloadErrorUnknown:
+		return "unknown error"
+	case ReloadErrorNone:
+		return "none"
+	case ReloadErrorLoad:
+		return "load error"
+	case ReloadErrorValidate:
+		return "validation error"
+	case ReloadErrorSave:
+		return "save error"
+	default:
+		return "unknown error"
+	}
+}
 
 // Parsing errors.
 var (

api/types_test.go

@@ -173,6 +173,30 @@ func TestErrCode_String(t *testing.T) {
 	}
 }
 
+func TestConfigReloadErrorType_String(t *testing.T) {
+	tests := []struct {
+		name string
+		code ConfigReloadErrorType
+		want string
+	}{
+		{"unknown", ReloadErrorUnknown, "unknown error"},
+		{"none", ReloadErrorNone, "none"},
+		{"load", ReloadErrorLoad, "load error"},
+		{"validate", ReloadErrorValidate, "validation error"},
+		{"save", ReloadErrorSave, "save error"},
+		{"invalid value", ConfigReloadErrorType(99), "unknown error"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := tt.code.String()
+			if got != tt.want {
+				t.Errorf("String() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestJobID(t *testing.T) {
 	// Test that JobID is a distinct type
 	var id JobID = "test-123"

docs/API.md

@@ -509,7 +509,7 @@ Container image configuration.
 
 Import path: `github.com/posit-dev/launcher-go-sdk/api`
 
-The api package contains all type definitions matching the Launcher Plugin API v3.5.
+The api package contains all type definitions matching the Launcher Plugin API v3.6.
 
 ### Type: Job
 

docs/ARCHITECTURE.md

@@ -98,7 +98,7 @@ type DefaultOptions struct { /* ... */ }
 
 #### `api` - Type Definitions
 
-Contains all types matching the Launcher Plugin API v3.5:
+Contains all types matching the Launcher Plugin API v3.6:
 
 ```go
 type Job struct { /* 30+ fields */ }

docs/GUIDE.md

@@ -977,6 +977,36 @@ func (p *MyPlugin) SyncNodes(nodes []api.Node) {
 }
 ```
 
+### Configuration reloading
+
+The Launcher can ask plugins to reload their configuration at runtime without restarting (API v3.6.0+). At minimum, plugins should reload user profiles and resource profiles. Reloading additional configuration is permitted but not required.
+
+Implement `ConfigReloadablePlugin` to support this:
+
+```go
+func (p *MyPlugin) ReloadConfig(ctx context.Context) error {
+    profiles, err := loadProfiles(p.profilePath)
+    if err != nil {
+        return &launcher.ConfigReloadError{
+            Type:    api.ReloadErrorLoad,
+            Message: fmt.Sprintf("failed to load profiles: %v", err),
+        }
+    }
+    if err := profiles.Validate(); err != nil {
+        return &launcher.ConfigReloadError{
+            Type:    api.ReloadErrorValidate,
+            Message: fmt.Sprintf("invalid profiles: %v", err),
+        }
+    }
+    p.mu.Lock()
+    p.profiles = profiles
+    p.mu.Unlock()
+    return nil
+}
+```
+
+Plugins that do not implement this interface automatically send a success response. Error types help the Launcher classify failures: `ReloadErrorLoad` for file read errors, `ReloadErrorValidate` for invalid configuration, and `ReloadErrorSave` for errors persisting state. Returning a plain `error` (instead of `*ConfigReloadError`) defaults to `ReloadErrorUnknown`.
+
 ### User profiles
 
 System administrators may want to set default or maximum values for certain features on a per-user or per-group basis. For example, different groups of users could have different memory limits or CPU counts.

internal/protocol/rpc.go

@@ -20,7 +20,9 @@ type Request interface {
 	Type() int
 }
 
-func requestFromJSON(buf []byte) (Request, error) {
+// RequestFromJSON parses a JSON-encoded request message into the appropriate
+// concrete request type.
+func RequestFromJSON(buf []byte) (Request, error) {
 	var base BaseRequest
 	if err := json.Unmarshal(buf, &base); err != nil {
 		return nil, fmt.Errorf("%w: %v", ErrMsgInvalid, err) //nolint:errorlint // intentionally wrapping only the sentinel error
@@ -75,6 +77,8 @@ func requestForType(rt requestType) (interface{}, error) {
 		return &MultiClusterInfoRequest{}, nil
 	case requestSetLoadBalancerNodes:
 		return &SetLoadBalancerNodesRequest{}, nil
+	case requestConfigReload:
+		return &ConfigReloadRequest{}, nil
 	default:
 		return nil, fmt.Errorf("%w: %d", ErrUnknownRequestType, rt)
 	}
@@ -95,6 +99,7 @@ const (
 	requestClusterInfo
 	requestMultiClusterInfo     requestType = 17
 	requestSetLoadBalancerNodes requestType = 201
+	requestConfigReload         requestType = 202
 )
 
 // BaseRequest contains base fields shared by all request types.
@@ -207,6 +212,11 @@ type MultiClusterInfoRequest struct {
 	BaseUserRequest
 }
 
+// ConfigReloadRequest is the config reload request.
+type ConfigReloadRequest struct {
+	BaseUserRequest
+}
+
 type responseType int
 
 const (
@@ -222,6 +232,7 @@ const (
 	responseClusterInfo
 	responseMultiClusterInfo     responseType = 17
 	responseSetLoadBalancerNodes responseType = 201
+	responseConfigReload         responseType = 202
 )
 
 type responseBase struct {
@@ -440,3 +451,16 @@ func NewSetLoadBalancerNodesResponse(requestID, responseID uint64) *SetLoadBalan
 		responseSetLoadBalancerNodes, requestID, responseID,
 	}
 }
+
+// ConfigReloadResponse is the config reload response.
+type ConfigReloadResponse struct {
+	responseBase
+	ErrorType    api.ConfigReloadErrorType `json:"errorType"`
+	ErrorMessage string                    `json:"errorMessage"`
+}
+
+// NewConfigReloadResponse creates a new config reload response.
+func NewConfigReloadResponse(requestID, responseID uint64, errorType api.ConfigReloadErrorType, errorMessage string) *ConfigReloadResponse {
+	base := responseBase{responseConfigReload, requestID, responseID}
+	return &ConfigReloadResponse{responseBase: base, ErrorType: errorType, ErrorMessage: errorMessage}
+}

internal/protocol/rpc_test.go

@@ -0,0 +1,98 @@
+package protocol
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/posit-dev/launcher-go-sdk/api"
+)
+
+func TestRequestFromJSON_ConfigReload(t *testing.T) {
+	input := `{"messageType": 202, "requestId": 42, "requestUsername": "admin", "username": "testuser"}`
+
+	req, err := RequestFromJSON([]byte(input))
+	if err != nil {
+		t.Fatalf("RequestFromJSON() error = %v", err)
+	}
+
+	cr, ok := req.(*ConfigReloadRequest)
+	if !ok {
+		t.Fatalf("expected *ConfigReloadRequest, got %T", req)
+	}
+
+	if cr.ID() != 42 {
+		t.Errorf("ID() = %d, want 42", cr.ID())
+	}
+	if cr.Username != "testuser" {
+		t.Errorf("Username = %q, want %q", cr.Username, "testuser")
+	}
+	if cr.ReqUsername != "admin" {
+		t.Errorf("ReqUsername = %q, want %q", cr.ReqUsername, "admin")
+	}
+}
+
+func TestNewConfigReloadResponse_Success(t *testing.T) {
+	resp := NewConfigReloadResponse(42, 7, api.ReloadErrorNone, "")
+
+	data, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	var got map[string]interface{}
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+
+	if mt := int(got["messageType"].(float64)); mt != 202 {
+		t.Errorf("messageType = %d, want 202", mt)
+	}
+	if rid := uint64(got["requestId"].(float64)); rid != 42 {
+		t.Errorf("requestId = %d, want 42", rid)
+	}
+	if resID := uint64(got["responseId"].(float64)); resID != 7 {
+		t.Errorf("responseId = %d, want 7", resID)
+	}
+	if et := int(got["errorType"].(float64)); et != 0 {
+		t.Errorf("errorType = %d, want 0", et)
+	}
+	if em := got["errorMessage"].(string); em != "" {
+		t.Errorf("errorMessage = %q, want empty", em)
+	}
+}
+
+func TestNewConfigReloadResponse_ErrorTypes(t *testing.T) {
+	tests := []struct {
+		name      string
+		errorType api.ConfigReloadErrorType
+		wantCode  int
+	}{
+		{"Unknown", api.ReloadErrorUnknown, -1},
+		{"Load", api.ReloadErrorLoad, 1},
+		{"Validate", api.ReloadErrorValidate, 2},
+		{"Save", api.ReloadErrorSave, 3},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			resp := NewConfigReloadResponse(10, 3, tt.errorType, "error msg")
+
+			data, err := json.Marshal(resp)
+			if err != nil {
+				t.Fatalf("json.Marshal() error = %v", err)
+			}
+
+			var got map[string]interface{}
+			if err := json.Unmarshal(data, &got); err != nil {
+				t.Fatalf("json.Unmarshal() error = %v", err)
+			}
+
+			if et := int(got["errorType"].(float64)); et != tt.wantCode {
+				t.Errorf("errorType = %d, want %d", et, tt.wantCode)
+			}
+			if em := got["errorMessage"].(string); em != "error msg" {
+				t.Errorf("errorMessage = %q, want %q", em, "error msg")
+			}
+		})
+	}
+}