rsurl 0.0.2

A pure-Rust implementation of curl. Library, C FFI, and CLI for HTTP/HTTPS/FTP/FTPS.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

/*
 * rsurl.h — C ABI for the rsurl pure-Rust HTTP client.
 *
 * Copyright (c) 2026 Karpelès Lab Inc. — MIT License.
 *
 * Link against -lrsurl (librsurl.so / .dylib / .dll). Function names use
 * the rsurl_ prefix so the library can coexist with libcurl in the same
 * process without symbol collisions.
 */

#ifndef RSURL_H
#define RSURL_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Opaque easy-handle. Created with rsurl_easy_init, freed with
 * rsurl_easy_cleanup. */
typedef struct RSURL RSURL;

/* Option identifiers passed to rsurl_easy_setopt_str / _long. */
typedef enum {
    RSURLOPT_URL              = 1,  /* const char* */
    RSURLOPT_CUSTOMREQUEST    = 2,  /* const char* */
    RSURLOPT_HEADER           = 3,  /* const char* "Name: value" (repeat) */
    RSURLOPT_POSTFIELDSSTRING = 4,  /* const char* (UTF-8 body) */
    RSURLOPT_CONNECTTIMEOUT   = 5,  /* long seconds */
    RSURLOPT_TIMEOUT          = 6,  /* long seconds */
    RSURLOPT_USERAGENT        = 7   /* const char* */
} rsurl_option_t;

/* Status codes returned by API functions. */
typedef enum {
    RSURLE_OK              = 0,
    RSURLE_INVALID_HANDLE  = 1,
    RSURLE_UNKNOWN_OPTION  = 2,
    RSURLE_INVALID_ARG     = 3,
    RSURLE_NO_RESPONSE     = 4,
    RSURLE_NETWORK         = 5,
    RSURLE_BAD_RESPONSE    = 6,
    RSURLE_UNSUPPORTED     = 7
} rsurl_code_t;

/* --- Lifecycle ---------------------------------------------------------- */

/* Allocate a new easy handle. Returns NULL on allocation failure. */
RSURL *rsurl_easy_init(void);

/* Free an easy handle. NULL is a no-op. */
void rsurl_easy_cleanup(RSURL *handle);

/* Reset options and clear stored response. Handle remains valid. */
rsurl_code_t rsurl_easy_reset(RSURL *handle);

/* --- Options ------------------------------------------------------------ */

/* Set a string-valued option. Pass NULL to clear it. The string is copied. */
rsurl_code_t rsurl_easy_setopt_str(RSURL *handle, int option,
                                     const char *value);

/* Set a long-valued option. Values <= 0 disable the option where applicable. */
rsurl_code_t rsurl_easy_setopt_long(RSURL *handle, int option, long value);

/* --- Execution ---------------------------------------------------------- */

/* Execute the request. Replaces any previous response on the handle. */
rsurl_code_t rsurl_easy_perform(RSURL *handle);

/* --- Response inspection ------------------------------------------------ */

/* Borrow the response body. *out_ptr / *out_len are valid until the next
 * rsurl_easy_perform / _reset / _cleanup on this handle. */
rsurl_code_t rsurl_easy_response_body(const RSURL *handle,
                                        const uint8_t **out_ptr,
                                        size_t *out_len);

/* Return the HTTP status code (e.g. 200), or 0 if no response is available. */
long rsurl_easy_response_status(const RSURL *handle);

/* Return the number of response headers available. */
size_t rsurl_easy_response_header_count(const RSURL *handle);

/* Borrow a NUL-terminated "Name: value" string for header at `index`, or
 * NULL if out of range. Pointer is valid until the next perform/reset/cleanup. */
const char *rsurl_easy_response_header(const RSURL *handle, size_t index);

/* --- Utility ------------------------------------------------------------ */

/* Static human-readable string for a rsurl_code_t value. */
const char *rsurl_strerror(int code);

/* NUL-terminated version string, e.g. "rsurl/0.0.1". */
const char *rsurl_version(void);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* RSURL_H */