Swiftpack.co - Package - vzsg/Curly

Curly

This package wraps 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-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

// 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.

try client.get("https://self-signed.badssl.com/", beforeSend: { req in
    req.addCurlyOption(.sslVerifyPeer(false))
})
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.

try services.register(CurlyProvider(globalOptions: [
    .sslCAFilePath("my-selfsigned-certs.crt")
]))

Available options

  • proxy(String)

    Equivalent to the -x/--proxy parameter of curl, which enables proxying via a HTTP, HTTPS or SOCKS proxy.

  • proxyAuth(user: String, password: String)

    Equivalent to the -U/--proxy-user 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 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 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 and -c/--cookie-jar 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 parameter of curl, which enables following redirects automatically.

  • insecure(Bool)

    Equivalent to the -k/--insecure 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, used to enable or disable server certificate verification.

  • sslVerifyHost(Bool) (New in 0.6.0)

    Equivalent to CURLOPT_SSL_VERIFYHOST, 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, --key-type and --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 and --cert-type parameters, used to specify a client certificate.

  • sslCAFilePath(String) (New in 0.6.0)

    Equivalent to the --cacert parameter, used to specify a certificate to verify the server certificates against.

  • sslCADirPath(String) (New in 0.6.0)

    Equivalent to the --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 parameter, used to specify which ciphers to allow. See this page for details.

  • sslPinnedPublicKey(String) (New in 0.6.0)

    Equivalent to the --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.

Github

link
Stars: 25

Dependencies

Used By

Total: 0

Releases

"Share the Fun" - 2020-02-02 17:18:14

If setting CurlyOptions for every request is getting cumbersome, CurlyProvider is here to help. Global options passed to its initializer will be applied to all requests.

try services.register(CurlyProvider(globalOptions: [
    .sslCAFilePath("my-selfsigned-certs.crt")
]))

"Trust Issues" - 2019-12-18 21:49:57

With Curly 0.6.0, you now have fine-grained control over client and server certificate validation – no need to disable security altogether just for a self-signed certificate.

"Counting Seconds" - 2019-09-07 23:44:18

With Curly 0.5.0:

  • The timeout and connectTimeout options lost the name of their argument. Typing out seconds: felt superfluous, especially considering...
  • ...the brand new timeoutMs and connectTimeoutMs options, which allow using milliseconds for more precise control.

"Overcome Insecurities" - 2019-06-11 15:25:44

Curly 0.4 is here with three neat changes:

  • TLS getting you down? You can now disable certificate checks with the .insecure CurlyOption. Who knows, perhaps in the future, custom certificates will be an option too.
  • Speaking of the future, Swift 4.2 and 5.0 should no longer report warnings (by @mxcl).
  • Speaking of reports, CURL errors are now wrapped into public CurlyErrors, so you can check what went wrong and respond accordingly (by @FredericRuaudel).

"Too Much Power" - 2019-03-18 18:48:29

With 0.3.0, CurlyClient got a new name: "Curly". Fancy.

But on a more serious note, 0.3.0 exposes a bunch of advanced curl options, including proxy and cookie jar support. Check the README to learn more.

"Inside // I Stand Alone" - 2019-02-14 14:07:17

Curly no longer requires any obscure dependencies on Linux, nor does it pull in half of the Perfect world! Using it on Heroku and Vapor Cloud should now be possible without any extra steps.