Reference

Protobuf time types

View as Markdown

OpenShell represents absolute times with google.protobuf.Timestamp and elapsed times with google.protobuf.Duration in its protobuf APIs.

Provider profile YAML and JSON accept canonical duration strings such as cache_ttl: "0.500s". The legacy cache_ttl_seconds, refresh_before_seconds, and max_lifetime_seconds inputs remain supported for existing profiles.

In protobuf JSON, timestamps are RFC 3339 strings and durations are strings ending in s:

{
  "createdTime": "2026-08-31T14:05:06.123456789Z",
  "executionTimeout": "1.500s"
}

An absent message means that no timestamp or duration was supplied. It is different from the Unix epoch (1970-01-01T00:00:00Z) and from a zero duration (0s). OpenShell validates protobuf timestamp and duration bounds at API boundaries.

Upgrade from scalar time fields

The well-known time fields replace earlier public fields encoded as Unix milliseconds, integer seconds, or duration strings. Their names and protobuf tags changed, so clients generated from the old schema are not wire-compatible with a gateway generated from the new schema. Upgrade the gateway, CLI, all SDK clients, compute drivers, credential drivers, middleware services, and sandbox supervisors together. Mixing versions can silently discard fields whose tags changed. For example, the new gateway does not recognize an old credential driver’s tag-3 expiry and would treat that credential as non-expiring.

Before upgrading a gateway with persisted state:

  1. Stop all gateway replicas.
  2. Back up the SQLite database or PostgreSQL database.
  3. Upgrade every gateway replica, client, driver, middleware service, and sandbox supervisor from the same OpenShell release.
  4. Start one gateway replica and wait for startup to complete before starting the remaining replicas.

At startup, the gateway migrates affected protobuf payloads in one database transaction. Legacy zero timestamps become absent. Zero expiry-map values are removed, and the legacy maximum-integer refresh sentinel becomes an absent next-refresh timestamp. The database columns created_at_ms and updated_at_ms remain unchanged because they are internal ordering metadata.

If a legacy payload is malformed or outside protobuf time bounds, startup fails with the affected object type and ID and rolls back the transaction. Legacy sandbox condition transition strings that are not valid RFC 3339 are dropped because earlier releases allowed arbitrary driver-provided strings. Restore the backup or repair any other reported record with the previous OpenShell version before retrying the upgrade.

User-facing timeout options and gateway TOML settings keep their existing units. The CLI and SDKs convert those values at the protobuf boundary.