package wasmeld:kv@0.1.0;

/// Small persistent byte-value store scoped to the stable service ID.
///
/// Revisions of the same service share a namespace, so a deployment change
/// preserves values. Keys are non-empty UTF-8 strings of at most 256 bytes and
/// values are at most 64 KiB in this version of the Host implementation.
/// Operations are not multi-key transactions.
interface store {
  /// Expected validation or backend failures.
  variant kv-error {
    /// The key is empty or exceeds the Host byte limit.
    invalid-key(string),
    /// The attempted or stored value exceeds the Host byte limit.
    value-too-large(u64),
    /// Persistence failed, timed out, or was temporarily unavailable.
    ///
    /// A timeout is not cancellation: a mutation may finish after the caller
    /// receives this error. Retried `set` and `delete` operations should be
    /// idempotent.
    operation-failed(string),
  }

  /// Returns the current value, or `none` when the key does not exist.
  get: func(key: string) -> result<option<list<u8>>, kv-error>;

  /// Creates or replaces one value.
  set: func(key: string, value: list<u8>) -> result<_, kv-error>;

  /// Removes one value; deleting a missing key succeeds.
  delete: func(key: string) -> result<_, kv-error>;
}

/// Host-side world used by Wasmeld to link persistent KV.
world kv-host {
  import store;
}