v2.0.0 (Added Documentation) (#73)

* feat: add decoding capability in case of failure caused due to HTTP status code Resolves: none. * feat: override User-Agent HTTP header in session configuration (#26) Resolves: none. * Add macOS example (#27) * feat: move iOS example project into new sub folder Resolves: none. * fix: update framework search paths Resolves: none. * feat: add empt macOS example project to workspace Resolves: none. * fix: update framework scheme name Resolves: none. * feat: add files to macOS example directory Resolves: none. * fix: apply public access modifier to DefaultHTTPErrorBody and DefaultNetworkAPIError Resolves: none. * refactor: add description comment for ProcessInfo extension Resolves: none. * fix: add RxNetworkKit bridging header reference Resolves: none. * refactor: apply project recommended settings Resolves: none. * feat: connect viewModel to tableview UI Resolves: none. * feat: complete ViewController class in macOS Example Resolves: none. * refactor: remove old un-needed file Resolves: none. * fix: apply correct image scale for error view Resolves: none. * Apply new version (0.0.2) (#28) * fix: remove tinted button warning Resolves: none. * version: 0.0.2 Resolves: none. * fix: update version for podSpec file Resolves: none. * fix: remove RxDataSources import statement (#31) Resolves: none. * Add CI Workflows For Repository (#33) * feat: add iOS workflow Resolves: none. * fix: update build-ios.yml Resolves: none. * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Create build-macos.yml * Update build-ios.yml + build-macos.yml * fix error 65 * Update build-ios.yml * update build-ios.yml + build-macos.yml * Update build-macos.yml * Update project.pbxproj * add publish-podspec.yml * add workflow files outside of folders * Update publish-podspec.yml * Update publish-podspec.yml * Update publish-podspec.yml * Create pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * test container workflow * Update build.yml * Update build.yml * add some changes * Update build.yml * add some changes * Update build.yml * refactor: update names + remove comments Resolves: none. * add trigger for trunk push workflow * add dummy project to test SPM integration * add spm-lint.yml * Update spm-lint.yml * Update spm-lint.yml * Update spm-lint.yml * Update spm-lint.yml * update dummy project * update workspace dependencies versions * Update CI Workflows * update CI workflows * Update CI Workflow * Update Dependency Version Rules (#45) * fix: update version rules for SPM to upToNextMajor Resolves: none. * fix: update version rule for SPM in iOS Example project Resolves: none. * fix: update version rules for cocoapods in podspec file Resolves: none. * feat: add WebSocket capability to NetworkManager (#46) Resolves: none. * fix a typo * update dependencies versions Resolves: none. * update Package.swift + podspec file * change xcode version used in CI/CD to 14.3.1 Resolves: none. * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update build.yml * Update build.yml * update workflow files * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-trunk-push.yml * Update spm-lint.yml * Update build-macos.yml * update Xcode version to 15.0.0 for CI workflows * Update pod-lib-lint.yml * Update pod-lib-lint.yml * Update pod-lib-lint.yml * break: drop support for Cocoapods (cannot work with Xcode 15) Resolves: none. * [49][DocC][Update Documentation] (#50) * feat: update overview for classes, structs, enums, typaliases and protocols Resolves: none. * feat: add docs catalog Resolves: none. * update CI workflows to build docs Resolves: none. * update CI workflows Resolves: none. * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * Update build-ios.yml * fix: update corrupt ci workflow file Resolves: none. * Delete build-deploy-docs1.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * update CI workflows * Update build.yml * Update build-ios.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update build-deploy-docs.yml * Update websocket error handling (#58) * feature: bind send and ping errors to the error relay in WebSocket object Resolves: none. * fix: capture weak reference to self to avoid retain cycle in example viewModel Resolves: none. * feat: add WebSocketError Resolves: none. * Update NetworkManager.md * Update build.yml * Rename Types and Organize Project files (#61) * feat: sort files by name inside Source folder Resolves: none. * feat: restructure framework project Resolves: none. * feat: update docs Resolves: none. * feat: update docs Resolves: none. * feat: update examples Resolves: none. * feat: update docs Resolves: none. * feat: move common http types to separate framework Resolves: none. * update ci * update ci * feat: add CoreHTTP as swift package Resolves: none. * Update Package.swift * feat: add CoreHTTP as a remote Swift Package Resolves: none. * Update Package.swift * Update Package.swift * feat: update docs Resolves: none. * Update build-macos.yml * Update build-macos.yml * feat: add CoreExample framework Resolves: none. * feat: add CoreExample as a dependency Resolves: none. * feat: add CoreExample to macOS Example Resolves: none. * fix: update code signing for framework Resolves: none. * Update build-macos.yml * Update build-macos.yml * update frameworks flow * Update build-ios.yml * Update Package.resolved * Update project.pbxproj * Update project.pbxproj * Update build-ios.yml * update dependencies * feat: add Session object that can be shared between RESTClient and HTTPClient Resolves: none. * refactor: remove reference to event monitor in RESTClient and HTTPClient Resolves: none. * feat: update ci workflows Resolves: none. * feat: update documentation Resolves: none. * Update build.yml * Update build.yml * feat: bump Xcode version to 15.1.0 for workflow files Resolves: none. * Feature/add watch os example (#62) * feat: add watch os example Resolves: none. * Update ViewController.swift * Update build.yml * Update build-watchos.yml * Update build-watchos.yml * Update README.md * Update README.md * Update README.md * feat: bump product version to 1.0.0 Resolves: none. * fix: silence warnings Resolves: none. * feat: add watchOS platform to package manifest + sort files Resolves: none. * Feature/add tvos support (#63) * feat: add tvOS support + example Resolves: none. * Update build.yml * Update build.yml * Update build-tvos.yml * feat: update documentation Resolves: none. * Update README.md * feat: update Dummy project used to verify SPM Resolves: none. * fix: update README.md + add missing initializers Resolves: none. * Update RxNetworkKit.md * Update spm-lint.yml * fix: update ci file + remove typo Resolves: none. * Feature/add request logging (#67) * feat: add HTTPRequestLogger and SessionConfiguration Resolves: none. * fix: update examples Resolves: none. * feat: remove un-needed files + update RequestRouter Resolves: none * Update Package.resolved * Update README.md * feat: update documentation Resolves: none. * feat: bump versions to 2.0.0 Resolves: none. * Update Package.swift * Update SessionConfiguration.swift * Feature/add documentation articles (#72) * feat: add Getting Started article. Resolves: none. * Update GettingStarted.md * feat: add making first request article Resolves: none. * feat: add articles for download and upload requests Resolves: none. * feat: add web socket article Resolves: none. * feat: add monitoring reachability article Resolves: none. * fix: lint documentation Resolves: none.
loay-ashraf · Jan 27, 2024 · ff37cfc · ff37cfc
1 parent 420cfe8
commit ff37cfc
Show file tree

Hide file tree

Showing 19 changed files with 879 additions and 10 deletions.
diff --git a/Docs.docc/Articles/ConnectingToWebSocket.md b/Docs.docc/Articles/ConnectingToWebSocket.md
@@ -0,0 +1,106 @@
+# Connecting To WebSocket Server
+
+Connect to a web socket server with **RxNetworkKit**
+
+## Overview
+
+In this article we will walk you through on how to connect to a web socket server and how to send/receive messages.
+
+### Creating a http client
+
+In this section, you will create a ``HTTPClient`` using a ``Session``.
+
+- First, go to *ViewController.swift* file.
+
+- Second, create a ``HTTPClient`` using a ``Session`` in the `viewDidLoad` method as done below:
+
+```swift 
+import UIKit
+import RxSwift
+import RxNetworkKit
+
+class ViewController: UIViewController {
+
+ let disposeBag: DisposeBag = .init()
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ // Do any additional setup after loading the view.
+ let sessionConfiguration = SessionConfiguration.default
+ let session = Session(configuration: sessionConfiguration)
+ let requestInterceptor = RequestInterceptor()
+ let httpClient = HTTPClient(session: session, requestInterceptor: requestInterceptor)
+ }
+
+}
+```
+
+- Now, you are ready to connect to a web socket server.
+
+### Connecting to a websocket server
+
+In this section, you will create a ``WebSocket`` and send/receive messages to/from the server.
+
+- First, call the `HTTPClient.websocket` method and pass the server url, protocols and close handler as arguments.
+
+- Second, Subscribe to the output `Observable`s and call `WebSocket.connect` method as done below:
+
+
+```swift 
+import UIKit
+import RxSwift
+import RxNetworkKit
+
+class ViewController: UIViewController {
+
+ let disposeBag: DisposeBag = .init()
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ // Do any additional setup after loading the view.
+ let sessionConfiguration = SessionConfiguration.default
+ let session = Session(configuration: sessionConfiguration)
+ let requestInterceptor = RequestInterceptor()
+ let httpClient = HTTPClient(session: session, requestInterceptor: requestInterceptor)
+ // Replace with your web socket server url
+ let webSocket: WebSocket<Model> = httpClient.webSocket(URL(string: "wss://example")!,
+ ["ts1"],
+ .init(code: { _ in .normalClosure },
+ reason: { _ in nil }))
+ webSocket.text
+ .subscribe(onNext: { text in
+ // print incoming text message
+ print(text)
+ })
+ .disposed(by: disposeBag)
+ webSocket.data
+ .subscribe(onNext: { model in
+ // dump incoming data
+ dump(model)
+ })
+ .disposed(by: disposeBag)
+ webSocket.error
+ .subscribe(onNext: { error in
+ // print error description (if any)
+ print(error.localizedDescription)
+ })
+ .disposed(by: disposeBag)
+ webSocket.connect()
+ }
+
+}
+```
+
+- Optionally, you can send messages to the server via the `WebSocket.send(_:)` method.
+
+- That's it, you are connected to a web socket server and ready to send/receive messages.
+
+- Tip: You can disconnect from the web socket server at any time by calling the `WebSocket.disconnect` method.
+
+- Note: Connection to the web socket server is terminated when the ``WebSocket`` instance is deallocated.
+
+- Warning: If you intend to make updates to the UI, you must use the `observe(on: MainScheduler.instance)` operator to avoid updating the UI on a background thread (which may lead to unexpected behavior or crashes).
+
+## Conclusion
+
+Now, you can use **RxNetworkKit** to connect to a web socket server.
diff --git a/Docs.docc/Articles/GettingStarted.md b/Docs.docc/Articles/GettingStarted.md
@@ -0,0 +1,119 @@
+# Getting Started
+
+Add **RxNetworkKit** and the essential networking code to your project.
+
+## Overview
+
+You can add RxNetworkKit to your project as a Swift Package via SPM.
+
+You also need to create ``Session`` and ``RESTClient`` objects so you can start making requests.
+
+### Adding RxNetworkKit to your project
+
+In this section, you will be adding RxNetworkKit to your project via Swift Package Manager.
+
+- First, open the dependencies tab of your project.
+
+- Tap the *+* button.
+
+- In the search bar to the top right corner, paste this url:
+
+[https://github.com/loay-ashraf/RxNetworkKit](https://github.com/loay-ashraf/RxNetworkKit)
+
+- Tap the *Add Package* button to the bottom right corner.
+
+![Add package window is visible and RxNetworkKit package is selected.](article-getting-started-#1.png)
+
+- Second, tap the *Add Package* button and wait for Xcode to resolve package graph.
+
+![Xcode is resolving the package graph.](article-getting-started-#2.png)
+
+- Now, your all set and can now use **RxNetworkKit** in your project.
+
+![Xcode has finished resolving the package graph and RxNetworkKit can be used in the project.](article-getting-started-#3.png)
+
+### Adding required networking code
+
+In this section, you will be creating ``Session`` and ``RESTClient`` objects.
+
+- First, add a new Swift file to your project and name it *RequestInterceptor.swift*.
+
+- Second, add an import statement for **RxNetworkKit** to the top of the newly created file.
+
+- Add a new class with the name `RequestInterceptor` that conforms to the ``HTTPRequestInterceptor`` protocol as done below:
+
+```swift
+import Foundation
+import RxNetworkKit
+
+class RequestInterceptor: HTTPRequestInterceptor {
+
+ func adapt(_ request: URLRequest, for session: URLSession) -> URLRequest {
+ return request
+ }
+
+ func retryMaxAttempts(_ request: URLRequest, for session: URLSession) -> Int {
+ return 5
+ }
+
+ func retryPolicy(_ request: URLRequest, for session: URLSession) -> HTTPRequestRetryPolicy {
+ return .constant(time: 5.0)
+ }
+
+ func shouldRetry(_ request: URLRequest, for session: URLSession, dueTo error: HTTPError) -> Bool {
+ return true
+ }
+
+}
+```
+
+- Finally, add an import statement for **RxNetworkKit** in *ViewController.swift* file and create ``SessionConfiguration``, ``Session`` and ``RESTClient`` objects in the `viewDidLoad` method as done below:
+
+```swift
+import UIKit
+import RxNetworkKit
+
+class ViewController: UIViewController {
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ // Do any additional setup after loading the view.
+ let sessionConfiguration = SessionConfiguration.default
+ let session = Session(configuration: sessionConfiguration)
+ let requestInterceptor = RequestInterceptor()
+ let restClient = RESTClient(session: session, requestInterceptor: requestInterceptor)
+ }
+
+}
+```
+
+- Alternatively, you can override the default ``SessionConfiguration`` by creating your own instance and providing different property values as done below:
+
+```swift
+import UIKit
+import RxNetworkKit
+
+class ViewController: UIViewController {
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ // Do any additional setup after loading the view.
+ let sessionConfiguration = SessionConfiguration(urlSessionConfiguration: .default)
+ sessionConfiguration.setUserAgentHeader = false
+ sessionConfiguration.setUserAgentHeader = false
+ let session = Session(configuration: sessionConfiguration)
+ let requestInterceptor = RequestInterceptor()
+ let restClient = RESTClient(session: session, requestInterceptor: requestInterceptor)
+ }
+
+}
+```
+
+## Conclusion
+
+Now you are one step away from making a request using **RxNetworkKit**.
+
+In the next article, you will learn how to create a ``HTTPRequestRouter`` and a `Decodable` model and use them with ``RESTClient`` to make a request.
+
+You can read the next article here:
+- <doc:MakingFirstRequest>
diff --git a/Docs.docc/Articles/MakingDownloadRequest.md b/Docs.docc/Articles/MakingDownloadRequest.md
@@ -0,0 +1,120 @@
+# Making Download Requests
+
+Make download requests with **RxNetworkKit**
+
+## Overview
+
+In this article, we will walk you through on how to make download requests.
+
+### Adding a download request router
+
+In this section, you will be adding a ``HTTPDownloadRequestRouter``.
+
+- First, add a new Swift file to your project and name it *DownloadRequestRouter.swift*.
+
+- Second, add an import statement for **RxNetworkKit** to the top of the newly created file.
+
+- Finally, add a new enumeration with the name `DownloadRequestRouter` that conforms to the ``HTTPDownloadRequestRouter`` protocol as done below:
+
+```swift 
+import Foundation
+import RxNetworkKit
+
+enum DownloadRequestRouter: HTTPDownloadRequestRouter {
+
+ case `default`(url: URL)
+
+ var scheme: HTTPScheme {
+ .https
+ }
+
+ var domain: String {
+ ""
+ }
+
+ var path: String {
+ ""
+ }
+
+ var headers: [String : String] {
+ [:]
+ }
+
+ var parameters: [String : String]? {
+ nil
+ }
+
+ var url: URL? {
+ switch self {
+ case .default(let url):
+ return url
+ }
+ }
+
+}
+```
+
+- Note: Download requests have `GET` http method set by default, so you don't have to specify it in the download request router.
+
+### Making a download request
+
+In this section, you will create a ``HTTPClient`` and use the ``HTTPDownloadRequestRouter`` you created in the previous section with it to make a download request.
+
+- First, go to *ViewController.swift* file and create a ``HTTPClient`` using a ``Session`` in the `viewDidLoad` method
+
+- Second, Create a `DownloadRequestRouter`.
+
+- Call the `HTTPClient.download` method and pass the `DownloadRequestRouter` as an argument.
+
+- Subscribe to the output `Observable` as done below:
+
+```swift
+import UIKit
+import RxSwift
+import RxNetworkKit
+
+class ViewController: UIViewController {
+
+ let disposeBag: DisposeBag = .init()
+
+ override func viewDidLoad() {
+ super.viewDidLoad()
+ // Do any additional setup after loading the view.
+ let sessionConfiguration = SessionConfiguration.default
+ let session = Session(configuration: sessionConfiguration)
+ let requestInterceptor = RequestInterceptor()
+ let httpClient = HTTPClient(session: session, requestInterceptor: requestInterceptor)
+ // Replace with your download url
+ let downloadRequestRouter = DownloadRequestRouter.default(url: URL(string: "https://example.com/image/2435454.png")!)
+ httpClient.download(downloadRequestRouter)
+ .subscribe(onNext: { event in
+ switch event {
+ case .progress(let progress):
+ // print download progress
+ print("Downloading: \(progress.fractionCompleted)%")
+ case .completedWithData(data: let data):
+ // dump the received file data
+ dump(data)
+ default: break
+ }
+ }, onError: { error in
+ // print the error description (if any)
+ print(error.localizedDescription)
+ })
+ .disposed(by: disposeBag)
+ }
+
+}
+```
+
+- That's it, you made a download request.
+
+- Tip: If you need to save the downloaded file to the disk, you can provide the save location url through the `fileURL` parameter.
+
+- Note: If you choose to save the downloaded file to the disk, you will receive the `completed` download event instead of the `completedWithData` download event.
+
+- Warning: If you intend to make updates to the UI, you must use the `observe(on: MainScheduler.instance)` operator to avoid updating the UI on a background thread (which may lead to unexpected behavior or crashes).
+
+## Conclusion
+
+Now, you can use **RxNetworkKit** to make download requests.