Skip to content

Latest commit

 

History

History
163 lines (101 loc) · 6.92 KB

README.md

File metadata and controls

163 lines (101 loc) · 6.92 KB
Raw

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.