cachefile

package
v0.4.0-beta Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 3, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package cachefile provides offline file-backed caching for the Translaas SDK.

FileProvider implements the L2 disk cache with JSON wrappers, a root manifest, atomic writes, and expiration-as-miss semantics aligned with the .NET SDK.

HybridProvider adds an expirable LRU memory layer (L1) over any Provider (L2), promoting disk hits into memory and writing through to both tiers on save.

CachingClient decorates client.Client with offline fallback modes (CacheFirst, APIFirst, CacheOnly), offline entry resolution, and cache warming after API reads.

SyncService pulls translations from the API into a Provider using the inner client (not CachingClient) and supports optional background sync on a ticker.

ParseOfflineZip and FileProvider.ImportOfflineBundle import offline ZIP bundles (HTTP spec §7.6) into the same on-disk layout. SyncFromOfflineZip combines download and import in one call.

Index

Constants

View Source 
const (
	// ManifestVersion is the root manifest schema version written by the SDK.
	ManifestVersion = "1.0"
	// DefaultSDKVersion is the offline cache format version recorded in manifest.json.
	DefaultSDKVersion = "1.0.0"
)

Variables

This section is empty.

Functions

func ResolveProjectKey 

func ResolveProjectKey(bundle *OfflineBundle, project string) (string, error)

ResolveProjectKey maps a logical project id to the folder key used inside the bundle.

func SanitizePathSegment 

func SanitizePathSegment(name string) (string, error)

SanitizePathSegment replaces invalid filename characters with '_' for use in cache directory names.

Types

type CacheManifest 

type CacheManifest struct {
	Version    string                      `json:"version"`
	SDKVersion string                      `json:"sdkVersion"`
	CreatedAt  time.Time                   `json:"createdAt"`
	LastSyncAt time.Time                   `json:"lastSyncAt"`
	Projects   map[string]ProjectCacheInfo `json:"projects"`
}

CacheManifest is the root offline cache index (manifest.json).

type CachedLocales 

type CachedLocales struct {
	CachedAt  time.Time             `json:"cachedAt"`
	ExpiresAt *time.Time            `json:"expiresAt,omitempty"`
	Data      models.ProjectLocales `json:"data"`
}

CachedLocales wraps supported locales with cache metadata.

type CachedProject 

type CachedProject struct {
	CachedAt  time.Time                 `json:"cachedAt"`
	ExpiresAt *time.Time                `json:"expiresAt,omitempty"`
	Data      models.TranslationProject `json:"data"`
}

CachedProject wraps a translation project payload with cache metadata.

type CachingClient 

type CachingClient struct {
	// contains filtered or unexported fields
}

CachingClient decorates client.Client with offline fallback semantics.

func NewCachingClient 

func NewCachingClient(inner client.Client, cache Provider, opts Options) (*CachingClient, error)

NewCachingClient wraps inner with offline cache behavior.

func (*CachingClient) GetEntry 

func (c *CachingClient) GetEntry(ctx context.Context, group, entry, lang string, opts ...client.GetEntryOption) (string, error)

GetEntry resolves a translation with offline fallback behavior.

func (*CachingClient) GetGroup 

func (c *CachingClient) GetGroup(
	ctx context.Context,
	project, group, lang string,
	opts ...client.GetGroupOption,
) (*models.TranslationGroup, error)

GetGroup retrieves a group with offline fallback behavior.

func (*CachingClient) GetOfflineCache 

func (c *CachingClient) GetOfflineCache(
	ctx context.Context,
	project string,
	opts ...client.GetOfflineCacheOption,
) (*models.OfflineCacheDownloadResult, error)

GetOfflineCache delegates to the inner client.

func (*CachingClient) GetProject 

func (c *CachingClient) GetProject(
	ctx context.Context,
	project, lang string,
	opts ...client.GetProjectOption,
) (*models.TranslationProject, error)

GetProject retrieves a project with offline fallback behavior.

func (*CachingClient) GetProjectLocales 

func (c *CachingClient) GetProjectLocales(
	ctx context.Context,
	project string,
	opts ...client.GetProjectLocalesOption,
) (*models.ProjectLocales, error)

GetProjectLocales retrieves locales with offline fallback behavior.

func (*CachingClient) ReportMissingKeys 

func (c *CachingClient) ReportMissingKeys(ctx context.Context, keys []models.ReportMissingKeyItem) error

ReportMissingKeys delegates to the inner client.

func (*CachingClient) ValidateAPIKey 

func (c *CachingClient) ValidateAPIKey(ctx context.Context) (*models.ValidateAPIKeyResponse, error)

ValidateAPIKey delegates to the inner client.

type FallbackMode 

type FallbackMode int

FallbackMode selects cache vs API ordering for intercepted reads. 

const (
	// FallbackCacheFirst reads disk first, then API on miss.
	FallbackCacheFirst FallbackMode = iota
	// FallbackAPIFirst reads API first, then disk on network/API errors.
	FallbackAPIFirst
	// FallbackCacheOnly reads disk only.
	FallbackCacheOnly
)

type FileProvider 

type FileProvider struct {
	// contains filtered or unexported fields
}

FileProvider persists offline translation payloads as JSON on disk.

func NewFileProvider 

func NewFileProvider(cacheDirectory string) (*FileProvider, error)

NewFileProvider creates a file-backed offline cache at cacheDirectory. Relative paths resolve against the process working directory.

func (*FileProvider) CacheDirectory 

func (p *FileProvider) CacheDirectory() string

CacheDirectory returns the absolute cache root path.

func (*FileProvider) Clear 

func (p *FileProvider) Clear(ctx context.Context) error

Clear removes the entire cache directory tree.

func (*FileProvider) GetGroup 

func (p *FileProvider) GetGroup(ctx context.Context, project, group, lang string) (*models.TranslationGroup, error)

GetGroup returns a group extracted from the cached project payload.

func (*FileProvider) GetLocales 

func (p *FileProvider) GetLocales(ctx context.Context, project string) (*models.ProjectLocales, error)

GetLocales returns cached locales, falling back to manifest or locale directories.

func (*FileProvider) GetManifest 

func (p *FileProvider) GetManifest(ctx context.Context) (*CacheManifest, error)

GetManifest reads root manifest.json or returns (nil, nil) when absent.

func (*FileProvider) GetProject 

func (p *FileProvider) GetProject(ctx context.Context, project, lang string) (*models.TranslationProject, error)

GetProject returns cached project data or (nil, nil) on miss or expiry.

func (*FileProvider) ImportOfflineBundle 

func (p *FileProvider) ImportOfflineBundle(ctx context.Context, project string, zipBytes []byte) error

ImportOfflineBundle parses zipBytes and persists the matching project into this provider's cache directory. It uses SaveProject and SaveLocales so atomic writes and manifest updates stay consistent with API sync.

func (*FileProvider) IsCached 

func (p *FileProvider) IsCached(ctx context.Context, project, lang string) (bool, error)

IsCached reports whether a non-expired project/language payload exists on disk.

func (*FileProvider) SaveLocales 

func (p *FileProvider) SaveLocales(
	ctx context.Context,
	project string,
	data *models.ProjectLocales,
	opts ...SaveOption,
) error

SaveLocales writes locales.json and updates the root manifest.

func (*FileProvider) SaveProject 

func (p *FileProvider) SaveProject(
	ctx context.Context,
	project, lang string,
	data *models.TranslationProject,
	opts ...SaveOption,
) error

SaveProject writes project data to disk and updates the root manifest.

func (*FileProvider) UpdateManifest 

func (p *FileProvider) UpdateManifest(ctx context.Context, update func(*CacheManifest) error) error

UpdateManifest read-modify-writes manifest.json atomically.

type HybridOptions 

type HybridOptions struct {
	// Enabled turns the memory layer on. When false, HybridProvider delegates to L2 only.
	Enabled bool
	// MemoryExpiration is the TTL for L1 entries. Zero uses DefaultHybridMemoryExpiration.
	MemoryExpiration time.Duration
	// MaxEntries is the LRU capacity per L1 partition (projects, groups, locales). Zero uses defaultHybridMaxEntries.
	MaxEntries int
}

HybridOptions configures the in-memory L1 layer over a file-backed L2 Provider.

func DefaultHybridOptions 

func DefaultHybridOptions() HybridOptions

DefaultHybridOptions returns HybridOptions with .NET-aligned defaults.

type HybridProvider 

type HybridProvider struct {
	// contains filtered or unexported fields
}

HybridProvider combines an expirable LRU memory cache (L1) with a disk Provider (L2).

func NewHybridProvider 

func NewHybridProvider(l2 Provider, opts HybridOptions) (*HybridProvider, error)

NewHybridProvider wraps l2 with an optional in-memory L1 cache.

func (*HybridProvider) Clear 

func (p *HybridProvider) Clear(ctx context.Context) error

Clear removes all L1 and L2 cache data.

func (*HybridProvider) ClearMemoryCache 

func (p *HybridProvider) ClearMemoryCache()

ClearMemoryCache removes all L1 entries without touching L2.

func (*HybridProvider) GetGroup 

func (p *HybridProvider) GetGroup(ctx context.Context, project, group, lang string) (*models.TranslationGroup, error)

GetGroup checks L1, then L2, promoting L2 hits into L1.

func (*HybridProvider) GetLocales 

func (p *HybridProvider) GetLocales(ctx context.Context, project string) (*models.ProjectLocales, error)

GetLocales checks L1, then L2, promoting L2 hits into L1.

func (*HybridProvider) GetManifest 

func (p *HybridProvider) GetManifest(ctx context.Context) (*CacheManifest, error)

GetManifest delegates to L2 (manifest is not cached in L1).

func (*HybridProvider) GetProject 

func (p *HybridProvider) GetProject(ctx context.Context, project, lang string) (*models.TranslationProject, error)

GetProject checks L1, then L2, promoting L2 hits into L1.

func (*HybridProvider) IsCached 

func (p *HybridProvider) IsCached(ctx context.Context, project, lang string) (bool, error)

IsCached reports whether data exists in L1 or L2.

func (*HybridProvider) MemoryCacheStats 

func (p *HybridProvider) MemoryCacheStats() (projects, groups, locales int)

MemoryCacheStats returns current L1 entry counts by partition.

func (*HybridProvider) SaveLocales 

func (p *HybridProvider) SaveLocales(
	ctx context.Context,
	project string,
	data *models.ProjectLocales,
	opts ...SaveOption,
) error

SaveLocales updates L1 and persists to L2.

func (*HybridProvider) SaveProject 

func (p *HybridProvider) SaveProject(
	ctx context.Context,
	project, lang string,
	data *models.TranslationProject,
	opts ...SaveOption,
) error

SaveProject updates L1 and persists to L2.

func (*HybridProvider) UpdateManifest 

func (p *HybridProvider) UpdateManifest(ctx context.Context, update func(*CacheManifest) error) error

UpdateManifest delegates to L2 (manifest is not cached in L1).

func (*HybridProvider) Warmup 

func (p *HybridProvider) Warmup(ctx context.Context, project, lang string) (bool, error)

Warmup loads project data from L2 into L1 for the given project and language.

type OfflineBundle 

type OfflineBundle struct {
	Manifest              CacheManifest
	LocalesByProject      map[string]CachedLocales
	ProjectsByProjectLang map[string]map[string]CachedProject
}

OfflineBundle holds parsed offline ZIP contents keyed by path segments from the archive.

func ParseOfflineZip 

func ParseOfflineZip(content []byte) (*OfflineBundle, error)

ParseOfflineZip reads an offline ZIP bundle (HTTP spec §7.6).

type OfflineCacheOptions 

type OfflineCacheOptions struct {
	// Enabled turns offline file caching on. When false, sync helpers no-op at the app layer.
	Enabled bool

	// CacheDirectory is the root path for on-disk cache files (absolute or relative to CWD).
	CacheDirectory string

	// FallbackMode selects cache vs API ordering for CachingClient reads.
	FallbackMode FallbackMode

	// AutoSync enables periodic background synchronization when StartBackgroundSync is used.
	AutoSync bool

	// AutoSyncInterval controls the delay between background sync runs.
	// Nil disables interval-based sync (StartBackgroundSync becomes a no-op).
	AutoSyncInterval *time.Duration

	// Projects lists project IDs to sync in SyncAll and background sync.
	Projects []string

	// Languages limits pre-cache to these locale codes. Empty means all project locales.
	Languages []string

	// DefaultProjectID is required for offline GetEntry lookups via CachingClient.
	DefaultProjectID string
}

OfflineCacheOptions configures file-backed offline caching and background sync.

func DefaultOfflineCacheOptions 

func DefaultOfflineCacheOptions() OfflineCacheOptions

DefaultOfflineCacheOptions returns .NET-aligned defaults.

type Options 

type Options struct {
	FallbackMode     FallbackMode
	DefaultProjectID string
}

Options configures the offline CachingClient decorator.

func DefaultOptions 

func DefaultOptions() Options

DefaultOptions returns Options with .NET-aligned defaults.

type ProjectCacheInfo 

type ProjectCacheInfo struct {
	Languages  []string  `json:"languages"`
	LastSyncAt time.Time `json:"lastSyncAt"`
	Status     string    `json:"status"`
}

ProjectCacheInfo tracks cached languages for one project.

type Provider 

type Provider interface {
	GetProject(ctx context.Context, project, lang string) (*models.TranslationProject, error)
	SaveProject(ctx context.Context, project, lang string, data *models.TranslationProject, opts ...SaveOption) error

	GetGroup(ctx context.Context, project, group, lang string) (*models.TranslationGroup, error)
	GetLocales(ctx context.Context, project string) (*models.ProjectLocales, error)
	SaveLocales(ctx context.Context, project string, data *models.ProjectLocales, opts ...SaveOption) error

	GetManifest(ctx context.Context) (*CacheManifest, error)
	UpdateManifest(ctx context.Context, update func(*CacheManifest) error) error

	IsCached(ctx context.Context, project, lang string) (bool, error)
	Clear(ctx context.Context) error
}

Provider is the offline disk cache contract (L2). Implementations must be safe for concurrent use.

type SaveOption 

type SaveOption func(*saveConfig)

SaveOption configures SaveProject and SaveLocales.

func WithExpiresAt 

func WithExpiresAt(t *time.Time) SaveOption

WithExpiresAt sets wrapper ExpiresAt (nil = no expiry).

type SyncCallbacks 

type SyncCallbacks struct {
	OnSyncCompleted    func(SyncCompletedEvent)
	OnSyncFailed       func(SyncFailedEvent)
	OnSyncAllCompleted func(SyncResult)
}

SyncCallbacks holds optional hooks for sync lifecycle events.

type SyncCompletedEvent 

type SyncCompletedEvent struct {
	Project  string
	Language string
	SyncedAt time.Time
}

SyncCompletedEvent reports a successful project/language sync.

type SyncFailedEvent 

type SyncFailedEvent struct {
	Project  string
	Language string
	Err      error
}

SyncFailedEvent reports a failed project/language sync.

type SyncResult 

type SyncResult struct {
	SyncedProjects []string
	FailedProjects []string
	CompletedAt    time.Time
}

SyncResult aggregates SyncAll outcomes across configured projects.

type SyncService 

type SyncService struct {
	// contains filtered or unexported fields
}

SyncService synchronizes offline cache files with the Translaas API. It uses the inner HTTP client directly, not a CachingClient decorator.

func NewSyncService 

func NewSyncService(
	inner client.Client,
	cache Provider,
	options OfflineCacheOptions,
	callbacks SyncCallbacks,
) (*SyncService, error)

NewSyncService constructs a SyncService.

func (*SyncService) IsBackgroundSyncRunning 

func (s *SyncService) IsBackgroundSyncRunning() bool

IsBackgroundSyncRunning reports whether StartBackgroundSync started a loop that has not stopped.

func (*SyncService) StartBackgroundSync 

func (s *SyncService) StartBackgroundSync(ctx context.Context)

StartBackgroundSync runs an initial SyncAll, then repeats on AutoSyncInterval until ctx is canceled.

func (*SyncService) StopBackgroundSync 

func (s *SyncService) StopBackgroundSync()

StopBackgroundSync cancels the background loop and waits for it to exit.

func (*SyncService) SyncAll 

func (s *SyncService) SyncAll(ctx context.Context) (*SyncResult, error)

SyncAll synchronizes every project listed in OfflineCacheOptions.Projects.

func (*SyncService) SyncFromOfflineZip 

func (s *SyncService) SyncFromOfflineZip(ctx context.Context, project string) error

SyncFromOfflineZip downloads the offline ZIP for project via the inner client and imports it. It is a no-op when GetOfflineCache returns NotModified or empty content.

func (*SyncService) SyncProject 

func (s *SyncService) SyncProject(ctx context.Context, project, lang string) error

SyncProject fetches one project language from the API and persists it to disk.

func (*SyncService) SyncProjectAllLanguages 

func (s *SyncService) SyncProjectAllLanguages(ctx context.Context, project string) error

SyncProjectAllLanguages fetches locales and syncs each configured language for a project.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.