Route icon results through UI events (T-607)

core/application/event.go

@@ -17,6 +17,8 @@ const (
 	EventAppStarted        EventType = "AppStarted"
 	EventAppExited         EventType = "AppExited"
 	EventLicenseChanged    EventType = "LicenseChanged"
+	EventIconReady         EventType = "IconReady"
+	EventIconFailed        EventType = "IconFailed"
 )
 
 var validEventTypes = map[EventType]struct{}{
@@ -33,6 +35,8 @@ var validEventTypes = map[EventType]struct{}{
 	EventAppStarted:        {},
 	EventAppExited:         {},
 	EventLicenseChanged:    {},
+	EventIconReady:         {},
+	EventIconFailed:        {},
 }
 
 // Valid reports whether eventType is part of the documented event contract.

core/application/event_relay.go

@@ -0,0 +1,138 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+)
+
+var (
+	ErrEventRelayClosed  = errors.New("application event relay closed")
+	ErrEventRelayInvalid = errors.New("application event relay is invalid")
+)
+
+// EventRelay is a bounded FIFO between background event pumps and the UI frame.
+// Submit applies lossless backpressure; Drain must only run on the UI goroutine.
+type EventRelay struct {
+	events    chan Event
+	slots     chan struct{}
+	done      chan struct{}
+	mu        sync.Mutex
+	closed    bool
+	closeOnce sync.Once
+}
+
+// NewEventRelay creates a relay with a strictly positive bounded capacity.
+func NewEventRelay(capacity int) (*EventRelay, error) {
+	if capacity <= 0 {
+		return nil, fmt.Errorf(
+			"%w: capacity must be positive",
+			ErrEventRelayInvalid,
+		)
+	}
+	relay := &EventRelay{
+		events: make(chan Event, capacity),
+		slots:  make(chan struct{}, capacity),
+		done:   make(chan struct{}),
+	}
+	for index := 0; index < capacity; index++ {
+		relay.slots <- struct{}{}
+	}
+	return relay, nil
+}
+
+// Submit queues one event or returns when the context/relay closes.
+func (relay *EventRelay) Submit(ctx context.Context, event Event) error {
+	if relay == nil {
+		return fmt.Errorf("%w: nil relay", ErrEventRelayInvalid)
+	}
+	if !event.Type.Valid() {
+		return fmt.Errorf(
+			"%w: unknown type %q",
+			ErrInvalidEvent,
+			event.Type,
+		)
+	}
+	select {
+	case <-relay.done:
+		return ErrEventRelayClosed
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-relay.slots:
+	}
+
+	relay.mu.Lock()
+	defer relay.mu.Unlock()
+	if relay.closed {
+		relay.slots <- struct{}{}
+		return ErrEventRelayClosed
+	}
+	if err := ctx.Err(); err != nil {
+		relay.slots <- struct{}{}
+		return err
+	}
+	relay.events <- event
+	return nil
+}
+
+// Drain applies the events present at entry without extending a UI frame forever.
+func (relay *EventRelay) Drain(apply func(Event) error) error {
+	if relay == nil || apply == nil {
+		return fmt.Errorf("%w: nil relay or apply function", ErrEventRelayInvalid)
+	}
+	limit := len(relay.events)
+	var applyErrors []error
+	for index := 0; index < limit; index++ {
+		select {
+		case event := <-relay.events:
+			relay.slots <- struct{}{}
+			if err := apply(event); err != nil {
+				applyErrors = append(applyErrors, err)
+			}
+		default:
+			return errors.Join(applyErrors...)
+		}
+	}
+	return errors.Join(applyErrors...)
+}
+
+// Close unblocks pending submissions. Queued events remain available to Drain.
+func (relay *EventRelay) Close() {
+	if relay == nil {
+		return
+	}
+	relay.closeOnce.Do(func() {
+		relay.mu.Lock()
+		relay.closed = true
+		close(relay.done)
+		relay.mu.Unlock()
+	})
+}
+
+// PumpEvents forwards application events to a relay and requests a UI frame.
+// invalidate may be called concurrently; no UI state may be mutated here.
+func PumpEvents(
+	ctx context.Context,
+	events <-chan Event,
+	relay *EventRelay,
+	invalidate func(),
+) error {
+	if events == nil || relay == nil || invalidate == nil {
+		return fmt.Errorf("%w: incomplete event pump", ErrEventRelayInvalid)
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case event, open := <-events:
+			if !open {
+				return nil
+			}
+			if err := relay.Submit(ctx, event); err != nil {
+				return err
+			}
+			invalidate()
+		}
+	}
+}

core/application/event_relay_test.go

@@ -0,0 +1,208 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestEventRelayUsesBoundedFIFOBackpressure(t *testing.T) {
+	relay, err := NewEventRelay(1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	first := Event{Type: EventCatalogRefreshed, RequestID: "first"}
+	second := Event{Type: EventCatalogRejected, RequestID: "second"}
+	if err := relay.Submit(context.Background(), first); err != nil {
+		t.Fatal(err)
+	}
+
+	started := make(chan struct{})
+	secondResult := make(chan error, 1)
+	go func() {
+		close(started)
+		secondResult <- relay.Submit(context.Background(), second)
+	}()
+	<-started
+	select {
+	case err := <-secondResult:
+		t.Fatalf("second Submit() completed while relay was full: %v", err)
+	default:
+	}
+
+	var received []string
+	if err := relay.Drain(func(event Event) error {
+		received = append(received, event.RequestID)
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if err := waitRelayResult(secondResult); err != nil {
+		t.Fatalf("second Submit() error = %v", err)
+	}
+	if err := relay.Drain(func(event Event) error {
+		received = append(received, event.RequestID)
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(received, []string{"first", "second"}) {
+		t.Fatalf("received order = %v", received)
+	}
+}
+
+func TestEventRelayCloseAndContextUnblockFullSubmit(t *testing.T) {
+	tests := []struct {
+		name    string
+		unblock func(*EventRelay, context.CancelFunc)
+		wantErr error
+	}{
+		{
+			name: "close",
+			unblock: func(relay *EventRelay, _ context.CancelFunc) {
+				relay.Close()
+			},
+			wantErr: ErrEventRelayClosed,
+		},
+		{
+			name: "cancel",
+			unblock: func(_ *EventRelay, cancel context.CancelFunc) {
+				cancel()
+			},
+			wantErr: context.Canceled,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			relay, err := NewEventRelay(1)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := relay.Submit(
+				context.Background(),
+				Event{Type: EventCatalogRefreshed},
+			); err != nil {
+				t.Fatal(err)
+			}
+			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+			started := make(chan struct{})
+			result := make(chan error, 1)
+			go func() {
+				close(started)
+				result <- relay.Submit(ctx, Event{Type: EventCatalogRejected})
+			}()
+			<-started
+			test.unblock(relay, cancel)
+			if err := waitRelayResult(result); !errors.Is(err, test.wantErr) {
+				t.Fatalf("Submit() error = %v, want %v", err, test.wantErr)
+			}
+		})
+	}
+}
+
+func TestPumpEventsInvalidatesBeforeUIDrainAndStops(t *testing.T) {
+	relay, err := NewEventRelay(1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := make(chan Event, 2)
+	invalidated := make(chan struct{}, 2)
+	ctx, cancel := context.WithCancel(context.Background())
+	pumpResult := make(chan error, 1)
+	go func() {
+		pumpResult <- PumpEvents(ctx, source, relay, func() {
+			invalidated <- struct{}{}
+		})
+	}()
+
+	first := Event{Type: EventCatalogRefreshed, RequestID: "first"}
+	second := Event{Type: EventCatalogRejected, RequestID: "second"}
+	source <- first
+	source <- second
+	waitSignal(t, invalidated)
+
+	var received []string
+	if len(received) != 0 {
+		t.Fatal("background pump applied an event before UI drain")
+	}
+	if err := relay.Drain(func(event Event) error {
+		received = append(received, event.RequestID)
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	waitSignal(t, invalidated)
+	if err := relay.Drain(func(event Event) error {
+		received = append(received, event.RequestID)
+		return nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(received, []string{"first", "second"}) {
+		t.Fatalf("received order = %v", received)
+	}
+
+	cancel()
+	if err := waitRelayResult(pumpResult); !errors.Is(err, context.Canceled) {
+		t.Fatalf("PumpEvents() error = %v", err)
+	}
+}
+
+func TestEventRelayDrainReportsErrorsAndContinues(t *testing.T) {
+	relay, err := NewEventRelay(2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, eventType := range []EventType{EventCatalogRefreshed, EventCatalogRejected} {
+		if err := relay.Submit(context.Background(), Event{Type: eventType}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	wantErr := errors.New("apply failed")
+	applied := 0
+	err = relay.Drain(func(Event) error {
+		applied++
+		return wantErr
+	})
+	if !errors.Is(err, wantErr) || applied != 2 {
+		t.Fatalf("Drain() = (%d applies, %v)", applied, err)
+	}
+}
+
+func TestNewEventRelayRejectsInvalidCapacity(t *testing.T) {
+	if _, err := NewEventRelay(0); !errors.Is(err, ErrEventRelayInvalid) {
+		t.Fatalf("NewEventRelay(0) error = %v", err)
+	}
+	relay, err := NewEventRelay(1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	relay.Close()
+	if err := relay.Submit(
+		context.Background(),
+		Event{Type: EventCatalogRefreshed},
+	); !errors.Is(err, ErrEventRelayClosed) {
+		t.Fatalf("Submit(after Close) error = %v", err)
+	}
+}
+
+func waitRelayResult(result <-chan error) error {
+	select {
+	case err := <-result:
+		return err
+	case <-time.After(2 * time.Second):
+		return errors.New("timed out waiting for relay")
+	}
+}
+
+func waitSignal(t *testing.T, signal <-chan struct{}) {
+	t.Helper()
+	select {
+	case <-signal:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for signal")
+	}
+}

core/application/event_test.go

@@ -17,6 +17,8 @@ func TestEventTypeValid(t *testing.T) {
 		EventAppStarted,
 		EventAppExited,
 		EventLicenseChanged,
+		EventIconReady,
+		EventIconFailed,
 	}
 
 	for _, eventType := range eventTypes {

core/application/icon_event.go

@@ -0,0 +1,270 @@
+package application
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"image"
+	"reflect"
+	"strings"
+)
+
+const (
+	MinIconDPI = 48
+	MaxIconDPI = 768
+)
+
+var ErrInvalidIconEvent = errors.New("invalid icon application event")
+
+// IconFailureCode is a stable, non-sensitive reason exposed to UI adapters.
+type IconFailureCode string
+
+const (
+	IconFailureUnavailable IconFailureCode = "unavailable"
+	IconFailureInvalid     IconFailureCode = "invalid_content"
+	IconFailureUnsafe      IconFailureCode = "unsafe_cache"
+)
+
+// Valid reports whether code is part of the documented icon event contract.
+func (code IconFailureCode) Valid() bool {
+	switch code {
+	case IconFailureUnavailable, IconFailureInvalid, IconFailureUnsafe:
+		return true
+	default:
+		return false
+	}
+}
+
+// IconEventIdentity correlates one background request with one catalog icon.
+type IconEventIdentity struct {
+	RequestID string
+	AppID     string
+	Reference string
+	DPI       int
+}
+
+// NewIconEventIdentity validates and canonicalizes an icon event identity.
+func NewIconEventIdentity(
+	requestID string,
+	appID string,
+	reference string,
+	dpi int,
+) (IconEventIdentity, error) {
+	if strings.TrimSpace(requestID) == "" {
+		return IconEventIdentity{}, fmt.Errorf(
+			"%w: empty request ID",
+			ErrInvalidIconEvent,
+		)
+	}
+	if strings.TrimSpace(appID) == "" {
+		return IconEventIdentity{}, fmt.Errorf(
+			"%w: empty app ID",
+			ErrInvalidIconEvent,
+		)
+	}
+	canonicalReference, err := NormalizeIconReference(reference)
+	if err != nil {
+		return IconEventIdentity{}, err
+	}
+	if dpi < MinIconDPI || dpi > MaxIconDPI {
+		return IconEventIdentity{}, fmt.Errorf(
+			"%w: DPI %d outside %d..%d",
+			ErrInvalidIconEvent,
+			dpi,
+			MinIconDPI,
+			MaxIconDPI,
+		)
+	}
+	return IconEventIdentity{
+		RequestID: requestID,
+		AppID:     appID,
+		Reference: canonicalReference,
+		DPI:       dpi,
+	}, nil
+}
+
+// NormalizeIconReference returns the canonical sha256:<lower-hex> form.
+func NormalizeIconReference(reference string) (string, error) {
+	const prefix = "sha256:"
+	if !strings.HasPrefix(reference, prefix) {
+		return "", fmt.Errorf(
+			"%w: icon reference must use sha256",
+			ErrInvalidIconEvent,
+		)
+	}
+	digest := strings.ToLower(strings.TrimPrefix(reference, prefix))
+	decoded, err := hex.DecodeString(digest)
+	if err != nil || len(decoded) != sha256.Size || len(digest) != sha256.Size*2 {
+		return "", fmt.Errorf(
+			"%w: malformed icon digest",
+			ErrInvalidIconEvent,
+		)
+	}
+	return prefix + digest, nil
+}
+
+// IconReadyPayload contains an image decoded outside the Gio UI goroutine.
+type IconReadyPayload struct {
+	Reference string
+	DPI       int
+	Image     image.Image
+}
+
+// IconFailedPayload contains a stable failure classification, never a raw URL.
+type IconFailedPayload struct {
+	Reference string
+	DPI       int
+	ErrorCode IconFailureCode
+}
+
+// IconEvent is the validated representation consumed by UI adapters.
+type IconEvent struct {
+	Type      EventType
+	Identity  IconEventIdentity
+	Image     image.Image
+	ErrorCode IconFailureCode
+}
+
+// NewIconReadyEvent builds a validated ready event.
+func NewIconReadyEvent(
+	identity IconEventIdentity,
+	icon image.Image,
+) (Event, error) {
+	validated, err := NewIconEventIdentity(
+		identity.RequestID,
+		identity.AppID,
+		identity.Reference,
+		identity.DPI,
+	)
+	if err != nil {
+		return Event{}, err
+	}
+	if isNilImage(icon) {
+		return Event{}, fmt.Errorf("%w: nil ready image", ErrInvalidIconEvent)
+	}
+	return Event{
+		Type:      EventIconReady,
+		RequestID: validated.RequestID,
+		AppID:     validated.AppID,
+		Payload: IconReadyPayload{
+			Reference: validated.Reference,
+			DPI:       validated.DPI,
+			Image:     icon,
+		},
+	}, nil
+}
+
+// NewIconFailedEvent builds a validated failure event.
+func NewIconFailedEvent(
+	identity IconEventIdentity,
+	code IconFailureCode,
+) (Event, error) {
+	validated, err := NewIconEventIdentity(
+		identity.RequestID,
+		identity.AppID,
+		identity.Reference,
+		identity.DPI,
+	)
+	if err != nil {
+		return Event{}, err
+	}
+	if !code.Valid() {
+		return Event{}, fmt.Errorf(
+			"%w: unknown failure code %q",
+			ErrInvalidIconEvent,
+			code,
+		)
+	}
+	return Event{
+		Type:      EventIconFailed,
+		RequestID: validated.RequestID,
+		AppID:     validated.AppID,
+		Payload: IconFailedPayload{
+			Reference: validated.Reference,
+			DPI:       validated.DPI,
+			ErrorCode: code,
+		},
+	}, nil
+}
+
+// ParseIconEvent validates an icon envelope. Non-icon events return handled=false.
+func ParseIconEvent(event Event) (parsed IconEvent, handled bool, err error) {
+	switch event.Type {
+	case EventIconReady:
+		payload, ok := event.Payload.(IconReadyPayload)
+		if !ok {
+			return IconEvent{}, true, fmt.Errorf(
+				"%w: ready payload has type %T",
+				ErrInvalidIconEvent,
+				event.Payload,
+			)
+		}
+		identity, identityErr := NewIconEventIdentity(
+			event.RequestID,
+			event.AppID,
+			payload.Reference,
+			payload.DPI,
+		)
+		if identityErr != nil {
+			return IconEvent{}, true, identityErr
+		}
+		if isNilImage(payload.Image) {
+			return IconEvent{}, true, fmt.Errorf(
+				"%w: nil ready image",
+				ErrInvalidIconEvent,
+			)
+		}
+		return IconEvent{
+			Type:     event.Type,
+			Identity: identity,
+			Image:    payload.Image,
+		}, true, nil
+	case EventIconFailed:
+		payload, ok := event.Payload.(IconFailedPayload)
+		if !ok {
+			return IconEvent{}, true, fmt.Errorf(
+				"%w: failed payload has type %T",
+				ErrInvalidIconEvent,
+				event.Payload,
+			)
+		}
+		identity, identityErr := NewIconEventIdentity(
+			event.RequestID,
+			event.AppID,
+			payload.Reference,
+			payload.DPI,
+		)
+		if identityErr != nil {
+			return IconEvent{}, true, identityErr
+		}
+		if !payload.ErrorCode.Valid() {
+			return IconEvent{}, true, fmt.Errorf(
+				"%w: unknown failure code %q",
+				ErrInvalidIconEvent,
+				payload.ErrorCode,
+			)
+		}
+		return IconEvent{
+			Type:      event.Type,
+			Identity:  identity,
+			ErrorCode: payload.ErrorCode,
+		}, true, nil
+	default:
+		return IconEvent{}, false, nil
+	}
+}
+
+func isNilImage(icon image.Image) bool {
+	if icon == nil {
+		return true
+	}
+	value := reflect.ValueOf(icon)
+	switch value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map,
+		reflect.Ptr, reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}

core/application/icon_event_test.go

@@ -0,0 +1,126 @@
+package application
+
+import (
+	"errors"
+	"image"
+	"strings"
+	"testing"
+)
+
+func TestIconEventRoundTrip(t *testing.T) {
+	reference := "sha256:" + strings.Repeat("A1", 32)
+	identity, err := NewIconEventIdentity("request-1", "app-one", reference, 144)
+	if err != nil {
+		t.Fatalf("NewIconEventIdentity() error = %v", err)
+	}
+	if identity.Reference != strings.ToLower(reference) {
+		t.Fatalf("canonical reference = %q", identity.Reference)
+	}
+
+	icon := image.NewNRGBA(image.Rect(0, 0, 24, 24))
+	ready, err := NewIconReadyEvent(identity, icon)
+	if err != nil {
+		t.Fatalf("NewIconReadyEvent() error = %v", err)
+	}
+	parsed, handled, err := ParseIconEvent(ready)
+	if err != nil || !handled {
+		t.Fatalf("ParseIconEvent(ready) = (%+v, %t, %v)", parsed, handled, err)
+	}
+	if parsed.Type != EventIconReady || parsed.Identity != identity || parsed.Image != icon {
+		t.Fatalf("parsed ready event = %+v", parsed)
+	}
+
+	failed, err := NewIconFailedEvent(identity, IconFailureUnsafe)
+	if err != nil {
+		t.Fatalf("NewIconFailedEvent() error = %v", err)
+	}
+	parsed, handled, err = ParseIconEvent(failed)
+	if err != nil || !handled {
+		t.Fatalf("ParseIconEvent(failed) = (%+v, %t, %v)", parsed, handled, err)
+	}
+	if parsed.Type != EventIconFailed ||
+		parsed.Identity != identity ||
+		parsed.ErrorCode != IconFailureUnsafe {
+		t.Fatalf("parsed failed event = %+v", parsed)
+	}
+
+	parsed, handled, err = ParseIconEvent(Event{Type: EventCatalogRefreshed})
+	if err != nil || handled {
+		t.Fatalf("ParseIconEvent(non-icon) = (%+v, %t, %v)", parsed, handled, err)
+	}
+}
+
+func TestIconEventRejectsInvalidIdentityAndPayload(t *testing.T) {
+	validReference := "sha256:" + strings.Repeat("0a", 32)
+	tests := []struct {
+		name      string
+		requestID string
+		appID     string
+		reference string
+		dpi       int
+	}{
+		{name: "empty request", appID: "app", reference: validReference, dpi: 96},
+		{name: "empty app", requestID: "request", reference: validReference, dpi: 96},
+		{name: "bad reference", requestID: "request", appID: "app", reference: "md5:00", dpi: 96},
+		{name: "low DPI", requestID: "request", appID: "app", reference: validReference, dpi: 47},
+		{name: "high DPI", requestID: "request", appID: "app", reference: validReference, dpi: 769},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := NewIconEventIdentity(
+				test.requestID,
+				test.appID,
+				test.reference,
+				test.dpi,
+			)
+			if !errors.Is(err, ErrInvalidIconEvent) {
+				t.Fatalf("NewIconEventIdentity() error = %v", err)
+			}
+		})
+	}
+
+	identity, err := NewIconEventIdentity("request", "app", validReference, 96)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := NewIconReadyEvent(identity, nil); !errors.Is(err, ErrInvalidIconEvent) {
+		t.Fatalf("NewIconReadyEvent(nil) error = %v", err)
+	}
+	var typedNil *image.NRGBA
+	if _, err := NewIconReadyEvent(identity, typedNil); !errors.Is(err, ErrInvalidIconEvent) {
+		t.Fatalf("NewIconReadyEvent(typed nil) error = %v", err)
+	}
+	if _, err := NewIconFailedEvent(identity, IconFailureCode("raw-http-error")); !errors.Is(err, ErrInvalidIconEvent) {
+		t.Fatalf("NewIconFailedEvent(invalid code) error = %v", err)
+	}
+
+	invalidPayloads := []Event{
+		{Type: EventIconReady, RequestID: "request", AppID: "app", Payload: "wrong"},
+		{Type: EventIconFailed, RequestID: "request", AppID: "app", Payload: "wrong"},
+		{
+			Type:      EventIconReady,
+			RequestID: "request",
+			AppID:     "app",
+			Payload: IconReadyPayload{
+				Reference: validReference,
+				DPI:       96,
+			},
+		},
+		{
+			Type:      EventIconFailed,
+			RequestID: "request",
+			AppID:     "app",
+			Payload: IconFailedPayload{
+				Reference: validReference,
+				DPI:       96,
+				ErrorCode: IconFailureCode("raw"),
+			},
+		},
+	}
+	for _, event := range invalidPayloads {
+		_, handled, err := ParseIconEvent(event)
+		if !handled || !errors.Is(err, ErrInvalidIconEvent) {
+			t.Fatalf("ParseIconEvent(%+v) handled=%t error=%v", event, handled, err)
+		}
+	}
+}