mem

package
v0.1.0-dev.20260814220830 Latest Latest
Warning

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

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

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 struct {
	op.ResourceBase

	// Hash is the lowercase hex SHA-256 of the archived content. Identity-bearing — also encoded in the URI's
	// <specific> portion as `sha256:<Hash>`. Populated by both construction (post-hash) and rehydration (parsed
	// from URI). Not persisted in serialized form because the URI carries the same value.
	Hash string `json:"-" yaml:"-"`
}

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.

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.

func (*Resource) Addressing 

func (r *Resource) Addressing() op.AddressingMode

Addressing reports that mem.Resource is content-addressed.

Overrides op.ResourceBase.Addressing's op.AddressingUnknown default. The boot-discipline check in pkg/op/addressing_test.go relies on every announced Resource type returning a non-Unknown mode here.

Returns:

func (*Resource) CanConvertTo 

func (r *Resource) CanConvertTo(target reflect.Type) bool

CanConvertTo reports whether this Resource can project to the given target Go type.

Supports []byte and string — both read the archived content through a memory-mapped view. Overrides op.ResourceBase.CanConvertTo's URI-as-string baseline because mem.Resource's string projection means content-as-text, not URI.

Parameters:

  • `target`: destination Go type the caller wants to project the Resource into.

Returns:

  • `bool`: true when target is []byte or string; false otherwise.

func (*Resource) ConvertTo 

func (r *Resource) ConvertTo(target reflect.Type) (result any, err error)

ConvertTo projects the Resource into the requested target Go type.

Supports []byte and string. Both read the archived content through a fresh memory-mapped view that is opened, drained, and closed within this call.

Parameters:

  • `target`: destination Go type — must be []byte or string.

Returns:

  • `any`: projected value ([]byte or string).
  • `error`: unrecognized target type, missing source path, or read failure.

func (*Resource) Digest 

func (r *Resource) Digest() (op.Digest, error)

Digest returns the content digest of the archived bytes.

The SHA-256 was computed during construction (or parsed from the URI on rehydration) and stamped on Resource.Hash. This method reassembles the canonical `sha256:<hex>` form via op.ParseDigest, yielding the strict op.Digest shape with Algorithm = "sha256" and Bytes = the raw 32-byte digest. Overrides op.ResourceBase.Digest's op.ErrUnimplemented default.

Returns:

  • `op.Digest`: {Algorithm: "sha256", Bytes: decoded Hash}.
  • `error`: non-nil if Hash is malformed; should not occur post-construction or post-rehydration.

func (*Resource) Equal 

func (r *Resource) Equal(other any) bool

Equal reports whether r and other identify the same mem.Resource.

Strict equality: other must be a *mem.Resource (not merely an op.Resource with the same URI). Once the type check passes, URI comparison is delegated to op.ResourceBase.Equal.

Parameters:

  • `other`: candidate value to compare against; nil or any non-*mem.Resource value returns false.

Returns:

  • `bool`: true when other is a *mem.Resource with the same URI as r.

func (*Resource) Pack 

func (r *Resource) Pack() ([]byte, error)

Pack implements op.Packer.

The transportable content is the archived bytes themselves, read back from the content-addressed store — the exact bytes whose SHA-256 the URI carries, so pack → unpack → pack round-trips byte-identical.

Returns:

  • `[]byte`: the archived content bytes.
  • `error`: missing SourcePath (a URI-only rehydrated resource has no local content), or a read failure.

func (*Resource) Reader 

func (r *Resource) Reader() (io.ReadCloser, error)

Reader opens a fresh memory-mapped view of the archived content.

Each call opens a new mmap. The caller must Close the returned reader — Close unmaps the underlying file.

Returns:

  • `io.ReadCloser`: reader over the full archived content; Close releases the mmap.
  • `error`: missing SourcePath, or mmap failure.

func (*Resource) SourcePath 

func (r *Resource) SourcePath() fsroot.Path

SourcePath returns the on-disk archive path for this Resource under the runtime environment's fsroot.Root.

The path follows the CAS sharded formula `<Root>/.devlore/<last-pkg-segment>/<lowercase(TypeName)>/<algo>/<hex[0:2]>/<hex>`, where `<last-pkg-segment>` and `<TypeName>` are derived from the URI fragment (the canonical Go type id) and `<algo>:<hex>` is parsed from the URI's <specific> portion. The 2-character prefix shard keeps any single directory bounded as content grows. Embedders inherit this method automatically; their distinct typeID drives a distinct subdirectory (e.g., function.Resource → `.devlore/function/resource/<algo>/<hex[0:2]>/<hex>`).

Returns:

  • `fsroot.Path`: canonical archive path, or the zero fsroot.Path when the Resource has no op.RuntimeEnvironment, no Root, or a <specific> that is not in `<algo>:<hex>` form.

func (*Resource) String 

func (r *Resource) String() string

String returns the compact JSON encoding of the Resource for debug output.

Delegates to op.ResourceBase.Format per the project Go style guideline that String() of every concrete Resource type calls r.Format(r).

Returns:

  • `string`: the compact JSON encoding of r.

func (*Resource) UnmarshalJSON 

func (r *Resource) UnmarshalJSON(data []byte) error

UnmarshalJSON populates the receiver from its JSON document (a bare URI string).

The caller pre-seeds the receiver's embedded op.ResourceBase with a valid op.RuntimeEnvironment before invoking this method. The URI alone is sufficient to reconstruct the Resource: Hash is parsed from the URI's <specific> portion, and SourcePath is computed deterministically from the URI and the runtime environment's Root.

Parameters:

  • `data`: JSON bytes encoding a single bare URI string.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, malformed JSON, or rehydration failure.

func (*Resource) UnmarshalText 

func (r *Resource) UnmarshalText(text []byte) error

UnmarshalText populates the receiver from raw UTF-8 bytes containing the URI.

Same prerequisites and semantics as Resource.UnmarshalJSON; the receiver's op.RuntimeEnvironment must be set before invocation.

Parameters:

  • `text`: UTF-8 bytes containing the canonical tag URI.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, or rehydration failure.

func (*Resource) UnmarshalYAML 

func (r *Resource) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML populates the receiver from its YAML document (a bare URI scalar).

Same prerequisites and semantics as Resource.UnmarshalJSON; the receiver's op.RuntimeEnvironment must be set before invocation.

Parameters:

  • `unmarshal`: yaml decode hook supplied by the YAML library; called with a *string target.

Returns:

  • `error`: missing RuntimeEnvironment on receiver, decode failure, or rehydration failure.

func (*Resource) Unpack 

func (r *Resource) Unpack(runtimeEnvironment *op.RuntimeEnvironment, uri string, content []byte) (op.Resource, error)

Unpack implements op.Unpacker.

Archives `content` into the local content-addressed store and rebuilds the resource from it — the inverse of Resource.Pack. The receiver carries no state (graph load dispatches Unpack on a zero value resolved from the URI fragment's type id). The rebuilt URI must equal `uri`: the URI's digest is covered by the graph checksum and signature, so the equality check is what catches tampered content bytes.

Parameters:

  • `runtimeEnvironment`: the session runtime environment; supplies the store root.
  • `uri`: the canonical tag URI recorded in the document.
  • `content`: the packed bytes produced by Resource.Pack.

Returns:

  • `op.Resource`: the reconstructed *mem.Resource, not interned in any catalog.
  • `error`: store write failure, identity construction failure, or a URI mismatch (integrity failure).

Source Files

View all Source files

Directories

Path Synopsis

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.