4 System Services

Racket

4 System Services🔗ℹ

package: rivet

The generated native host installs a system-adapter during startup. Headless tools and tests may parameterize current-system-adapter with a deterministic adapter. The default adapter fails closed instead of silently pretending that an operating-system action succeeded.

struct
(struct system-adapter ( name
capabilities
acquire-single-instance
register-activation-handler
show-notification
set-tray-menu
set-autostart
autostart-enabled
secure-store-set
secure-store-ref
secure-store-remove
install-crash-hook))
  name : symbol?
  capabilities : list?
  acquire-single-instance : procedure?
  register-activation-handler : procedure?
  show-notification : procedure?
  set-tray-menu : procedure?
  set-autostart : procedure?
  autostart-enabled : procedure?
  secure-store-set : procedure?
  secure-store-ref : procedure?
  secure-store-remove : procedure?
  install-crash-hook : procedure?

Defines the operations supplied by a first-party native host or a test double.

parameter
(current-system-adapter) → system-adapter?
(current-system-adapter adapter) → void?
adapter : system-adapter?

The adapter used by all system-service convenience procedures.

struct
(struct settings-store (path lock data)
    #:mutable)
  path : path?
  lock : semaphore?
  data : hash?

Represents one synchronized, JSON-backed preferences file.

parameter
(current-rivet-log-sink) → procedure?
(current-rivet-log-sink sink) → void?
sink : procedure?

Receives each structured log record. The default writes JSON to the current error port.

parameter
(current-rivet-crash-reporter) → procedure?
(current-rivet-crash-reporter reporter) → void?
reporter : procedure?

Receives a structured crash record and its exception. The default is a no-op.

procedure
(system-capabilities) → list?

Returns capability symbols advertised by the active adapter.

procedure
(acquire-single-instance! application-id
activation) → any/c
application-id : string?
activation : any/c

Acquires the application instance lock or forwards activation data to the existing instance, according to the native adapter.

procedure
(register-activation-handler! handler) → any/c
handler : procedure?

Registers the handler for deep links, file associations, and forwarded secondary-instance activation.

procedure
(show-system-notification! title
body
[ #:tag tag]) → any/c
  title : string?
  body : string?
  tag : (or/c #f string?) = #f

Displays an operating-system notification.

procedure
(set-tray-menu! items) → any/c
items : list?

Configures a Windows tray or macOS menu-bar menu.

procedure
(set-autostart! enabled?) → any/c
enabled? : boolean?

Enables or disables login startup.

procedure
(autostart-enabled?) → boolean?

Reports the current login-startup state.

procedure
(secure-store-set! service account secret) → any/c
  service : string?
  account : string?
  secret : bytes?

Stores a secret through Windows Credential Manager or macOS Keychain.

procedure
(secure-store-ref service account [default]) → any/c
  service : string?
  account : string?
  default : any/c = #f

Reads a secret, returning default when no value is present.

procedure
(secure-store-remove! service account) → any/c
service : string?
account : string?

Removes a stored secret.

4.1 Settings and Diagnostics🔗ℹ

procedure
(make-settings-store path) → settings-store?
path : path-string?

Loads an atomic JSON-backed settings store.

procedure
(settings-ref store key [default]) → any/c
  store : settings-store?
  key : (or/c symbol? string?)
  default : any/c = #f

Reads a setting.

procedure
(settings-set! store key value) → any/c
  store : settings-store?
  key : (or/c symbol? string?)
  value : any/c

Persists a setting using atomic file replacement.

procedure
(settings-remove! store key) → void?
store : settings-store?
key : (or/c symbol? string?)

Removes a persisted setting.

procedure
(settings-snapshot store) → hash?
store : settings-store?

Returns the current immutable settings hash.

procedure
(rivet-log level event [#:fields fields]) → hash?
  level : (or/c 'debug 'info 'warning 'error 'critical)
  event : any/c
  fields : hash? = (hasheq)

Sends a structured record to current-rivet-log-sink and returns it.

procedure
(call-with-crash-reporting thunk
[ #:context context]) → any/c
thunk : (-> any/c)
context : hash? = (hasheq)

Reports an uncaught Racket exception through current-rivet-crash-reporter, then re-raises it.

1	Installation
2	Architecture and Module Boundaries
3	Application Backend
4	System Services
5	Distribution and Secure Updates
6	Command-Line Workflow
7	Further Reading