How to branch out of a 'Future' sequence in a single Vapor route?

Question

How can computation flow branch out of a sequence of multiple Future actions, in a single Vapor route, to return a simple String Response which indicates which stage was exited?

Future methods catch(_:), catchMap(on:_:), and catchFlatMap(_:) can execute if a error is thrown; however, my experiments so far with any catch approach have not been able to branch out the sequence of Future actions. (see API & Docs)

Note: Since Vapor 3 Async core is built on top of swift-nio, a SwiftNIO solution would also be of interest.

Example

For example, consider a Future sequence which will create a db entry, update the same db entry, query (read) the db entry, and then return some String response.

Structure for Posting

{
  "number": 0
}

public struct ExamplePipe: Codable {
  public var id: UUID?
  public var number: Int
  
  init(number: Int) {
    self.number = number
  }
  
  public func description() -> String {
    return """
    UUID: \(id?.uuidString ?? "nil.....-....-....-....-............") 
    {number:\(number)}
    """
  }
}

// Database model for fetching and saving data via Fluent. 
extension ExamplePipe: SQLiteUUIDModel {}
// Content convertable to/from HTTP message.
extension ExamplePipe: Content {}
// Database migration
extension ExamplePipe: Migration {}
// Dynamic HTTP routing parameter: `id`
extension ExamplePipe: Parameter {}

struct ExamplePipeController: RouteCollection {
  func boot(router: Router) throws {
    let pipelineRoutes = router.grouped("api", "pipeline")
    
    // POST http://localhost:8080/api/pipeline/linear
    pipelineRoutes.post(ExamplePipe.self, at: "linear", use: linearPost)
    
    // POST http://localhost:8080/api/pipeline/nested
    pipelineRoutes.post(ExamplePipe.self, at: "nested", use: nestedPost)
  }
  // …
}

Scenario: map Linear Sequence

// POST http://localhost:8080/api/example/pipeline/basic
func linearPost(_ request: Request, _ pipelineData: ExamplePipe)
               throws -> Future<String> { 
  var s = "##### Linear Pipeline Data #####\n"
  
  let mutableA = pipelineData
  s += "## STAGE_A \(mutableA.description())\n"
  let futureA: Future<ExamplePipe> = mutableA.create(on: request)
  
  let futureB: Future<ExamplePipe> = futureA.flatMap(to: ExamplePipe.self) { 
    (nonmutableB: ExamplePipe) -> Future<ExamplePipe> in
    var mutableB = nonmutableB
    mutableB.number += 1
    if mutableB.number == 2 {
      print("POSSIBLE TO EXIT SEQUENCE AT STAGE B??")
    }
    s += "## STAGE_B \(mutableB.description())\n"
    let futureB: Future<ExamplePipe> = mutableB.update(on: request)
    return futureB
    }
        
  let futureC: Future<ExamplePipe?> = futureB.flatMap { 
    (nonmutableC: ExamplePipe) -> Future<ExamplePipe?> in
    s += "## STAGE_C \(nonmutableC.description())\n"
    if nonmutableC.id == nil {
      print("POSSIBLE TO EXIT SEQUENCE AT STAGE C??")
    }
    let uuid = nonmutableC.id!
    let futureC: Future<ExamplePipe?> = ExamplePipe
      .query(on: request)
      .filter(\ExamplePipe.id==uuid)
      .first()
    return futureC      
  }
  
  let futureD: Future<String> = futureC.map(to: String.self) { 
    (nonmutableD: ExamplePipe?) -> String in
    guard var mutableD = nonmutableD else {
      s += "## STAGE_D ExamplePipe is NIL\n"
      s += "#################################\n"
      print(s)
      return s
    }
    mutableD.number += 1
    s += "## STAGE_D \(mutableD.description())\n"
    s += "#################################\n"
    print(s)
    return s
  }
  
  return futureD
}

Scenario: map Nested Sequence

// POST http://localhost:8080/api/example/pipeline/nested
func nestedPost(_ request: Request, _ pipelineData: ExamplePipe)
                throws -> Future<String> { 
  var s = "##### Nested Pipeline Data #####\n"
  
  let mutableA = pipelineData
  s += "## STAGE:A \(mutableA.description())\n"
  let futureA: Future<ExamplePipe> = mutableA.create(on: request)
  
  let futureD: Future<String> = futureA.flatMap { 
    (nonmutableB: ExamplePipe) -> Future<String> in
    var mutableB = nonmutableB
    mutableB.number += 1
    if mutableB.number == 2 {
      print("POSSIBLE TO EXIT SEQUENCE AT STAGE B??")
    }
    s += "## STAGE:B \(mutableB.description())\n"
    let futureB: Future<ExamplePipe> = mutableB.update(on: request)
    
    let futureDD: Future<String> = futureB.flatMap { 
      (nonmutableC: ExamplePipe) -> Future<String> in
      s += "## STAGE:C \(nonmutableC.description())\n"
      if nonmutableC.id == nil {
        print("POSSIBLE TO EXIT SEQUENCE AT STAGE C??")
      }
      let uuid = nonmutableC.id!
      let futureC: Future<ExamplePipe?> = ExamplePipe
        .query(on: request)
        .filter(\ExamplePipe.id==uuid)
        .first()
      
      let futureDDD: Future<String> = futureC.map(to: String.self) { 
        (nonmutableD: ExamplePipe?) -> String in
        guard var mutableD = nonmutableD else {
          s += "## STAGE:D ExamplePipe is `nil`\n"
          s += "#################################\n"
          print(s)
          return s
        }
        mutableD.number += 1
        s += "## STAGE:D \(mutableD.description())\n"
        s += "#################################\n"
        print(s)
        return s
      }
      return futureDDD
    }
    return futureDD
  }
  return futureD
}

Answer 1

Vapor 3 Async core which is built on top of swift-nio do not appear to have any direct mechanism(s) to branch out of a multiple Future sequence. Future is a typealias for SwiftNIO EventLoopFuture.

Below are two possible Swift-based approaches to either exit the sequence or effectively "skip over" the remaining sequence. Both approaches can return some meaningful full String to the client.

Approach 1: Exit Sequence (throws Debuggable error)

If the objective is to return some meaningful information to the client when exiting the sequence, then one possibility is to throw a Debuggable error to exit the Future sequence. Debuggable allows for a response which contains the reason. In this scenario, the String becomes a JSON "reason" value.

Setup:

public struct ExamplePipeError: Error {
  let comment: String
  
  init(comment: String) {
    self.comment = comment
  }
}

extension ExamplePipeError: Debuggable {
  // `Debuggable` Required Attributes
  public var identifier: String {
    return "\(ExamplePipeError.readableName)"
  }
  
  public var reason: String {
    return "\(comment)"
  }
}


private func checkNumber(number: Int, mustNotBe: Int, comment: String) throws {
  if number == mustNotBe {
    let error = ExamplePipeError(comment: comment)
    throw error
  }
}

Use:

let futureB: Future<ExamplePipe> = futureA.flatMap(to: ExamplePipe.self) { 
  (nonmutableB: ExamplePipe) throws -> Future<ExamplePipe> in
  var mutableB = nonmutableB
  mutableB.number += 1
  s += "## STAGE_B \(mutableB.description())\n"
  try self.checkNumber(
    number: mutableB.number, 
    mustNotBe: 2, 
    comment: "STAGE_B requires number which is not 2."
  )
  let futureB: Future<ExamplePipe> = mutableB.update(on: request)
  return futureB
}

Client receives:

{"error":true,"reason":"STAGE_B requires number which is not 2."}

Approach 2: Skip Through Sequence Stages (uses state variable)

Setup:

enum ExamplePipeState {
  case ok
  case exitedStageB
  case exitedStageC
}

Use:

func linearStageFlagPost(_ request: Request, _ pipelineData: ExamplePipe) 
                         throws -> Future<String> {
  var state: ExamplePipeState = .ok 
  var s = ""
  s += "##### Pipeline Data: `linear-stage-flag` #####\n"
  
  let mutableA = pipelineData
  s += "## STAGE_A \(mutableA.description())\n"
  let futureA: Future<ExamplePipe> = mutableA.create(on: request)
  
  let futureB = futureA.flatMap { 
    (nonmutableB: ExamplePipe) -> Future<ExamplePipe> in
    var mutableB = nonmutableB
    mutableB.number += 1
    s += "## STAGE_B \(mutableB.description())\n"
    if mutableB.number == 2 {
      s += " … EXIT/SKIP SEQUENCE AT STAGE B.\n"
      state = ExamplePipeState.exitedStageB
      let skipB: Future<ExamplePipe> = request.eventLoop.future(nonmutableB)
      return skipB
    }
    let futureB = mutableB.update(on: request)
    return futureB
  }
  
  let futureC: Future<ExamplePipe?> = futureB.flatMap { 
    (nonmutableC: ExamplePipe) -> Future<ExamplePipe?> in
    guard state == .ok else {
      s += "## STAGE_C SKIPPED\n"
      return request.eventLoop.future(nonmutableC)
    }
    s += "## STAGE_C \(nonmutableC.description())\n"
    if nonmutableC.number == 3 {
      s += " … EXIT/SKIP SEQUENCE AT STAGE C.\n"
      state = ExamplePipeState.exitedStageC
      let skipC: Future<ExamplePipe?> = request.eventLoop.future(nil)
      return skipC
    }
    let uuid = nonmutableC.id!
    let futureC: Future<ExamplePipe?> = ExamplePipe
      .query(on: request)
      .filter(\ExamplePipe.id==uuid)
      .first()
    return futureC      
  }
  
  let futureD: Future<String> = futureC.map(to: String.self) { 
    (nonmutableD: ExamplePipe?) -> String in
    switch state {
    case .ok:
      guard var mutableD = nonmutableD else {
        s += "## STAGE_D ExamplePipe is NIL\n"
        s += "##########################\n"
        print(s)
        return s
      }
      mutableD.number += 1
      s += "## STAGE_D \(mutableD.description())\n"
      s += "##########################\n"
      print(s)
      return s
      
    case .exitedStageB:
      s += "## STAGE_D after exiting STAGE_B and skipping STAGE_C\n"
      s += "##########################\n"
      print(s)
      return s
      
    case .exitedStageC:
      s += "## STAGE_D after exiting STAGE_C\n"
      s += "##########################\n"
      print(s)
      return s
      
    }
  }
  
  return futureD
}

Client receives:

##### Pipeline Data: `linear-stage-flag` #####
## STAGE_A UUID: nil.....-....-....-....-............ 
{number:1}
## STAGE_B UUID: 904156A2-BC1A-42B1-AC89-0C4A598EA4BB 
{number:2}
 … EXIT/SKIP `linear-try-catch` SEQUENCE AT STAGE B.
## STAGE_C SKIPPED `linear-stage-flag` SEQUENCE AT STAGE C
## STAGE_D after exiting STAGE_B and skipping STAGE_C
##########################