Not-critical API changes wishlist

Julian Gutierrez Oschmann (@juli4n)

Let's make a list of API changes we would like to make that are non-critical RIGHT NOW but should be evaluated before we call it 1.0

Of the 19 items in #1378, 10 are done on upstream/main (checked at 0f457249):

Rename SnapshotsConfig → SnapshotConfig and snapshots_config → snapshot_config (Rename SnapshotsConfig to SnapshotConfig everywhere in the codebase #1791)
Don't allow UNSPECIFIED for enums. All 11 enum fields now have +k8s:minimum=1. The comment on LocalSnapshot.content_scope still says UNSPECIFIED "is tolerated for compatibility", which no longer matches.
Store default values instead of leaving fields unset. "Add support for field defaults" (2b25500) fills them in on Create and Update.
Remove all reserved use in proto files. Remove reserved fields from protos #1793 removed them, but ateom/actor ID split: Clean up purpose from MintActorCertificate #1810 added reserved 4; reserved "purpose"; back to MintActorCertificateRequest.
Bundle page_size and page_token into ListOptions. They're still separate fields, and docs/api-style-guide.md shows them that way.
Decide between quantity strings and fixed units (cpu_millicores, etc.). In practice the code uses quantity strings parsed as resource.Quantity (for Limits.quantity and volume capacity), but no decision is written down.
Settle capitalization of API nouns in comments. ateapi.proto is mixed: "the Actor" appears 54 times and "the actor" 37.
Settle "microVM" vs "micro-vm" and "gVisor" vs "gvisor". Docs are mixed: microvm 90, microVM 14, gvisor 64, gVisor 60.
Do error translation in one place instead of per method in atepg and the impl. codes.* mapping is still spread across controlapi/*.go, and atepg has no shared helper.
Decide whether to use godoc-style comments. Proto comments still mix path must be… with Name of the volume….
Rename LocalSnapshotInfo → LocalSnapshot (Rename LocalSnapshotInfo to LocalSnapshot #1856)
Delete unused ActorAssignment.actor_template_ref.
Rename ExternalVolume.volume_name → name. The sibling field volume_type would need the same treatment to match the comment's type.
Rename ActorStatus.actor_volumes → external_volumes
Default HTTPGetAction.path to / and have examples set /readyz explicitly (Rename ActorTemplate.containers.readyz to wakeupProbe. #1794). The proto comment says it defaults to /, but the field is still tagged +k8s:required.
Rename readyz → wakeupProbe. This covers both the readinessProbe comment and the follow-up thread choosing wakeupProbe (Rename ActorTemplate.containers.readyz to wakeupProbe. #1794).
All Delete methods enforce DeleteOptions and preconditions (Add DeletePreconditions to all Delete<Resource> methods #1807, plus DeleteActorEgressPolicy added later). All six Delete RPCs pass the options through toDeletePreconditions, but Add DeleteOptions and honor version/uid preconditions on all Delete RPCs #866 is still open and could be closed.

Julian Gutierrez Oschmann (@juli4n) Eitan Yarmush (@EItanya)

"SnapshotsConfig" -> "SnapshotConfig" and "snapshots_config" -> "snapshot_config"

Don't allow UNSPECIFIED for enums (we don't have a back-compat requirement yet)

Should we reify default values of leave them as unspecified fields?

Remove all "reserved" use in proto files

Bundle page_size and page_token into ListOptions

Should we use quantity-strings ("1Gi", "0.001m", etc) or require quantized units ("cpu_millcores", "memory_megabytes"). Quantities are hard because a) floating point can be very imprecise (exactly what is "1.6Gi"); b) it can represent numbers that we don't want to quantize (e.g. "0.001m"); and c) can easily overflow standard ints. Handling them as native types is tricky. Also it's weird to encode "3 cores" as a string "3".

https://github.com/agent-substrate/substrate/pull/1283/changes#r3918227639

And if we DO use the string format, do we process those values as math/big.Float or something?

Decide and be consistent about capitalization of API nouns in comments ("this Actor will..." vs "this actor will...")

Also "microVM" vs "micro-vm" and "gVisor" vs "gvisor".

All the methods in atepg and impl do different error transformations -- we should have one place where than is done the same for everyone?

Remove reserved fields from protos (agent-substrate#1793)

Rename SnapshotsConfig to SnapshotConfig everywhere in the codebase (a…

Rename LocalSnapshotInfo to LocalSnapshot (agent-substrate#1856)

Remove reserved fields from proto and update back-compat instruction …

Should we rename resumed to already_running?

substrate/pkg/proto/ateapipb/ateapi.proto

Lines 1603 to 1608 in 1808e43

    
           message ResumeActorResponse { 
        
             Actor actor = 1; 
        
             // True if a resume workflow was executed to activate the actor. 
        
             // False if the actor was already RUNNING. 
        
             bool resumed = 2;

if I call

resp, err := client.ResumeActor(ctx, req)
if !resp.GetResumed() {
    ...
}

can be interpreted as it failed to resume?

Open question - should proto enums become string enums?

Delete unused `actor_template_ref` from `ActorAssigment` sub-resource (…

Merge upstream main through 25a0b88 (#67)

Rename some `ExternalVolume` fields (agent-substrate#2404)

Sync upstream sandbox, snapshot, and HTTPS egress updates (#69)

Wrap page size and next page token in a `ListOptions` message.

Wrap page size and next page token in a `ListOptions` message. (agent…

Navigation Menu

Repository navigation

Not-critical API changes wishlist #1378

16 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	message ResumeActorResponse {
	Actor actor = 1;

	// True if a resume workflow was executed to activate the actor.
	// False if the actor was already RUNNING.
	bool resumed = 2;

Not-critical API changes wishlist #1378

Description

Activity

thockin commented on Sep 1, 2026

thockin commented on Sep 1, 2026

thockin commented on Sep 2, 2026

thockin commented on Sep 3, 2026

thockin commented on Sep 3, 2026

thockin commented on Sep 3, 2026

thockin commented on Sep 4, 2026

BenTheElder commented on Sep 4, 2026

thockin commented on Sep 4, 2026

16 remaining items

zoez7 commented on Oct 6, 2026

thockin commented on Oct 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions