Update readme with simple tutorial #2

artemredkin · 2019-04-08T14:49:45Z

Motivation:

Every library should have a tutorial

Modifications:

Added README.md

Result:

Users will have a tutorial to get started with this library

tomerd · 2019-04-09T21:16:50Z

nice progress!

=> one small comment is we generally follow a template for commit messages and PRs, see

=> check out the readme on swift-log and swift-metrics. they roughly have the following sections:

overview
tl;dr / getting started guide
detailed design / architecture with examples

tomerd · 2019-04-09T21:17:51Z

README.md

+
+```swift
+dependencies: [
+    .package(url: "https://github.com/swift-server/swift-nio-http-client.git", from: "1.0.0")


did we tag yet? if not, maybe be more explicit about that, see swift-log and swift-metrics READMEs

replaced with .branch("master")

tomerd · 2019-04-09T21:18:38Z

README.md

+## Status
+
+This library provides the following:
+1. Async single request methods


"single request methods" is a bit unclear, rephrase?

fixed, do you thinks its better now?

tomerd · 2019-04-09T21:18:56Z

README.md

+This library provides the following:
+1. Async single request methods
+2. Simple follow-redirect support (cookie headers are dropped)
+3. Body download streaming


Streaming body download

fixed, thanks

tomerd · 2019-04-09T21:19:09Z

README.md

+
+This library provides the following:
+1. Async single request methods
+2. Simple follow-redirect support (cookie headers are dropped)


~~support~~

fixed, thanks

tomerd · 2019-04-09T21:20:04Z

README.md

+4. TLS support
+5. Cookie parsing (but not storage)
+
+## How to use


Usage guide

tomerd · 2019-04-09T21:20:24Z

README.md

+### Request-Response API
+The code snippet below illustrates how to make a simple GET request to a remote server:
+
+```import HTTPClient


fixed here and in all other blocks

tomerd · 2019-04-09T21:21:29Z

README.md

+```import HTTPClient
+
+let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)
+let response = try httpClient.get(url: "https://swift.org").wait()


personally i dont love guiding users to use wait, and where we do we should make a note that this is not the proper way to do things

good point! re-wrote example

tomerd · 2019-04-09T21:22:57Z

README.md

+```
+In this case shutdown of the client is not neccecary.
+
+Library provides methods for most HTTP-methods. In case you need to have more control over the method, or you want to add headers or body, use ```HTTPRequest``` struct:


Library provides methods for most HTTP-methods -> Most common HTTP methods are supported out of the box

done, thanks!

tomerd · 2019-04-09T21:23:29Z

README.md

+}
+```
+
+### Redirect following


tomerd · 2019-04-09T21:24:03Z

README.md

+```
+
+### Redirect following
+To enable follow-redirects behaviour, enable in using client configuration:


Enable follow-redirects behavior using the client configuration:

tomerd · 2019-04-09T21:24:43Z

README.md

+```
+
+### Timeouts
+Timeouts (connect and read) can be set in the client configuration:


Timeouts (connect and read) can also be set using the client configuration:

tomerd · 2019-04-09T21:25:15Z

README.md

+```
+or on per-request basis:
+```
+let response = try httpClient.execute(request: request, timeout: Timeout(connectTimeout: .seconds(1), readTimeout: .seconds(1))).wait()


format to be more readable

re-formatted, is it better now?

tomerd · 2019-04-09T21:27:53Z

README.md

+```
+
+### Streaming
+In case greater control over body processing is needed or you want to process HTTP Reponse body in a streaming manner, following delegate protocol could be used (example shows how to count bytes in response body without copiying it to the memory):


When dealing with larger amount of data, it's critical to steam the response body instead of aggregating it-memory. Handling a response stream is done using a delegate protocol. The following example demonstrates how to count the number of bytes in a streaming response body:

fixed, thanks

artemredkin · 2019-04-10T19:07:56Z

I've re-structured it a bit, what do you think? Should I add more info about architecture?

tomerd · 2019-04-10T19:08:23Z

README.md

@@ -1,3 +1,146 @@
 # swift-nio-http-client


SwiftNIOHTTPClient

tomerd · 2019-04-10T19:08:39Z

README.md

+```
+and  ```SwiftNIOHTTP``` dependency to your target:
+```swift
+.target(name: "MyApp", dependencies: ["SwiftNIOHTTP"]),


module name should be NIOHTTPClient

I've submitted the #4 to fix it

tomerd · 2019-04-10T19:09:02Z

README.md

+
+---
+
+**NOTE**: You will need [Xcode 10.2](https://itunes.apple.com/us/app/xcode/id497799835) or [Swift 5.0](https://swift.org/download/#swift-50) to try out `swift-nio-htt-client`.


SwiftNIOHTTPClient

tomerd · 2019-04-10T19:11:29Z

README.md

+or on per-request basis:
+```swift
+let timeout = Timeout(connectTimeout: .seconds(1), readTimeout: .seconds(1))
+let response = try httpClient.execute(request: request, timeout: timeout).wait()


tomerd · 2019-04-10T19:12:30Z

README.md

+```
+or on per-request basis:
+```swift
+let timeout = Timeout(connectTimeout: .seconds(1), readTimeout: .seconds(1))


unrelated to this PR but i would rename connectTimeout to connect or connection and readTimeout to read since these are properties of a Timeout object

tomerd · 2019-04-10T19:13:25Z

README.md

+```
+
+### Streaming
+When dealing with larger amount of data, it's critical to steam the response body instead of aggregating it-memory. Handling a response stream is done using a delegate protocol. The following example demonstrates how to count the number of bytes in a streaming response body:


type steam -> stream

type it-memory -> in-memory

tomerd · 2019-04-10T19:14:12Z

README.md

+let request = try HTTPRequest(url: "https://swift.org")
+let delegate = CountingDelegate()
+
+let count = try httpClient.execute(request: request, delegate: delegate).wait()


tomerd · 2019-04-10T19:14:47Z

nice work @artemredkin couple of more small comments. +1 to merge after they are addressed

Should I add more info about architecture?

i think that's a good idea, but we can do a follow up PR to control scope

more tests

* Proposal to fix #362. Allows user to setup a channel with a client certificate and key but still use default root certificates. * fix #362. Respect PR critique. make roots_pem() public. Update Channel init. * fix #362: make roots_pem() return force-unwrapped String. Change Channel API accordingly. * Remove an obsolete comment. * Minor whitespace tweak #1 * Minor whitespace tweak #2

Update readme with simple tutorial

cee4bef

artemredkin requested a review from weissi April 8, 2019 14:49

weissi requested a review from tanner0101 April 8, 2019 18:36

tomerd reviewed Apr 9, 2019

View reviewed changes

review fixes

3785391

tomerd reviewed Apr 10, 2019

View reviewed changes

README.md Outdated

@@ -1,3 +1,146 @@

# swift-nio-http-client

Copy link

Contributor

tomerd Apr 10, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SwiftNIOHTTPClient

tomerd reviewed Apr 10, 2019

View reviewed changes

review fixes

9be0315

tomerd approved these changes Apr 10, 2019

View reviewed changes

tomerd mentioned this pull request Apr 10, 2019

Rename package to NIOHTTPClient #4

Merged

artemredkin merged commit 43d1b72 into master Apr 10, 2019

artemredkin deleted the updated-readme branch April 10, 2019 22:14

PopFlamingo mentioned this pull request Aug 15, 2019

Remove eventLoop property from Task #82

Closed

weissi pushed a commit to weissi/async-http-client that referenced this pull request Feb 10, 2020

Merge pull request swift-server#2 from weissi/jw-more-tests

cbe0f24

more tests


		---

		NOTE: You will need [Xcode 10.2](https://itunes.apple.com/us/app/xcode/id497799835) or [Swift 5.0](https://swift.org/download/#swift-50) to try out `swift-nio-htt-client`.

Update readme with simple tutorial #2

Update readme with simple tutorial #2

Conversation

artemredkin commented Apr 8, 2019 • edited

tomerd commented Apr 9, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomerd Apr 9, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

artemredkin commented Apr 10, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tomerd commented Apr 10, 2019 • edited

artemredkin commented Apr 8, 2019 •

edited

tomerd commented Apr 9, 2019 •

edited

tomerd Apr 9, 2019 •

edited

tomerd commented Apr 10, 2019 •

edited