feat: add lock and unlock client commands

Add "dutctl <device> lock [duration]" and "dutctl <device> unlock
[--force]" subcommands, plus a -u flag to set the lock owner identity
(defaults to user@host). The owner is sent on Run, Lock and Unlock via
the OwnerHeader. Lock duration defaults to 30m and must be positive.

Signed-off-by: Fabian Wienand <fabian.wienand@blindspot.software>

Author: RiSKeD

cmds/dutctl/dutctl.go

@@ -20,6 +20,7 @@ import (
 	"connectrpc.com/connect"
 	"github.com/BlindspotSoftware/dutctl/internal/buildinfo"
 	"github.com/BlindspotSoftware/dutctl/internal/output"
+	"github.com/BlindspotSoftware/dutctl/pkg/lock"
 	"github.com/BlindspotSoftware/dutctl/protobuf/gen/dutctl/v1/dutctlv1connect"
 	"golang.org/x/net/http2"
 )
@@ -32,6 +33,8 @@ SYNOPSIS:
 	dutctl [options] <device>
 	dutctl [options] <device> <command> [args...]
 	dutctl [options] <device> <command> help
+	dutctl [options] <device> lock [duration]
+	dutctl [options] <device> unlock
 	dutctl version
 
 `
@@ -42,16 +45,22 @@ The optional args are passed to the command.
 To list all available devices, use the list command. If only a device is provided,
 dutctl list all available commands for the device.
 
-If a device, a command and the keyword help are provided, dutctl will show usage 
+If a device, a command and the keyword help are provided, dutctl will show usage
 information for the command.
 
+The lock command reserves a device for the current user; the optional duration
+(e.g. 30m, 2h) defaults to 30m. The unlock command releases it; pass the -force
+option to release a lock held by another user.
+
 `
 
 const (
 	serverAddrInfo   = `Address and port of the dutagent to connect to in the format: address:port`
 	outputFormatInfo = `Output format, text|json|yaml|oneline, default is text`
 	verboseInfo      = `Verbose output`
 	noColorInfo      = `Disable colored output`
+	userInfo         = `User Identity of the user of the device, defaults to <user>@<host>`
+	forceInfo        = `Force unlock a device locked by another user`
 )
 
 func newApp(stdin io.Reader, stdout, stderr io.Writer, exitFunc func(int), args []string) *application {
@@ -78,6 +87,8 @@ func newApp(stdin io.Reader, stdout, stderr io.Writer, exitFunc func(int), args
 	fs.StringVar(&app.outputFormat, "f", "", outputFormatInfo)
 	fs.BoolVar(&app.verbose, "v", false, verboseInfo)
 	fs.BoolVar(&app.noColor, "no-color", false, noColorInfo)
+	fs.StringVar(&app.user, "u", lock.DefaultUser(), userInfo)
+	fs.BoolVar(&app.force, "force", false, forceInfo)
 
 	//nolint:errcheck // flag.Parse always returns no error because of flag.ExitOnError
 	fs.Parse(args[1:])
@@ -106,6 +117,8 @@ type application struct {
 	outputFormat      string
 	verbose           bool
 	noColor           bool
+	user              string
+	force             bool
 	args              []string
 	printFlagDefaults func()
 
@@ -177,6 +190,13 @@ func (app *application) start() {
 	command := app.args[1]
 	cmdArgs := app.args[2:]
 
+	switch command {
+	case "lock":
+		app.exit(app.lockRPC(device, cmdArgs))
+	case "unlock":
+		app.exit(app.unlockRPC(device))
+	}
+
 	if len(cmdArgs) > 0 && cmdArgs[0] == "help" {
 		err := app.detailsRPC(device, command, "help")
 		app.exit(err)

cmds/dutctl/rpc.go

@@ -14,9 +14,11 @@ import (
 	"log"
 	"os"
 	"strings"
+	"time"
 
 	"connectrpc.com/connect"
 	"github.com/BlindspotSoftware/dutctl/internal/output"
+	"github.com/BlindspotSoftware/dutctl/pkg/lock"
 
 	pb "github.com/BlindspotSoftware/dutctl/protobuf/gen/dutctl/v1"
 )
@@ -56,6 +58,86 @@ func (app *application) listRPC() error {
 	return nil
 }
 
+// defaultLockDuration is used when the user runs "lock" without a duration.
+const defaultLockDuration = 30 * time.Minute
+
+// parseLockDuration resolves the lock duration from the lock command's
+// arguments. An empty argument list yields defaultLockDuration. The duration
+// must be positive.
+func parseLockDuration(cmdArgs []string) (time.Duration, error) {
+	if len(cmdArgs) == 0 || cmdArgs[0] == "" {
+		return defaultLockDuration, nil
+	}
+
+	parsed, err := time.ParseDuration(cmdArgs[0])
+	if err != nil {
+		return 0, fmt.Errorf("invalid lock duration %q: %w", cmdArgs[0], err)
+	}
+
+	if parsed <= 0 {
+		return 0, fmt.Errorf("lock duration must be positive, got %q", cmdArgs[0])
+	}
+
+	return parsed, nil
+}
+
+func (app *application) lockRPC(device string, cmdArgs []string) error {
+	duration, err := parseLockDuration(cmdArgs)
+	if err != nil {
+		return err
+	}
+
+	ctx := context.Background()
+	req := connect.NewRequest(&pb.LockRequest{
+		Device:          device,
+		DurationSeconds: int64(duration.Seconds()),
+	})
+	req.Header().Set(lock.UserHeader, app.user)
+
+	res, err := app.rpcClient.Lock(ctx, req)
+	if err != nil {
+		return err
+	}
+
+	app.formatter.WriteContent(output.Content{
+		Type: output.TypeLockResult,
+		Data: output.DeviceEntry{
+			Name:      res.Msg.GetDevice(),
+			Locked:    true,
+			Owner:     res.Msg.GetOwner(),
+			ExpiresAt: res.Msg.GetExpiresAt(),
+		},
+		Metadata: map[string]string{
+			"server": app.serverAddr,
+			"msg":    "Lock Response",
+		},
+	})
+
+	return nil
+}
+
+func (app *application) unlockRPC(device string) error {
+	ctx := context.Background()
+	req := connect.NewRequest(&pb.UnlockRequest{Device: device, Force: app.force})
+	req.Header().Set(lock.UserHeader, app.user)
+
+	_, err := app.rpcClient.Unlock(ctx, req)
+	if err != nil {
+		return err
+	}
+
+	app.formatter.WriteContent(output.Content{
+		Type: output.TypeLockResult,
+		Data: output.DeviceEntry{Name: device},
+		Metadata: map[string]string{
+			"server": app.serverAddr,
+			"msg":    "Unlock Response",
+		},
+	})
+
+	return nil
+}
+
 func (app *application) commandsRPC(device string) error {
 	ctx := context.Background()
 	req := connect.NewRequest(&pb.CommandsRequest{Device: device})
@@ -116,6 +198,8 @@ func (app *application) runRPC(device, command string, cmdArgs []string) error {
 	errChan := make(chan error, numWorkers)
 
 	stream := app.rpcClient.Run(runCtx)
+	stream.RequestHeader().Set(lock.UserHeader, app.user)
+
 	req := &pb.RunRequest{
 		Msg: &pb.RunRequest_Command{
 			Command: &pb.Command{

cmds/dutctl/rpc_test.go

@@ -0,0 +1,77 @@
+// Copyright 2025 Blindspot Software
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"testing"
+	"time"
+)
+
+func TestParseLockDuration(t *testing.T) {
+	tests := []struct {
+		name    string
+		args    []string
+		want    time.Duration
+		wantErr bool
+	}{
+		{
+			name: "no args uses default",
+			args: nil,
+			want: defaultLockDuration,
+		},
+		{
+			name: "empty arg uses default",
+			args: []string{""},
+			want: defaultLockDuration,
+		},
+		{
+			name: "explicit minutes",
+			args: []string{"5m"},
+			want: 5 * time.Minute,
+		},
+		{
+			name: "explicit compound duration",
+			args: []string{"1h30m"},
+			want: 90 * time.Minute,
+		},
+		{
+			name:    "unparseable duration",
+			args:    []string{"banana"},
+			wantErr: true,
+		},
+		{
+			name:    "zero duration rejected",
+			args:    []string{"0s"},
+			wantErr: true,
+		},
+		{
+			name:    "negative duration rejected",
+			args:    []string{"-5m"},
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseLockDuration(tt.args)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got duration %v", got)
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if got != tt.want {
+				t.Errorf("duration = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}