Documentation ¶
Index ¶
- Constants
- Variables
- func ExitCodeForCategory(category interface{}) int
- func ExitCodeForError(err error) int
- func ReboxRioError(err error) error
- type Error
- type ErrorCategory
- type Event
- type Event_Log
- type Event_Output
- type Event_Result
- type FormulaContext
- type InputControl
- type LogLevel
- type Monitor
- type RunFunc
Constants ¶
const ( ErrUsage = ErrorCategory("repeatr-usage-error") // Indicates some piece of user input to a command was invalid and unrunnable. ErrWarehouseUnwritable = ErrorCategory(rio.ErrWarehouseUnwritable) // The corresponding rio error halted execution. ErrWareNotFound = ErrorCategory(rio.ErrWareNotFound) // The corresponding rio error halted execution. ErrWareCorrupt = ErrorCategory(rio.ErrWareCorrupt) // The corresponding rio error halted execution. ErrWareHashMismatch = ErrorCategory(rio.ErrWareHashMismatch) // The corresponding rio error halted execution. ErrCancelled = ErrorCategory(rio.ErrCancelled) // The corresponding rio error halted execution. ErrRioCacheProblem = ErrorCategory(rio.ErrLocalCacheProblem) // The corresponding rio error halted execution. ErrAssemblyInvalid = ErrorCategory(rio.ErrAssemblyInvalid) // The corresponding rio error halted execution. ErrPackInvalid = ErrorCategory(rio.ErrPackInvalid) // The corresponding rio error halted execution. ErrInoperablePath = ErrorCategory(rio.ErrInoperablePath) // The corresponding rio error halted execution. (This one shouldn't show up much...! Things like "out of disk" or such could still cause this though.) ErrFilterRejection = ErrorCategory(rio.ErrFilterRejection) // The corresponding rio error halted execution. (This one shouldn't show up much! By default, Repeatr uses "keep all" settings. But users can still configure rejection filters.) ErrJobUnsuccessful = ErrorCategory("repeatr-job-unsuccessful") // Not an error -- indicates that the contained process exited nonzero. TODO review if this needs an error category or just a reserved space in the exit code table. ErrJobInvalid = ErrorCategory("repeatr-job-invalid") // Indicates the container could not be launched because some part of its specification was invalid -- for example, the CWD requested is not a dir, or the command to exec is not an executable. (The whole filesystem may have been necessary to set up before this can be detected.) ErrLocalCacheProblem = ErrorCategory("repeatr-local-cache-problem") // Indicates an error while while handling internal filesystem paths (for example, if an executor can't mkdir its workspace dirs). ErrExecutor = ErrorCategory("repeatr-executor-problem") // Indicates an error occured while launching containment or handling the child processes. Should be seen rarely -- comes up for esotera like "out of file handles". ErrRPCBreakdown = ErrorCategory("repeatr-rpc-breakdown") // Raised when running a remote process and the control channel is lost, the process fails to start, or unrecognized messages are received. )
Variables ¶
var Atlas = atlas.MustBuild( Event_AtlasEntry, Error_AtlasEntry, commonatlases.Time_AsUnixInt, api.FormulaRunRecord_AtlasEntry, api.WareID_AtlasEntry, )
repeatr.Atlas encompases all the response types of RunFunc, and also includes event/log serialization.
var ErrorTable = []struct { ExitCode int RepeatrError ErrorCategory }{ {ExitCode: 1, RepeatrError: ErrUsage}, {ExitCode: 2, RepeatrError: ""}, {ExitCode: 3, RepeatrError: ErrWarehouseUnavailable}, {ExitCode: 4, RepeatrError: ErrWarehouseUnwritable}, {ExitCode: 5, RepeatrError: ErrWareNotFound}, {ExitCode: 6, RepeatrError: ErrWareCorrupt}, {ExitCode: 7, RepeatrError: ErrWareHashMismatch}, {ExitCode: 8, RepeatrError: ErrCancelled}, {ExitCode: 9, RepeatrError: ErrRioCacheProblem}, {ExitCode: 10, RepeatrError: ErrAssemblyInvalid}, {ExitCode: 11, RepeatrError: ErrPackInvalid}, {ExitCode: 12, RepeatrError: ErrInoperablePath}, {ExitCode: 13, RepeatrError: ErrFilterRejection}, {ExitCode: 32, RepeatrError: ErrJobUnsuccessful}, {ExitCode: 40, RepeatrError: ErrJobInvalid}, {ExitCode: 41, RepeatrError: ErrLocalCacheProblem}, {ExitCode: 42, RepeatrError: ErrExecutor}, {ExitCode: 120, RepeatrError: ErrRPCBreakdown}, }
var Error_AtlasEntry = atlas.BuildEntry(Error{}).StructMap().Autogenerate().Complete()
var Event_AtlasEntry = atlas.BuildEntry((*Event)(nil)).KeyedUnion(). Of(map[string]*atlas.AtlasEntry{ "log": Event_Log_AtlasEntry, "txt": Event_Output_AtlasEntry, "result": Event_Result_AtlasEntry, })
var Event_Log_AtlasEntry = atlas.BuildEntry(Event_Log{}).StructMap().Autogenerate().Complete()
var Event_Output_AtlasEntry = atlas.BuildEntry(Event_Output{}).StructMap().Autogenerate().Complete()
var Event_Result_AtlasEntry = atlas.BuildEntry(Event_Result{}).StructMap().Autogenerate().Complete()
var FormulaContext_AtlasEntry = atlas.BuildEntry(FormulaContext{}).StructMap().Autogenerate().Complete()
Functions ¶
func ExitCodeForCategory ¶
func ExitCodeForCategory(category interface{}) int
ExitCodeForCategory translates an errcat category into a numeric exit code.
func ExitCodeForError ¶
ExitCodeForError translates an error into a numeric exit code, looking up a code based on the errcat category of the error.
func ReboxRioError ¶
ReboxRioError is a utility function for flipping rio.ErrorCategory into repeatr.ErrorCategory (or, returning ErrRPCBreakdown for unexpected cases).
Types ¶
type Error ¶
type Error struct { Category_ ErrorCategory `json:"category" refmt:"category"` Message_ string `json:"message" refmt:"message"` Details_ map[string]string `json:"details,omitempty" refmt:"details,omitempty"` }
Error implements the errcat.Error interface, specifically using this package's ErrorCategory as the concrete category, and giving us a type to hang custom serialization on.
type ErrorCategory ¶
type ErrorCategory string
type Event ¶
type Event interface {
// contains filtered or unexported methods
}
A "union" type of all the kinds of event that may be generated in the course of any of the functions.
type Event_Log ¶
type Event_Log struct { Time time.Time `refmt:"t"` Level LogLevel `refmt:"lvl"` Msg string `refmt:"msg"` Detail [][2]string `refmt:"detail,omitempty"` }
Logs from repeatr code. May include logs proxied up from rio.
type Event_Output ¶
Output from the contained process (stdout/stderr conjoined). Stderr/stdout are conjoined so their ordering does not slip. There is no guarantee of buffering (especially not line buffering); in other words, `printch('.')` may indeed flush.
type Event_Result ¶
type Event_Result struct { Record *api.FormulaRunRecord `refmt:"runRecord,omitempty"` Error *Error `refmt:",omitempty"` }
Final results. (Also converted into returns.)
type FormulaContext ¶
type FormulaContext struct { FetchUrls map[api.AbsPath][]api.WarehouseLocation SaveUrls map[api.AbsPath]api.WarehouseLocation }
FormulaContext bundles information which is important to being *able* to run the computation, but *immaterial* to the output. Specifically, this means URLs for where to get things, and where to save them.
This type definition is hiding in the repeatr-specific package rather than escalated into the group of main API types because it's useful precisely at the level of repeatr. Lower levels, e.g. Rio, don't need these groupings; and higher levels, e.g. Stellar, also do something more opinionated (see: WareSourcing).
type InputControl ¶
type InputControl struct {
Chan <-chan string
}
type LogLevel ¶
type LogLevel int8
const ( LogError LogLevel = 4 // Error log lines, if used, mean the program is on its way to exiting non-zero. If used more than once, all but the first are other serious failures to clean up gracefully. LogWarn LogLevel = 3 // Warning logs are for systems which have failed, but in acceptable ways; for example, a warehouse that's not online (but a fallback is, so overall we proceeded happily). LogInfo LogLevel = 2 // Info logs are statements about control flow; for example, which warehouses have been tried in what order. LogDebug LogLevel = 1 // Debug logs are off by default. They may get down to the resolution of called per-file in a transmat, for example. )
type Monitor ¶
type Monitor struct {
Chan chan<- Event
}
Monitor hold a channel which is used for event reporting. Logs, contained process output, and results will all be sent to the channel if one is provided.
The same channel and monitor may be used for multiple runs. The channel is not closed when the job is done; any goroutine with blocking service to a channel used for a single job should return after recieving an Event_Result, as it will be the final event.
type RunFunc ¶
type RunFunc func( ctx context.Context, boundOp api.Formula, formulaContext FormulaContext, input InputControl, monitor Monitor, ) (*api.FormulaRunRecord, error)