feat: add WriteFile to FilesystemService, deprecate on client

Move the filesystem.file_receive API call implementation from the
transport layer (client.Client) to FilesystemService where it belongs
alongside Stat and SetPermissions.

The WriteFile method on FileCaller is marked deprecated — callers
should use FilesystemService.WriteFile instead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deevus

filesystem_service.go

@@ -2,6 +2,7 @@ package truenas
 
 import (
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 )
@@ -41,6 +42,36 @@ func (s *FilesystemService) Client() FileCaller {
 	return s.client
 }
 
+// WriteFile writes content to a file on the remote system via filesystem.file_receive.
+func (s *FilesystemService) WriteFile(ctx context.Context, path string, params WriteFileParams) error {
+	b64Content := base64.StdEncoding.EncodeToString(params.Content)
+
+	uid := -1
+	if params.UID != nil {
+		uid = *params.UID
+	}
+	gid := -1
+	if params.GID != nil {
+		gid = *params.GID
+	}
+
+	apiParams := []any{
+		path,
+		b64Content,
+		map[string]any{
+			"mode": int(params.Mode),
+			"uid":  uid,
+			"gid":  gid,
+		},
+	}
+
+	_, err := s.client.Call(ctx, "filesystem.file_receive", apiParams)
+	if err != nil {
+		return fmt.Errorf("write file %q: %w", path, err)
+	}
+	return nil
+}
+
 // Stat returns filesystem stat information for the given path.
 // Mode is masked with 0o777 to strip file type bits.
 func (s *FilesystemService) Stat(ctx context.Context, path string) (*StatResult, error) {

filesystem_service_iface.go

@@ -5,6 +5,7 @@ import "context"
 // FilesystemServiceAPI defines the interface for filesystem operations.
 type FilesystemServiceAPI interface {
 	Client() FileCaller
+	WriteFile(ctx context.Context, path string, params WriteFileParams) error
 	Stat(ctx context.Context, path string) (*StatResult, error)
 	SetPermissions(ctx context.Context, opts SetPermOpts) error
 }
@@ -16,6 +17,7 @@ var _ FilesystemServiceAPI = (*MockFilesystemService)(nil)
 // MockFilesystemService is a test double for FilesystemServiceAPI.
 type MockFilesystemService struct {
 	ClientFunc         func() FileCaller
+	WriteFileFunc      func(ctx context.Context, path string, params WriteFileParams) error
 	StatFunc           func(ctx context.Context, path string) (*StatResult, error)
 	SetPermissionsFunc func(ctx context.Context, opts SetPermOpts) error
 }
@@ -27,6 +29,13 @@ func (m *MockFilesystemService) Client() FileCaller {
 	return nil
 }
 
+func (m *MockFilesystemService) WriteFile(ctx context.Context, path string, params WriteFileParams) error {
+	if m.WriteFileFunc != nil {
+		return m.WriteFileFunc(ctx, path, params)
+	}
+	return nil
+}
+
 func (m *MockFilesystemService) Stat(ctx context.Context, path string) (*StatResult, error) {
 	if m.StatFunc != nil {
 		return m.StatFunc(ctx, path)

filesystem_service_test.go

@@ -15,6 +15,101 @@ func sampleFileStatJSON() json.RawMessage {
 	return json.RawMessage(`{"mode": 33188, "uid": 0, "gid": 0}`)
 }
 
+func TestFilesystemService_WriteFile(t *testing.T) {
+	mock := &mockFileCaller{
+		mockAsyncCaller: mockAsyncCaller{
+			mockCaller: mockCaller{
+				callFunc: func(ctx context.Context, method string, params any) (json.RawMessage, error) {
+					if method != "filesystem.file_receive" {
+						t.Errorf("expected method filesystem.file_receive, got %s", method)
+					}
+					args := params.([]any)
+					if args[0] != "/mnt/pool/test.txt" {
+						t.Errorf("expected path /mnt/pool/test.txt, got %v", args[0])
+					}
+					// Content should be base64-encoded "hello"
+					if args[1] != "aGVsbG8=" {
+						t.Errorf("expected base64 'aGVsbG8=', got %v", args[1])
+					}
+					opts := args[2].(map[string]any)
+					if opts["mode"] != int(0o644) {
+						t.Errorf("expected mode %d, got %v", int(0o644), opts["mode"])
+					}
+					if opts["uid"] != -1 {
+						t.Errorf("expected uid -1 (unset), got %v", opts["uid"])
+					}
+					if opts["gid"] != -1 {
+						t.Errorf("expected gid -1 (unset), got %v", opts["gid"])
+					}
+					return nil, nil
+				},
+			},
+		},
+	}
+
+	svc := NewFilesystemService(mock, Version{})
+	err := svc.WriteFile(context.Background(), "/mnt/pool/test.txt", WriteFileParams{
+		Content: []byte("hello"),
+		Mode:    0o644,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFilesystemService_WriteFile_WithUID(t *testing.T) {
+	mock := &mockFileCaller{
+		mockAsyncCaller: mockAsyncCaller{
+			mockCaller: mockCaller{
+				callFunc: func(ctx context.Context, method string, params any) (json.RawMessage, error) {
+					args := params.([]any)
+					opts := args[2].(map[string]any)
+					if opts["uid"] != 1000 {
+						t.Errorf("expected uid 1000, got %v", opts["uid"])
+					}
+					if opts["gid"] != 1000 {
+						t.Errorf("expected gid 1000, got %v", opts["gid"])
+					}
+					return nil, nil
+				},
+			},
+		},
+	}
+
+	svc := NewFilesystemService(mock, Version{})
+	uid, gid := 1000, 1000
+	err := svc.WriteFile(context.Background(), "/mnt/pool/test.txt", WriteFileParams{
+		Content: []byte("hello"),
+		Mode:    0o644,
+		UID:     &uid,
+		GID:     &gid,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFilesystemService_WriteFile_Error(t *testing.T) {
+	mock := &mockFileCaller{
+		mockAsyncCaller: mockAsyncCaller{
+			mockCaller: mockCaller{
+				callFunc: func(ctx context.Context, method string, params any) (json.RawMessage, error) {
+					return nil, errors.New("permission denied")
+				},
+			},
+		},
+	}
+
+	svc := NewFilesystemService(mock, Version{})
+	err := svc.WriteFile(context.Background(), "/mnt/pool/test.txt", WriteFileParams{
+		Content: []byte("hello"),
+		Mode:    0o644,
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
 func TestFilesystemService_Stat(t *testing.T) {
 	mock := &mockFileCaller{
 		mockAsyncCaller: mockAsyncCaller{

interfaces.go

@@ -22,6 +22,7 @@ type AsyncCaller interface {
 // Embeds AsyncCaller because filesystem.setperm is job-based.
 type FileCaller interface {
 	AsyncCaller
+	// Deprecated: Use FilesystemService.WriteFile instead.
 	WriteFile(ctx context.Context, path string, params WriteFileParams) error
 	ReadFile(ctx context.Context, path string) ([]byte, error)
 	DeleteFile(ctx context.Context, path string) error