Align scale-to-zero internal terminology with OpenAPI spec

Rename refcounted hold methods to Acquire/Release so that Disable/Enable
can carry the idempotent persistent-toggle semantics defined by the
/scaletozero/{disable,enable} API. Split the low-level direct toggle out
into a separate Toggler interface (unikraftCloudToggler) wrapped by
DebouncedController.

Author: sjmiller609

server/cmd/api/api/api.go

@@ -49,7 +49,7 @@ type ApiService struct {
 
 	// DevTools upstream manager (Chromium supervisord log tailer)
 	upstreamMgr *devtoolsproxy.UpstreamManager
-	stz         scaletozero.PinnedController
+	stz         scaletozero.Controller
 
 	// inputMu serializes input-related operations (mouse, keyboard, screenshot)
 	inputMu sync.Mutex
@@ -96,7 +96,7 @@ func New(
 	recordManager recorder.RecordManager,
 	factory recorder.FFmpegRecorderFactory,
 	upstreamMgr *devtoolsproxy.UpstreamManager,
-	stz scaletozero.PinnedController,
+	stz scaletozero.Controller,
 	nekoAuthClient *nekoclient.AuthClient,
 	captureSession *capturesession.CaptureSession,
 	eventStream    *events.EventStream,

server/cmd/api/api/scaletozero.go

@@ -8,15 +8,15 @@ import (
 )
 
 func (s *ApiService) DisableScaleToZero(ctx context.Context, _ oapi.DisableScaleToZeroRequestObject) (oapi.DisableScaleToZeroResponseObject, error) {
-	if err := s.stz.Pin(ctx); err != nil {
+	if err := s.stz.Disable(ctx); err != nil {
 		logger.FromContext(ctx).Error("failed to disable scale-to-zero", "err", err)
 		return oapi.DisableScaleToZero500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to disable scale-to-zero"}}, nil
 	}
 	return oapi.DisableScaleToZero204Response{}, nil
 }
 
 func (s *ApiService) EnableScaleToZero(ctx context.Context, _ oapi.EnableScaleToZeroRequestObject) (oapi.EnableScaleToZeroResponseObject, error) {
-	if err := s.stz.Unpin(ctx); err != nil {
+	if err := s.stz.Enable(ctx); err != nil {
 		logger.FromContext(ctx).Error("failed to enable scale-to-zero", "err", err)
 		return oapi.EnableScaleToZero500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{Message: "failed to enable scale-to-zero"}}, nil
 	}

server/cmd/api/main.go

@@ -51,7 +51,7 @@ func main() {
 	// ensure ffmpeg is available
 	mustFFmpeg()
 
-	stz := scaletozero.NewDebouncedControllerWithCooldown(scaletozero.NewUnikraftCloudController(), config.ScaleToZeroCooldown)
+	stz := scaletozero.NewDebouncedControllerWithCooldown(scaletozero.NewUnikraftCloudToggler(), config.ScaleToZeroCooldown)
 	r := chi.NewRouter()
 	r.Use(
 		chiMiddleware.Logger,

server/lib/recorder/ffmpeg.go

@@ -183,9 +183,9 @@ func (fr *FFmpegRecorder) Start(ctx context.Context) error {
 		return fmt.Errorf("recording already in progress")
 	}
 
-	if err := fr.stz.Disable(ctx); err != nil {
+	if err := fr.stz.Acquire(ctx); err != nil {
 		fr.mu.Unlock()
-		return fmt.Errorf("failed to disable scale-to-zero: %w", err)
+		return fmt.Errorf("failed to acquire scale-to-zero hold: %w", err)
 	}
 
 	// ensure internal state
@@ -196,7 +196,7 @@ func (fr *FFmpegRecorder) Start(ctx context.Context) error {
 
 	args, err := ffmpegArgs(fr.params, fr.outputPath)
 	if err != nil {
-		_ = fr.stz.Enable(context.WithoutCancel(ctx))
+		_ = fr.stz.Release(context.WithoutCancel(ctx))
 		fr.cmd = nil
 		close(fr.exited)
 		fr.mu.Unlock()
@@ -214,7 +214,7 @@ func (fr *FFmpegRecorder) Start(ctx context.Context) error {
 	fr.mu.Unlock()
 
 	if err := cmd.Start(); err != nil {
-		_ = fr.stz.Enable(context.WithoutCancel(ctx))
+		_ = fr.stz.Release(context.WithoutCancel(ctx))
 		fr.mu.Lock()
 		fr.ffmpegErr = err
 		fr.cmd = nil // reset cmd on failure to start so IsRecording() remains correct
@@ -238,7 +238,7 @@ func (fr *FFmpegRecorder) Start(ctx context.Context) error {
 
 // Stop gracefully stops the recording using a multi-phase shutdown process.
 func (fr *FFmpegRecorder) Stop(ctx context.Context) error {
-	defer fr.stz.Enable(context.WithoutCancel(ctx))
+	defer fr.stz.Release(context.WithoutCancel(ctx))
 
 	// Use singleflight to prevent concurrent Stop() calls from sending multiple SIGINTs
 	// to ffmpeg, which causes immediate abort without proper file closure.
@@ -281,7 +281,7 @@ func (fr *FFmpegRecorder) WaitForFinalization(ctx context.Context) error {
 func (fr *FFmpegRecorder) ForceStop(ctx context.Context) error {
 	log := logger.FromContext(ctx)
 
-	defer fr.stz.Enable(context.WithoutCancel(ctx))
+	defer fr.stz.Release(context.WithoutCancel(ctx))
 	shutdownErr := fr.shutdownInPhases(ctx, []shutdownPhase{
 		{"kill", []syscall.Signal{syscall.SIGKILL}, 100 * time.Millisecond, "immediate kill"},
 	})
@@ -530,7 +530,7 @@ func ffmpegArgs(params FFmpegRecordingParams, outputPath string) ([]string, erro
 // update the internal state accordingly. It also triggers finalization to add proper duration
 // metadata for recordings that exit naturally (max duration, max file size, etc.).
 func (fr *FFmpegRecorder) waitForCommand(ctx context.Context) {
-	defer fr.stz.Enable(context.WithoutCancel(ctx))
+	defer fr.stz.Release(context.WithoutCancel(ctx))
 
 	log := logger.FromContext(ctx)
 

server/lib/scaletozero/middleware.go

@@ -8,10 +8,10 @@ import (
 	"github.com/kernel/kernel-images/server/lib/logger"
 )
 
-// Middleware returns a standard net/http middleware that disables scale-to-zero
-// at the start of each request and re-enables it after the handler completes.
-// Connections from loopback addresses are ignored and do not affect the
-// scale-to-zero state.
+// Middleware returns a standard net/http middleware that acquires a
+// scale-to-zero hold at the start of each request and releases it after the
+// handler completes. Connections from loopback addresses are ignored and do
+// not affect the scale-to-zero state.
 func Middleware(ctrl Controller) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -20,12 +20,12 @@ func Middleware(ctrl Controller) func(http.Handler) http.Handler {
 				return
 			}
 
-			if err := ctrl.Disable(r.Context()); err != nil {
-				logger.FromContext(r.Context()).Error("failed to disable scale-to-zero", "error", err)
-				http.Error(w, "failed to disable scale-to-zero", http.StatusInternalServerError)
+			if err := ctrl.Acquire(r.Context()); err != nil {
+				logger.FromContext(r.Context()).Error("failed to acquire scale-to-zero hold", "error", err)
+				http.Error(w, "failed to acquire scale-to-zero hold", http.StatusInternalServerError)
 				return
 			}
-			defer ctrl.Enable(context.WithoutCancel(r.Context()))
+			defer ctrl.Release(context.WithoutCancel(r.Context()))
 
 			next.ServeHTTP(w, r)
 		})

server/lib/scaletozero/middleware_test.go

@@ -1,17 +1,44 @@
 package scaletozero
 
 import (
+	"context"
 	"net/http"
 	"net/http/httptest"
+	"sync"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestMiddlewareDisablesAndEnablesForExternalAddr(t *testing.T) {
+type mockController struct {
+	mu           sync.Mutex
+	acquireCalls int
+	releaseCalls int
+	acquireErr   error
+	releaseErr   error
+}
+
+func (m *mockController) Acquire(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.acquireCalls++
+	return m.acquireErr
+}
+
+func (m *mockController) Release(ctx context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.releaseCalls++
+	return m.releaseErr
+}
+
+func (m *mockController) Disable(ctx context.Context) error { return nil }
+func (m *mockController) Enable(ctx context.Context) error  { return nil }
+
+func TestMiddlewareAcquiresAndReleasesForExternalAddr(t *testing.T) {
 	t.Parallel()
-	mock := &mockScaleToZeroer{}
+	mock := &mockController{}
 	handler := Middleware(mock)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
 	}))
@@ -23,8 +50,8 @@ func TestMiddlewareDisablesAndEnablesForExternalAddr(t *testing.T) {
 	handler.ServeHTTP(rec, req)
 
 	assert.Equal(t, http.StatusOK, rec.Code)
-	assert.Equal(t, 1, mock.disableCalls)
-	assert.Equal(t, 1, mock.enableCalls)
+	assert.Equal(t, 1, mock.acquireCalls)
+	assert.Equal(t, 1, mock.releaseCalls)
 }
 
 func TestMiddlewareSkipsLoopbackAddrs(t *testing.T) {
@@ -41,7 +68,7 @@ func TestMiddlewareSkipsLoopbackAddrs(t *testing.T) {
 	for _, tc := range loopbackAddrs {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
-			mock := &mockScaleToZeroer{}
+			mock := &mockController{}
 			var called bool
 			handler := Middleware(mock)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 				called = true
@@ -56,15 +83,15 @@ func TestMiddlewareSkipsLoopbackAddrs(t *testing.T) {
 
 			assert.True(t, called, "handler should still be called")
 			assert.Equal(t, http.StatusOK, rec.Code)
-			assert.Equal(t, 0, mock.disableCalls, "should not disable for loopback addr")
-			assert.Equal(t, 0, mock.enableCalls, "should not enable for loopback addr")
+			assert.Equal(t, 0, mock.acquireCalls, "should not acquire for loopback addr")
+			assert.Equal(t, 0, mock.releaseCalls, "should not release for loopback addr")
 		})
 	}
 }
 
-func TestMiddlewareDisableError(t *testing.T) {
+func TestMiddlewareAcquireError(t *testing.T) {
 	t.Parallel()
-	mock := &mockScaleToZeroer{disableErr: assert.AnError}
+	mock := &mockController{acquireErr: assert.AnError}
 	var called bool
 	handler := Middleware(mock)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		called = true
@@ -76,9 +103,9 @@ func TestMiddlewareDisableError(t *testing.T) {
 
 	handler.ServeHTTP(rec, req)
 
-	assert.False(t, called, "handler should not be called on disable error")
+	assert.False(t, called, "handler should not be called on acquire error")
 	assert.Equal(t, http.StatusInternalServerError, rec.Code)
-	assert.Equal(t, 0, mock.enableCalls)
+	assert.Equal(t, 0, mock.releaseCalls)
 }
 
 func TestIsLoopbackAddr(t *testing.T) {