grpc-swift/OVERVIEW.md

gRPC for Swift - Public API

This document will provide an overview of the gRPC API for Swift. It follows a standard form used by each language-platform implementation.

##Basic Functionality

The following examples use echo.proto to demonstrate basic gRPC operation and generated code.

###How is a New Stub Created?

Swift gRPC client and server code is generated by the protoc-gen-swiftgrpc plugin. The plugin is called from protoc and can be invoked for echo.proto like this:

protoc Examples/Echo/echo.proto --proto_path=Examples/Echo --swiftgrpc_out=. 

###Simple Request-Response RPC: Client-side RPC

var requestMessage = Echo_EchoRequest(text:message)
print("Sending: " + requestMessage.text)
let responseMessage = try service.get(requestMessage)
print("get received: " + responseMessage.text)

###Simple Request-Response RPC: Server Implementation of RPC

// get returns requests as they were received.
func get(request : Echo_EchoRequest) throws -> Echo_EchoResponse {
  return Echo_EchoResponse(text:"Swift echo get: " + request.text)
}

###Show how Client does two RPCs sequentially

###Show how Client does two RPCs asynchronously

###Any code for handling incoming RPC on server that might need to be written

###Server Streaming RPC: Client-side code

let requestMessage = Echo_EchoRequest(text:message)
print("Sending: " + requestMessage.text)
let expandCall = try service.expand(requestMessage)
var running = true
while running {
  do {
    let responseMessage = try expandCall.Receive()
    print("Received: \(responseMessage.text)")
  } catch Echo_EchoClientError.endOfStream {
    print("expand closed")
    running = false
  }
}

###Server Streaming RPC: Server-side code

// expand splits a request into words and returns each word in a separate message.
func expand(request : Echo_EchoRequest, session : Echo_EchoExpandSession) throws -> Void {
  let parts = request.text.components(separatedBy: " ")
  var i = 0
  for part in parts {
    try session.Send(Echo_EchoResponse(text:"Swift echo expand (\(i)): \(part)"))
    i += 1
    sleep(1)
  }
}

###How is a Server Created?

var done = NSCondition()
let echoProvider = EchoProvider()
var echoServer: Echo_EchoServer!
if useSSL {
  print("Starting secure server")
  let certificateURL = URL(fileURLWithPath:"ssl.crt")
  let keyURL = URL(fileURLWithPath:"ssl.key")
  echoServer = Echo_EchoServer(address:"localhost:8443",
                               certificateURL:certificateURL,
                               keyURL:keyURL,
                               provider:echoProvider)
} else {
  print("Starting insecure server")
  echoServer = Echo_EchoServer(address:"localhost:8081",
                               provider:echoProvider)
}
echoServer.start()
// Block to keep the main thread from finishing while the server runs.
// This server never exits. Kill the process to stop it.
done.lock()
done.wait()
done.unlock()

##Advanced

###RPC canceling on client side

###Code to look for and handle cancelled RPC on Server side

###Client Streaming RPC: Client-side code

let collectCall = try service.collect()
let parts = message.components(separatedBy:" ")
for part in parts {
  let requestMessage = Echo_EchoRequest(text:part)
  print("Sending: " + part)
  try collectCall.Send(requestMessage)
  sleep(1)
}
let responseMessage = try collectCall.CloseAndReceive()

###Client Streaming RPC: Server-side code

// collect collects a sequence of messages and returns them concatenated when the caller closes.
func collect(session : Echo_EchoCollectSession) throws -> Void {
  var parts : [String] = []
  while true {
    do {
      let request = try session.Receive()
      parts.append(request.text)
    } catch Echo_EchoServerError.endOfStream {
      break
    } catch (let error) {
      print("\(error)")
    }
  }
  let response = Echo_EchoResponse(text:"Swift echo collect: " + parts.joined(separator: " "))
  try session.SendAndClose(response)
}

###Flow control interactions while sending & receiving messages

###Flow control and buffer pool : Control API

###Bi Directional Streaming : Client-side code

var done = NSCondition()
let updateCall = try service.update()
DispatchQueue.global().async {
  var running = true
  while running {
    do {
      let responseMessage = try updateCall.Receive()
      print("Received: \(responseMessage.text)")
    } catch Echo_EchoClientError.endOfStream {
      print("update closed")
      done.lock()
      done.signal()
      done.unlock()
      break
    } catch (let error) {
      print("error: \(error)")
    }
  }
}
let parts = message.components(separatedBy:" ")
for part in parts {
  let requestMessage = Echo_EchoRequest(text:part)
  print("Sending: " + requestMessage.text)
  try updateCall.Send(requestMessage)
  sleep(1)
}
try updateCall.CloseSend()
// Wait for the call to complete.
done.lock()
done.wait()
done.unlock()

###Bi Directional Streaming : Server-side code

// update streams back messages as they are received in an input stream.
func update(session : Echo_EchoUpdateSession) throws -> Void {
  var count = 0
  while true {
    do {
      let request = try session.Receive()
      count += 1
      try session.Send(Echo_EchoResponse(text:"Swift echo update (\(count)): \(request.text)"))
    } catch Echo_EchoServerError.endOfStream {
      break
    } catch (let error) {
      print("\(error)")
    }
  }
  try session.Close()
}

###Any stub deletion/cleanup code needed