Skip to content

feat(driver-contract): write the driver contract documents as binary protobuf - #5519

Open
elezar wants to merge 1 commit into
refactor/5456-driver-contract-format/elezarfrom
feat/5456-write-driver-contract-files/elezar
Open

elezar wants to merge 1 commit into
refactor/5456-driver-contract-format/elezarfrom
feat/5456-write-driver-contract-files/elezar

Conversation

@elezar

@elezar elezar commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Split the contract file handling into a write side and a read side, and have the Docker driver write the documents as binary protobuf beside the legacy JSON.

Related Issue

Part of #5456. Stacked on #5508.

Changes

  • write::encode validates a document and returns both files (binary protobuf and legacy JSON), each with its name and bytes, encoded from one value so they cannot disagree.
  • read::boundary_config and read::runtime_descriptor prefer the binary file beside a legacy path and fall back to the legacy one; an invalid binary file is an error, not a fallback. read::consume removes every form of a single-use document. read::descriptor_payload serves the built-in runtime until the legacy encoding is removed. The naming rule stays internal.
  • The Docker driver writes both forms; the supervisor and sandbox boundary read through the contract crate. Docker still restarts from its legacy state files, so a narrowly scoped helper reads the optional binary sibling during restart staging. Moving that restart state into a private record is refactor(drivers): keep Docker and Podman restart state in a private record #5565.
  • A driver must not be replaced by an older one that leaves new files behind: newer readers would prefer the stale files.

Release Notes

None.

Testing

  • Checks appropriate to the affected code and behavior pass
    • fmt, clippy, workspace tests, rust:deny:policy, buf lint and buf breaking pass at this tip. The openshell-driver-vm tests were not run to completion: they need mke2fs, which was unavailable locally.
  • Unit tests added/updated (if applicable)
  • E2E tests added/updated (if applicable)
    • Not run on this version.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

@elezar elezar added the area:drivers Compute and secret drivers, host OS/architecture support, backend isolation, and lifecycle. label Nov 12, 2026
@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 12, 2026
@elezar
elezar added this pull request to stack #5532 November 13, 2026 12:35
@elezar
elezar force-pushed the feat/5456-write-driver-contract-files/elezar branch from d282977 to 3725213 Compare November 13, 2026 12:52
@elezar
elezar force-pushed the feat/5456-write-driver-contract-files/elezar branch from 3725213 to 44f01ed Compare November 13, 2026 13:07
@elezar elezar added the test:e2e Requires end-to-end coverage label Nov 13, 2026
@github-actions

Copy link
Copy Markdown

Label test:e2e applied for 44f01ed. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

@elezar
elezar force-pushed the feat/5456-write-driver-contract-files/elezar branch from 44f01ed to 3caff35 Compare November 13, 2026 13:39
@purp purp added the topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. label Nov 15, 2026
@elezar
elezar force-pushed the feat/5456-write-driver-contract-files/elezar branch from 3caff35 to 2ad5f56 Compare November 16, 2026 12:40
@elezar elezar changed the title feat(driver-docker): write the driver contract documents as protobuf JSON feat(driver-contract): write the driver contract documents as binary protobuf Nov 16, 2026
…protobuf

Split the file handling into a write side and a read side. write::encode
validates a document and returns both files of it, the binary protobuf file
and the legacy JSON beside it, each with its name and bytes, encoded from one
value so they cannot disagree. read::boundary_config and
read::runtime_descriptor prefer the binary file beside a legacy path and fall
back to the legacy one; an invalid binary file is an error, not a fallback.
read::consume removes every form of a single-use document, and
read::descriptor_payload serves the built-in runtime until the legacy
encoding is removed. The file naming rule stays internal.

The Docker driver writes both forms. The supervisor and the sandbox boundary
read through the contract crate. Docker still restarts from its legacy state
files, so a narrowly scoped helper reads the optional binary sibling during
restart staging.

Signed-off-by: Evan Lezar <elezar@nvidia.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:drivers Compute and secret drivers, host OS/architecture support, backend isolation, and lifecycle. state:accepted A maintainer decided OpenShell should pursue this issue test:e2e Requires end-to-end coverage topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants