runtime

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Aug 1, 2026 License: MIT Imports: 52 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EmitNFCTag 

func EmitNFCTag(uid string)

EmitNFCTag lets a native NFC backend (e.g. the gomobile bridge) push a "nfc:tag" event without depending on the Provider interface for it.

func GetArchInfo 

func GetArchInfo() string

func GetEnvInfo 

func GetEnvInfo(key string) string

func Getenv 

func Getenv(key string) string
func MenuSupported() bool

MenuSupported reports whether this platform has a native menu-bar backend (macOS today). Query it (or goleo:capabilities) before offering menu UI.

func NewEmbedFS 

func NewEmbedFS(e embed.FS, subDir string) (fs.FS, error)

func NotificationPermissionGranted 

func NotificationPermissionGranted() bool

func Notify 

func Notify(title, body string) error

func OpenURL 

func OpenURL(url string) error

func RegisterBLE 

func RegisterBLE(b *Bridge)

func RegisterBackground 

func RegisterBackground(b *Bridge)

func RegisterBattery 

func RegisterBattery(b *Bridge)

func RegisterBuiltins 

func RegisterBuiltins(b *Bridge)

func RegisterCamera 

func RegisterCamera(b *Bridge)

func RegisterClipboard 

func RegisterClipboard(b *Bridge)

func RegisterDesktopFeatures 

func RegisterDesktopFeatures(b *Bridge)

RegisterDesktopFeatures registers all host features that are available on desktop (Windows, macOS, Linux). On mobile this file is excluded at compile time, so no extra permissions are declared.

func RegisterDialogs 

func RegisterDialogs(b *Bridge)

func RegisterFS 

func RegisterFS(b *Bridge)

func RegisterGeolocation 

func RegisterGeolocation(b *Bridge)

func RegisterNFC 

func RegisterNFC(b *Bridge)

func RegisterPush 

func RegisterPush(b *Bridge)

func RegisterSampleCommands 

func RegisterSampleCommands(b *Bridge)

func RegisterSensors 

func RegisterSensors(b *Bridge)

func RegisterShare 

func RegisterShare(b *Bridge)

func RegisterStore 

func RegisterStore(b *Bridge)

RegisterStore exposes the persistent key/value store to the frontend. Unlike device features it needs no build tag or permission and works on every target (the Go backend owns a JSON file in the app data dir); the frontend falls back to localStorage when there is no backend (PWA).

func RegisterUpdater 

func RegisterUpdater(b *Bridge, cfg UpdaterConfig)

RegisterUpdater exposes desktop auto-update to the frontend. Mobile/PWA apps update through their store, so this is opt-in and desktop-only. cfg carries the signed-manifest URL, the embedded ed25519 public key (base64), and the running app version.

func RegisterVibration 

func RegisterVibration(b *Bridge)

func RegisterWakeLock 

func RegisterWakeLock(b *Bridge)

func RequestNotificationPermission 

func RequestNotificationPermission() string

func SetBLEProvider 

func SetBLEProvider(p BLEProvider)

func SetBackgroundProvider 

func SetBackgroundProvider(p BackgroundProvider)

func SetBatteryProvider 

func SetBatteryProvider(p BatteryProvider)

func SetCameraProvider 

func SetCameraProvider(p CameraProvider)

func SetClipboardProvider 

func SetClipboardProvider(p ClipboardProvider)

func SetDialogsProvider 

func SetDialogsProvider(p DialogsProvider)

func SetGeolocationProvider 

func SetGeolocationProvider(p GeolocationProvider)

func SetNFCProvider 

func SetNFCProvider(p NFCProvider)

func SetNativeNotifier 

func SetNativeNotifier(n NativeNotifier)

func SetPushProvider 

func SetPushProvider(p PushProvider)

func SetSensorsProvider 

func SetSensorsProvider(p SensorsProvider)

func SetShareProvider 

func SetShareProvider(p ShareProvider)

func SetVibrationProvider 

func SetVibrationProvider(p VibrationProvider)

func SetWakeLockProvider 

func SetWakeLockProvider(p WakeLockProvider)

func TraySupported 

func TraySupported() bool

TraySupported reports whether this platform/build can show a system tray icon. False on mobile and wasm/PWA builds.

func WindowingSupported 

func WindowingSupported() bool

WindowingSupported reports whether this platform/build can open additional native windows (see App.OpenWindow). False on mobile and wasm/PWA builds, where the platform hosts a single WebView itself. Developer code can check this before calling windowing APIs; the APIs also guard internally.

Types

type App 

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

func New 

func New(cfg Config) *App

func (*App) Bridge 

func (a *App) Bridge() *Bridge

func (*App) CloseWindow 

func (a *App) CloseWindow(id int) error

CloseWindow closes the window with the given id. Guarded like OpenWindow.

func (*App) Config 

func (a *App) Config() Config

func (*App) Emit 

func (a *App) Emit(event string, data any)

func (*App) Invoke 

func (a *App) Invoke(name string, fn InvokeHandler)

func (*App) ListWindows 

func (a *App) ListWindows() ([]int, error)

ListWindows returns the ids of open managed windows. On platforms without windowing it returns an errors.ErrUnsupported-wrapped error.

func (*App) On 

func (a *App) On(event string, fn EventHandler)

func (*App) OpenWindow 

func (a *App) OpenWindow(opts WindowOptions) (int, error)

OpenWindow opens an additional native window (a child process hosting one webview) and returns its id. Guarded: on platforms without native windowing (mobile, wasm/PWA) it returns an errors.ErrUnsupported-wrapped error rather than attempting to run. Available after Run has started the desktop app.

func (*App) Quit 

func (a *App) Quit()

Quit triggers a graceful shutdown: it unblocks the run loop, which closes all managed windows (CloseAll), runs OnShutdown, and stops the server. Safe to call from any goroutine — a bridge handler, an OS signal, or an ExitOnClose window closing — and idempotent (context cancellation is).

func (*App) Run 

func (a *App) Run() error

func (*App) SetMenu 

func (a *App) SetMenu(menu []MenuItem) error

SetMenu installs the application menu bar. Native on macOS; returns an errors.ErrUnsupported-wrapped error on Windows/Linux/mobile (no native menu bar yet — use an in-page HTML menu there). Safe to call after Run has started or from Config.Menu at startup.

func (*App) SetPolicy 

func (a *App) SetPolicy(p *Policy)

SetPolicy installs a capability ACL (see Policy) enforced on every invoke. Call before Run. Passing nil (the default) disables enforcement.

func (*App) StartServer 

func (a *App) StartServer() (int, error)

func (*App) Stop 

func (a *App) Stop()

Stop is a deprecated alias for Quit.

type BLEDevice 

type BLEDevice = bluetooth.BLEDevice

type BLEProvider 

type BLEProvider = bluetooth.Provider

BLEProvider and BLEDevice are re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type BackgroundProvider 

type BackgroundProvider = background.Provider

BackgroundProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type BatteryInfo 

type BatteryInfo = battery.BatteryInfo

type BatteryProvider 

type BatteryProvider = battery.Provider

BatteryProvider and BatteryInfo are re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type Bridge 

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

func NewBridge 

func NewBridge() *Bridge

func (*Bridge) Call 

func (b *Bridge) Call(method string, args any) (any, error)

func (*Bridge) DispatchEvent 

func (b *Bridge) DispatchEvent(event string, data json.RawMessage)

func (*Bridge) Emit 

func (b *Bridge) Emit(event string, data any)

func (*Bridge) Handle 

func (b *Bridge) Handle(name string, fn InvokeHandler)

func (*Bridge) HandleRequest 

func (b *Bridge) HandleRequest(req InvokeRequest) InvokeResponse

func (*Bridge) On 

func (b *Bridge) On(event string, fn EventHandler)

func (*Bridge) SetPolicy 

func (b *Bridge) SetPolicy(p *Policy)

SetPolicy installs a capability ACL enforced on every invoke. Passing nil disables enforcement (the default). See Policy.

func (*Bridge) Subscribe 

func (b *Bridge) Subscribe() chan EventMessage

func (*Bridge) Unsubscribe 

func (b *Bridge) Unsubscribe(ch chan EventMessage)

type CameraProvider 

type CameraProvider = camera.Provider

CameraProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type ClipboardProvider 

type ClipboardProvider = clipboard.Provider

ClipboardProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type Config 

type Config struct {
	Title      string
	Width      int
	Height     int
	DevMode    bool
	DevServer  string
	Port       int
	WindowMode WindowMode
	EmbedFS    any
	// InProcessWindows opts additional windows into the in-process model
	// (each on its own OS thread) instead of child processes. Windows only for
	// now; ignored elsewhere (falls back to multi-process). See spikes/win-multiwindow.
	InProcessWindows bool
	// NativeIPC routes the primary window's frontend<->backend calls over the
	// webview's in-process message channel (Bind/Eval) instead of the loopback
	// WebSocket, when a native webview hosts the UI. The WebSocket/HTTP server
	// stays up and remains the transport for child-process windows, browser/PWA,
	// and mobile — so the @goleo/bridge auto-detects the native channel and
	// falls back transparently. Lower latency and no WS surface for that window.
	// See nativeipc.go. Desktop (WindowModeWebview) only.
	NativeIPC bool
	// SchemeAssets serves the primary window's embedded UI from a portless, secure
	// custom origin (AssetScheme://, default "goleo://") instead of the loopback
	// HTTP server — so with NativeIPC on, that window opens no TCP port at all
	// while keeping a secure context (localStorage/crypto.subtle/getUserMedia).
	// Takes effect only in production (embedded FS, not DevMode) on backends that
	// support it (macOS/Linux via glaze); elsewhere it transparently falls back to
	// the loopback server. The server stays up as the fallback transport.
	SchemeAssets bool
	// AssetScheme overrides the custom scheme name used by SchemeAssets
	// (default "goleo"). Must be a plain scheme token, no "://".
	AssetScheme string
	// SingleInstance, when true, allows only one running instance; a second
	// launch forwards its args to the running one (emitting app:secondInstance)
	// and exits. AppID identifies the app for the lock (defaults to Title).
	SingleInstance bool
	AppID          string
	// Background runs the app as a headless controller: no auto primary window
	// (open windows on demand via OpenWindow / the tray), and the main thread
	// runs the tray (if Tray is set) or blocks until Quit.
	Background bool
	// Tray adds a system tray icon + menu (used with Background). Desktop only.
	Tray *TrayConfig
	// OnReady runs (in a goroutine) once the server + window manager are up and
	// the port is known — where OpenWindow works. Unlike OnStartup, which runs
	// before the server binds.
	OnReady func(ctx context.Context)
	// URLScheme, if set (e.g. "myapp"), registers a custom URL scheme so
	// myapp:// links launch/wake the app. The frontend reads the launch URL via
	// goleo:initialURL and listens for app:openURL (forwarded from later launches).
	URLScheme string
	// InitJS is the path to a JavaScript startup script that controls window
	// creation (createWindow/getConfig API). When set, the file must exist.
	// When empty, init.js then backend/init.js are tried; if neither exists
	// the window is created from this Config directly.
	InitJS string
	// Menu is the native application menu bar (macOS). When empty, macOS installs
	// StandardMenu(Title) so webview keyboard shortcuts (Cmd+C/V/X/A/Z) work;
	// Windows/Linux have no native menu bar yet (use an in-page HTML menu). See
	// runtime/menu.go, App.SetMenu.
	Menu       []MenuItem
	OnStartup  func(ctx context.Context)
	OnShutdown func(ctx context.Context)
}

type DialogsProvider 

type DialogsProvider = dialogs.Provider

DialogsProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type EventHandler 

type EventHandler func(ctx context.Context, data json.RawMessage)

type EventMessage 

type EventMessage struct {
	Event string          `json:"event"`
	Data  json.RawMessage `json:"data,omitempty"`
}

type GeolocationProvider 

type GeolocationProvider = geolocation.Provider

GeolocationProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type Hub 

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

func (*Hub) GetAll 

func (h *Hub) GetAll() []*WSClient

type InvokeHandler 

type InvokeHandler func(ctx context.Context, args json.RawMessage) (any, error)

type InvokeRequest 

type InvokeRequest struct {
	ID     string          `json:"id"`
	Method string          `json:"method"`
	Args   json.RawMessage `json:"args,omitempty"`
}

type InvokeResponse 

type InvokeResponse struct {
	ID     string `json:"id"`
	Result any    `json:"result,omitempty"`
	Error  string `json:"error,omitempty"`
}

type JSRuntime 

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

func NewJSRuntime 

func NewJSRuntime(cfg Config, app *App) *JSRuntime

func (*JSRuntime) Run 

func (jsr *JSRuntime) Run() error

Run loads and executes the startup script. Resolution:

  • Config.InitJS set: that file must exist (embedded or on disk) — an error is returned if it cannot be loaded.
  • Config.InitJS empty: init.js, then backend/init.js are tried; if none exists Run returns nil and the app falls back to the built-in Go-driven window setup from Config.

func (*JSRuntime) Stop 

func (jsr *JSRuntime) Stop()
type MenuItem struct {
	Label       string
	Role        MenuRole
	Accelerator string // e.g. "cmd+q", "cmd+shift+z" (cmd/ctrl/alt/shift + key)
	OnClick     func()
	Submenu     []MenuItem
	Separator   bool
}

MenuItem is one entry in a native menu. A top-level MenuItem (with a Submenu) is a menu in the menu bar; nested items are its entries. Exactly one of Role / OnClick / Submenu / Separator is meaningful per item (Role wins over OnClick).

func StandardMenu 

func StandardMenu(appName string) []MenuItem

StandardMenu returns a conventional macOS menu bar — an App menu (Quit) and an Edit menu (undo/redo/cut/copy/paste/select-all) — so webview keyboard shortcuts work. Installed automatically on macOS when Config.Menu is empty; also a handy base to extend for custom menus. 

type MenuRole string

MenuRole is a standard menu action wired to the platform's native handler (e.g. the responder chain on macOS), so the item works without a Go callback. Roles are what make Cmd+C/V/X/A/Z etc. work in the webview on macOS. 

const (
	RoleNone      MenuRole = ""
	RoleQuit      MenuRole = "quit"
	RoleUndo      MenuRole = "undo"
	RoleRedo      MenuRole = "redo"
	RoleCut       MenuRole = "cut"
	RoleCopy      MenuRole = "copy"
	RolePaste     MenuRole = "paste"
	RoleSelectAll MenuRole = "selectAll"
	RoleMinimize  MenuRole = "minimize"
	RoleClose     MenuRole = "close"
)

type NFCMessage 

type NFCMessage = nfc.NFCMessage

type NFCProvider 

type NFCProvider = nfc.Provider

NFCProvider, NFCMessage and NFCRecord are re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type NFCRecord 

type NFCRecord = nfc.NFCRecord

type NativeNotifier 

type NativeNotifier = notify.Notifier

type OSInfo 

type OSInfo struct {
	OS      string `json:"os"`
	Arch    string `json:"arch"`
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

func GetOSInfo 

func GetOSInfo() OSInfo

type PlatformInfo 

type PlatformInfo struct {
	Platform  string `json:"platform"`
	IsMobile  bool   `json:"isMobile"`
	IsDesktop bool   `json:"isDesktop"`
	IsBrowser bool   `json:"isBrowser"`
}

func GetPlatformInfo 

func GetPlatformInfo() PlatformInfo

type Policy 

type Policy struct {
	// Allow lists permitted invoke methods. "goleo:store*" allows the whole
	// store plugin; "goleo:fsReadTextFile" allows exactly one command.
	Allow []string
	// FSRoots limits filesystem access to these path prefixes.
	FSRoots []string
	// HTTPHosts limits the http plugin to these hosts.
	HTTPHosts []string
	// ShellPrograms limits the shell plugin to these program names.
	ShellPrograms []string
}

Policy is a runtime capability ACL. When set on a Bridge (SetPolicy), every invoke is checked centrally before its handler runs: the method must be in Allow (exact match, or a "prefix*" wildcard) or an always-safe core command, otherwise it is denied. Scope lists further constrain specific plugins; an empty scope list leaves that plugin unconstrained (its method-level Allow still governs whether it can be called at all).

No policy set = no enforcement (legacy-permissive). Setting a policy opts into deny-by-default, matching Tauri's capability model.

func (*Policy) AllowsFSPath 

func (p *Policy) AllowsFSPath(path string) bool

AllowsFSPath reports whether path is within an allowed root. Empty FSRoots = unconstrained. Uses cleaned paths so "../" traversal cannot escape a root.

func (*Policy) AllowsHTTPHost 

func (p *Policy) AllowsHTTPHost(host string) bool

AllowsHTTPHost reports whether host is permitted. Empty HTTPHosts = unconstrained.

func (*Policy) AllowsShellProgram 

func (p *Policy) AllowsShellProgram(program string) bool

AllowsShellProgram reports whether program is permitted. Empty = unconstrained.

type PushProvider 

type PushProvider = push.Provider

PushProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type SensorsProvider 

type SensorsProvider = sensors.Provider

SensorsProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type Server 

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

func NewServer 

func NewServer(cfg Config, bridge *Bridge) (*Server, error)

func (*Server) Start 

func (s *Server) Start(ctx context.Context) (int, error)

func (*Server) Stop 

func (s *Server) Stop(ctx context.Context) error

type ShareData 

type ShareData = share.ShareData

type ShareProvider 

type ShareProvider = share.Provider

ShareProvider and ShareData are re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package.

type TrayConfig 

type TrayConfig struct {
	Icon    []byte
	Tooltip string
	Items   []TrayItem
}

TrayConfig configures an optional system tray icon + menu. Set Config.Tray (with Config.Background) to run as a tray app. Icon is PNG bytes.

type TrayItem 

type TrayItem struct {
	Label   string
	OnClick func()
}

TrayItem is one system-tray menu entry.

type UpdaterConfig 

type UpdaterConfig = updater.Config

UpdaterConfig is re-exported so apps can configure the updater without importing the sub-package.

type VibrationProvider 

type VibrationProvider = vibration.Provider

VibrationProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type WSClient 

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

type WakeLockProvider 

type WakeLockProvider = wakelock.Provider

WakeLockProvider is re-exported so shells (e.g. the gomobile bridge) can inject a native backend without importing the sub-package directly.

type WebviewWindow 

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

func NewWebviewWindow 

func NewWebviewWindow(cfg windowConfig) WebviewWindow

func (*WebviewWindow) Bind 

func (win *WebviewWindow) Bind(name string, fn any) error

func (*WebviewWindow) Destroy 

func (win *WebviewWindow) Destroy()

func (*WebviewWindow) Dispatch 

func (win *WebviewWindow) Dispatch(f func())

func (*WebviewWindow) Eval 

func (win *WebviewWindow) Eval(js string)

func (*WebviewWindow) Init 

func (win *WebviewWindow) Init(js string)

func (*WebviewWindow) IsValid 

func (win *WebviewWindow) IsValid() bool

func (*WebviewWindow) NativeHandle 

func (win *WebviewWindow) NativeHandle() unsafe.Pointer

NativeHandle returns the OS window handle — GtkWindow* on Linux, NSWindow* on macOS, HWND on Windows — used by the native menu-bar backend. Nil if the window isn't created.

func (*WebviewWindow) Navigate 

func (win *WebviewWindow) Navigate(url string)

func (*WebviewWindow) Run 

func (win *WebviewWindow) Run()

func (*WebviewWindow) SetSize 

func (win *WebviewWindow) SetSize(width, height int)

func (*WebviewWindow) SetTitle 

func (win *WebviewWindow) SetTitle(title string)

func (*WebviewWindow) Terminate 

func (win *WebviewWindow) Terminate()

type WindowManager 

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

WindowManager tracks additional webview windows, each running as a child process of this executable (see window_child.go). The primary window is still hosted in-process by App.runWebview; this manages every window opened after startup via App.OpenWindow / the goleo:window* bridge commands.

func (*WindowManager) Close 

func (wm *WindowManager) Close(id int) error

Close terminates the window with the given id. The webview child holds no unsaved state (it is pure UI), so killing the process is safe.

func (*WindowManager) CloseAll 

func (wm *WindowManager) CloseAll()

CloseAll terminates every managed window; called during shutdown.

func (*WindowManager) List 

func (wm *WindowManager) List() []int

List returns the ids of all currently open managed windows.

func (*WindowManager) Open 

func (wm *WindowManager) Open(opts WindowOptions) (int, error)

Open spawns a new window process and returns its id. The child connects to this process's server as an ordinary bridge client, so cross-window state and events flow through the existing hub.

type WindowMode 

type WindowMode int
const (
	WindowModeBrowser WindowMode = iota
	WindowModeWebview
	WindowModeMobile
)

type WindowOptions 

type WindowOptions struct {
	Title  string `json:"title"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
	// URL, if set, is loaded verbatim. Otherwise the window loads the app's own
	// server root plus Path (e.g. Path "/settings" → "<serverURL>/settings").
	URL  string `json:"url"`
	Path string `json:"path"`
	// ExitOnClose quits the whole app when this window closes (via App.Quit).
	// Default false: closing just closes the window; the app keeps running.
	ExitOnClose bool `json:"exitOnClose"`
}

WindowOptions describes an additional window to open at runtime.

Source Files

View all Source files

Directories

Path Synopsis
Package autostart registers/unregisters an app to launch on login.
 Package autostart registers/unregisters an app to launch on login.
Package deeplink registers a custom URL scheme (myapp://) so links launch or wake the app.
 Package deeplink registers a custom URL scheme (myapp://) so links launch or wake the app.
Package singleinstance enforces a single running instance of an app and forwards a later launch's args to the primary (e.g.
 Package singleinstance enforces a single running instance of an app and forwards a later launch's args to the primary (e.g.
Package store is a simple persistent key/value store backed by a JSON file in the app data directory.
 Package store is a simple persistent key/value store backed by a JSON file in the app data directory.
Package updater is a desktop auto-update client.
 Package updater is a desktop auto-update client.

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.