Smalll documentation, TODOs.

api.rst

@@ -4,8 +4,8 @@
 ✓ GET    /api/projects                                   -- return project summaries
 - POST   /api/projects                                   -- create a new project
 - GET    /api/project/<proj-id>                          -- TODO
-- GET    /api/project/<proj-id>/runs                     -- list summary information for all runs
+* GET    /api/project/<proj-id>/runs                     -- list summary information for all runs
-- GET    /api/project/<proj-id>/runs/active              -- list summary information about all currently active runs
+* GET    /api/project/<proj-id>/runs/active              -- list summary information about all currently active runs
 - GET    /api/project/<proj-id>/runs/<run-id>            -- list detailed information about a specific run
 ✓ GET    /api/project/<proj-id>/versions                 -- list the versions of this project that have been built
 * GET    /api/project/<proj-id>/version/<ref>            -- return detailed project definition (include steps) at a specific version

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":

src/test/nim/functional/tserver.nim

@@ -104,7 +104,6 @@ suite "strawboss server":
     let statusFile = runArtifactsDir & "/status.json"
     check fileExists(statusFile)
 
-    # TODO
     # check that the run status is not failed
     var status = loadBuildStatus(statusFile)
     check status.state != "failed"
@@ -122,9 +121,14 @@ suite "strawboss server":
     let binFile = runArtifactsDir & "/test_project"
     check existsFile(binFile)
 
+  # TODO
   test "run a time-consuming build and check the status via the API":
     check false
 
+  # TODO
+  #test "kick off multiple runs and check the list of active runs via the API":
+  #  check false
+
   # Last-chance catch to kill the server in case some test err'ed and didn't
   # reach it's teardown handler
   discard newAsyncHttpClient().post(apiBase & "/service/debug/stop")