cURL for WebAssembly

v8.22.0WebAssembly

cURL 8.22.0 for browsers, Node.js and edge runtimes, precompiled for wasm32, single-threaded and multi-threaded as @crossbind/port-curl-wasm.

npm install @crossbind/port-curl-wasm@beta

npm ↗Port recipe and licence files ↗

Install

shell

npm install @crossbind/port-curl-wasm@beta

crossbind.config.js

import curlWasm from '@crossbind/port-curl-wasm/crossbind.config.js';
 
export default {
    dependencies: [curlWasm],
    paths: { config: import.meta.url },
};

crossbind itself arrives with your bundler plugin, or with a new project from npm create crossbind@beta; Bundlers has Vite, Webpack, Rspack and Rollup.

Usage

Each example runs here, in this tab, and prints what the site build checked.

Each example also has a JavaScript only tab: the same task with no C++ file, calling cURL's own headers from @crossbind/port-curl directly. All 5 work that way.

Parse a URL the way curl will fetch it

libcurl's URL API: curl_url_set checks a URL and removes its dot segments, curl_url_get reads one part back, with CURLU_DEFAULT_PORT and CURLU_URLDECODE when asked, and curl_url_strerror explains a URL curl refuses. The host keeps the case it was written in.

src/native/url_parts.h

#pragma once
 
#include <curl/curl.h>
 
#include <stdexcept>
#include <string>
 
// libcurl's URL API, the parser curl runs on a URL before every transfer. Each call parses the URL
// into a fresh CURLU handle, reads one part back and frees the handle.
class UrlParts {
public:
    // The URL as curl stores it: the scheme lowercased and dot segments removed. The host keeps its case.
    static std::string normalize(const std::string& url) { return get(url, CURLUPART_URL, 0); }
 
    static std::string host(const std::string& url) { return get(url, CURLUPART_HOST, 0); }
 
    // CURLU_DEFAULT_PORT answers with the scheme's port when the URL does not name one.
    static std::string port(const std::string& url) { return get(url, CURLUPART_PORT, CURLU_DEFAULT_PORT); }
 
    static std::string path(const std::string& url) { return get(url, CURLUPART_PATH, 0); }
 
    // CURLU_URLDECODE turns %XX sequences back into the bytes they stand for.
    static std::string query(const std::string& url) { return get(url, CURLUPART_QUERY, CURLU_URLDECODE); }
 
private:
    static std::string get(const std::string& url, CURLUPart part, unsigned int flags) {
        CURLU* handle = curl_url();
        if (!handle) throw std::runtime_error("out of memory");
        char* value = nullptr;
        CURLUcode code = curl_url_set(handle, CURLUPART_URL, url.c_str(), 0);
        if (code == CURLUE_OK) code = curl_url_get(handle, part, &value, flags);
        curl_url_cleanup(handle);
        if (code != CURLUE_OK) throw std::runtime_error(curl_url_strerror(code));
        const std::string result = value;
        curl_free(value);
        return result;
    }
};

main.js

import { initNative, UrlParts } from './native/url_parts.h';
 
await initNative();
const url = 'HTTPS://Example.com/docs/../api/search?q=caf%C3%A9#results';
console.log(await UrlParts.normalize(url));
console.log(await UrlParts.host(url), await UrlParts.port(url), await UrlParts.path(url));
console.log(await UrlParts.query(url));
try {
    await UrlParts.host('https://example.com:99999/');
} catch (error) {
    console.log(error.message);
}

PRINTSfirst run downloads 4.3 MB

https://Example.com/api/search?q=caf%C3%A9#results
Example.com 443 /api/search
q=café
std::runtime_error: Port number was not a decimal number between 0 and 65535

The same curl_url_set and curl_url_get calls, imported from curl/urlapi.h: crossbind binds only what the imported header declares, so curl/curl.h does not bring the URL API. curl_url_get writes a char * into an allocPointer(1) slot, which JavaScript reads with readPointerAt and readCString and frees with curl_free; the CURLU_* flags are #defines the binding leaves out, so they are written as numbers. A failure is the returned CURLUcode, turned into text by curl_url_strerror, so the last line has no std::runtime_error: prefix.

main.js

import {
    initNative, curl_url, curl_url_set, curl_url_get, curl_url_cleanup, curl_url_strerror,
    CURLUPart, CURLUcode,
} from '@crossbind/port-curl/curl/urlapi.h';
import {
    curl_free, allocPointer, readPointerAt, readCString,
} from '@crossbind/port-curl/curl/curl.h';
 
await initNative();
const CURLU_DEFAULT_PORT = 1 << 0;
const CURLU_URLDECODE = 1 << 6;
const ok = await CURLUcode.CURLUE_OK;
const check = async (code) => {
    if (code !== ok) throw new Error(await curl_url_strerror(code));
};
const url = await curl_url();
const slot = await allocPointer(1);
const get = async (part, flags = 0) => {
    await check(await curl_url_get(url, part, slot, flags));
    const value = await readPointerAt(slot, 0);
    const text = await readCString(value);
    await curl_free(value);
    return text;
};
 
await check(await curl_url_set(url, await CURLUPart.CURLUPART_URL, 'HTTPS://Example.com/docs/../api/search?q=caf%C3%A9#results', 0));
console.log(await get(await CURLUPart.CURLUPART_URL));
const host = await get(await CURLUPart.CURLUPART_HOST);
const port = await get(await CURLUPart.CURLUPART_PORT, CURLU_DEFAULT_PORT);
const path = await get(await CURLUPart.CURLUPART_PATH);
console.log(host, port, path);
console.log(await get(await CURLUPart.CURLUPART_QUERY, CURLU_URLDECODE));
try {
    await check(await curl_url_set(url, await CURLUPart.CURLUPART_URL, 'https://example.com:99999/', 0));
} catch (error) {
    console.log(error.message);
}
await curl_url_cleanup(url);

PRINTSfirst run downloads 4.5 MB

https://Example.com/api/search?q=caf%C3%A9#results
Example.com 443 /api/search
q=café
Port number was not a decimal number between 0 and 65535

Build a URL from parts without breaking it

curl_url_set with CURLU_APPENDQUERY and CURLU_URLENCODE adds a query pair with its value escaped, CURLU_URLENCODE on the path escapes a file name, and a relative reference set on a URL is resolved the way curl follows a redirect.

src/native/url_builder.h

#pragma once
 
#include <curl/curl.h>
 
#include <stdexcept>
#include <string>
 
// Builds URLs with libcurl's URL API instead of string concatenation: references are resolved the
// way curl follows a redirect, and CURLU_URLENCODE escapes what a path or a query cannot hold.
class UrlBuilder {
public:
    // `reference` is resolved against `base`, as curl does with a Location header.
    static std::string resolve(const std::string& base, const std::string& reference) { return edit(base, CURLUPART_URL, reference, 0); }
 
    // Replaces the path, percent-encoding spaces and other characters a path cannot hold.
    static std::string withPath(const std::string& url, const std::string& path) { return edit(url, CURLUPART_PATH, path, CURLU_URLENCODE); }
 
    // Appends one name=value pair to the query. The value is encoded: a space becomes +, and a
    // literal + or & becomes %2B or %26.
    static std::string addQuery(const std::string& url, const std::string& pair) {
        return edit(url, CURLUPART_QUERY, pair, CURLU_APPENDQUERY | CURLU_URLENCODE);
    }
 
private:
    static std::string edit(const std::string& url, CURLUPart part, const std::string& value, unsigned int flags) {
        CURLU* handle = curl_url();
        if (!handle) throw std::runtime_error("out of memory");
        char* result = nullptr;
        CURLUcode code = curl_url_set(handle, CURLUPART_URL, url.c_str(), 0);
        if (code == CURLUE_OK) code = curl_url_set(handle, part, value.c_str(), flags);
        if (code == CURLUE_OK) code = curl_url_get(handle, CURLUPART_URL, &result, 0);
        curl_url_cleanup(handle);
        if (code != CURLUE_OK) throw std::runtime_error(curl_url_strerror(code));
        const std::string text = result;
        curl_free(result);
        return text;
    }
};

main.js

import { initNative, UrlBuilder } from './native/url_builder.h';
 
await initNative();
let url = await UrlBuilder.resolve('https://api.example.com/v1/', 'search');
url = await UrlBuilder.addQuery(url, 'q=crème brûlée & tea');
url = await UrlBuilder.addQuery(url, 'sort=price+asc');
console.log(url);
console.log(await UrlBuilder.resolve(url, '../v2/items?id=7'));
console.log(await UrlBuilder.withPath(url, '/files/Q3 report.pdf'));

PRINTSfirst run downloads 4.3 MB

https://api.example.com/v1/search?q=cr%C3%A8me+br%C3%BBl%C3%A9e+%26+tea&sort=price%2Basc
https://api.example.com/v2/items?id=7
https://api.example.com/files/Q3%20report.pdf?q=cr%C3%A8me+br%C3%BBl%C3%A9e+%26+tea&sort=price%2Basc

The same curl_url_set calls with the same flags, written as numbers because CURLU_APPENDQUERY and CURLU_URLENCODE are #defines the binding leaves out. One handle holds the URL and curl_url_dup copies it before the redirect is resolved; reading the result back is the allocPointer, readPointerAt, readCString and curl_free sequence of the previous example.

main.js

import {
    initNative, curl_url, curl_url_dup, curl_url_set, curl_url_get, curl_url_cleanup,
    curl_url_strerror, CURLUPart, CURLUcode,
} from '@crossbind/port-curl/curl/urlapi.h';
import {
    curl_free, allocPointer, readPointerAt, readCString,
} from '@crossbind/port-curl/curl/curl.h';
 
await initNative();
const CURLU_URLENCODE = 1 << 7;
const CURLU_APPENDQUERY = 1 << 8;
const CURLUPART_URL = await CURLUPart.CURLUPART_URL;
const CURLUPART_PATH = await CURLUPart.CURLUPART_PATH;
const CURLUPART_QUERY = await CURLUPart.CURLUPART_QUERY;
const ok = await CURLUcode.CURLUE_OK;
const check = async (code) => {
    if (code !== ok) throw new Error(await curl_url_strerror(code));
};
const slot = await allocPointer(1);
const text = async (url) => {
    await check(await curl_url_get(url, CURLUPART_URL, slot, 0));
    const value = await readPointerAt(slot, 0);
    const result = await readCString(value);
    await curl_free(value);
    return result;
};
 
const url = await curl_url();
await check(await curl_url_set(url, CURLUPART_URL, 'https://api.example.com/v1/', 0));
await check(await curl_url_set(url, CURLUPART_URL, 'search', 0));
await check(await curl_url_set(url, CURLUPART_QUERY, 'q=crème brûlée & tea', CURLU_APPENDQUERY | CURLU_URLENCODE));
await check(await curl_url_set(url, CURLUPART_QUERY, 'sort=price+asc', CURLU_APPENDQUERY | CURLU_URLENCODE));
console.log(await text(url));
 
const redirect = await curl_url_dup(url);
await check(await curl_url_set(redirect, CURLUPART_URL, '../v2/items?id=7', 0));
console.log(await text(redirect));
 
await check(await curl_url_set(url, CURLUPART_PATH, '/files/Q3 report.pdf', CURLU_URLENCODE));
console.log(await text(url));
await curl_url_cleanup(redirect);
await curl_url_cleanup(url);

PRINTSfirst run downloads 4.5 MB

https://api.example.com/v1/search?q=cr%C3%A8me+br%C3%BBl%C3%A9e+%26+tea&sort=price%2Basc
https://api.example.com/v2/items?id=7
https://api.example.com/files/Q3%20report.pdf?q=cr%C3%A8me+br%C3%BBl%C3%A9e+%26+tea&sort=price%2Basc

Percent-encode and decode text

curl_easy_escape encodes every byte except letters, digits and - . _ ~, the encoding the curl tool's --data-urlencode and --url-query use. JavaScript's encodeURIComponent leaves ( ) ! * ' alone. curl_easy_unescape decodes %XX only: + stays +, and a % that starts no valid sequence is kept.

src/native/percent_codec.h

#pragma once
 
#include <curl/curl.h>
 
#include <cstddef>
#include <cstring>
#include <stdexcept>
#include <string>
 
// curl_easy_escape and curl_easy_unescape: percent-encoding the way curl does it. Every byte except
// A-Z, a-z, 0-9 and - . _ ~ is escaped, so the result is safe in any part of a URL. Since libcurl
// 7.82.0 both functions ignore their handle argument, so no easy handle is needed.
class PercentCodec {
public:
    static std::string escape(const std::string& text) {
        char* escaped = curl_easy_escape(nullptr, text.data(), static_cast<int>(text.size()));
        return take(escaped, escaped ? std::strlen(escaped) : 0);
    }
 
    // Decodes %XX sequences only: + stays +, and a % that starts no valid sequence is kept.
    static std::string unescape(const std::string& text) {
        int size = 0;
        char* decoded = curl_easy_unescape(nullptr, text.data(), static_cast<int>(text.size()), &size);
        return take(decoded, static_cast<std::size_t>(size));
    }
 
private:
    static std::string take(char* data, std::size_t size) {
        if (!data) throw std::runtime_error("out of memory");
        const std::string result(data, size);
        curl_free(data);
        return result;
    }
};

main.js

import { initNative, PercentCodec } from './native/percent_codec.h';
 
await initNative();
const text = 'crème brûlée & tea (50%)';
const escaped = await PercentCodec.escape(text);
console.log(escaped);
console.log(await PercentCodec.unescape(escaped));
console.log(encodeURIComponent(text));
console.log(await PercentCodec.unescape('a+b%20c%zz'));

PRINTSfirst run downloads 4.3 MB

cr%C3%A8me%20br%C3%BBl%C3%A9e%20%26%20tea%20%2850%25%29
crème brûlée & tea (50%)
cr%C3%A8me%20br%C3%BBl%C3%A9e%20%26%20tea%20(50%25)
a+b c%zz

Both functions return a char * that JavaScript reads with readCString and frees with curl_free, and they take null for the handle as the C++ does. The length arguments count bytes, so they are 0 here and curl measures the UTF-8 text itself: text.length counts UTF-16 units and cuts crème brûlée & tea (50%) three bytes short. readCString stops at the first zero byte, so a decoded %00 ends the text; to read past it, pass an allocBuffer(4) handle as the int * length and read that many bytes with readBytes, one character per byte.

main.js

import {
    initNative, curl_easy_escape, curl_easy_unescape, curl_free, readCString,
} from '@crossbind/port-curl/curl/curl.h';
 
await initNative();
const encode = async (text) => {
    const escaped = await curl_easy_escape(null, text, 0);
    const result = await readCString(escaped);
    await curl_free(escaped);
    return result;
};
const decode = async (text) => {
    const decoded = await curl_easy_unescape(null, text, 0, null);
    const result = await readCString(decoded);
    await curl_free(decoded);
    return result;
};
 
const text = 'crème brûlée & tea (50%)';
const escaped = await encode(text);
console.log(escaped);
console.log(await decode(escaped));
console.log(encodeURIComponent(text));
console.log(await decode('a+b%20c%zz'));

PRINTSfirst run downloads 4.5 MB

cr%C3%A8me%20br%C3%BBl%C3%A9e%20%26%20tea%20%2850%25%29
crème brûlée & tea (50%)
cr%C3%A8me%20br%C3%BBl%C3%A9e%20%26%20tea%20(50%25)
a+b c%zz

Read the dates in HTTP headers

curl_getdate reads the three date formats HTTP allows, and variations such as zone names, as seconds since 1970 in UTC. A date without a zone is GMT, where JavaScript's Date.parse takes local time, and ISO 8601 is not a format it reads.

src/native/http_dates.h

#pragma once
 
#include <curl/curl.h>
 
#include <ctime>
#include <string>
 
// curl_getdate, the date parser curl uses for Last-Modified, Expires, cookie expiry and the tool's
// -z option. It reads the three HTTP date formats and many variations, and a date without a time
// zone is taken as GMT.
class HttpDates {
public:
    // Seconds since 1970-01-01 UTC, or -1 when curl cannot read the text as a date.
    static double seconds(const std::string& text) { return static_cast<double>(curl_getdate(text.c_str(), nullptr)); }
 
    // The same instant written as ISO 8601 in UTC.
    static std::string iso(const std::string& text) {
        const time_t when = curl_getdate(text.c_str(), nullptr);
        if (when == -1) return "not a date";
        std::tm parts{};
        gmtime_r(&when, &parts);
        char buffer[32];
        std::strftime(buffer, sizeof buffer, "%Y-%m-%dT%H:%M:%SZ", &parts);
        return buffer;
    }
};

main.js

import { initNative, HttpDates } from './native/http_dates.h';
 
await initNative();
const formats = ['Sun, 06 Nov 1994 08:49:37 GMT', 'Sunday, 06-Nov-94 08:49:37 GMT', 'Sun Nov  6 08:49:37 1994'];
for (const date of formats) {
    console.log(await HttpDates.seconds(date), await HttpDates.iso(date));
}
console.log(await HttpDates.iso('Sun, 06 Nov 1994 08:49:37 CEST'));
console.log(await HttpDates.seconds('1994-11-06T08:49:37Z'));

PRINTSfirst run downloads 4.3 MB

784111777 1994-11-06T08:49:37Z
784111777 1994-11-06T08:49:37Z
784111777 1994-11-06T08:49:37Z
1994-11-06T06:49:37Z
-1

curl_getdate returns a time_t, 64 bits in this build, so the seconds arrive as a BigInt, and as -1n when curl cannot read the text as a date. JavaScript's Date writes the ISO form the C++ made with gmtime_r and strftime.

main.js

import { initNative, curl_getdate } from '@crossbind/port-curl/curl/curl.h';
 
await initNative();
const iso = (seconds) => new Date(Number(seconds) * 1000).toISOString().replace('.000Z', 'Z');
const formats = ['Sun, 06 Nov 1994 08:49:37 GMT', 'Sunday, 06-Nov-94 08:49:37 GMT', 'Sun Nov  6 08:49:37 1994'];
for (const date of formats) {
    const seconds = await curl_getdate(date, null);
    console.log(seconds, iso(seconds));
}
console.log(iso(await curl_getdate('Sun, 06 Nov 1994 08:49:37 CEST', null)));
console.log(await curl_getdate('1994-11-06T08:49:37Z', null));

PRINTSfirst run downloads 4.5 MB

784111777 1994-11-06T08:49:37Z
784111777 1994-11-06T08:49:37Z
784111777 1994-11-06T08:49:37Z
1994-11-06T06:49:37Z
-1

Check what this libcurl was built with

curl_version_info lists the protocols and features compiled in, so code can check before relying on one. This is the WebAssembly build: no HTTP/2, no compression, no IDN and no IPv6. Its protocols are compiled in, but in a browser a transfer goes through fetch, so only HTTP and HTTPS leave the page. The Android and iOS packages report the same protocols, plus libz.

src/native/build_info.h

#pragma once
 
#include <curl/curl.h>
 
#include <string>
 
// curl_version_info reports what this libcurl was built with, so code can check for a protocol or
// a feature before relying on it.
class BuildInfo {
public:
    static std::string version() { return curl_version(); }
 
    static std::string protocols() { return join(info()->protocols); }
 
    static std::string features() { return join(info()->feature_names); }
 
    static bool supports(const std::string& feature) {
        for (const char* const* item = info()->feature_names; item && *item; ++item) {
            if (feature == *item) return true;
        }
        return false;
    }
 
private:
    static const curl_version_info_data* info() { return curl_version_info(CURLVERSION_NOW); }
 
    static std::string join(const char* const* items) {
        std::string text;
        for (; items && *items; ++items) text += (text.empty() ? "" : " ") + std::string(*items);
        return text;
    }
};

main.js

import { initNative, BuildInfo } from './native/build_info.h';
 
await initNative();
console.log(await BuildInfo.version());
console.log(await BuildInfo.protocols());
console.log(await BuildInfo.features());
console.log(await BuildInfo.supports('HTTP2'), await BuildInfo.supports('HSTS'));

PRINTSfirst run downloads 4.3 MB

libcurl/8.22.0 OpenSSL/4.0.2
dict file ftp ftps gopher gophers http https imap imaps mqtt mqtts pop3 pop3s rtsp smtp smtps telnet tftp ws wss
alt-svc AsynchDNS HSTS HTTPS-proxy Largefile SSL threadsafe UnixSockets
false true

curl_version returns a char *, read with readCString and not freed: it points at a static buffer. curl_version_info_data crosses with its number fields only, so the protocols and feature_names lists never reach JavaScript: the protocols here are the schemes libcurl 8.22.0 knows that the URL API accepts (the rest return CURLUE_UNSUPPORTED_SCHEME), and the features are the features bitmask decoded with the CURL_VERSION_* bits from curl.h. A feature without a bit, such as HTTPSRR or SSLS-EXPORT, cannot be seen this way.

main.js

import {
    initNative, curl_version, curl_version_info, CURLversion, readCString,
} from '@crossbind/port-curl/curl/curl.h';
import {
    curl_url, curl_url_set, curl_url_cleanup, CURLUPart, CURLUcode,
} from '@crossbind/port-curl/curl/urlapi.h';
 
await initNative();
console.log(await readCString(await curl_version()));
 
const schemes = 'dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt mqtts pop3 pop3s rtsp scp sftp smb smbs smtp smtps telnet tftp ws wss';
const ok = await CURLUcode.CURLUE_OK;
const url = await curl_url();
const protocols = [];
for (const scheme of schemes.split(' ')) {
    if ((await curl_url_set(url, await CURLUPart.CURLUPART_SCHEME, scheme, 0)) === ok) protocols.push(scheme);
}
await curl_url_cleanup(url);
console.log(protocols.join(' '));
 
const info = await curl_version_info(await CURLversion.CURLVERSION_TWELFTH);
const features = await info.features;
const bits = {
    'alt-svc': 24, AsynchDNS: 7, brotli: 23, Debug: 6, gsasl: 29, 'GSS-API': 17, HSTS: 28, HTTP2: 16, HTTP3: 25,
    'HTTPS-proxy': 21, IDN: 10, IPv6: 0, Kerberos: 18, Largefile: 9, libz: 3, MultiSSL: 22, NTLM: 4, PSL: 20,
    SPNEGO: 8, SSL: 2, SSPI: 11, threadsafe: 30, Unicode: 27, UnixSockets: 19, zstd: 26,
};
const supports = (name) => (features & (1 << bits[name])) !== 0;
console.log(Object.keys(bits).filter(supports).join(' '));
console.log(supports('HTTP2'), supports('HSTS'));

PRINTSfirst run downloads 4.5 MB

libcurl/8.22.0 OpenSSL/4.0.2
dict file ftp ftps gopher gophers http https imap imaps mqtt mqtts pop3 pop3s rtsp smtp smtps telnet tftp ws wss
alt-svc AsynchDNS HSTS HTTPS-proxy Largefile SSL threadsafe UnixSockets
false true

What is different on WebAssembly

In a browser the module runs in a Worker by default (useWorker), so every call returns a promise: await calls and constructors alike.
The module has its own filesystem: m.FS writes files, m.getFileBytes reads them back and m.autoMountFiles mounts File objects from an <input type=file>. /memfs lives in memory; /opfs persists across reloads and needs the Worker. See Filesystem.
In Node.js, m.FS is the real disk, so use real paths there.
Multi-threaded builds (runtime: 'mt') need COOP and COEP headers in production. See Threading.

Other platforms

cURL overview: the apps, every platform's setup and the packages.
cURL for Android: React Native apps on Android.
cURL for iOS: React Native apps on iOS.
cURL for WASI: command-line programs under wasmtime.

Facts on this page come from the port manifests in the repository and from what npm served on beta when the site was built. See the Libraries guide for the full consumer flow.

MORE LIBRARIES

Expat GDAL GEOS GeoTIFF iconv LERC libjpeg-turbo libTIFF OpenSSL PROJ SpatiaLite SQLite WebP zlib Zstandard