Actyx / machines

5 stars 0 forks source link

machine-check API ergonomics issues #63

Open Kelerchian opened 1 year ago

Kelerchian commented 1 year ago

When writing API for machine-check, there are some concerns regarding the ergonomics:

Repeated arbitrary string

Arbitrary strings in the SwarmTypeProtocol transition properties are prone to error, especially typos. While target and source states cannot be non-arbitrary strings without any significant change, writing a role and cmd can be omitted.

sidenote: This, however, would be a non-problem if eventually machine-check codes will be autogenerated.

cmd name must match the implemented MachineProtocol

There does not seem to be any point in ensuring that cmd name matches the implemented MachineProtocol. cmd name is neither persisted in Actyx nor used in any transition calculation. It is used only for function naming purposes, which should be irrelevant to the well-formed ness of a machine-runner MachineProtocol,

Possible Solution

Replace role field with MachineProtocol

machine-check understands the types exposed by machine-runner. Therefore machine-check knows how to extract createJSONForAnalysis and subsequently the subscriptions of each machines. This solves repeated arbitrary string issue for role.

Use builder pattern to collect events and define states before defining the transitions

SwarmProtocolInteractionDesign
  .build(ProtocolEvents.All, [
    "Initial",
    "Docking",
    "DockedAndWaitingForWater",
    "WaterDrawn"
  ])
  .transition(
    "Initial", 
    pump.machine, 
    [ProtocolEvents.DockAvailable.type],
    "Docking"
  )
  .transition(
    "Docking", 
    robot.machine, 
    [ProtocolEvents.RobotIsDocked.type], 
    "DockedAndWaitingForWater"
  )
  .transition(
    "DockedAndWaitingForWater", 
    pump.machine, 
    [ProtocolEvents.WaterSupplied.type], 
    "WaterDrawn"
  )
  .transition(
    "WaterDrawn", 
    robot.machine, 
    [ProtocolEvents.RobotIsUndocked.type], 
    "Undocked"
  )
  .roleInitial(robot.machine, robot._1_WaitingForDock)
  .roleInitial(pump.machine, pump._1_Initial)
  .finish()
  .test()
  // at this point: 
  // 1. all roles have initials figured out
  // 2. test suite can figure out the subscriptions
  // 3. test suite can test each role's projections

Remove cmd checking in the rust code

This solves cmd name must match the implemented MachineProtocol

rkuhn commented 1 year ago

This may be valuable background for but also superseded by #74 and #66 .