favicon.go RawHistoryFolder

1// Package service defines domain service interfaces.
2package service
3
4import "context"
5
6// FaviconService provides favicon retrieval and caching operations.
7// It works with raw bytes, leaving texture conversion to the UI layer.
8type FaviconService interface {
9	// Get returns favicon bytes for a domain.
10	// Checks memory cache, then disk cache, then fetches from external API.
11	Get(ctx context.Context, domain string) ([]byte, error)
12
13	// GetCached returns favicon bytes only if already cached (no external fetch).
14	// Returns the bytes and true if found, nil and false otherwise.
15	GetCached(domain string) ([]byte, bool)
16
17	// Store saves favicon bytes for a domain to cache.
18	Store(domain string, data []byte) error
19
20	// DiskPath returns the filesystem path where a domain's favicon is cached (ICO).
21	DiskPath(domain string) string
22
23	// DiskPathPNG returns the filesystem path for PNG favicon.
24	// PNG format is required by CLI tools like rofi/fuzzel.
25	DiskPathPNG(domain string) string
26
27	// HasPNGOnDisk checks if a PNG favicon exists on disk for the domain.
28	HasPNGOnDisk(domain string) bool
29
30	// WritePNG writes raw PNG data to disk for a domain.
31	// Used by UI layer to export WebKit textures for CLI tools.
32	WritePNG(domain string, pngData []byte)
33
34	// DiskPathPNGSized returns the filesystem path for a sized PNG favicon.
35	// Used for normalized favicon export (e.g., 32x32) for CLI tools.
36	DiskPathPNGSized(domain string, size int) string
37
38	// HasPNGSizedOnDisk checks if a sized PNG favicon exists on disk.
39	HasPNGSizedOnDisk(domain string, size int) bool
40
41	// EnsureSizedPNG creates a resized PNG from the original if it doesn't exist.
42	// This is used to generate normalized icons for dmenu/fuzzel.
43	EnsureSizedPNG(ctx context.Context, domain string, size int) error
44
45	// Close shuts down background workers and releases resources.
46	Close()
47}