Documentation
¶
Overview ¶
Package pwa provides small, explicit Progressive Web App helpers that stay outside the core rendering runtime. The current shipped surface covers web app manifest generation, explicit service-worker registration and update lifecycle coordination, installability observation, release-manifest to service-worker asset planning, Cache Storage coordination, and structured PWA diagnostics so applications can add installability and offline behavior without hiding ownership inside unrelated runtime code.
Index ¶
- Constants
- func MarshalManifestJSON(parseManifest Manifest) ([]byte, error)
- func MarshalManifestJSONIndented(parseManifest Manifest, parsePrefix, parseIndent string) ([]byte, error)
- type BackgroundSyncCapabilities
- type CacheStorageAssetKind
- type CacheStorageEntry
- type CacheStorageManager
- type CacheStoragePlan
- type CacheStoragePlanOptions
- type CacheStorageSnapshot
- type CacheStorageStrategy
- type DiagnosticsOptions
- type DiagnosticsSnapshot
- type InstallPromptResult
- type InstallabilityManager
- func (parseManager InstallabilityManager) Prompt(parseInstallCtx context.Context) (InstallPromptResult, error)
- func (parseManager InstallabilityManager) State() InstallabilityState
- func (parseManager InstallabilityManager) Subscribe(parseInstallHandler func(InstallabilityState)) (InstallabilitySubscription, error)
- type InstallabilityOptions
- type InstallabilityState
- type InstallabilitySubscription
- type Manifest
- type ManifestDiagnostics
- type ManifestDisplay
- type ManifestImage
- type ManifestOrientation
- type ManifestShortcut
- type OfflineQueueDiagnostics
- type OfflineQueueEntry
- type RelatedApplication
- type ServiceWorkerAssetPlan
- type ServiceWorkerAssetPlanOptions
- type ServiceWorkerOptions
- type ServiceWorkerRegistration
- func (parseRegistration ServiceWorkerRegistration) BackgroundSyncCapabilities() BackgroundSyncCapabilities
- func (parseRegistration ServiceWorkerRegistration) RegisterSync(parseSyncCtx context.Context, parseSyncTag string) error
- func (parseRegistration ServiceWorkerRegistration) ReloadOnControllerChange() (ServiceWorkerSubscription, error)
- func (parseRegistration ServiceWorkerRegistration) SkipWaiting(parseSkipCtx context.Context) error
- func (parseRegistration ServiceWorkerRegistration) Snapshot() ServiceWorkerSnapshot
- func (parseRegistration ServiceWorkerRegistration) SubscribeLifecycle(parseLifecycleHandler func(ServiceWorkerSnapshot)) (ServiceWorkerSubscription, error)
- func (parseRegistration ServiceWorkerRegistration) Unregister(parseUnregisterCtx context.Context) (bool, error)
- func (parseRegistration ServiceWorkerRegistration) Update(parseUpdateCtx context.Context) error
- type ServiceWorkerSnapshot
- type ServiceWorkerState
- type ServiceWorkerSubscription
- type ServiceWorkerVersion
- type StoragePressureDiagnostics
- type Subscription
- type UpdatePrompt
- type VersionSkewRefreshDecision
- type VersionSkewRefreshInput
- type WasmReleaseArtifact
- type WasmReleaseFlags
- type WasmReleaseManifest
- type WasmRolloutConfig
- type WasmRolloutDecision
Examples ¶
Constants ¶
const ( ServiceWorkerTypeClassic string = "classic" ServiceWorkerTypeModule string = "module" )
Service-worker script type values for ServiceWorkerOptions.Type (the standard ServiceWorkerContainer.register `type` option). String constants — assignable to the field — so a typo is a compile error at the use site instead of a silent registration quirk.
const ( UpdateViaCacheImports string = "imports" UpdateViaCacheAll string = "all" UpdateViaCacheNone string = "none" )
HTTP-cache policy values for ServiceWorkerOptions.UpdateViaCache (the standard `updateViaCache` option): "imports" (default — bypass cache for the top script, use it for imports), "all" (use the cache for both), "none" (bypass for both).
Variables ¶
This section is empty.
Functions ¶
func MarshalManifestJSON ¶
MarshalManifestJSON serializes a normalized, validated Manifest to JSON bytes.
Types ¶
type BackgroundSyncCapabilities ¶
func (BackgroundSyncCapabilities) Available ¶
func (parseCapabilities BackgroundSyncCapabilities) Available() bool
type CacheStorageAssetKind ¶
type CacheStorageAssetKind string
const ( CacheStorageAssetKindShell CacheStorageAssetKind = "shell" CacheStorageAssetKindWasm CacheStorageAssetKind = "wasm" CacheStorageAssetKindScript CacheStorageAssetKind = "script" CacheStorageAssetKindStyle CacheStorageAssetKind = "style" CacheStorageAssetKindMedia CacheStorageAssetKind = "media" CacheStorageAssetKindAsset CacheStorageAssetKind = "asset" )
type CacheStorageEntry ¶
type CacheStorageEntry struct {
URL string
Kind CacheStorageAssetKind
Strategy CacheStorageStrategy
}
type CacheStorageManager ¶
type CacheStorageManager struct {
// contains filtered or unexported fields
}
func OpenCacheStorageManager ¶
func OpenCacheStorageManager() (CacheStorageManager, error)
OpenCacheStorageManager is a non-browser stub that always returns an unavailable error.
func (CacheStorageManager) Inspect ¶
func (parseM CacheStorageManager) Inspect(parseCtx context.Context, parsePlan CacheStoragePlan) (CacheStorageSnapshot, error)
func (CacheStorageManager) Sync ¶
func (parseM CacheStorageManager) Sync(parseCtx context.Context, parsePlan CacheStoragePlan) (CacheStorageSnapshot, error)
type CacheStoragePlan ¶
type CacheStoragePlan struct {
CacheName string
CachePrefix string
ManifestRevision string
Entries []CacheStorageEntry
}
func BuildCacheStoragePlan ¶
func BuildCacheStoragePlan(parseAssetPlan ServiceWorkerAssetPlan, parseOptions ...CacheStoragePlanOptions) (CacheStoragePlan, error)
BuildCacheStoragePlan builds a CacheStoragePlan from a ServiceWorkerAssetPlan and optional options.
Example ¶
ExampleBuildCacheStoragePlan shows building a service-worker cache plan from an asset plan, the input to a generated service worker for offline support.
package main
import (
"github.com/monstercameron/GoWebComponents/v4/pwa"
)
func main() {
parsePlan, parseErr := pwa.BuildCacheStoragePlan(pwa.ServiceWorkerAssetPlan{})
if parseErr != nil {
return
}
_ = parsePlan
}
Output:
type CacheStoragePlanOptions ¶
type CacheStorageSnapshot ¶
type CacheStorageSnapshot struct {
CacheName string
CachePrefix string
EntryCount int
Entries []CacheStorageEntry
CacheNames []string
}
type CacheStorageStrategy ¶
type CacheStorageStrategy string
const ( CacheStorageStrategyCacheFirst CacheStorageStrategy = "cache-first" CacheStorageStrategyNetworkFirst CacheStorageStrategy = "network-first" CacheStorageStrategyStaleWhileRevalidate CacheStorageStrategy = "stale-while-revalidate" )
type DiagnosticsOptions ¶
type DiagnosticsOptions struct {
Manifest *Manifest
Installability *InstallabilityManager
ServiceWorker *ServiceWorkerRegistration
CacheStorage *CacheStorageManager
CacheStoragePlan *CacheStoragePlan
OfflineQueue func() ([]OfflineQueueEntry, error)
}
type DiagnosticsSnapshot ¶
type DiagnosticsSnapshot struct {
Manifest ManifestDiagnostics
Installability InstallabilityState
ServiceWorker ServiceWorkerSnapshot
CacheStorage CacheStorageSnapshot
OfflineQueue OfflineQueueDiagnostics
Storage StoragePressureDiagnostics
}
func InspectDiagnostics ¶
func InspectDiagnostics(parseDiagnosticsCtx context.Context, parseDiagnosticsOptions DiagnosticsOptions) (DiagnosticsSnapshot, error)
InspectDiagnostics is a non-browser stub that always returns an unavailable error.
type InstallPromptResult ¶
type InstallabilityManager ¶
type InstallabilityManager struct {
// contains filtered or unexported fields
}
func ObserveInstallability ¶
func ObserveInstallability(parseInstallOptions InstallabilityOptions) (InstallabilityManager, error)
ObserveInstallability is a non-browser stub that always returns an unavailable error.
func (InstallabilityManager) Prompt ¶
func (parseManager InstallabilityManager) Prompt(parseInstallCtx context.Context) (InstallPromptResult, error)
func (InstallabilityManager) State ¶
func (parseManager InstallabilityManager) State() InstallabilityState
func (InstallabilityManager) Subscribe ¶
func (parseManager InstallabilityManager) Subscribe(parseInstallHandler func(InstallabilityState)) (InstallabilitySubscription, error)
type InstallabilityOptions ¶
type InstallabilityOptions struct {
Manifest *Manifest
}
type InstallabilityState ¶
type InstallabilitySubscription ¶
type InstallabilitySubscription = Subscription
InstallabilitySubscription is the handle returned by InstallabilityManager.Subscribe.
type Manifest ¶
type Manifest struct {
ID string `json:"id,omitempty"`
Name string `json:"name,omitempty"`
ShortName string `json:"short_name,omitempty"`
Description string `json:"description,omitempty"`
StartURL string `json:"start_url,omitempty"`
Scope string `json:"scope,omitempty"`
Display ManifestDisplay `json:"display,omitempty"`
DisplayOverride []ManifestDisplay `json:"display_override,omitempty"`
Orientation ManifestOrientation `json:"orientation,omitempty"`
ThemeColor string `json:"theme_color,omitempty"`
BackgroundColor string `json:"background_color,omitempty"`
Lang string `json:"lang,omitempty"`
Dir string `json:"dir,omitempty"`
Categories []string `json:"categories,omitempty"`
Icons []ManifestImage `json:"icons,omitempty"`
Screenshots []ManifestImage `json:"screenshots,omitempty"`
Shortcuts []ManifestShortcut `json:"shortcuts,omitempty"`
PreferRelatedApplications bool `json:"prefer_related_applications,omitempty"`
RelatedApplications []RelatedApplication `json:"related_applications,omitempty"`
}
func (Manifest) Normalized ¶
type ManifestDiagnostics ¶
type ManifestDisplay ¶
type ManifestDisplay string
const ( ManifestDisplayBrowser ManifestDisplay = "browser" ManifestDisplayMinimalUI ManifestDisplay = "minimal-ui" ManifestDisplayStandalone ManifestDisplay = "standalone" ManifestDisplayFullscreen ManifestDisplay = "fullscreen" ManifestDisplayWindowControlsOverlay ManifestDisplay = "window-controls-overlay" )
func (ManifestDisplay) Normalized ¶
func (parseD ManifestDisplay) Normalized() ManifestDisplay
func (ManifestDisplay) Valid ¶
func (parseD ManifestDisplay) Valid() bool
type ManifestImage ¶
type ManifestOrientation ¶
type ManifestOrientation string
const ( ManifestOrientationAny ManifestOrientation = "any" ManifestOrientationNatural ManifestOrientation = "natural" ManifestOrientationLandscape ManifestOrientation = "landscape" ManifestOrientationLandscapePrimary ManifestOrientation = "landscape-primary" ManifestOrientationLandscapeSecondary ManifestOrientation = "landscape-secondary" ManifestOrientationPortrait ManifestOrientation = "portrait" ManifestOrientationPortraitPrimary ManifestOrientation = "portrait-primary" ManifestOrientationPortraitSecondary ManifestOrientation = "portrait-secondary" )
func (ManifestOrientation) Normalized ¶
func (parseO ManifestOrientation) Normalized() ManifestOrientation
func (ManifestOrientation) Valid ¶
func (parseO ManifestOrientation) Valid() bool
type ManifestShortcut ¶
type ManifestShortcut struct {
Name string `json:"name,omitempty"`
ShortName string `json:"short_name,omitempty"`
Description string `json:"description,omitempty"`
URL string `json:"url,omitempty"`
Icons []ManifestImage `json:"icons,omitempty"`
}
type OfflineQueueDiagnostics ¶
type OfflineQueueEntry ¶
type RelatedApplication ¶
type ServiceWorkerAssetPlan ¶
type ServiceWorkerAssetPlan struct {
CacheName string
ManifestRevision string
WasmURL string
ImmutableURLs []string
ShellURLs []string
PrecacheURLs []string
}
func BuildServiceWorkerAssetPlan ¶
func BuildServiceWorkerAssetPlan(parseManifest WasmReleaseManifest, parseOptions ...ServiceWorkerAssetPlanOptions) (ServiceWorkerAssetPlan, error)
BuildServiceWorkerAssetPlan builds a ServiceWorkerAssetPlan from a validated WasmReleaseManifest.
type ServiceWorkerOptions ¶
type ServiceWorkerOptions struct {
URL string
Scope string
// Type is the worker script type: use ServiceWorkerTypeClassic / ServiceWorkerTypeModule
// (a typo'd string silently registers nothing useful).
Type string
// UpdateViaCache is the HTTP-cache policy for the worker script + its imports: use
// UpdateViaCacheImports / UpdateViaCacheAll / UpdateViaCacheNone.
UpdateViaCache string
}
type ServiceWorkerRegistration ¶
type ServiceWorkerRegistration struct {
// contains filtered or unexported fields
}
func RegisterServiceWorker ¶
func RegisterServiceWorker(parseServiceCtx context.Context, parseServiceOptions ServiceWorkerOptions) (ServiceWorkerRegistration, error)
RegisterServiceWorker is a non-browser stub that always returns an unavailable error.
func (ServiceWorkerRegistration) BackgroundSyncCapabilities ¶
func (parseRegistration ServiceWorkerRegistration) BackgroundSyncCapabilities() BackgroundSyncCapabilities
func (ServiceWorkerRegistration) RegisterSync ¶
func (parseRegistration ServiceWorkerRegistration) RegisterSync(parseSyncCtx context.Context, parseSyncTag string) error
func (ServiceWorkerRegistration) ReloadOnControllerChange ¶
func (parseRegistration ServiceWorkerRegistration) ReloadOnControllerChange() (ServiceWorkerSubscription, error)
func (ServiceWorkerRegistration) SkipWaiting ¶
func (parseRegistration ServiceWorkerRegistration) SkipWaiting(parseSkipCtx context.Context) error
func (ServiceWorkerRegistration) Snapshot ¶
func (parseRegistration ServiceWorkerRegistration) Snapshot() ServiceWorkerSnapshot
func (ServiceWorkerRegistration) SubscribeLifecycle ¶
func (parseRegistration ServiceWorkerRegistration) SubscribeLifecycle(parseLifecycleHandler func(ServiceWorkerSnapshot)) (ServiceWorkerSubscription, error)
func (ServiceWorkerRegistration) Unregister ¶
func (parseRegistration ServiceWorkerRegistration) Unregister(parseUnregisterCtx context.Context) (bool, error)
type ServiceWorkerSnapshot ¶
type ServiceWorkerSnapshot struct {
Scope string
HasController bool
Installing ServiceWorkerVersion
Waiting ServiceWorkerVersion
Active ServiceWorkerVersion
}
type ServiceWorkerState ¶
type ServiceWorkerState string
const ( ServiceWorkerStateInstalling ServiceWorkerState = "installing" ServiceWorkerStateInstalled ServiceWorkerState = "installed" ServiceWorkerStateActivating ServiceWorkerState = "activating" ServiceWorkerStateActivated ServiceWorkerState = "activated" ServiceWorkerStateRedundant ServiceWorkerState = "redundant" )
type ServiceWorkerSubscription ¶
type ServiceWorkerSubscription = Subscription
ServiceWorkerSubscription is the handle returned by ServiceWorkerRegistration.SubscribeLifecycle and ReloadOnControllerChange.
type ServiceWorkerVersion ¶
type ServiceWorkerVersion struct {
ScriptURL string
State ServiceWorkerState
}
type Subscription ¶
type Subscription struct {
// contains filtered or unexported fields
}
Subscription is a cancellable handle returned by the package's subscribe APIs (service-worker lifecycle, installability). Cancel stops delivery and is safe to call more than once. The two named aliases below preserve the original API surface while sharing one implementation.
func (Subscription) Cancel ¶
func (parseSubscription Subscription) Cancel()
Cancel stops the subscription's callbacks. No-op if already cancelled or never armed.
type UpdatePrompt ¶
type UpdatePrompt struct {
// contains filtered or unexported fields
}
UpdatePrompt is the composite "a new version is available" flow on top of the service-worker lifecycle primitives. An app wires it to a banner: when a new service worker is waiting, Available() becomes true and the OnChange callback fires; calling Apply activates the new worker (SkipWaiting) and reloads once it takes control (ReloadOnControllerChange). This is the E3 10-rung "update-prompt flow" as one object, so apps don't hand-assemble the three primitives (the prior gap was that the primitives existed but the composite did not).
func NewUpdatePrompt ¶
func NewUpdatePrompt(parseRegistration ServiceWorkerRegistration) *UpdatePrompt
NewUpdatePrompt builds an update-prompt controller for a registration.
func (*UpdatePrompt) Apply ¶
func (parsePrompt *UpdatePrompt) Apply(parseCtx context.Context) error
Apply activates the waiting worker and reloads the page once it takes control. It arms the controller-change reload BEFORE skipping waiting so the reload fires on activation, not before.
func (*UpdatePrompt) Available ¶
func (parsePrompt *UpdatePrompt) Available() bool
Available reports whether a new service worker is waiting to take over.
func (*UpdatePrompt) OnChange ¶
func (parsePrompt *UpdatePrompt) OnChange(parseHandler func(bool))
OnChange registers the callback invoked whenever update-availability changes (e.g. to show or hide a banner). It is called with the current availability immediately if already started.
func (*UpdatePrompt) Start ¶
func (parsePrompt *UpdatePrompt) Start() error
Start subscribes to the service-worker lifecycle and begins tracking whether a waiting worker (a ready update) exists. It is idempotent.
func (*UpdatePrompt) Stop ¶
func (parsePrompt *UpdatePrompt) Stop()
Stop cancels the lifecycle subscription.
type VersionSkewRefreshDecision ¶
type VersionSkewRefreshDecision struct {
Mismatch bool
ShouldReload bool
BypassCache bool
LoopGuarded bool
SnapshotBeforeReload []byte
RestoreAfterReload bool
Reason string
}
func EvaluateVersionSkewRefresh ¶
func EvaluateVersionSkewRefresh(parseInput VersionSkewRefreshInput) VersionSkewRefreshDecision
EvaluateVersionSkewRefresh decides whether a stale wasm/client build should perform one cache-bypassing reload and carry a compatible state snapshot across that refresh.
type VersionSkewRefreshInput ¶
type WasmReleaseArtifact ¶
type WasmReleaseFlags ¶
type WasmReleaseManifest ¶
type WasmReleaseManifest struct {
Package string `json:"package,omitempty"`
Profile string `json:"profile,omitempty"`
GOOS string `json:"goos,omitempty"`
GOARCH string `json:"goarch,omitempty"`
BuildID string `json:"buildId,omitempty"`
Flags WasmReleaseFlags `json:"flags"`
Artifacts map[string]WasmReleaseArtifact `json:"artifacts,omitempty"`
}
func ParseWasmReleaseManifestJSON ¶
func ParseWasmReleaseManifestJSON(parseData []byte) (WasmReleaseManifest, error)
ParseWasmReleaseManifestJSON parses and validates a WasmReleaseManifest from JSON bytes.
func (WasmReleaseManifest) Normalized ¶
func (parseM WasmReleaseManifest) Normalized() WasmReleaseManifest
func (WasmReleaseManifest) Revision ¶
func (parseM WasmReleaseManifest) Revision() string
func (WasmReleaseManifest) Validate ¶
func (parseM WasmReleaseManifest) Validate() error
type WasmRolloutConfig ¶
type WasmRolloutConfig struct {
Stable WasmReleaseManifest
Canary WasmReleaseManifest
CanaryPercent int
Salt string
CacheTTLSeconds int
Rollback bool
}
type WasmRolloutDecision ¶
type WasmRolloutDecision struct {
Cohort string
BuildID string
WasmURL string
SHA256 string
ManifestRevision string
CacheTTLSeconds int
RolledBack bool
}
func ChooseWasmRollout ¶
func ChooseWasmRollout(parseConfig WasmRolloutConfig, parseClientID string) (WasmRolloutDecision, error)
ChooseWasmRollout deterministically assigns one client to the stable or canary wasm artifact. Rollback forces every client to stable immediately and caps the response TTL at one second so caches converge quickly.