Smalll documentation, TODOs.

src/main/nim/strawboss.nim

@@ -65,7 +65,7 @@ Options
         forceRebuild: args["--force-rebuild"],
         workspaceDir: wkspDir)
 
-      let status = core.runStep(cfg, req, logProcOutput)
+      let status = core.initiateBuild(cfg, req, logProcOutput)
       if status.state == "failed": raiseEx status.details
       echo "strawboss: build passed."
     except:

src/main/nim/strawbosspkg/core.nim

@@ -28,12 +28,16 @@ proc resolveEnvVars(line: string, env: StringTableRef): string =
 
 proc emitStatus(status: BuildStatus, statusFilePath: string,
                 outputHandler: HandleProcMsgCB): BuildStatus =
+  ## Emit a BuildStatus to the given file as a JSON object and to the given
+  ## message handlers.
   if statusFilePath != nil: writeFile(statusFilePath, $status)
   if outputHandler != nil:
     outputHandler.sendMsg(status.state & ": " & status.details)
   result = status
 
 proc publishStatus(wksp: Workspace, state, details: string) =
+  ## Update the status for a Workspace and publish this status to the
+  ## Workspace's status file and any output message handlers.
   let status = BuildStatus(state: state, details: details)
   wksp.status = emitStatus(status, wksp.statusFile, wksp.outputHandler)
 
@@ -87,6 +91,10 @@ proc setupProject(wksp: Workspace) =
 
 proc runStep*(wksp: Workspace, step: Step) =
 
+  ## Lower-level method to execute a given step within the context of a project
+  ## workspace that is setup and configured. May be called recursively to
+  ## satisfy step dependencies.
+
   let SB_EXPECTED_VARS = ["VERSION"]
 
   wksp.publishStatus("running",
@@ -151,9 +159,12 @@ proc runStep*(wksp: Workspace, step: Step) =
 
   wksp.publishStatus("complete", "")
 
-proc runStep*(cfg: StrawBossConfig, req: RunRequest,
+proc initiateRun*(cfg: StrawBossConfig, req: RunRequest,
               outputHandler: HandleProcMsgCB = nil): BuildStatus =
 
+  ## Execute a RunReuest given the StrawBoss configuration. This is the main
+  ## entrypoint to  running a build step.
+
   result = BuildStatus(
     state: "setup",
     details: "initializing build workspace")

src/main/nim/strawbosspkg/server.nim

@@ -131,6 +131,9 @@ proc start*(cfg: StrawBossConfig): void =
   let stopFuture = newFuture[void]()
   var workers: seq[Worker] = @[]
 
+  # TODO: add recurring clean-up down to clear completed workers from the
+  # workers queu and kick off pending requests as worker slots free up.
+
   settings:
     port = Port(8180)
     appName = "/api"
@@ -254,15 +257,14 @@ proc start*(cfg: StrawBossConfig): void =
 
       resp($(%runRequests), JSON)
 
-      # TODO
-      resp(Http501, makeJsonResp(Http501), JSON)
-
     get "/project/@projectName/runs/active":
       ## List all currently active runs
 
       checkAuth(); if not authed: return true
 
-      # TODO
+      #let statusFiles = workers.mapIt(it.workingDir & "/status.json")
+      #let statuses = statusFiles.mapIt(loadBuildStatus(it)).filterIt(it.state != "completed" && it.)
+      #resp($(%statuses), JSON)
       resp(Http501, makeJsonResp(Http501), JSON)
 
     get "/project/@projectName/runs/@runId":