Sulkta-Coop/clawdforge
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdforge/clients/c/include/clawdforge.h
Kayos a69e924592 clients/c: initial C SDK for clawdforge 
Synchronous client over libcurl + vendored cJSON. Single public
header (include/clawdforge.h) with an opaque cf_client_t and the
full surface: /healthz, /run, /files, /admin/tokens.

- C11, no GNU extensions; -Wall -Wextra -Wpedantic clean
- Hidden visibility on the shared lib + CF_API export attribute
- Static + shared lib via CMake; relocatable pkg-config (${pcfiledir})
- Errors via out-param cf_error_t; every output struct has a _free()
- Multipart upload streams from disk via curl_mime_filedata
- 15 in-process socket-loop tests; valgrind + ASan clean
2026-04-28 23:01:52 -07:00

282 lines
11 KiB
C
Raw Blame History

/*
* clawdforge — C SDK
*
* MIT License — see CMakeLists.txt for the full text.
*
* A small synchronous C client for the clawdforge HTTP service.
* The service wraps `claude -p` subprocess calls behind a
* bearer-token-gated REST API.
*
* Single public header. The client struct (cf_client_t) is opaque;
* callers only ever see a forward-declared typedef and a set of
* functions that take it.
*
* Threading: cf_client_t is NOT shared across threads. Create one
* client per thread (or guard one client with your own mutex).
*
* Errors are reported through a caller-provided cf_error_t out
* parameter — never through stderr or thread-local globals. Free
* any populated cf_error_t with cf_error_free().
*
* Every output struct has a matching _free() that releases its
* heap-allocated members. Stack-allocate the struct, pass its
* address in, free it when done.
*/
#ifndef CLAWDFORGE_H
#define CLAWDFORGE_H
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Visibility / export attribute. The shared library is built with
* -fvisibility=hidden by default; CF_API marks the public surface so
* those symbols stay visible. The static library and consumers use
* the empty default. */
#if defined(_WIN32) || defined(__CYGWIN__)
# if defined(CLAWDFORGE_BUILDING_DLL)
# define CF_API __declspec(dllexport)
# elif defined(CLAWDFORGE_USING_DLL)
# define CF_API __declspec(dllimport)
# else
# define CF_API
# endif
#else
# if defined(CLAWDFORGE_BUILDING_LIB) && defined(__GNUC__)
# define CF_API __attribute__((visibility("default")))
# else
# define CF_API
# endif
#endif
/* ------------------------------------------------------------------ */
/* Versioning */
/* ------------------------------------------------------------------ */
#define CLAWDFORGE_VERSION_MAJOR 0
#define CLAWDFORGE_VERSION_MINOR 1
#define CLAWDFORGE_VERSION_PATCH 0
#define CLAWDFORGE_VERSION_STRING "0.1.0"
/* Returns the runtime library version string ("X.Y.Z"). */
CF_API const char *cf_version(void);
/* ------------------------------------------------------------------ */
/* Status codes */
/* ------------------------------------------------------------------ */
typedef enum cf_status {
CF_OK = 0, /* success */
CF_ERR_AUTH = 1, /* 401 / 403 from server, or missing token */
CF_ERR_API = 2, /* server returned a structured error envelope */
CF_ERR_TRANSPORT = 3, /* network / TLS / connection */
CF_ERR_USAGE = 4, /* caller passed a bad argument */
CF_ERR_OOM = 5, /* malloc / calloc returned NULL */
CF_ERR_PARSE = 6 /* server response was not the expected JSON shape */
} cf_status_t;
/* ------------------------------------------------------------------ */
/* Error type */
/* ------------------------------------------------------------------ */
/*
* cf_error_t is filled in by every fallible function on failure.
* On CF_OK the contents are left untouched — do not call cf_error_free
* if the call returned CF_OK.
*
* Recommended pattern:
*
* cf_error_t err = {0};
* if (cf_run(c, &req, &res, &err) != CF_OK) {
* fprintf(stderr, "%s\n", cf_error_message(&err));
* cf_error_free(&err);
* return 1;
* }
*/
typedef struct cf_error {
cf_status_t code;
long http_status; /* HTTP status code if applicable, else 0 */
char *message; /* heap-allocated, NUL-terminated */
} cf_error_t;
CF_API const char *cf_error_message(const cf_error_t *err);
CF_API void cf_error_free(cf_error_t *err);
/* Static, never-NULL human label for a status code (e.g. "CF_OK"). */
CF_API const char *cf_status_str(cf_status_t code);
/* ------------------------------------------------------------------ */
/* Client */
/* ------------------------------------------------------------------ */
/* Opaque. */
typedef struct cf_client cf_client_t;
/*
* Construct a new client.
*
* base_url: e.g. "http://192.168.0.5:8800". A trailing slash is
* tolerated. Required.
* token: bearer token for /run + /files. May be NULL if the
* caller only intends to use admin endpoints with a
* separately-provided admin token (see cf_client_set_admin_token).
*
* Returns NULL on allocation failure. cf_client_free() releases.
*/
CF_API cf_client_t *cf_client_new(const char *base_url, const char *token);
/* Optional: install or replace the admin bootstrap token used for
* the /admin endpoints. Pass NULL to clear. */
CF_API cf_status_t cf_client_set_admin_token(cf_client_t *c, const char *admin_token);
/* Optional: set the libcurl connection + request timeout in seconds.
* Default is 600 seconds. Setting <= 0 leaves the current value. */
CF_API void cf_client_set_timeout_secs(cf_client_t *c, long timeout_secs);
CF_API void cf_client_free(cf_client_t *c);
/* ------------------------------------------------------------------ */
/* /healthz */
/* ------------------------------------------------------------------ */
typedef struct cf_healthz {
int ok; /* "ok" field */
int claude_present; /* "claude_present" field */
char *claude_version; /* "claude_version" or NULL */
} cf_healthz_t;
CF_API cf_status_t cf_healthz(cf_client_t *c, cf_healthz_t *out, cf_error_t *err);
CF_API void cf_healthz_free(cf_healthz_t *h);
/* ------------------------------------------------------------------ */
/* /run */
/* ------------------------------------------------------------------ */
/*
* Request struct. Initialise with `cf_run_request_t r = {0};` and
* populate the fields you need. Strings are caller-owned; clawdforge
* copies them as needed.
*/
typedef struct cf_run_request {
const char *prompt; /* required, non-empty */
const char *model; /* optional, NULL = server default */
const char *system; /* optional system prompt */
const char *const *files; /* array of file_token strings */
size_t files_count;
int timeout_secs; /* 0 = server default; else 5..600 */
} cf_run_request_t;
/*
* Response from a successful /run call.
*
* result_json: the inner "result" field re-serialised back to a
* JSON string. Always non-NULL on CF_OK. If the server
* returned a string, this is a JSON-encoded string
* (including the surrounding quotes); if it returned
* an object, this is the object as JSON.
*
* result_is_string: 1 iff the server's "result" was a JSON string;
* 0 if it was an object/array/number/bool/null.
*
* stop_reason: e.g. "end_turn"; may be NULL.
*
* duration_ms: server-reported duration in ms.
*/
typedef struct cf_run_result {
char *result_json;
int result_is_string;
char *stop_reason;
long duration_ms;
} cf_run_result_t;
CF_API cf_status_t cf_run(cf_client_t *c,
const cf_run_request_t *req,
cf_run_result_t *out,
cf_error_t *err);
CF_API void cf_run_result_free(cf_run_result_t *r);
/*
* Convenience: parse out->result_json with cJSON. Returns NULL if
* the result was not valid JSON (shouldn't happen in normal use,
* but defensive). The caller must cJSON_Delete() the returned node.
*
* The return type is `void *` so the public header does not have
* to expose the cJSON struct. Callers including cJSON.h can cast
* directly to `cJSON *`.
*/
CF_API void *cf_run_result_as_cjson(const cf_run_result_t *r);
/* ------------------------------------------------------------------ */
/* /files */
/* ------------------------------------------------------------------ */
typedef struct cf_file_token {
char *file_token; /* "ff_..." */
long ttl_secs;
long size;
} cf_file_token_t;
/*
* Upload a file from disk via multipart/form-data. The file is
* streamed (not buffered into memory).
*
* path: absolute or relative filesystem path; must be readable.
* ttl_secs: 60..86400; 0 selects the server default (3600).
*/
CF_API cf_status_t cf_upload_file(cf_client_t *c,
const char *path,
long ttl_secs,
cf_file_token_t *out,
cf_error_t *err);
CF_API void cf_file_token_free(cf_file_token_t *ft);
/* ------------------------------------------------------------------ */
/* /admin/tokens */
/* ------------------------------------------------------------------ */
typedef struct cf_admin_token {
char *name;
char *token; /* plaintext, only present on create */
char **ip_cidrs;
size_t ip_cidrs_count;
} cf_admin_token_t;
typedef struct cf_admin_token_info {
char *name;
char **ip_cidrs;
size_t ip_cidrs_count;
long created_at; /* UNIX seconds, 0 if absent */
long last_used_at; /* UNIX seconds, 0 if absent */
} cf_admin_token_info_t;
typedef struct cf_admin_token_list {
cf_admin_token_info_t *items;
size_t count;
} cf_admin_token_list_t;
/* Mint a new app token. ip_cidrs/ip_cidrs_count may be 0 to omit. */
CF_API cf_status_t cf_admin_create_token(cf_client_t *c,
const char *name,
const char *const *ip_cidrs,
size_t ip_cidrs_count,
cf_admin_token_t *out,
cf_error_t *err);
CF_API void cf_admin_token_free(cf_admin_token_t *t);
CF_API cf_status_t cf_admin_list_tokens(cf_client_t *c,
cf_admin_token_list_t *out,
cf_error_t *err);
CF_API void cf_admin_token_list_free(cf_admin_token_list_t *l);
CF_API cf_status_t cf_admin_revoke_token(cf_client_t *c,
const char *name,
cf_error_t *err);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* CLAWDFORGE_H */
Reference in a new issue View git blame Copy permalink