@mikrojs/native 0.18.0 → 0.18.2-next.20260826235606

package/runtime/ota/ota.ts

@@ -1,77 +1,41 @@
-import {readFile} from 'mikro/fs'
-import {sysGet, sysSet} from 'native:mikro/nvs_kv'
-import * as native from 'native:mikro/ota'
+// `mikro/ota` — the low-level update surface, for an app that talks to its own
+// registry. The built-in client (`mikro/ota/client`) covers the ordinary case
+// and does not go through here.
+//
+// Every member is the C policy (src/mik_ota_policy.cpp): the retry budget, the
+// trial gates and the staging session all live there, so this module and the
+// built-in client cannot disagree about the crash-loop latch they share.
+
+import {config} from 'mikro/ota/config'
+import {
+  applyConfig,
+  applyOffer,
+  bearer,
+  configState,
+  confirm,
+  parseConfig,
+  parseOffer,
+  reconcile,
+  registry,
+  revert,
+  running,
+} from 'native:mikro/ota_client'
 
-import {createOta, type OtaStore} from './policy.js'
 import type {Ota} from './types.js'
 
-// Policy state, persisted to the mik.sys NVS namespace so the retry budget
-// survives a crash-loop and app-level nvsStorage.clear() can't wipe it.
-// NVS keys are capped at 15 chars.
-// A dropped write cannot be recovered from here, but it must not pass in
-// silence: `ota.tries` and `ota.inflight` are the crash-loop latch, so losing
-// either hands the retry budget back on every boot and the bound that stops a
-// panicking build from being retried forever is gone.
-function put(key: string, value: string | number): void {
-  const r = sysSet(key, value)
-  // eslint-disable-next-line no-console
-  if (!r.ok) console.error(`ota: could not persist ${key}`, r.error)
-}
-
-const store: OtaStore = {
-  getUrl: () => {
-    const v = sysGet('ota.url')
-    return typeof v === 'string' ? v : undefined
-  },
-  setUrl: (url) => put('ota.url', url),
-  getAttempt: () => {
-    const v = sysGet('ota.att')
-    return typeof v === 'string' ? v : undefined
-  },
-  setAttempt: (checksum) => put('ota.att', checksum),
-  getTries: () => {
-    const v = sysGet('ota.tries')
-    return typeof v === 'number' ? v : 0
-  },
-  setTries: (n) => put('ota.tries', n),
-  getBad: () => {
-    const v = sysGet('ota.bad')
-    return typeof v === 'string' ? v : undefined
-  },
-  setBad: (checksum) => put('ota.bad', checksum),
-  getInFlight: () => sysGet('ota.inflight') === 1,
-  setInFlight: (value) => put('ota.inflight', value ? 1 : 0),
-}
-
-// Written as a pair to mik.sys by `mikro ota enroll`: the registry url and
-// the device update key that authenticates against it.
-function bearer(): string | undefined {
-  const v = sysGet('ota.updateKey')
-  return typeof v === 'string' ? v : undefined
-}
-
-function registry(): string | undefined {
-  const v = sysGet('ota.registry')
-  return typeof v === 'string' ? v : undefined
-}
-
-function readAppVersion(): string | undefined {
-  const r = readFile('/app/package.json', 'utf-8')
-  if (!r.ok) return undefined
-  try {
-    const pkg = JSON.parse(r.value) as {version?: unknown}
-    return typeof pkg.version === 'string' ? pkg.version : undefined
-  } catch {
-    return undefined
-  }
-}
-
-const ota: Ota = createOta({
-  native,
-  store,
-  readAppVersion,
+const ota: Ota = {
+  reconcile,
+  running,
+  parseOffer,
+  applyOffer,
+  confirm,
+  revert,
   bearer,
   registry,
-})
+  config,
+  parseConfig,
+  applyConfig,
+  configState,
+}
 
 export {ota}

package/runtime/ota/types.ts

@@ -1,3 +1,6 @@
+import type {RequestError} from 'mikro/http/helpers'
+
+import type {CborError} from '../cbor/types.js'
 import type {Result} from '../result/types.js'
 
 /** An update offered by a registry: what to fetch and how to verify it, nothing
@@ -114,6 +117,107 @@ export type ApplyOutcome =
  *  mismatch code, since it cannot tell a bad hash from bad bytes. */
 export type OtaError = OtaWriteError | OtaBeginError | OtaInstallError | OtaDownloadError
 
+/** One stored config document: the complete effective config computed and
+ *  validated by the registry (or by the CLI at cable-seed time), the opaque
+ *  token that identifies it, and the release version it was computed for.
+ *  The device stores and returns it without understanding it: validation is
+ *  the writer's job, and the registry already ships the code. */
+export interface StoredConfig {
+  /** Opaque registry-issued token echoed as `configRev` on check-ins. The
+   *  registry serves its document whenever the echo differs from its own
+   *  current rev, so a document it does not recognize is replaced. */
+  rev?: string
+  /** The release version this document was computed for. A document stamped
+   *  for another version is ignored by `ota.config()`. */
+  version: string
+  /** The served document: the deviation overlay the read resolves over the
+   *  build's manifest defaults. */
+  doc?: unknown
+}
+
+/** The three config slots, mirroring the build's install slots: `current` is
+ *  what the running build reads, `next` is staged with an offered build,
+ *  `prev` is the rollback baseline while a trial is unresolved. */
+export type ConfigSlot = 'current' | 'next' | 'prev'
+
+/** A running-release config delivery on trial. `left` is the boot budget
+ *  (each boot that reads config burns one); `read` records that the app has
+ *  read the document since delivery. A completed check-in adopts the trial
+ *  only once that is true, or an app that reads config only at boot could
+ *  have a never-executed document adopted under it. */
+export interface ConfigTrial {
+  left: number
+  read: boolean
+}
+
+/** What a config write did to the store. Only `applied` and `cleared` change
+ *  what the running build reads; `staged` changes what the next one will. */
+export type ConfigWrite =
+  /** Stored as the running build's config. The document it replaced is kept as
+   *  the rollback baseline and a trial is armed, so the next `ota.confirm()`
+   *  after the app has read it is what keeps it. */
+  | 'applied'
+  /** Stored for the release the document names, which is not the one running.
+   *  It applies when that build installs, with the build. */
+  | 'staged'
+  /** The document was removed. The manifest defaults stand alone again. */
+  | 'cleared'
+  /** Nothing moved: the document is identical to the one already held (rev
+   *  included), or it was a clear with nothing to clear. */
+  | 'unchanged'
+  /** Nothing was written, and the reason is transient: the store could not
+   *  answer, or the running version could not be read. Keep echoing the rev
+   *  from `configState()` so the document is served again, rather than the rev
+   *  of the document that did not land. */
+  | 'failed'
+  /** Not a usable config document. Validate with `parseConfig` first to find
+   *  out before the delivery, and log what the wire actually carried. */
+  | 'invalid'
+
+/** What a check-in body owes the registry about config, for a client that
+ *  builds its own. */
+export interface ConfigState {
+  /** The rev to send as `configRev`: the registry serves its document whenever
+   *  this differs from its own current rev. Absent when the device holds no
+   *  document. After a rolled-back trial this is the FAILED document's rev,
+   *  which is what stops the registry serving it again. */
+  rev?: string
+  /** A document that failed its trial and was rolled back, reported until it
+   *  is replaced. Send it as `configError`, or an operator has no way to see
+   *  that the document they published took the device down. */
+  error?: ConfigErrorReport
+}
+
+/** A config document rolled back after a failed trial; reported on check-ins
+ *  while it stands. `rev` names the failed document, and the client keeps
+ *  echoing it as `configRev`, which is what stops the registry re-serving
+ *  the same document until an operator changes the config. */
+export interface ConfigErrorReport {
+  rev: string
+  message: string
+}
+
+declare global {
+  /**
+   * Merge your app's config type into this interface (next to the schema
+   * definition) to type `ota.config()` app-wide, with no type parameter at
+   * the call sites:
+   *
+   * ```ts
+   * declare global {
+   *   interface OtaConfig extends InferRead<typeof ConfigSchema> {}
+   * }
+   * ```
+   *
+   * A global rather than a module augmentation because `mikro/ota` re-exports
+   * its types, and module augmentation does not merge through re-exports. An
+   * explicit `ota.config<T>()` still works and wins over the registration.
+   */
+  interface OtaConfig {}
+}
+
+export type RegisteredConfig = keyof OtaConfig extends never ? unknown : OtaConfig
+
 export interface Ota {
   /** Report what happened to a previous update on this boot, and clear the report. */
   reconcile(): InstallOutcome
@@ -122,14 +226,20 @@ export interface Ota {
   /** Validate a registry value into an `Offer`, or `undefined` if unusable.
    *  `allowInsecure` (dev only) accepts an http build url instead of https. */
   parseOffer(raw: unknown, opts?: {allowInsecure?: boolean}): Offer | undefined
-  /** Run the full update policy: skip checks, compatibility, retry limit,
-   *  download via the `download` callback, and verification. */
+  /** Run the full update policy: skip checks and the retry limit, download
+   *  via the `download` callback, and verification. Compatibility is not
+   *  re-checked: the registry selected this build for the reported firmware,
+   *  and a mismatched archive fails its checksum or fails to load. */
   applyOffer(
     offer: Offer,
     download: DownloadFn,
     options?: InstallOptions,
   ): Promise<Result<ApplyOutcome, OtaError>>
-  /** Mark the running trial as healthy so it is kept rather than rolled back. */
+  /** Mark the running trial as healthy so it is kept rather than rolled back.
+   *  Settles a delivered config document's trial by the same call: a completed
+   *  check-in is the health signal both of them wait for. A config trial waits
+   *  additionally for the app to have read the document, so a `confirm()` from
+   *  an app that never called `config()` keeps nothing. */
   confirm(): void
   /** Reinstall the previous build immediately. */
   revert(): Result<void, OtaInstallError>
@@ -140,8 +250,198 @@ export interface Ota {
   /** The registry url the device was enrolled against, written next to the
    *  update key at enrollment, or `undefined` on an un-enrolled device. */
   registry(): string | undefined
+  /**
+   * The app's effective config: the running build's manifest defaults with the
+   * document the registry computed for this release spread over them, top level
+   * only. Always an object for a build that went through the tooling, so no
+   * `?? fallback` at the call sites; fields the schema gives no default are the
+   * ones that can be absent, and the read type marks exactly those optional.
+   *
+   * Reads current state on every call: it changes exactly when a check-in
+   * completes, and every call hands back a fresh object, so mutating one never
+   * reaches the cached defaults. The one thing held between calls is the last
+   * document that read successfully, which is served while, and only while, the
+   * store cannot answer. A read fails under heap pressure, and flipping a
+   * running app onto the defaults for a beat would re-configure its hardware
+   * mid-handshake. A cleared document removes the key and reads back as an
+   * honest absence, so a clear is never mistaken for a failure.
+   *
+   * The device never merges deeper than one level and never validates: every
+   * writer of the document validated it against this release's schema before
+   * writing, and the type comes from the same source definition
+   * (`ota.config<Config>()` with the schema's `InferRead`).
+   *
+   * Throws when there is nothing to serve at all: a build carrying no readable
+   * manifest and no stored document (deploy it with `mikro deploy`, or run
+   * `mikro dev`), or a store that failed before any read succeeded this runtime
+   * on a build whose manifest could not be parsed either. Both are transient or
+   * fixable states, never a value the app has to branch on.
+   */
+  config<T = RegisteredConfig>(): T
+  /**
+   * Validate a config document a client received over its own transport, or
+   * `undefined` when it cannot be used. What `parseOffer` is to an offer.
+   *
+   * A usable document is an object with a non-empty `version` (the release it
+   * was computed for, which decides where `applyConfig` puts it), an optional
+   * `rev` short enough to echo intact, and a `doc` that is an object or absent.
+   * An absent `doc` is the clear, not a malformed document.
+   *
+   * Whether the document survives CBOR is settled by `applyConfig`, which is
+   * where the stored bytes are made.
+   */
+  parseConfig(raw: unknown): StoredConfig | undefined
+  /**
+   * Store a config document, for a client that received one over its own
+   * transport. The built-in client covers the ordinary case and does not go
+   * through here.
+   *
+   * The `version` stamp decides where it lands: stamped for the running
+   * release it is applied, and the document it replaces is kept as the
+   * rollback baseline; stamped for another it is staged for the build it
+   * names, to apply when that build installs. The return value says which
+   * happened, and says when nothing did.
+   *
+   * A delivery to the running release arms a trial. Each boot whose first
+   * `config()` read serves the document burns one of `trialBoots`, and the
+   * budget spent with no `confirm()` in between restores the previous
+   * document. On a wake-cycle device every wake is a boot, so raise
+   * `trialBoots` above the default when a check-in can plausibly fail a few
+   * cycles in a row.
+   */
+  applyConfig(config: StoredConfig, options?: {trialBoots?: number}): ConfigWrite
+  /**
+   * What the device owes its registry about config: the rev to echo, and a
+   * rolled-back document to report. A client that builds its own check-in body
+   * needs both. Without the echo the registry re-serves the same document on
+   * every check-in; without the report a document that took the device down is
+   * re-served forever and nobody is told.
+   */
+  configState(): ConfigState
 }
 
 /** The `mikro/ota` singleton. The runtime value is provided by the on-device
  *  builtin (or the sim stub); this declaration carries its type for hosts. */
 export declare const ota: Ota
+
+/* ── mikro/ota/client ──────────────────────────────────────────────────────
+ * The check-in client's surface. The implementation is C
+ * (src/mik_ota_client.cpp); these are the shapes it marshals across. */
+
+export interface CheckOptions {
+  /** Budget for the check-in round trip. Default 10s. */
+  checkinTimeoutMs?: number
+  /** Budget for the build download. Separate from the check-in's because it is
+   *  a total wallclock deadline that cancels the transfer mid-stream, and an
+   *  image needs orders of magnitude more of it than a check-in body does.
+   *  Default 5m. */
+  downloadTimeoutMs?: number
+  /** Require a completed check-in (via `ota.confirm()`, which the client fires
+   *  itself) before an installed build is kept. Default true. */
+  requireConfirm?: boolean
+  /** Clean boots a trial may consume before an unconfirmed build reverts.
+   *  A deep-sleep wake counts as a clean boot, so wake-cycle devices on flaky
+   *  networks should raise this above the default 1. The same budget arms a
+   *  delivered config document's trial. */
+  trialBoots?: number
+}
+
+/** Runs after its round settles: after the check and any download, and before
+ *  an auto-restart, so the network brought up in `beforeCheck` can go down.
+ *
+ *  Whatever it returns is ignored, so it can call something that reports a
+ *  Result without having to unwrap or discard it. A promise is awaited before
+ *  the round is considered over. */
+export type Teardown = () => unknown
+
+/** What a `beforeCheck` hands back:
+ *
+ *  - a **function**: the round runs, and that function runs after it
+ *  - **nothing**: the round runs, with no teardown
+ *  - an **`err`**: the round is skipped and retried at the failure interval,
+ *    and no teardown runs, since unwinding a partial setup is the hook's own job
+ *  - an **`ok`**: as its value, a teardown function or nothing
+ *
+ *  Throwing has the same effect as returning an `err`. The bare-function form
+ *  is there because wrapping a teardown in `ok()` is ceremony on the path that
+ *  always succeeds; the Result form is what lets a failing setup hand its own
+ *  error straight back. */
+export type BeforeCheckResult = Teardown | void | Result<Teardown | void, unknown>
+
+export interface WatchOptions extends CheckOptions {
+  /** Steady interval between rounds, end-of-round to start-of-next. Default
+   *  30m, floored at 30s: each round's TLS session leaves heap and socket
+   *  residue that needs time to drain on small-heap devices, and the value
+   *  may arrive from remote config, and the floor is what bounds the damage a
+   *  mistyped document can do. */
+  checkinIntervalMs?: number
+  /** Delay before the first round. Default 5s. */
+  initialDelayMs?: number
+  /** Interval after a failed round, capped at `checkinIntervalMs`. Default 1m. */
+  retryAfterFailureMs?: number
+  /** Spread every scheduled sleep by ±10%, so a fleet that lost power together
+   *  does not check in phase-locked forever. Default true; pass false for
+   *  exact intervals (a demo watching for the update to land, a single
+   *  device where the spread only delays it). */
+  jitter?: boolean
+  /** Bring the network up for one round. State shared with the teardown stays
+   *  in this one scope. See {@link BeforeCheckResult} for what to hand back. */
+  beforeCheck?(): BeforeCheckResult | Promise<BeforeCheckResult>
+  /** Called after a completed round changes the effective config the running
+   *  build reads: delivered or cleared by that round, or applied by this boot's
+   *  install or rollback. Receives the new effective config. A watch loop is
+   *  otherwise silent, so without this an app has to poll `ota.config()` to
+   *  notice.
+   *
+   *  Not called for a config staged alongside an offered build: that one
+   *  applies at its trial boot, so the running app cannot read it yet. */
+  onConfig?(config: RegisteredConfig): void
+}
+
+export interface Watcher {
+  /** Prevent future rounds and cancel the pending sleep. An in-flight round
+   *  completes, but a build it stages no longer auto-restarts: it stays armed
+   *  for the next natural reboot. */
+  stop(): void
+  /** Change the cadence without restarting the watcher, floored at 30s like
+   *  {@link WatchOptions.checkinIntervalMs}. A wait already counting is re-timed
+   *  from when it started, so a shorter interval brings the next round forward
+   *  rather than waiting out the old one. The initial delay is left alone. */
+  setCheckinInterval(intervalMs: number): void
+}
+
+/** Why an offered build was not armed. Each is the policy working as intended;
+ *  the distinction is logged and returned because the app's next move differs. */
+export type DeclineReason =
+  | 'trial-pending'
+  | 'current'
+  | 'abandoned'
+  | 'exhausted'
+  | 'download-failed'
+  | 'install-failed'
+
+/** The check-in never completed. */
+export type CheckError =
+  | RequestError
+  | CborError
+  | {name: 'Status'; status: number}
+  /** The response body was past the size the client will buffer. */
+  | {name: 'TooLarge'; message: string}
+
+export type CheckResult =
+  /** Build downloaded, verified, and armed. The app restarts when ready. */
+  | {status: 'staged'; offer: Offer}
+  /** `configUpdated` reports that the running build's stored config changed
+   *  since the app could last have read it: delivered or cleared this round,
+   *  or applied by this boot's install or rollback. An app that read config
+   *  early in the cycle knows to read it again. */
+  | {status: 'up-to-date'; configUpdated?: boolean}
+  /** An offer arrived but was not armed. */
+  | {status: 'not-staged'; reason: DeclineReason; error?: OtaError}
+  /** Transient: the check-in did not complete, so the running trial (if any)
+   *  was not confirmed. */
+  | {status: 'failed'; error: CheckError}
+  /** The registry rejected the update key (HTTP 401). Permanent until
+   *  re-enrollment over the cable. */
+  | {status: 'unauthorized'}
+  | {status: 'not-enrolled'}