🥮 mooncakes.io

    moon-lander-moonx

    Optional isolated Moonx process launcher and private Node payload lifetime

    Download zip
    Author
    Version
    0.11.0
    License
    Apache-2.0
    Repository
    Last updated
    4 days ago
    Downloads
    258

    #Moonx process launcher

    moonrockz/moon-lander-moonx is an optional parent process adapter. Its root package contains portable immutable launch values. The process driver owns a separate runtime; keep canonical hosting and actors in the application process.

    Parse executable text and arguments once. Empty arguments, delimiters, Unicode and newlines remain opaque. NUL is rejected because OS argument arrays cannot represent it. A shutdown grace period is positive and defaults to five seconds.

    The Node executable must be available on PATH, or the application supplies an explicit executable. This module does not install Node or own application schemas.

    Original SIGINT/SIGTERM forwarding is guaranteed on POSIX. Stock Windows Moonrun delivers parent Ctrl-C as Ctrl-Break to Node, whose genuine host reports Quit/131. The parent retains its original observation and full Windows status. See the guide for this limitation and actual Windows cleanup qualification.

    The launcher and payload guide describes the public synchronous driver, private Node payloads and typed completion callbacks. Runtime provenance records the frozen source, test inputs and removal path.

    ///|
    test "construct an immutable Node payload plan" {
      let entry = @moonx.RelativeFilePath::parse("app/entry.js")
      let payload = @moonx.Payload::new([
        @moonx.PayloadFile::new(entry, b"process.exitCode = 23;"),
      ], entry)
      let arguments = @moonx.Arguments::parse(["", "--", "a b", "é🙂"])
      let plan = @moonx.NodeLaunch::new(payload, arguments)
      assert_eq(plan.payload().entry().to_string(), "app/entry.js")
      assert_eq(plan.arguments().to_array(), ["", "--", "a b", "é🙂"])
    }

    ArgumentsError

    source
    pub suberror ArgumentsError {
      ArgumentContainsNul(input~ : String, index~ : Int)
    } derive(
    Debug    )

    An argument that an OS process cannot represent.

    ArgumentsError::to_repr

    source

    ExecutableError

    source
    pub suberror ExecutableError {
      InvalidExecutable(input~ : String, rule~ : ExecutableRule)
    } derive(
    Debug    )

    Invalid executable text, retained with its rule.

    ExecutableError::to_repr

    source

    PayloadError

    source
    pub suberror PayloadError {
      DuplicatePayloadPath(first~ : RelativeFilePath, second~ : RelativeFilePath)
      PayloadFileDirectoryConflict(file~ : RelativeFilePath, descendant~ : RelativeFilePath)
      PayloadDirectoryCaseConflict(first~ : RelativeFilePath, second~ : RelativeFilePath)
      PayloadEntryMissing(entry~ : RelativeFilePath)
    } derive(
    Debug    )

    A layout collision or missing entry, retaining the parsed names involved.

    PayloadError::to_repr

    source

    PayloadPathError

    source
    pub suberror PayloadPathError {
      InvalidPayloadPath(input~ : String, rule~ : PayloadPathRule)
    } derive(
    Debug    )

    An invalid original asset name and the rule that it breaks.

    PayloadPathError::to_repr

    source

    ShutdownGraceError

    source
    pub suberror ShutdownGraceError {
      NonPositiveShutdownGrace(milliseconds~ : Int)
    } derive(
    Debug    )

    A graceful-stop deadline must be positive and fit the runtime millisecond count.

    ShutdownGraceError::to_repr

    source

    Arguments

    source
    pub struct Arguments {
      // private fields
    }

    An immutable ordered argument array. Empty elements and delimiters are opaque.

    Arguments::concat

    source
    fn Arguments::concat(self : Arguments, other : Arguments) -> Arguments

    Derive a valid argument list from two already parsed lists, without parsing their elements again or sharing a mutable array.

    Arguments::empty

    source
    fn Arguments::empty() -> Arguments

    A valid empty argument list.

    Arguments::parse

    source
    fn Arguments::parse(inputs : Array[String]) -> Arguments raise ArgumentsError

    Parse NUL-free arguments and retain a separate immutable array value.

    Arguments::to_array

    source
    fn Arguments::to_array(self : Arguments) -> Array[String]

    A fresh array. Mutating it cannot change these arguments.

    CancellationCause

    source
    pub(all) enum CancellationCause {
      Signal(LauncherSignal)
      Requested
    } derive(
    Debug    )

    Distinguish an observed OS signal from ordinary cancellation.

    CancellationCause::to_repr

    source

    ChildCompletion

    source
    pub(all) enum ChildCompletion {
      Exited(ProcessStatus)
      Stopped(cause~ : CancellationCause, status~ : ProcessStatus, force_requested~ : Bool)
      Failed(Error)
    } derive(
    Debug    )

    Observed completion of a started child. The force flag records a request; the status is the actual wait result, independent of inferred cause of death.

    ChildCompletion::to_repr

    source

    Command

    source
    pub struct Command {
      // private fields
    }

    A process invocation with no shell interpretation.

    Command::arguments

    source
    fn Command::arguments(self : Command) -> Arguments

    The immutable application argument list.

    Command::executable

    source
    fn Command::executable(self : Command) -> Executable

    The selected executable.

    Command::new

    source
    fn Command::new(program : Executable, args : Arguments) -> Command

    Construct an invocation from already parsed process inputs.

    Executable

    source
    pub struct Executable {
      // private fields
    } derive(
    Debug    )

    An executable path or PATH lookup name. It is nonempty and has no NUL.

    Executable::node

    source
    fn Executable::node() -> Executable

    Look up Node through the caller's PATH.

    Executable::parse

    source
    fn Executable::parse(input : String) -> Executable raise ExecutableError

    Parse nonempty, NUL-free executable text without changing its spelling.

    Executable::to_repr

    source

    Executable::to_string

    source
    fn Executable::to_string(self : Executable) -> String

    The original executable text.

    ExecutableRule

    source
    pub enum ExecutableRule {
      Empty
      ContainsNul
    } derive(Eq, 
    Debug    )

    A rule that executable text can break.

    ExecutableRule::equal

    source

    ExecutableRule::not_equal

    source
    fn ExecutableRule::not_equal(x : ExecutableRule, y : ExecutableRule) -> Bool

    ExecutableRule::to_repr

    source

    FinalizationFailure

    source
    pub(all) enum FinalizationFailure {
      PayloadCleanup(Error)
      Finalizer(Error)
    } derive(
    Debug    )

    A protected cleanup or application finalizer failure after child reaping.

    FinalizationFailure::to_repr

    source

    LaunchOutcome

    source
    pub struct LaunchOutcome {
      // private fields
    }

    Observations made by the driver after cleanup. The selected parent status is separate from child completion because a signal or finalization failure can select a different parent status. The callback receives the selection before its own invocation; a callback failure can still turn success into failure.

    LaunchOutcome::finalization_failures

    source
    fn LaunchOutcome::finalization_failures(self : LaunchOutcome) -> Array[FinalizationFailure]

    A fresh collection of protected cleanup and finalizer failures.

    LaunchOutcome::new

    source
    fn LaunchOutcome::new(result : LaunchResult, selected : ProcessStatus, failures : Array[FinalizationFailure]) -> LaunchOutcome

    Retain typed observations and a separate copy of the failure collection.

    LaunchOutcome::result

    source

    The observed startup boundary and child completion.

    LaunchOutcome::selected_status

    source
    fn LaunchOutcome::selected_status(self : LaunchOutcome) -> ProcessStatus

    Parent status selected after cleanup and before the completion callback.

    LaunchPlan

    source
    pub(all) enum LaunchPlan {
      Process(Command)
      Node(NodeLaunch)
    }

    Work for the optional process driver. Every case contains valid immutable values.

    LaunchResult

    source
    pub(all) enum LaunchResult {
      NotStarted(StartupStop)
      Started(ChildCompletion)
    } derive(
    Debug    )

    The factual startup boundary used for application-owned result reporting.

    LaunchResult::to_repr

    source

    LauncherSignal

    source
    pub(all) enum LauncherSignal {
      Interrupt
      Terminate
      Hangup
      Break
    } derive(Eq, 
    Debug    )

    OS identity, independent of platform-specific signal numbers.

    LauncherSignal::equal

    source

    LauncherSignal::not_equal

    source
    fn LauncherSignal::not_equal(x : LauncherSignal, y : LauncherSignal) -> Bool

    LauncherSignal::to_repr

    source

    NodeLaunch

    source
    pub struct NodeLaunch {
      // private fields
    }

    A Node executable, owned payload and opaque application arguments.

    NodeLaunch::arguments

    source
    fn NodeLaunch::arguments(self : NodeLaunch) -> Arguments

    The opaque application arguments after the private absolute entry path.

    NodeLaunch::executable

    source
    fn NodeLaunch::executable(self : NodeLaunch) -> Executable

    The selected Node executable, defaulting to PATH lookup.

    NodeLaunch::new

    source
    fn NodeLaunch::new(payload : Payload, args : Arguments, node? : Executable) -> NodeLaunch

    Construct a Node launch from a valid complete payload and parsed arguments.

    NodeLaunch::payload

    source
    fn NodeLaunch::payload(self : NodeLaunch) -> Payload

    The immutable complete file layout.

    Payload

    source
    pub struct Payload {
      // private fields
    }

    A complete collision-free immutable layout with an entry that names an actual file. File order is retained; path identity is ASCII case insensitive.

    Payload::entry

    source
    fn Payload::entry(self : Payload) -> RelativeFilePath

    The exact retained entry filename.

    Payload::files

    source
    fn Payload::files(self : Payload) -> Array[PayloadFile]

    A fresh array whose immutable entries retain the original order.

    Payload::new

    source
    fn Payload::new(files : Array[PayloadFile], entry : RelativeFilePath) -> Payload raise PayloadError

    Parse collection rules once and take ownership of a separate file array.

    PayloadFile

    source
    pub struct PayloadFile {
      // private fields
    }

    An immutable asset entry. Bytes are immutable MoonBit values.

    PayloadFile::bytes

    source
    fn PayloadFile::bytes(self : PayloadFile) -> Bytes

    The exact immutable asset bytes.

    PayloadFile::new

    source
    fn PayloadFile::new(path : RelativeFilePath, bytes : Bytes) -> PayloadFile

    Pair a parsed asset name with immutable bytes.

    PayloadFile::path

    source

    The asset's parsed relative name.

    PayloadPathRule

    source
    pub(all) enum PayloadPathRule {
      Empty
      Absolute
      EmptySegment
      DotSegment
      ParentSegment
      Backslash
      ControlCharacter
      NonAscii
      ReservedCharacter
      TrailingDotOrSpace
      ReservedName
    } derive(Eq, 
    Debug    )

    A lexical rule for portable payload-owned relative names. This restriction applies only to embedded asset names, never to argv, cwd or user paths.

    PayloadPathRule::equal

    source

    PayloadPathRule::not_equal

    source
    fn PayloadPathRule::not_equal(x : PayloadPathRule, y : PayloadPathRule) -> Bool

    PayloadPathRule::to_repr

    source

    ProcessStatus

    source
    pub struct ProcessStatus {
      // private fields
    } derive(Eq, 
    Debug    )

    A full process status bit pattern. Windows keeps all 32 bits; POSIX process boundaries retain the low byte. The driver normalizes a POSIX signal result before constructing this value.

    ProcessStatus::bits

    source
    fn ProcessStatus::bits(self : ProcessStatus) -> UInt

    The complete unsigned status bit pattern.

    ProcessStatus::equal

    source

    ProcessStatus::failure

    source
    fn ProcessStatus::failure() -> ProcessStatus

    The conventional unhandled-failure status.

    ProcessStatus::from_bits

    source
    fn ProcessStatus::from_bits(bits : UInt) -> ProcessStatus

    Every unsigned 32-bit pattern is a valid Windows process status.

    ProcessStatus::is_success

    source
    fn ProcessStatus::is_success(self : ProcessStatus) -> Bool

    Whether the complete status is zero.

    ProcessStatus::not_equal

    source
    fn ProcessStatus::not_equal(x : ProcessStatus, y : ProcessStatus) -> Bool

    ProcessStatus::success

    source
    fn ProcessStatus::success() -> ProcessStatus

    A successful finite process completion.

    ProcessStatus::to_int

    source
    fn ProcessStatus::to_int(self : ProcessStatus) -> Int

    Signed representation accepted by the process exit boundary, without losing Windows status bits.

    ProcessStatus::to_repr

    source

    RelativeFilePath

    source
    pub struct RelativeFilePath {
      // private fields
    } derive(
    Debug    )

    A nonempty relative slash-separated ASCII asset name, portable to Windows and POSIX filesystems, with no traversal, reserved syntax or ambiguous names.

    RelativeFilePath::parse

    source
    fn RelativeFilePath::parse(input : String) -> RelativeFilePath raise PayloadPathError

    Parse an unambiguous portable asset name before filesystem access.

    RelativeFilePath::to_repr

    source

    RelativeFilePath::to_string

    source
    fn RelativeFilePath::to_string(self : RelativeFilePath) -> String

    The retained spelling of this relative asset name.

    ShutdownGrace

    source
    pub struct ShutdownGrace {
      // private fields
    }

    A positive grace period before forced child termination.

    ShutdownGrace::from_milliseconds

    source
    fn ShutdownGrace::from_milliseconds(milliseconds : Int) -> ShutdownGrace raise ShutdownGraceError

    Parse a positive runtime millisecond count.

    ShutdownGrace::milliseconds

    source
    fn ShutdownGrace::milliseconds(self : ShutdownGrace) -> Int

    The validated runtime millisecond count.

    ShutdownGrace::standard

    source
    fn ShutdownGrace::standard() -> ShutdownGrace

    The standard five-second child grace period.

    StartupFailure

    source
    pub(all) enum StartupFailure {
      Materialization(Error)
      NodeMissing(executable~ : Executable, cause~ : Error)
      ProcessStart(Error)
    } derive(
    Debug    )

    Typed failure boundaries before an owned child was created.

    StartupFailure::to_repr

    source

    StartupStop

    source
    pub(all) enum StartupStop {
      Failed(StartupFailure)
      Cancelled(CancellationCause)
    } derive(
    Debug    )

    Why no child started, including cancellation during materialization.

    StartupStop::to_repr

    source

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io