Documentation
¶
Overview ¶
Package appnet provides network actions for the operation graph.
Index ¶
- Constants
- type Provider
- type Resource
- func (r *Resource) Addressing() op.AddressingMode
- func (*Resource) CanConvertFrom(source reflect.Type) bool
- func (*Resource) ConvertFrom(value any) (any, error)
- func (r *Resource) Digest() (op.Digest, error)
- func (r *Resource) Equal(other any) bool
- func (r *Resource) Etag() (string, error)
- func (r *Resource) String() string
- func (r *Resource) UnmarshalJSON(data []byte) error
- func (r *Resource) UnmarshalText(text []byte) error
- func (r *Resource) UnmarshalYAML(unmarshal func(any) error) error
Constants ¶
const (
Download op.ActionName = "appnet.download"
)
Action-name constants for the appnet provider's plan-mode actions.
Each constant is the short dotted action label its method dispatches under. Pass these to plan.Plan, op.ReceiverRegistry().BuildAction, RuntimeEnvironment.ActionByName, or WithActionNamed in place of a string literal so a typo is a compile error and rename / find-references work through the constant.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Provider ¶
type Provider struct {
op.ProviderBase
}
Provider provides network actions.
+devlore:access=planned
func NewProvider ¶
func NewProvider(runtimeEnvironment *op.RuntimeEnvironment) *Provider
NewProvider creates a network-actions provider bound to the given context.
func (*Provider) Download ¶
Download fetches the content at the given URL and returns the response body.
Parameters:
- `url`: network resource identifying the URL to fetch.
Returns:
- `[]byte`: the response body read from the URL.
- `error`: non-nil if the request fails, the response status is not 200 OK, or the body cannot be read.
type Resource ¶
type Resource struct {
op.ResourceBase
// SourceURL is a parsed view of the URI. Derived from URI at construction and on unmarshal; not
// persisted (the URI on ResourceBase is authoritative).
SourceURL *url.URL `json:"-" yaml:"-"`
}
Resource represents a network resource identified by a URL.
The URI IS the canonical full URL — scheme, host, path, and query. The scheme is preserved because it's reachability-critical (http vs. https vs. ftp are distinct endpoints). Canonicalization normalizes host casing, strips default ports, normalizes percent-encoding, strips trailing slashes, collapses repeated slashes, and sorts query parameters — all semantics-preserving transforms over the given URL.
Two URLs that differ only in the transport scheme (e.g., "http://x" vs. "https://x") produce distinct resources. This is a deliberate consequence of "identity ensures reachability." Consumers that want transport-independent addressing should factor that into their own logic; appnet.Resource does not.
SourceURL is a non-persisted *url.URL view of the URI, populated at construction (and reparsed on unmarshal) for callers that want structured URL access. It always equals url.Parse(URI).
func DiscoverResource ¶
func DiscoverResource(runtimeEnvironment *op.RuntimeEnvironment, value any) (*Resource, error)
DiscoverResource registers an appnet.Resource via op.ResourceCatalog.Discover without claiming production.
Used by the framework's resource registry adapter for slot coercion (when starlark supplies a string and the slot expects a *appnet.Resource), and by callers that hold a reference handle without claiming to have produced the underlying URL endpoint (UnmarshalJSON/Text/YAML rehydration is the canonical example).
Discover does not stamp a producer, so unlike NewResource it takes only `runtimeEnvironment` — no unit reference is needed.
Nil-Catalog tolerance mirrors the receipt-rehydration paths.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `value`: a string URL with a transport scheme.
Returns:
- `*Resource`: the canonical catalog entry (or the unlinked candidate when no catalog is present).
- `error`: if `value` is not a string, does not parse as a URL, or has no scheme.
func NewResource ¶
func NewResource(runtimeEnvironment *op.RuntimeEnvironment, producerID string, value any) (*Resource, error)
NewResource constructs an appnet.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, scanner-style discovery, the framework's slot-coercion adapter).
Today no appnet provider method actually claims production — Download returns []byte, not *Resource; future fetchers (e.g., 13.0(k.10)'s Download → *stream.Resource) would produce a stream.Resource, not an appnet.Resource. NewResource exists for symmetry with the m.4 two-constructor pattern and as a stable surface for any future appnet producer.
The URL is canonicalized (lowercase host, strip default port, normalize percent-encoding, strip trailing slash, collapse double slashes, sort query parameters) while preserving the transport scheme. The canonicalized URL becomes the Resource's URI; SourceURL is populated by reparsing it.
Nil-Catalog tolerance mirrors DiscoverResource: when `runtimeEnvironment.Catalog` is nil (test fixtures, library callers without a runtime), the candidate is returned unlinked.
Parameters:
- `runtimeEnvironment`: the session runtime environment.
- `producerID`: the producing caller's id (`activationRecord.CallerID`), or "" for caller-less dispatch. for non-graph dispatch.
- `value`: a string URL with a transport scheme.
Returns:
- `*Resource`: the canonical catalog entry (or the unlinked candidate when no catalog is present).
- `error`: if `value` is not a string, does not parse as a URL, or has no scheme.
func (*Resource) Addressing ¶
func (r *Resource) Addressing() op.AddressingMode
Addressing reports that appnet.Resource is location-keyed: the canonical URL is the identity.
The bytes served at that URL are not part of this Resource's identity — that concern belongs to a separate stream-shaped Resource (planned: stream.Resource in 13.0(k) sub-step k.10), which Download will eventually return instead of bare bytes.
Returns:
- `op.AddressingMode`: always op.AddressingLocation.
func (*Resource) CanConvertFrom ¶
CanConvertFrom reports whether `source` can be projected into a *Resource via Resource.ConvertFrom.
Opts the appnet Resource into the framework's op.TargetConverter contract — accepted source shape is `string` (interpreted as a URL). The framework consults this probe both at plan-time via [op.typesAreInterconvertible] (the bubble-up parameter-consistency check) and at dispatch-time via op.Convert step 7 (env-less fallback). The canonical dispatch-time path remains the registered constructor at op.Convert step 6, which receives the full op.RuntimeEnvironment and canonicalizes the URL via [buildCandidate].
Cheap-probe contract: this method is called against a nil-or-zero `*Resource` receiver by [op.typesAreInterconvertible] during plan-time bubble-up checks. MUST NOT dereference receiver fields.
Parameters:
- `source`: the candidate source type to test.
Returns:
- `bool`: true when `source` is `string`.
func (*Resource) ConvertFrom ¶
ConvertFrom projects `value` into an env-less unlinked *Resource.
Used by op.Convert step 7 when the env-aware registered constructor (step 6) is unavailable — env-less library callers, tests, or op.RuntimeEnvironment.Registry-missing contexts. The returned Resource carries only the SourceURL parsed from `value`; the canonical URI on the embedded op.ResourceBase is NOT populated here. Provider methods consuming the projected Resource are responsible for re-canonicalization via their own NewResource/DiscoverResource path when full identity is required.
Parameters:
- `value`: the source value; must be `string`.
Returns:
- `any`: the constructed unlinked *Resource.
- `error`: non-nil when `value` is not a `string` or does not parse as a URL.
func (*Resource) Digest ¶
Digest returns sha256 of the canonical URL.
The bytes served at the URL are not part of identity here (see Resource.Addressing); content addressing of fetched bytes is the future stream.Resource's job. Hashing the URL keeps the digest consistent in algorithm with the rest of the system (the catalog's op.ParseDigest only accepts sha256) and gives appnet.Resource a stable, content-addressable token derived from its identity.
Returns:
- `op.Digest`: sha256 algorithm with 32 raw bytes.
- `error`: nil under normal conditions.
func (*Resource) Equal ¶
Equal reports whether r and other identify the same appnet resource.
Strict equality: other must be a *appnet.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`: the value to compare against; may be any, including nil or a non-Resource.
Returns:
- `bool`: true if `other` is a *appnet.Resource with the same URI as r.
func (*Resource) Etag ¶
Etag returns the canonical URL itself.
For a URL-keyed Resource, the URL IS the change-detection token — two appnet.Resources with the same URL are the same Resource (same etag); two with different URLs are different Resources (different URI, different catalog entry, no shadowing involved). The catalog's Etag fast-path therefore always matches for an unchanged appnet.Resource.
Returns:
- `string`: the canonical URL (identical to op.ResourceBase.URI).
- `error`: nil under normal conditions.
func (*Resource) String ¶
String returns a debug-oriented single-line representation of the resource.
Returns:
- `string`: `appnet.Resource{uri=<URI>}`.
func (*Resource) UnmarshalJSON ¶
UnmarshalJSON populates the receiver from its JSON document (a bare URL string).
The caller pre-seeds the receiver's embedded op.ResourceBase with a valid op.RuntimeEnvironment before invoking this method. The URL alone is sufficient — identity IS reachability.
Parameters:
- `data`: JSON-encoded document (a bare URL string).
Returns:
- `error`: missing RuntimeEnvironment on receiver, JSON decode failure, or rehydration failure.
func (*Resource) UnmarshalText ¶
UnmarshalText populates the receiver from raw UTF-8 bytes containing the URL.
Parameters:
- `text`: UTF-8 bytes containing the resource's URL.
Returns:
- `error`: missing RuntimeEnvironment on receiver, or rehydration failure.
func (*Resource) UnmarshalYAML ¶
UnmarshalYAML populates the receiver from its YAML document (a bare URL scalar).
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.
Source Files
Directories