serviceapi

type Definition interface {
	px.Value
	issue.Labeled

	// Identifier returns a TypedName that uniquely identifies the step within the service.
	Identifier() px.TypedName

	// ServiceId is the identifier of the service
	ServiceId() px.TypedName

	// Properties is an ordered map of properties of this definition. Will be of type
	// Hash[Pattern[/\A[a-z][A-Za-z]+\z/],RichData]
	Properties() px.OrderedMap
}

type ErrorObject interface {
	px.PuppetObject

	// Kind returns the error kind
	Kind() string

	// Message returns the error message
	Message() string

	// IssueCode returns the issue code
	IssueCode() string

	// PartialResult returns the optional partial result. It returns
	// pcore.UNDEF if no partial result exists
	PartialResult() px.Value

	// Details returns the optional details. It returns
	// an empty map when no details exist
	Details() px.OrderedMap

	// ToReported checks if the IssueCode represents a known issue.Reported code in this executable,
	// and if so, reconstructs the original error using the code and arguments and returns it and true.
	//
	// nil, false is returned if the IssueCode is unknown to the current executable.
	ToReported() (issue.Reported, bool)
}

type Identity interface {
	BumpEra(px.Context)
	AddReference(ctx px.Context, internalId, otherId string)
	Associate(ctx px.Context, internalID string, externalID string)
	GetExternal(ctx px.Context, internalID string) (string, bool)
	GetInternal(ctx px.Context, externalID string) (string, bool)
	PurgeExternal(ctx px.Context, externalID string)
	PurgeInternal(ctx px.Context, internalID string)
	PurgeReferences(ctx px.Context, internalIDPrefix string)
	RemoveExternal(ctx px.Context, externalID string)
	RemoveInternal(ctx px.Context, internalID string)
	Search(ctx px.Context, internalIDPrefix string) px.List
	Sweep(ctx px.Context, internalIDPrefix string)
	Garbage(ctx px.Context, internalIDPrefix string) px.List
}

type Invokable interface {
	// Invoke will call a method with the given name on the object identified by the given
	// identifier and return the result.
	Invoke(c px.Context, identifier, name string, arguments ...px.Value) px.Value
}

type Metadata interface {
	Metadata(px.Context) (typeSet px.TypeSet, definitions []Definition)
}

type Parameter interface {
	px.Value

	// Name of the parameter
	Name() string

	// Alias to use inside the step that uses this parameter or the empty
	// string if no alias exists.
	Alias() string

	// The Type of the parameter.
	Type() px.Type

	// The parameter value, or nil if parameter has no value. An Undef is
	// considered a valid value.
	Value() px.Value
}

type Service interface {
	Invokable
	Metadata
	StateResolver

	Identifier(px.Context) px.TypedName
}

type StateResolver interface {
	// State looks up a state that has been previously registered with the given name,
	// resolves it using the given parameters, and returns the created state object.
	State(c px.Context, name string, parameters px.OrderedMap) px.PuppetObject
}