Skip to content

chore: Add XState machines to model flows - #16

Closed
presleyp wants to merge 3 commits into
mainfrom
presleyp/diagrams
Closed

presleyp wants to merge 3 commits into
mainfrom
presleyp/diagrams

Conversation

@presleyp

@presleyp presleyp commented Jan 12, 2022 •

Copy link
Copy Markdown
Contributor

@kylecarbs and I worked out these XState machines to be able to visualize some of the concepts in Workspaces V2. There's a lot more than could be diagrammed and I'd love comments about how to make these better or for others to add on.

The goal is to make it easier for us all to get on the same page about the plan. Accordingly, I optimized these more for comprehension than runnable implementation, but we could push the envelope there as we flesh out more details.

I recommend opening the code in VSCode, installing the XState VSCode extension, and clicking Open Inspector just above each machine definition to see and interact with each one.

Some questions I still have include:

  • what does a model of projects look like?
  • what determines when a provisioner parses vs when it provisions? (Does it do them in sequence automatically or does provisionerd send one kind of instruction or the other?)

Sneak peek of one model:
Screen Shot 2022-01-11 at 10 38 56 PM

@presleyp
presleyp requested review from ketang and kylecarbs January 12, 2022 03:40
@codecov

codecov Bot commented Jan 12, 2022 •

Copy link
Copy Markdown

Codecov Report

Merging #16 (a1ea349) into main (ec3685b) will decrease coverage by 0.71%.
The diff coverage is n/a.

Impacted file tree graph

@@            Coverage Diff             @@
##             main      #16      +/-   ##
==========================================
- Coverage   71.58%   70.86%   -0.72%     
==========================================
  Files          17       17              
  Lines        1112     1112              
==========================================
- Hits          796      788       -8     
- Misses        246      252       +6     
- Partials       70       72       +2     
Flag Coverage Δ
macos-latest ?
ubuntu-latest 70.86% <ø> (+1.43%) ⬆️
windows-latest ?
Impacted Files Coverage Δ
peer/conn.go 71.78% <0.00%> (-2.51%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ec3685b...a1ea349. Read the comment docs.

invoke: {
id: "callProvisionerWithParameters",
src: "provisionerModel",
onDone: { target: "polling", actions: ["returnState", "parseProjectCode"] },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What returnState does?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not implemented since this is for diagramming purposes, but it represents the fact that when provisionerd calls a provisioner and the provisioner executes the code, the resulting state is returned.

@bryphe-coder bryphe-coder left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding these, @presleyp !

I'll need to think through the workspace creation workflow - it would be nice to have a diagram for that too. Maybe we can chat a bit in our 1:1 tomorrow.

@bryphe-coder

bryphe-coder commented Jan 13, 2022 •

Copy link
Copy Markdown
Contributor

@presleyp and I came up with this initial flow for the workspace-creation experience (from a user's perspective):

Workspace Creation: UI

import { createMachine } from "xstate"

/** If using VSCode, install the XState VSCode extension to get a
 * "Open Inspector" link above each machine in your code that will
 * visualize the machine. Otherwise, you can paste code into stately.ai/viz.
 */

interface CreateWorkspaceContext {
  provisioner: any,
  template: any,
  parameters: any,
}

type WorkspaceEvent = { type: "START" } | { type: "BACK" } | { type: "SELECT_PROVISIONER" } | { type: "SELECT_TEMPLATE" } | { type: " SUBMIT_VALUES" }

export const createWorkspaceModel = createMachine<CreateWorkspaceContext, WorkspaceEvent>({
  id: "workspaceV2Model",
  initial: "off",
  states: {
    off: {
      on: {
        START: "starting",
      },
    },
    starting: {
      invoke: {
        src: "listProvisioners",
        onDone: "selectProvisioner",
        onError: "error",
      },
    },
    selectProvisioner: {
      on: {
        SELECT_PROVISIONER: "loadTemplates",
      },
    },
    loadTemplates: {
      invoke: {
        src: "listTemplates",
        onDone: "selectTemplate",
        onError: "error",
      },
    },
    selectTemplate: {
      on: {
        BACK: "selectProvisioner",
        SELECT_TEMPLATE: "loadParameters"
      }
    },
    loadParameters: {
      invoke: {
        src: "listInputFieldsForTemplate",
        onDone: "enterParameters",
        onError: "error"
      }
    },
    enterParameters: {
      on: {
        SUBMIT_VALUES: "createWorkspace",
        BACK: "selectTemplate"
      }
    },
    createWorkspace: {
      invoke: {
        src: "callCreateWorkspaceAPI",
        onDone: "workspaceCreated",
        onError: "error"
      }
    },
    workspaceCreated: {
      type: "final"
    },
    error: {
      entry: "saveErrorMessage",
    },
  },
})

image

@BrunoQuaresma

Copy link
Copy Markdown
Contributor

Maybe, if you all see value on that, we can create substates for the error so we can add specific events for them and make more clear what the user can do in case they see that error. Example:

Screen Shot 2022-01-14 at 10 26 44

import { createMachine } from "xstate";

/** If using VSCode, install the XState VSCode extension to get a
 * "Open Inspector" link above each machine in your code that will
 * visualize the machine. Otherwise, you can paste code into stately.ai/viz.
 */

interface CreateWorkspaceContext {
  provisioner: any;
  template: any;
  parameters: any;
}

type WorkspaceEvent =
  | { type: "START" }
  | { type: "BACK" }
  | { type: "SELECT_PROVISIONER" }
  | { type: "SELECT_TEMPLATE" }
  | { type: "SUBMIT_VALUES" }
  | { type: "RETRY_CREATE_WORKSPACE" };

export const createWorkspaceModel = createMachine<
  CreateWorkspaceContext,
  WorkspaceEvent
>({
  id: "workspaceV2Model",
  initial: "off",
  states: {
    off: {
      on: {
        START: "starting",
      },
    },
    starting: {
      invoke: {
        src: "listProvisioners",
        onDone: "selectProvisioner",
        onError: "error.selectProvisionerError",
      },
    },
    selectProvisioner: {
      on: {
        SELECT_PROVISIONER: "loadTemplates",
      },
    },
    loadTemplates: {
      invoke: {
        src: "listTemplates",
        onDone: "selectTemplate",
        onError: "error.loadTemplateError",
      },
    },
    selectTemplate: {
      on: {
        BACK: "selectProvisioner",
        SELECT_TEMPLATE: "loadParameters",
      },
    },
    loadParameters: {
      invoke: {
        src: "listInputFieldsForTemplate",
        onDone: "enterParameters",
        onError: "error.loadParametersError",
      },
    },
    enterParameters: {
      on: {
        SUBMIT_VALUES: "createWorkspace",
        BACK: "selectTemplate",
      },
    },
    createWorkspace: {
      invoke: {
        src: "callCreateWorkspaceAPI",
        onDone: "workspaceCreated",
        onError: "error.createWorkspaceError",
      },
    },
    workspaceCreated: {
      type: "final",
    },
    error: {
      entry: "saveErrorMessage",
      states: {
        startingError: {},
        loadTemplateError: {},
        loadParametersError: {},
        createWorkspaceError: {
          on: {
            RETRY_CREATE_WORKSPACE: "#workspaceV2Model.createWorkspace",
          },
        },
        selectProvisionerError: {},
      },
    },
  },
});

PS: The machine is missing some info

@stale

stale Bot commented Jan 31, 2022

Copy link
Copy Markdown

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no activity occurs in the next 5 days.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

stale This issue is like stale bread.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants