mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-11-08 09:04:26 +08:00
Derek Carr
d68b7069c3
* refactor(proto)!: use well-known time types Signed-off-by: Derek Carr <decarr@redhat.com> * fix(proto): preserve time migration behavior Signed-off-by: Derek Carr <decarr@redhat.com> * fix(proto): preserve timestamp boundary semantics Signed-off-by: Derek Carr <decarr@redhat.com> * fix(proto): convert sandbox token expiry to timestamp Signed-off-by: Derek Carr <decarr@redhat.com> * fix(proto): preserve time compatibility semantics Signed-off-by: Derek Carr <decarr@redhat.com> * fix(proto): preserve exact endpoint and profile times Signed-off-by: Derek Carr <decarr@redhat.com> * test(e2e): use duration for interactive exec timeout Signed-off-by: Derek Carr <decarr@redhat.com> * fix(sdk-go)!: remove legacy profile duration fields BREAKING CHANGE: Go provider profile callers must use RefreshBefore, MaxLifetime, and CacheTTL with ProfileDuration instead of the whole-second fields. Signed-off-by: Derek Carr <decarr@redhat.com> --------- Signed-off-by: Derek Carr <decarr@redhat.com>
63 lines
2.8 KiB
Plaintext
63 lines
2.8 KiB
Plaintext
---
|
|
title: Protobuf time types
|
|
description: Timestamp and duration representation in the OpenShell API
|
|
---
|
|
|
|
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`:
|
|
|
|
```json
|
|
{
|
|
"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.
|