script

type Context struct {
	// Timeout, when positive, bounds this one execution instead of the engine's own timeout. A JavaScript destination
	// has its own timeout setting and shares the channel's engine; without this the setting was read and then ignored.
	Timeout time.Duration

	// Message is bound to msg: the inbound message as a tree. Nil for a preprocessor, which runs
	// before parsing and may be looking at something that does not parse at all.
	Message *xtree.Node

	// Raw is bound to message: the message as text. This is what a preprocessor reads and returns.
	Raw string

	// RawUnavailable says there is no message text to offer, which is not the same as a message whose text is empty.
	//
	// The path-addressed formats set this. Their scripts reach values through msg.get and msg.set, and this stage does no
	// re-serialisation on purpose - each format's handler owns its own encoding, and a stage that re-encoded would have to
	// learn three of them. So by the time a transformer runs, the declarative steps have already changed the message and the
	// bytes that arrived no longer describe it.
	//
	// Given that, the choice is between binding text that is stale and binding nothing. Stale is worse: it would give a script
	// two disagreeing views of one message, where msg.get returns the current value and message shows the old one, and
	// nothing would report the disagreement. Binding it at the filter and withholding it at the transformer would be accurate
	// but would make the same identifier mean different things two lines apart.
	//
	// So it is withheld throughout, and withheld rather than emptied. An empty string is the failure this project has hit
	// repeatedly: a script computes from nothing, writes a plausible answer and reports success. An absent identifier fails on
	// the first line that touches it, which is the outcome an author can act on. Raw text work belongs in a preprocessor,
	// which runs before any of this and does receive it.
	RawUnavailable bool

	// Output is bound to tmp. When nil, tmp is the same tree as msg, which is
	// what Mirth does for a channel with no outbound template and is how most
	// transformers are written.
	Output *xtree.Node

	ChannelName  string
	ChannelMap   *SharedMap
	ConnectorMap *SharedMap
	ResponseMap  *SharedMap
	SourceMap    *SharedMap

	// Log receives logger calls. When nil they are discarded.
	Log func(level, message string)
}

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

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

type Kind int

type Language string

type LogLine struct {
	Level   string
	Message string
}

type Options struct {
	// Timeout bounds a single execution. Zero means five seconds.
	Timeout time.Duration

	// Permissions granted to every script this engine runs.
	Permissions []Permission

	// FileRoots confines FileUtil to a set of directories.
	//
	// Required whenever PermFile is granted. Nil with PermFile granted means FileUtil refuses every call rather
	// than reaching the whole filesystem, which is what it used to do.
	FileRoots *FileRoots

	// MaxVMs bounds the pooled runtimes. Zero means eight.
	MaxVMs int

	// Language is which runtime the library belongs to.
	//
	// Needed because the library is compiled once at construction and a runtime cannot compile another runtime's source. Before
	// this field existed the library was always compiled as JavaScript, so a Lua library recorded a JavaScript syntax error that
	// only the JavaScript path ever looked at - and the Lua path, which had no library support at all, ignored both the error and
	// the library.
	//
	// Defaults to JavaScript, which is the zero value and the language every existing caller meant.
	Language Language

	// Library is source made available to every script this engine runs.
	//
	// This is Mirth's code templates. A site with forty channels usually has one library every channel
	// calls, and without this a migration means copying it into forty files - which is not only work
	// but forty places to fix the next time it changes.
	Library string

	// LibraryName is what the library is called in an error message. Defaults to a generic name.
	LibraryName string
}

type PathMessage[M any] struct {
	// Value is the message. Replaced rather than mutated when a script writes, because the format accessors are functional -
	// x12.Set returns a new message rather than editing one, which is what makes a failed step leave the original intact.
	Value M

	// Accessor resolves paths for this format.
	Accessor steps.Accessor[M]

	// Changed records the paths a script wrote, in order.
	//
	// Kept so the engine can report what a script did in the same terms a declarative step reports, and so a script that
	// wrote nothing can be told from one that wrote the same value back. The second matters for an audit trail: "the script
	// ran and changed nothing" and "the script ran and set three fields" are different facts.
	Changed []string
}

type Permission string

type Result struct {
	// Accept is the filter verdict. It is false for a transformer.
	Accept bool

	// Logs are the logger lines the script produced, in order.
	Logs []LogLine

	// Duration is how long the script ran.
	Duration time.Duration

	// Text is what a preprocessor returned, when it returned anything.
	Text string

	// Replaced says Text is meaningful. Without it an empty string returned deliberately could not be
	// told apart from a script that returned nothing, and one of those means "discard the message".
	Replaced bool

	// Messages is what a Reader script returned: zero or more raw messages to feed into the channel.
	Messages []string
}

type RouteFunc func(channel string, message []byte) error

type Script struct {
	Name string

	// Source is what the author wrote, kept so the interface can show it.
	Source string

	// Rewritten is what actually runs, kept because a stack trace refers to it.
	Rewritten string

	// Notes record the E4X constructs that were translated, so the interface can
	// say what happened to somebody's script instead of pretending nothing did.
	Notes []e4x.Note
	// contains filtered or unexported fields
}

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