Skip to content

Modern Docker Management, Designed for Everyone

8.4 KB
Raw Blame
package activity

import (
	"context"
	"encoding/json/v2"
	"errors"
	"fmt"
	"io"
	"log/slog"
	"net/http"
	"strings"

	activitytypes "github.com/getarcaneapp/arcane/types/v2/activity"
	schedulertypes "github.com/getarcaneapp/arcane/types/v2/scheduler"
	usertypes "github.com/getarcaneapp/arcane/types/v2/user"
	"github.com/samber/mo"

	"github.com/getarcaneapp/arcane/backend/v2/internal/database"
	"github.com/getarcaneapp/arcane/backend/v2/pkg/scheduler/jobcontext"
	"github.com/getarcaneapp/arcane/backend/v2/pkg/utils"
)

const (
	// ErrCanceled is the cancellation cause set on an activity's work context when a
	// user requests cancellation. Completion paths read context.Cause to record a
	// cancelled (rather than failed) terminal status.

	// cancelledMessage is the latest-message recorded when work is cancelled.
	cancelledMessage = "Cancelled by user"
)

var ErrCanceled = errors.New("activity cancelled by user")

type handlerActivityIDContextKey struct{}

func IDFromContext(ctx context.Context) string {
	if ctx == nil {
		return ""
	}
	activityID, _ := ctx.Value(handlerActivityIDContextKey{}).(string)
	return strings.TrimSpace(activityID)
}

// CancelledByContext reports whether ctx was cancelled by a user cancellation
// request (as opposed to app shutdown or a deadline). Callers that finalize an
// activity from a possibly-cancelled work context use this to choose between a
// cancelled and a failed terminal status.
func CancelledByContext(ctx context.Context) bool {
	return ctx != nil && errors.Is(context.Cause(ctx), ErrCanceled)
}

type HandlerOptions struct {
	EnvironmentID  string
	Type           activitytypes.Type
	ResourceType   string
	ResourceID     string
	ResourceName   string
	User           *usertypes.Actor
	Step           string
	Message        string
	SuccessMessage string
	Metadata       database.JSON
	// Queue routes the activity through the per-environment concurrency
	// limiter so bulk long-running operations wait visibly instead of all
	// running at once. Quick actions (start/stop/delete) must not set this.
	Queue bool
}

// AwaitHandlerActivitySlot blocks until the queued activity holds a
// concurrency slot (flipping it to running). A cancellation while waiting is
// not an error to the caller: the work context is already cancelled, so the
// subsequent action fails fast and CompleteHandlerActivity records the
// cancelled status.
func AwaitHandlerActivitySlot(ctx context.Context, activityService Service, activityID, environmentID string) {
	if activityService == nil || strings.TrimSpace(activityID) == "" {
		return
	}
	waiter, ok := activityService.(SlotWaiter)
	if !ok {
		return
	}
	if err := waiter.AwaitActivitySlot(ctx, activityID, environmentID); err != nil {
		slog.DebugContext(ctx, "queued activity wait ended before acquiring a slot", "activityId", activityID, "error", err)
	}
}

// StartHandlerActivity creates a background activity and returns its ID along
// with a work context the caller MUST use for the underlying operation. When
// the service supports cancellation (implements Tracker), the returned context
// is a cancelable child bound to the activity; cancelling the activity cancels
// this context. The activity registration is released when the activity is
// completed via the service. On failure it returns ("", ctx) unchanged.
//
// When queue is true the activity is routed through the per-environment
// concurrency limiter: when no slot is free the activity is created with
// status queued. The caller MUST then call AwaitHandlerActivitySlot on the
// returned work context before doing the actual work (streaming endpoints
// write their started line in between, so the client learns the activity ID
// before the queue wait begins). Quick actions (start/stop/delete) must pass
// false.
func StartHandlerActivity(
	ctx context.Context,
	activityService Service,
	environmentID string,
	activityType activitytypes.Type,
	resourceType string,
	resourceID string,
	resourceName string,
	user *usertypes.Actor,
	step string,
	message string,
	metadata database.JSON,
	queue bool,
) (string, context.Context) {
	if activityService == nil {
		return "", ctx
	}

	activity, err := activityService.StartActivity(ctx, StartRequest{
		EnvironmentID: environmentID,
		Type:          activityType,
		Queue:         queue,
		ResourceType:  mo.EmptyableToOption(strings.TrimSpace(resourceType)).ToPointer(),
		ResourceID:    mo.EmptyableToOption(strings.TrimSpace(resourceID)).ToPointer(),
		ResourceName:  mo.EmptyableToOption(strings.TrimSpace(resourceName)).ToPointer(),
		StartedBy:     user,
		Step:          step,
		LatestMessage: message,
		Metadata:      metadata,
	})
	if err != nil {
		slog.DebugContext(ctx, "failed to start background activity", "type", activityType, "error", err)
		return "", ctx
	}

	workCtx := ctx
	if tracker, ok := activityService.(Tracker); ok {
		workCtx = tracker.Track(ctx, activity.ID)
	}
	workCtx = context.WithValue(workCtx, handlerActivityIDContextKey{}, activity.ID)
	return activity.ID, workCtx
}

func CompleteHandlerActivity(ctx context.Context, activityService Service, activityID, successMessage string, err error) {
	if activityService == nil || strings.TrimSpace(activityID) == "" {
		return
	}

	status := activitytypes.StatusSuccess
	var errMessage *string
	finalMessage := successMessage
	if err != nil {
		// Read the cancellation cause from the (possibly-tracked) work context
		// before it is re-wrapped for the DB write below.
		if CancelledByContext(ctx) {
			status = activitytypes.StatusCancelled
			finalMessage = cancelledMessage
		} else {
			status = activitytypes.StatusFailed
			errText := err.Error()
			errMessage = &errText
			finalMessage = errText
		}
	}

	activityCtx := utils.ActivityRuntimeContext(ctx, nil)
	if _, completeErr := activityService.CompleteActivity(activityCtx, activityID, status, finalMessage, errMessage); completeErr != nil {
		slog.WarnContext(activityCtx, "failed to complete background activity", "activityId", activityID, "error", completeErr)
	}
}

// RunHandlerActivity starts an activity, runs action with the activity's work
// context (cancelable when the service supports it), and completes the activity.
// The action MUST use the provided context for its operation so cancellation
// propagates.
func RunHandlerActivity(ctx context.Context, activityService Service, opts HandlerOptions, action func(ctx context.Context) error) (string, error) {
	activityID, workCtx := StartHandlerActivity(
		ctx,
		activityService,
		opts.EnvironmentID,
		opts.Type,
		opts.ResourceType,
		opts.ResourceID,
		opts.ResourceName,
		opts.User,
		opts.Step,
		opts.Message,
		opts.Metadata,
		opts.Queue,
	)
	if opts.Queue {
		AwaitHandlerActivitySlot(workCtx, activityService, activityID, opts.EnvironmentID)
	}

	err := jobcontext.Progress(workCtx, schedulertypes.TargetOutcome{ID: opts.ResourceID, Status: schedulertypes.Running, ActivityID: activityID})
	if err == nil {
		err = action(workCtx)
	}
	CompleteHandlerActivity(workCtx, activityService, activityID, opts.SuccessMessage, err)
	target := schedulertypes.TargetOutcome{ID: opts.ResourceID, Status: schedulertypes.Succeeded, ActivityID: activityID}
	if err != nil {
		target.Status = schedulertypes.Failed
		target.Message = err.Error()
	}
	if progressErr := jobcontext.Progress(workCtx, target); progressErr != nil && err == nil {
		err = progressErr
	}
	return activityID, err
}

// WriteDoneLine writes the terminal success frame of an operation NDJSON
// stream. Clients resolve on this frame rather than relying on the network
// EOF, which proxies do not always propagate promptly.
func WriteDoneLine(writer io.Writer) {
	if writer == nil {
		return
	}
	_, _ = io.WriteString(writer, "{\"done\":true}\n")
	if flusher, ok := writer.(http.Flusher); ok {
		flusher.Flush()
	}
}

func WriteErrorLine(writer io.Writer, err error) {
	if writer == nil || err == nil {
		return
	}
	_ = json.MarshalWrite(writer, map[string]string{"error": err.Error()})
	_, _ = io.WriteString(writer, "\n")
	if flusher, ok := writer.(http.Flusher); ok {
		flusher.Flush()
	}
}

func WriteStartedLine(writer io.Writer, activityID string) {
	if writer == nil || strings.TrimSpace(activityID) == "" {
		return
	}

	payload := map[string]string{
		"type":       "activity",
		"activityId": activityID,
	}
	if err := json.MarshalWrite(writer, payload); err != nil {
		_, _ = fmt.Fprintf(writer, "{\"activityId\":%q}\n", activityID)
		return
	}
	_, _ = io.WriteString(writer, "\n")
}

func FlushWriter(writer io.Writer) {
	if flusher, ok := writer.(interface{ Flush() }); ok {
		flusher.Flush()
	}
}