# 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](Examples/Echo/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