resources

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ResourceNameRegexPattern is the regular expression pattern for a valid
	// Substrate resource name.
	ResourceNameRegexPattern = `[a-z0-9]([-a-z0-9]*[a-z0-9])?`
	// ActorDNSSuffix is suffix to the DNS name for direct access to Actor
	// "<actor_name>.<atespace>.actors.resources.substrate.ate.dev"
	ActorDNSSuffix = "actors.resources.substrate.ate.dev"
	// GoldenActorAtespace is the reserved system atespace that per-template golden
	// actors live in.
	GoldenActorAtespace = "ate-golden"
)
View Source 
const (
	ResourceCPU    = "cpu"
	ResourceMemory = "memory"
)

ResourceCPU and ResourceMemory are the two dimensions everything declares today, named as Kubernetes names them so an ActorTemplate's limits and a Worker's capacity meet under the same keys.

Variables

This section is empty.

Functions

func ActorDNSName added in v0.1.0 

func ActorDNSName(r ActorRef) string

ActorDNSName returns the uniform DNS name the actor is reachable at. This is: "<name>.<atespace>.actors.resources.substrate.ate.dev".

func AddToAllocated added in v0.1.0 

func AddToAllocated(total *ateapipb.WorkerResources, assignment *ateapipb.ActorAssignment, sign int64) (*ateapipb.WorkerResources, error)

AddToAllocated adjusts allocation by an assignment; sign is 1 or -1. It returns nil when allocation reaches zero.

func CPUMemory added in v0.1.0 

func CPUMemory(cpuMilli, memoryBytes int64) *ateapipb.Resources

CPUMemory is the Resources for those two dimensions, in the units the runtimes deal in. A zero dimension is omitted, which reads as unconstrained.

func IsValidResourceName added in v0.1.0 

func IsValidResourceName(name string) bool

IsValidResourceName reports whether name is a valid Substrate resource name (a DNS-1123 label; see ValidateResourceName for the rules). Use this for internal, non-proto checks where a plain predicate is wanted; to validate a proto request field with structured field-path errors, use ValidateResourceName. Empty is not a valid name.

func NetworkPolicyName added in v0.1.0 

func NetworkPolicyName(wpName string) string

NetworkPolicyName returns the deterministic Kubernetes NetworkPolicy name generated for a given WorkerPool name.

func NewSnapshotName added in v0.1.0 

func NewSnapshotName() string

NewSnapshotName returns a unique name for a new snapshot, durable or node-local.

func SumAllocated added in v0.1.0 

func SumAllocated(assignments []*ateapipb.ActorAssignment) (*ateapipb.WorkerResources, error)

SumAllocated is what a set of assignments takes from a Worker, or nil for none. Rebuilds the total rather than adjusting it, which is what the checks holding AddToAllocated to the assignments it counts compare against.

func ValidateAteomUID added in v0.1.0 

func ValidateAteomUID(targetAteomUID string) error

ValidateAteomUID rejects a target ateom pod UID that could escape the host paths built from it: the netns path (/run/netns/ateom:<uid>) and the ateom control socket (.../ateoms/<uid>/ateom.sock). Kubernetes pod UIDs are UUIDs, which are valid DNS-1123 labels, so a label check accepts every legitimate value while rejecting separators and "..".

func ValidateContainerNames added in v0.1.0 

func ValidateContainerNames(names []string) error

ValidateContainerNames ensures every application container name is safe to use as an OCI bundle path component. Each must be a DNS-1123 label (no separator or ".."), must not be the reserved "pause" name (which would collide with the sandbox-infra bundle and race its concurrent writer), and must be unique (duplicates map to the same bundle path and corrupt each other).

func ValidateGlobalObjectRef added in v0.1.0 

func ValidateGlobalObjectRef(ref *ateapipb.ObjectRef, fldPath *field.Path) field.ErrorList

ValidateGlobalObjectRef checks that a reference to a global-scoped resource is well-formed: its atespace must be empty (global resources do not belong to an atespace) and its name must be a valid resource name. It does not check that the referenced resource actually exists.

A nil ref is an error rather than a no-op: every global ref in the API names the resource a request acts on, and a request that names nothing cannot be served. TODO: EOL this when DV is fully implemented

func ValidateIP added in v0.1.0 

func ValidateIP(ip string, fldPath *field.Path) field.ErrorList

ValidateIP checks that the given string is a valid IP address, is not an IPv4-mapped IPv6 address, and is in canonical form.

func ValidateResourceName added in v0.1.0 

func ValidateResourceName(name string, fldPath *field.Path) field.ErrorList

ValidateResourceName checks that a string conforms to Agent Substrate's rules for a resource name, which is a subset of the rules for an RFC-1123 DNS label. This does not check for zero-length strings, which callers may want to handle differently (e.g., by returning a "required" error).

func ValidateRunscHash added in v0.1.0 

func ValidateRunscHash(sha256Hash string) error

ValidateRunscHash ensures the runsc SHA-256 hash is exactly 64 hex characters before it is used to build the on-disk binary path (static-files/runsc-<hash>) and, on a cache hit, returned for ateom to execute. Without this, a hash containing path separators or ".." could point the cache-hit early return (and the download target) at an arbitrary binary outside the static-files dir.

func ValidateSnapshotLocation added in v0.1.0 

func ValidateSnapshotLocation(location string) error

ValidateSnapshotLocation ensures an ActorTemplate's snapshotsConfig.location is a well-formed URI with a bucket, so a bad location fails fast instead of deep inside an object-storage call. It deliberately does not restrict the scheme: the storage layer only uses the host (bucket) and path, and which schemes are acceptable is a storage-backend policy, not a per-RPC one. The local paths used for snapshot upload/download are derived from the separately validated actor ref, not from this URI, so this is a sanity check rather than a path-traversal guard.

This validates the base that many snapshots share, not any one snapshot's URI; SnapshotURI is the type for the latter, and it applies this check when it is built.

func ValidateUUID added in v0.1.0 

func ValidateUUID(uuid string, fldPath *field.Path) field.ErrorList

ValidateUUID verifies that the specified value is a valid UUID (RFC 4122).

  • must be 36 characters long
  • must be in the normalized form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
  • must use only lowercase hexadecimal characters

Types

type ActorAttribution added in v0.1.0 

type ActorAttribution struct {
	Ref              ActorRef
	UID              string
	TemplateAtespace string
	TemplateName     string
}

ActorAttribution is what telemetry about an actor is attributed to: an ActorRef plus the two things a ref does not carry, the server-assigned uid and the template the actor was built from. Shared by ateattr, actorlog, and ateom's usage sampling so those producers cannot drift apart.

Unrelated to the credential sense of "actor identity" elsewhere in the repo (ateapi's ActorIdentity service, substratex509, ateompath.ActorIdentityDirPath) — nothing here is a secret or is presented as proof of anything.

func ActorAttributionFromActor added in v0.1.0 

func ActorAttributionFromActor(a *ateapipb.Actor) ActorAttribution

ActorAttributionFromActor builds the attribution for a loaded Actor. Nil-safe; a nil Actor yields zero-valued fields.

type ActorRef added in v0.1.0 

type ActorRef = ResourceRef[*ateapipb.Actor]

ActorRef identifies an actor by the (atespace, name).

func ActorRefFromActor added in v0.1.0 

func ActorRefFromActor(a *ateapipb.Actor) ActorRef

ActorRefFromActor returns the reference addressing the given actor.

func ActorRefFromObjectRef added in v0.1.0 

func ActorRefFromObjectRef(ref *ateapipb.ObjectRef) ActorRef

ActorRefFromObjectRef converts a wire reference to an ActorRef.

func ParseActorDNSName added in v0.1.0 

func ParseActorDNSName(name string) (ActorRef, error)

ParseActorDNSName parses a DNS name for a given actor.

The name is folded to lower case first. DNS lookups are case-insensitive (RFC 4343), so a client that resolved "MyActor.MySpace.<suffix>" reaches us with that spelling preserved in the Host header, while actor and atespace names are always lower case. Folding keeps the request addressed to the same actor its DNS lookup resolved to instead of failing to parse.

type ActorTemplateRef added in v0.1.0 

type ActorTemplateRef = ResourceRef[*ateapipb.ActorTemplate]

ActorTemplateRef identifies an ActorTemplate by the (atespace, name).

func ActorTemplateRefFromActorTemplate added in v0.1.0 

func ActorTemplateRefFromActorTemplate(t *ateapipb.ActorTemplate) ActorTemplateRef

ActorTemplateRefFromActorTemplate returns the reference addressing the given template.

func ActorTemplateRefFromObjectRef added in v0.1.0 

func ActorTemplateRefFromObjectRef(ref *ateapipb.ObjectRef) ActorTemplateRef

ActorTemplateRefFromObjectRef converts a wire reference to an ActorTemplateRef.

type Quantities added in v0.1.0 

type Quantities map[string]resource.Quantity

Quantities is the parsed form of an ateapipb.Resources: what an Actor asks for, what a Worker supplies, or the sum of what a Worker's Actors hold. The same type serves all three so they subtract, which is the point of naming Worker capacity the way an ActorTemplate names its limits.

An absent name is none of that resource. A Worker reports every dimension it has, so a name missing from its capacity is one it cannot supply at all.

func ParseQuantities added in v0.1.0 

func ParseQuantities(r *ateapipb.Resources) (Quantities, error)

ParseQuantities reads the wire form. It errors on a quantity it cannot parse rather than skipping it, so a malformed limit cannot silently become unconstrained.

func (Quantities) Add added in v0.1.0 

func (q Quantities) Add(other Quantities)

Add adds other into q, dimension by dimension.

func (Quantities) Covers added in v0.1.0 

func (q Quantities) Covers(want Quantities) bool

Covers reports whether q leaves room for want in every dimension want names.

A dimension q does not name is none of it, not any amount of it: a Worker reports everything it has, so silence about GPUs means it has no GPUs and cannot take an Actor asking for one. A dimension want does not name asks for nothing.

func (Quantities) Proto added in v0.1.0 

func (q Quantities) Proto() *ateapipb.Resources

Proto is the wire form, sorted by name. Sorting is what lets proto.Equal decide whether a report or a recomputed total actually changed anything; unsorted, equal sets would compare unequal and churn the record.

A dimension that has reached zero is dropped: it constrains nothing, and keeping it would make an emptied total compare unequal to an absent one.

func (Quantities) Sub added in v0.1.0 

func (q Quantities) Sub(other Quantities)

Sub subtracts other from q, dimension by dimension.

type Resource added in v0.1.0 

type Resource interface {
	GetMetadata() *ateapipb.ResourceMetadata
}

Resource is any Atespaced resource message carrying the common metadata.

type ResourceRef added in v0.1.0 

type ResourceRef[R Resource] struct {
	// Atespace is the isolation boundary the resource was created into. Required.
	Atespace string
	// Name is the resource's name, unique within Atespace. Required.
	Name string
}

ResourceRef identifies an Atespaced resource by the (atespace, name).

func (ResourceRef[R]) LogValue added in v0.1.0 

func (r ResourceRef[R]) LogValue() slog.Value

LogValue implements slog.LogValuer so that slog.Any("template", ref) records the two components as a group ("template.atespace", "template.name") rather than flattening them into one opaque string.

func (ResourceRef[R]) String added in v0.1.0 

func (r ResourceRef[R]) String() string

func (ResourceRef[R]) ToObjectRef added in v0.1.0 

func (r ResourceRef[R]) ToObjectRef() *ateapipb.ObjectRef

ToObjectRef converts the reference to its wire form.

type SnapshotOwner added in v0.1.0 

type SnapshotOwner struct {
	// contains filtered or unexported fields
}

SnapshotOwner is the resource whose objects a snapshot's prefix holds: the Actor that took it, or the Tag that copied it. Deletion is expressed as "collect everything under my own prefix", so an owner cannot name another's objects, and a borrowed snapshot is recognized by the URI alone rather than by a flag the two have to keep in sync.

func ActorSnapshotOwner added in v0.1.0 

func ActorSnapshotOwner(atespace, actorUID string) SnapshotOwner

ActorSnapshotOwner returns the owner of the snapshots an Actor takes. It is keyed on the UID rather than the name so that an Actor recreated under the same name never inherits its predecessor's objects.

func TagSnapshotOwner added in v0.1.0 

func TagSnapshotOwner(atespace, snapshotName string) SnapshotOwner

TagSnapshotOwner returns the owner of the one snapshot a Tag holds. A tag never takes a second snapshot, so its prefix is that snapshot's prefix, and the name is minted fresh rather than derived from the tag: a recreated tag cannot compute its way onto the objects its predecessor left.

func (SnapshotOwner) Atespace added in v0.1.0 

func (o SnapshotOwner) Atespace() string

Atespace returns the atespace the owner belongs to.

func (SnapshotOwner) IsZero added in v0.1.0 

func (o SnapshotOwner) IsZero() bool

IsZero reports whether o is the zero SnapshotOwner.

func (SnapshotOwner) Prefix added in v0.1.0 

func (o SnapshotOwner) Prefix(location string) (StoragePrefix, error)

Prefix returns the prefix holding every object this owner's snapshots are made of, under an ActorTemplate's snapshotsConfig.location.

func (SnapshotOwner) String added in v0.1.0 

func (o SnapshotOwner) String() string

type SnapshotURI added in v0.1.0 

type SnapshotURI struct {
	// contains filtered or unexported fields
}

SnapshotURI is where one external snapshot's objects live in object storage: an ActorTemplate's snapshotsConfig.location, plus the prefix of the resource that owns the snapshot. 

gs://bucket/root                                                    location
gs://bucket/root/atespaces/team-a/actors/<uid>                      an Actor's prefix
gs://bucket/root/atespaces/team-a/actors/<uid>/snapshots/<name>     one of its snapshots
gs://bucket/root/atespaces/team-a/tags/<name>                       a tag's prefix, and
                                                                    its only snapshot

func NewActorSnapshotURI added in v0.1.0 

func NewActorSnapshotURI(location, atespace, actorUID, name string) (SnapshotURI, error)

NewActorSnapshotURI returns the URI of a snapshot an Actor took, stored under an ActorTemplate's snapshotsConfig.location.

func NewTagSnapshotURI added in v0.1.0 

func NewTagSnapshotURI(location, atespace, name string) (SnapshotURI, error)

NewTagSnapshotURI returns the URI of the snapshot a Tag owns, stored under an ActorTemplate's snapshotsConfig.location. The tag's prefix and its snapshot's are the same: a tag holds exactly one snapshot.

func ParseSnapshotURI added in v0.1.0 

func ParseSnapshotURI(uri string) (SnapshotURI, error)

ParseSnapshotURI parses a given snapshot URI.

func (SnapshotURI) Atespace added in v0.1.0 

func (u SnapshotURI) Atespace() string

Atespace returns the atespace of the resource that owns the snapshot.

func (SnapshotURI) IsZero added in v0.1.0 

func (u SnapshotURI) IsZero() bool

IsZero reports whether u is the zero SnapshotURI.

func (SnapshotURI) Location added in v0.1.0 

func (u SnapshotURI) Location() string

Location returns the ActorTemplate snapshotsConfig.location this snapshot is stored under.

func (SnapshotURI) Name added in v0.1.0 

func (u SnapshotURI) Name() string

Name returns the snapshot's resource name.

func (SnapshotURI) ObjectURI added in v0.1.0 

func (u SnapshotURI) ObjectURI(name string) (string, error)

ObjectURI returns the address of a single object stored within the snapshot.

func (SnapshotURI) OwnedBy added in v0.1.0 

func (u SnapshotURI) OwnedBy(o SnapshotOwner) bool

OwnedBy reports whether the snapshot is owned by o. A collector asks this before deleting: an Actor whose snapshot came from a tag does not own it, and releasing it would break every other Actor cloned from that tag.

func (SnapshotURI) Owner added in v0.1.0 

func (u SnapshotURI) Owner() SnapshotOwner

Owner returns the resource whose prefix the snapshot lives under.

func (SnapshotURI) OwnerPrefix added in v0.1.0 

func (u SnapshotURI) OwnerPrefix() StoragePrefix

OwnerPrefix returns the prefix of the resource that owns the snapshot, holding this snapshot and every other that owner wrote. Collecting an owner takes only a URI it recorded, with no need to resolve its ActorTemplate for the storage location.

func (SnapshotURI) Prefix added in v0.1.0 

func (u SnapshotURI) Prefix() StoragePrefix

Prefix returns the prefix holding this one snapshot's objects.

func (SnapshotURI) String added in v0.1.0 

func (u SnapshotURI) String() string

type StoragePrefix added in v0.1.0 

type StoragePrefix struct {
	// contains filtered or unexported fields
}

StoragePrefix is a validated object-storage prefix: a scheme, a bucket and a path, with no query, fragment or userinfo. Every object below this prefix has a name starting with its path, so deleting the prefix collects all of them.

func (StoragePrefix) IsZero added in v0.1.0 

func (p StoragePrefix) IsZero() bool

IsZero reports whether p is empty

func (StoragePrefix) String added in v0.1.0 

func (p StoragePrefix) String() string

type TagRef added in v0.1.0 

type TagRef = ResourceRef[*ateapipb.Tag]

TagRef identifies a Tag by the (atespace, name).

func TagRefFromObjectRef added in v0.1.0 

func TagRefFromObjectRef(ref *ateapipb.ObjectRef) TagRef

TagRefFromObjectRef converts an ObjectRef to a TagRef.

func TagRefFromTag added in v0.1.0 

func TagRefFromTag(t *ateapipb.Tag) TagRef

TagRefFromTag returns the reference addressing the given tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.