Documentation
¶
Overview ¶
Package mem is the in-memory resource provider.
Its resources are content-addressable session values, keyed by digest and living only for the session that interned them.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Resource ¶
type Resource interface {
op.Resource
// Hash returns the lowercase hex SHA-256 of the archived content. Identity-bearing — also encoded in the
// URI's <specific> as `sha256:<hash>`.
Hash() string
// SourcePath returns the sharded on-disk location of the archived content.
SourcePath() fsroot.Path
// Reader opens the archived content, memory-mapped. Close releases the mapping.
Reader() (io.ReadCloser, error)
// Pack returns the archived bytes, for the document's content section.
Pack() ([]byte, error)
// Unpack rebuilds a resource from a document's content section.
Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)
// contains filtered or unexported methods
}
Resource represents an in-memory-origin data resource archived on disk at a content-addressed path.
The canonical URI is a tag URI of the form `tag:devlore.noblefactor.com,2026-01-01:<algo>:<hex>#github.com/.../mem.Resource`, where `<algo>:<hex>` is the SHA-256 of the archived bytes. Identity is the digest: two resources built from the same bytes resolve to the same URI and the same on-disk path — content deduplication by construction.
The on-disk path follows a sharded CAS layout: `<Root>/.devlore/mem/resource/<algo>/<hex[0:2]>/<hex>`. The 2-character prefix shard keeps any single directory bounded as content grows. Embedders inherit the formula via their distinct typeID.
Content bytes are never held in the Go heap after archival. Consumers read through Resource.Reader (a mmap-backed io.ReadCloser) or via the op.SourceConverter projections to []byte or string. Resource is this provider's resource type — the sealed interface over content-addressed bytes.
Sealed by an unexported marker, so the closed set of implementations is the one this package declares. That matters more here than anywhere else: identity IS the digest, so a forged mem resource is a claim about content nobody hashed.
func DiscoverResource ¶
func DiscoverResource(runtimeEnvironment *op.RuntimeEnvironment, value any) (Resource, error)
DiscoverResource constructs a *Resource and registers it without claiming production.
Used by the framework's resource registry adapter for slot coercion (when starlark supplies a string URI and the slot expects a *mem.Resource) and by callers holding a reference handle without claiming production. UnmarshalJSON / UnmarshalText / UnmarshalYAML rehydration is the canonical use case.
Discover does not stamp a producer, so unlike NewResource it takes only `runtimeEnvironment` — no unit reference is needed.
Same value-shape dispatch as NewResource: []byte / io.Reader archive content; string rehydrates metadata-only.
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `value`: []byte, io.Reader, or a canonical tag URI string; same dispatch as NewResource.
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported value type, filesystem write failure, malformed URI, or identity construction failure.
func NewResource ¶
func NewResource(runtimeEnvironment *op.RuntimeEnvironment, producerID string, value any) (Resource, error)
NewResource constructs a *Resource and claims production via op.ResourceCatalog.GetOrCreate.
Use NewResource from a producer dispatch context — typically a provider method that has received an op.ActivationRecord from the framework. The returned Resource is the canonical catalog entry, stamped with `producerID = activationRecord.CallerID.ID()` (or empty when `Unit` is nil for non-graph dispatch). Use DiscoverResource instead when the caller is not claiming production (rehydration, reference handles, the framework's slot-coercion adapter).
Identity is the SHA-256 of the archived bytes. The on-disk SourcePath is derived from that digest. When `value` is []byte the content is hashed in memory and written directly. When `value` is an io.Reader the content is streamed through a TeeReader into a staging file, hashed in flight, then renamed onto the canonical path. When `value` is a string URI the Resource is rehydrated metadata-only (no archival; the URI alone carries the digest).
Two callers with the same content produce the same URI; the first to reach the catalog wins the entry. The second caller's write overwrites the canonical path with byte-identical content.
Nil-Catalog tolerance: returns the unlinked candidate when no catalog is present.
Parameters:
- `runtimeEnvironment`: the session runtime environment. `Root` must be non-nil when `value` is []byte or io.Reader.
- `producerID`: the producing caller's id (`activationRecord.CallerID`), or "" for caller-less dispatch. for non-graph dispatch.
- `value`: []byte (in-memory archival), io.Reader (stream archival), or a canonical tag URI string (metadata-only rehydration).
Returns:
- `Resource`: canonical catalog entry, or the unlinked candidate when no catalog is present.
- `error`: unsupported value type, filesystem write failure, malformed URI, or identity construction failure.
Source Files
Directories