favicon_resolver.go RawHistoryFolder
1package port
2
3import (
4 "context"
5
6 "github.com/bnema/dumber/internal/domain/favicon"
7)
8
9// FaviconResolvePurpose identifies the context requesting favicon resolution.
10type FaviconResolvePurpose string
11
12const (
13 // FaviconResolvePurposeUI resolves favicons for end-user UI display.
14 FaviconResolvePurposeUI FaviconResolvePurpose = "ui"
15 // FaviconResolvePurposeSystemview resolves favicons for internal views without remote loads.
16 FaviconResolvePurposeSystemview FaviconResolvePurpose = "systemview"
17 // FaviconResolvePurposeRefresh resolves favicons for background refresh work.
18 FaviconResolvePurposeRefresh FaviconResolvePurpose = "refresh"
19)
20
21// FaviconResolveOptions controls cache lookup, blocking refresh, background refresh, and caller intent.
22type FaviconResolveOptions struct {
23 AllowBlockingRefresh bool
24 ScheduleBackgroundRefresh bool
25 Purpose FaviconResolvePurpose
26}
27
28// ResolvedFavicon is a fully resolved favicon payload with metadata and refresh state.
29// Key identifies the cache entry; Bytes and ContentType hold image data; Metadata and BackgroundRefreshScheduled describe state.
30type ResolvedFavicon struct {
31 Key favicon.Key
32 Bytes []byte
33 ContentType string
34 Metadata *favicon.Metadata
35 BackgroundRefreshScheduled bool
36}
37
38// FaviconResolver orchestrates favicon lookup, observation, refresh, sizing, and invalidation.
39// It extends FaviconSystemviewResolver for boundary-safe systemview reads.
40type FaviconResolver interface {
41 FaviconSystemviewResolver
42 Resolve(ctx context.Context, rawURLOrDomain string, size int, options FaviconResolveOptions) (*ResolvedFavicon, error)
43 Observe(ctx context.Context, pageURL, iconURL string, bytes []byte, source favicon.Source, contentType string) (*favicon.Metadata, error)
44 RefreshFromIconURLs(ctx context.Context, pageURL string, iconURLs []string) error
45 EnsureSized(ctx context.Context, key favicon.Key, size int) error
46 Invalidate(ctx context.Context, key favicon.Key) error
47}
48
49// FaviconSystemviewResolver is the boundary-safe API used by engine scheme
50// handlers. Implementations must resolve exact keys and parent fallbacks through
51// the application usecase and must not trigger remote network loads.
52type FaviconSystemviewResolver interface {
53 ResolveSystemviewIcon(ctx context.Context, rawDomain string, size int) (*ResolvedFavicon, error)
54}
55
56// SystemviewFaviconResolverSetter is an optional engine capability that wires
57// the application favicon resolver to internal systemview pages.
58type SystemviewFaviconResolverSetter interface {
59 SetSystemviewFaviconResolver(resolver FaviconSystemviewResolver)
60}