vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings #4679

zolk3ri · 2025-01-11T18:44:58Z

Add ~~minimal~~ comprehensive libcurl bindings providing a simple, memory-safe high-level API to interact with libcurl in Odin.

Key features:

Simple high-level API for HTTP(S) requests
Memory management via Odin's allocator system
Type-safe response handling with custom parsers
Comprehensive SSL/TLS support
Flexible configuration options
Well-documented API with examples

The implementation is based on curl.h version 8.11.1 and provides both low-level libcurl bindings and a high-level request API that follows Odin idioms.

Usage

Import the library:

import "vendor:curl"

Initialize before use:

if !curl.init() {
    fmt.eprintln("Failed to initialize curl")
    return
}
defer curl.cleanup()

Simple GET request:

config := curl.Request_Config{
    headers = []string{
        "User-Agent: odin-curl/0.1",
    },
}

res := curl.get("https://httpbin.org/get", config)
defer curl.destroy_response(&res)

if res.error != .None {
    fmt.eprintln("Request failed:", curl.error_string(res.error))
    return
}

fmt.println("Status:", res.status_code)
fmt.println("Response:", string(res.body))

Simple POST request:

config := curl.Request_Config{
    headers = []string{
        "User-Agent: odin-curl/0.1",
        "Content-Type: application/json",
    },
}

data := `{"test": "data"}`
res := curl.post("https://httpbin.org/post", data, config)
defer curl.destroy_response(&res)

if res.error != .None {
    fmt.eprintln("Request failed:", curl.error_string(res.error))
    return
}

fmt.println("Status:", res.status_code)
fmt.println("Response:", string(res.body))

GET with JSON parsing:

Post :: struct {
    id: int,
    title: string,
    body: string,
    userId: int,
}

config := curl.Request_Config{
    headers = []string{
        "User-Agent: odin-curl/0.1",
        "Accept: application/json",
    },
}

res := curl.get_json(Post, "https://jsonplaceholder.typicode.com/posts/1", config)
defer curl.destroy_response(&res)

if res.error != .None {
    fmt.eprintln("Request failed:", curl.error_string(res.error))
    return
}

fmt.printf("Post %d: %q\n", res.body.id, res.body.title)
fmt.println("Body:", res.body.body)

POST with JSON:

Post :: struct {
    id: int,
    title: string,
    body: string,
    userId: int,
}

config := curl.Request_Config{
    headers = []string{
        "User-Agent: odin-curl/0.1",
        "Content-Type: application/json",
    },
}

data := `{
    "title": "New Post",
    "body": "Example content",
    "userId": 1
}`
res := curl.post_json(Post, "https://jsonplaceholder.typicode.com/posts", data, config)
defer curl.destroy_response(&res)

if res.error != .None {
    fmt.eprintln("Request failed:", curl.error_string(res.error))
    return
}

fmt.printf("Created Post ID: %d\n", res.body.id)
fmt.println("Title:", res.body.title)
fmt.println("Body:", res.body.body)

Examples

The examples/ directory contains:

basic.odin
- Simple GET and POST requests with custom headers
- Request timeout handling (success and failure cases)
- Redirect following with configurable limits
- Timeout and redirect error handling
typed.odin
- Type-safe HTTP request/response handling with built-in and custom parsers
- Custom response parsing with proper cleanup
- Working with structured data via JSON API endpoints
ssl.odin
- HTTPS requests with configurable security levels
- TLS version selection
- Certificate verification
- Error handling for SSL/TLS issues
allocator.odin
- Memory allocation tracking with Tracking_Allocator

All examples run successfully and have been tested with valgrind to confirm no memory leaks.

I hope this library is suitable for inclusion in the vendor collection. If not, maintenance will continue here. All suggestions for improvement are welcome, whether they highlight blockers or provide general recommendations.

Thank you for your consideration! :)

Extract common HTTP method logic into do_method() and do_method_with() to reduce code duplication in request handling. This consolidates error handling and memory management while maintaining the existing public API.

Add post_string() wrapper that completes the set of string response handlers, providing consistent string handling across request types.

Simplify "Optional request configuration" documentation to match format used across other parameter descriptions.

gingerBill · 2025-01-13T10:54:15Z

vendor/curl/README.md

+  - Ubuntu/Debian: `sudo apt install libcurl4-dev`
+  - Fedora: `sudo dnf install libcurl-devel`
+  - macOS: `brew install curl`
+  - Windows: Download from [curl](https://curl.se/windows/)


For vendor, things should "just work", especially on Windows. So why does Windows not bundle with a .lib already?

gingerBill · 2025-01-13T10:54:57Z

vendor/curl/curl.odin

+CURL :: distinct rawptr
+
+// CURL_GLOBAL_ALL combines all initialization flags.
+CURL_GLOBAL_ALL: i64 = 3


Maybe remove the CURL_ prefix?

gingerBill · 2025-01-13T10:55:01Z

vendor/curl/curl.odin

+CURL_GLOBAL_ALL: i64 = 3
+
+// CURLOPT represents options for a transfer.
+CURLOPT :: enum i32 {


Maybe remove the CURL prefix?

gingerBill · 2025-01-13T10:55:22Z

vendor/curl/curl.odin

+// Error represents libcurl error codes.
+//
+// This maps directly to CURLcode error values from curl.h.
+Error :: enum {


Is this the correct size? Is this meant to be enum c.int?

gingerBill · 2025-01-13T10:55:28Z

vendor/curl/curl.odin

+}
+
+// CURLINFO represents information retrieval options.
+CURLINFO :: enum i32 {


Is this meant to be c.int?

gingerBill · 2025-01-13T10:55:35Z

vendor/curl/curl.odin

+CURL_GLOBAL_ALL: i64 = 3
+
+// CURLOPT represents options for a transfer.
+CURLOPT :: enum i32 {


Is this meant to be c.int?

gingerBill · 2025-01-13T10:56:33Z

vendor/curl/curl.odin

+
+// CURLOPT represents options for a transfer.
+CURLOPT :: enum i32 {
+  // Basic options


Please adhere to the Odin conventions of using tabs for indentation.

gingerBill · 2025-01-13T10:56:51Z

vendor/curl/curl.odin

+// - userdata: User provided data pointer
+//
+// Returns: Number of bytes handled.
+Write_Callback :: #type proc "c" (data: rawptr, size: c.size_t, nmemb: c.size_t, userdata: rawptr) -> c.size_t


Please try to keep the original naming conventions and DO NOT change it to Odin's core convention.

gingerBill · 2025-01-13T10:58:08Z

vendor/curl/curl.odin

+// Error represents libcurl error codes.
+//
+// This maps directly to CURLcode error values from curl.h.
+Error :: enum {


I know this wraps the other calls, but why not keep it the same? e.g. enum c.int?

gingerBill · 2025-01-13T10:58:35Z

vendor/curl/curl.odin

+  if ctx == nil do return false
+
+  result: i32
+  when T == string {


This will fail with distinct types.

gingerBill · 2025-01-13T11:01:08Z

Honestly, the PR has loads of styling issues and is not "minimal" in any sense. The general wrappers are not that great because they rely too much on parapoly and get numerous things wrong in the process too (the first thing being not understanding distinct is a thing).

gingerBill · 2025-01-13T11:07:53Z

I am closing this PR because it would be quicker for me to write my own bindings than explain everything wrong with it and then hope they get fixed correctly.

zolk3ri · 2025-01-13T11:48:48Z

Thank you for the feedback. You're right - while the binding started minimal, it grew more complex
with features like parametric polymorphism that I thought might be helpful for others.

As I need these bindings for my active projects, I'll continue maintenance here where I'll work on addressing these points.

zolk3ri added 4 commits January 11, 2025 19:27

vendor/curl: Add minimal libcurl bindings

408fdd3

refactor(easy): consolidate HTTP method handling into core procedures

7b4196c

Extract common HTTP method logic into do_method() and do_method_with() to reduce code duplication in request handling. This consolidates error handling and memory management while maintaining the existing public API.

feat(easy): add post_string() wrapper with example

8889e7f

Add post_string() wrapper that completes the set of string response handlers, providing consistent string handling across request types.

docs(easy): simplify config parameter documentation for consistency

6f619d5

Simplify "Optional request configuration" documentation to match format used across other parameter descriptions.

zolk3ri force-pushed the vendor/curl branch from 8c1b7e7 to 6f619d5 Compare January 12, 2025 18:44

gingerBill reviewed Jan 13, 2025

View reviewed changes

vendor/curl/curl.odin

}

// CURLINFO represents information retrieval options.

CURLINFO :: enum i32 {

Copy link

Member

gingerBill Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this meant to be c.int?

gingerBill reviewed Jan 13, 2025

View reviewed changes

vendor/curl/curl.odin

if ctx == nil do return false

result: i32

when T == string {

Copy link

Member

gingerBill Jan 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will fail with distinct types.

gingerBill closed this Jan 13, 2025

zolk3ri deleted the vendor/curl branch January 13, 2025 12:44

zolk3ri changed the title ~~vendor/curl: Add minimal libcurl bindings~~ vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings Jan 13, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings #4679

vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings #4679

zolk3ri commented Jan 11, 2025 •

edited

Loading

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025 •

edited

Loading

gingerBill Jan 13, 2025

gingerBill Jan 13, 2025

gingerBill commented Jan 13, 2025

gingerBill commented Jan 13, 2025

zolk3ri commented Jan 13, 2025

vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings #4679

vendor/curl: Add comprehensive (not-so-minimal) libcurl bindings #4679

Conversation

zolk3ri commented Jan 11, 2025 • edited Loading

Usage

Examples

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gingerBill Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gingerBill commented Jan 13, 2025

gingerBill commented Jan 13, 2025

zolk3ri commented Jan 13, 2025

zolk3ri commented Jan 11, 2025 •

edited

Loading

gingerBill Jan 13, 2025 •

edited

Loading