Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/vzsg/Curly

Embrace the power of curl in Vapor 3 apps
https://github.com/vzsg/Curly
Last synced: about 2 months ago
JSON representation
Embrace the power of curl in Vapor 3 apps
Host: GitHub
URL: https://github.com/vzsg/Curly
Owner: vzsg
License: mit
Created: 2019-02-07T18:16:03.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2020-06-02T12:13:36.000Z (over 4 years ago)
Last Synced: 2024-07-13T13:02:25.628Z (3 months ago)
Language: Swift
Homepage:
Size: 78.1 KB
Stars: 26
Watchers: 4
Forks: 4
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # Curly

This package wraps [Perfect-CURL](https://github.com/PerfectlySoft/Perfect-CURL) into a Vapor 3 `Client`. If you are running into issues with URLSession on Linux, or you want cookies or proxy support, this might be the way out.

## Usage

### 0. (Linux) Install libcurl development package

This package relies on the development package for libcurl4. Make sure you have `libcurl4-openssl-dev` installed before trying to build your Swift project.

```

sudo apt-get update

sudo apt-get install libcurl4-openssl-dev

```

### 1. Add this package as a dependency to your Vapor 3 project

```swift

// swift-tools-version:4.0

import PackageDescription

let package = Package(

    name: "VaporApp",

    dependencies: [

        // 💧 A server-side Swift web framework.

        .package(url: "https://github.com/vapor/vapor.git", from: "3.0.0"),

        .package(url: "https://github.com/vzsg/Curly.git", from: "0.6.0"),

        // ... other dependencies ...

    ],

    targets: [

        .target(name: "App", dependencies: ["Vapor", "...", "CurlyClient"]),

        // ... other targets ...

    ]

)

```

### 2. Register the CurlyProvider

```swift

// Typically, this is part of configure.swift

import Vapor

import CurlyClient

// ... other imports ...

public func configure(_ config: inout Config, _ env: inout Environment, _ services: inout Services) throws {

    try services.register(CurlyProvider())

    config.prefer(CurlyClient.self, for: Client.self)

    // ... other configuration ...

}

```

### 3. Profit!

Your Vapor app now uses curl directly instead of URLSession.

### 4. Extra profit: CurlyOptions

From 0.3.0, Curly exposes a few useful options from cURL that are otherwise not available via the Client interface, or even URLSession. To use them, you _must_ register Curly via the `CurlyProvider` as seen in step 2.

With that in place, you can call `Request.addCurlyOption` in either the `beforeSend` closure when using the convenience functions of Client, or on the Request instance itself when using `Client.send()` and a self-built Request object.  

The two approaches are functionally equivalent.

```swift

try client.get("https://self-signed.badssl.com/", beforeSend: { req in

    req.addCurlyOption(.sslVerifyPeer(false))

})

```

```swift

var http = HTTPRequest(method: .GET, url: "https://self-signed.badssl.com/")

http.headers.replaceOrAdd(name: "X-Test-Header", value: "Foo")

let req = Request(http: http, using: app)

req.addCurlyOption(.sslVerifyPeer(false))

try client.send(req)

```

> **Warning**: Calling `Request.addCurlyOption` without the Provider will result in a fatal error in debug builds, and a warning print in release builds.

Starting with 0.7.0, options can be applied to all requests made via Curly using the new `globalOptions` optional parameter of CurlyProvider.

```swift

try services.register(CurlyProvider(globalOptions: [

    .sslCAFilePath("my-selfsigned-certs.crt")

]))

```

#### Available options

- **proxy(String)**

    Equivalent to the [`-x`/`--proxy`](https://curl.haxx.se/docs/manpage.html#-x) parameter of curl, which enables proxying via a HTTP, HTTPS or SOCKS proxy.

- **proxyAuth(user: String, password: String)**

    Equivalent to the [`-U`/`--proxy-user`](https://curl.haxx.se/docs/manpage.html#-U) parameter of curl, which allows specifying the username and password to use when authenticating to the proxy server.

- **proxyPort(Int)** (New in 0.6.0)

    Equivalent to `CURLOPT_PROXYPORT`, which allows separately overriding the port used to connect to the proxy.

- **timeout(Int)**

    Equivalent to the [`-m`/`--max-time`](https://curl.haxx.se/docs/manpage.html#-m) parameter of curl, which allows specifying the maximum time allowed to service the request in seconds.

- **timeoutMs(Int)**

    Same as `timeout`, but with milliseconds precision.

- **connectTimeout(Int)**

    Equivalent to the [`--connect-timeout`](https://curl.haxx.se/docs/manpage.html#--connect-timeout) parameter of curl, which allows specifying the maximum time allowed for the connection to the server in seconds.

- **connectTimeoutMs(Int)** (New in 0.5.0)

    Same as `connectTimeout`, but with milliseconds precision.

- **cookieJar(String)**

    Equivalent to setting **both** the [`-b`/`--cookie`](https://curl.haxx.se/docs/manpage.html#-b) **and** [`-c`/`--cookie-jar`](https://curl.haxx.se/docs/manpage.html#-c) parameters of curl. The file name provided with the option will be used as a cookie storage – reading and writing – for this request. See the tests for an example.

- **followRedirects(Bool)**

    Equivalent to the [`-L`/`--location`](https://curl.haxx.se/docs/manpage.html#-L) parameter of curl, which enables following redirects automatically.

- **insecure(Bool)**

    Equivalent to the [`-k`/`--insecure`](https://curl.haxx.se/docs/manpage.html#-k) parameter of curl, which can disable verification of the certificates received from the remote server. Deprecated in favor of `sslVerifyPeer`.

- **sslVerifyPeer(Bool)** (New in 0.6.0)

    Equivalent to [`CURLOPT_SSL_VERIFYPEER`](https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html]), used to enable or disable server certificate verification.

- **sslVerifyHost(Bool)** (New in 0.6.0)

    Equivalent to [`CURLOPT_SSL_VERIFYHOST`](https://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html]), used to enable or disable verification of the server host name against the server certificates.

- **sslKey(path: String, type: CurlySSLFileType?, password: String?)** (New in 0.6.0)

    Equivalent to the [`--key`](https://curl.haxx.se/docs/manpage.html#--key), [`--key-type`](https://curl.haxx.se/docs/manpage.html#--key-type) and [`--pass`](https://curl.haxx.se/docs/manpage.html#--pass) parameters, used to specify a private key to use for client certificate verification.

- **sslCert(path: String, type: CurlySSLFileType?)** (New in 0.6.0)

    Equivalent to the [`-E`/`--cert`](https://curl.haxx.se/docs/manpage.html#-E) and [`--cert-type`](https://curl.haxx.se/docs/manpage.html#--cert-type) parameters, used to specify a client certificate.

- **sslCAFilePath(String)** (New in 0.6.0)

    Equivalent to the [`--cacert`](https://curl.haxx.se/docs/manpage.html#--cacert) parameter, used to specify a certificate to verify the server certificates against.

- **sslCADirPath(String)** (New in 0.6.0)

    Equivalent to the [`--cadir`](https://curl.haxx.se/docs/manpage.html#--cadir) parameter, used to specify a folder containing certificates to verify the server certificates against.

- **sslCiphers([String])** (New in 0.6.0)

    Equivalent to the [`--ciphers`](https://curl.haxx.se/docs/manpage.html#--ciphers) parameter, used to specify which ciphers to allow. See [this page](https://curl.haxx.se/docs/ssl-ciphers.html) for details.

- **sslPinnedPublicKey(String)** (New in 0.6.0)

    Equivalent to the [`--pinnedpubkey`](https://curl.haxx.se/docs/manpage.html#--pinnedpubkey) parameter, used to specify either a file with a PEM/DER encoded public key, or an SHA-256 hash that the server must present in its certificate chain.