readme updates & tests

Author: tib

README.md

@@ -63,14 +63,100 @@ The HttpClient provides the executors to perform data, download or upload tasks.
 
 You can create decodable, encodable, codable or raw request when using a codable pipeline collection.
 
-## Request pipelines
 
+## Using raw requests & responses
 
-## Custom decoder
+You can create raw HTTP requests using the HttpUrl and the HttpRawRequest type.   
 
-If you are using a request pipeline collection you can override the encoder and decoder objects.
+```swift
+let url = HttpUrl(scheme: "https",
+                  host: "jsonplaceholder.typicode.com",
+                  port: 80,
+                  path: ["todos"],
+                  resource: nil,
+                  query: [:],
+                  fragment: nil)
+
+let req = HttpRawRequest(url: url, method: .get, headers: [:], body: nil)
+
+/// execute the request using the client
+let client = UrlSessionHttpClient(session: .shared, log: true)
+let response = try await client.dataTask(req)
+
+/// use the response data
+let todos = try JSONDecoder().decode([Todo].self, from: response.data)
+// response.statusCode == .ok
+// response.headers -> response headers as a dictionary
+``` 
+
+You can use a specific HttpClient to execute a request using a data, download or upload task.
+
+
+## Constructing URLs
+
+The HttpUrl type allows us to construct various URLs using a base URL. 
 
 ```swift
 
+let baseUrl = HttpUrl(host: "jsonplaceholder.typicode.com")
 
-``` 
+// https://jsonplaceholder.typicode.com/todos/
+baseUrl.path("todos")               
+
+// https://jsonplaceholder.typicode.com/todos/1/
+baseUrl.path("todos", String(1))    
+
+// https://jsonplaceholder.typicode.com/todos/?foo=bar
+baseUrl.path("todos").query("foo", "bar")
+
+// https://jsonplaceholder.typicode.com/todos/?foo=baz&bar=1
+baseUrl.path("todos").query([
+    "foo": "baz",
+    "bar": "1",
+])
+```
+
+You can transform a HttpUrl object into a Foundation URL by using the `.url` property.
+
+## Requests
+
+You can create a raw request object using a HttpUrl and a HttpMethod, including additional headers and a body data.
+
+```swift
+let url = HttpUrl(host: "localhost", path: ["login"])
+
+let token: String = "valid-token"
+let body = try JSONEncoder().encode([
+    "foo": "bar",
+])
+let req = HttpRawRequest(url: url,
+                         method: .post,
+                         headers: [
+                            .key(.authorization): "Bearer \(token)",
+                            .custom("my-header"): "my-header-value",
+                         ],
+                         body: body)
+
+/*
+curl "https://localhost/login/" \
+    -X POST \
+    -H 'my-header: my-header-value' \
+    -H 'Authorization: Bearer valid-token' \
+    -d '{"foo":"bar"}'
+*/
+print(req.urlRequest.curlString) 
+```
+
+You can transform a HttpRequest into a URLReequest via the `.urlRequest` property.
+You can print the cURL representation of a request by using the `.curlString` property on a URLRequest object.
+
+
+## Pipelines
+
+A pipeline allows you to transform a raw request and a raw response using a set of custom actions. 
+
+You can create your own HttpRequestTransformer object to add extra headers to your request and encode a custom body object to a data value.
+
+You can create your own HttpResponseTransformer object to validate the response and decode a custom value from the response data.
+
+The codable (encodable, decodable, codable) pipelines are a good example of this approach.

Tests/SwiftHttpTests/HttpRawRequestTests.swift

@@ -0,0 +1,32 @@
+//
+//  HttpRawRequestTests.swift
+//  SwiftHttpTests
+//
+//  Created by Tibor Bodecs on 2022. 03. 13..
+//
+
+import XCTest
+@testable import SwiftHttp
+
+final class HttpRawRequestTests: XCTestCase {
+        
+    func testRawRequest() async throws {
+        let client = UrlSessionHttpClient(session: .shared, log: true)
+        
+        let url = HttpUrl(scheme: "https",
+                          host: "jsonplaceholder.typicode.com",
+                          port: 80,
+                          path: ["todos"],
+                          resource: nil,
+                          query: [:],
+                          fragment: nil)
+        
+        let req = HttpRawRequest(url: url, method: .get, headers: [:], body: nil)
+        
+        let response = try await client.dataTask(req)
+        let todos = try JSONDecoder().decode([Todo].self, from: response.data)
+        XCTAssertEqual(response.statusCode, .ok)
+        XCTAssertEqual(todos.count, 200)
+    }
+}
+

Tests/SwiftHttpTests/HttpRequestTests.swift

@@ -0,0 +1,39 @@
+//
+//  HttpRequestTests.swift
+//  SwiftHttp
+//
+//  Created by Tibor Bodecs on 2022. 03. 13..
+//
+
+import XCTest
+@testable import SwiftHttp
+
+final class HttpRequestTests: XCTestCase {
+        
+    func testRequests() async throws {
+        let url = HttpUrl(host: "localhost", path: ["login"])
+        
+        let token: String = "valid-token"
+        let body = try JSONEncoder().encode([
+            "foo": "bar",
+        ])
+        let req = HttpRawRequest(url: url,
+                                 method: .post,
+                                 headers: [
+                                    .key(.authorization): "Bearer \(token)",
+                                    .custom("my-header"): "my-header-value",
+                                 ],
+                                 body: body)
+        
+        let expectation = """
+            curl "https://localhost/login/" \\
+            \t-X POST \\
+            \t-H 'my-header: my-header-value' \\
+            \t-H 'Authorization: Bearer valid-token' \\
+            \t-d '{"foo":"bar"}'
+            """
+        
+        XCTAssertEqual(req.urlRequest.curlString, expectation)
+    }
+}
+

Tests/SwiftHttpTests/HttpUrlTests.swift

@@ -0,0 +1,32 @@
+//
+//  HttpUrlTests.swift
+//  SwiftHttpTests
+//
+//  Created by Tibor Bodecs on 2022. 03. 13..
+//
+
+import XCTest
+@testable import SwiftHttp
+
+final class HttpUrlTests: XCTestCase {
+        
+    func testBaseUrl() async throws {
+        let baseUrl = HttpUrl(host: "jsonplaceholder.typicode.com")
+        
+        let todosUrl = baseUrl.path("todos")
+        XCTAssertEqual(todosUrl.url.absoluteString, "https://jsonplaceholder.typicode.com/todos/")
+        
+        let todoUrl = baseUrl.path("todos", String(1))
+        XCTAssertEqual(todoUrl.url.absoluteString, "https://jsonplaceholder.typicode.com/todos/1/")
+        
+        let query1Url = baseUrl.path("todos").query("foo", "bar")
+        XCTAssertEqual(query1Url.url.absoluteString, "https://jsonplaceholder.typicode.com/todos/?foo=bar")
+        
+        let query2Url = baseUrl.path("todos").query([
+            "foo": "baz",
+            "bar": "1",
+        ])
+        XCTAssertEqual(query2Url.url.absoluteString, "https://jsonplaceholder.typicode.com/todos/?foo=baz&bar=1")
+    }
+}
+