fetch.h

Go to the documentation of this file.

 
#ifndef FETCH_H
#define FETCH_H
 
/* Include generated version information */
#include "cookie.h"
#include "version.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
 
#if defined(_WIN32) || defined(_WIN64)
#include <windows.h>
typedef HANDLE FETCH_FILE_HANDLE;
#define FETCH_INVALID_FILE_HANDLE INVALID_HANDLE_VALUE
#else
#include <stdio.h>
typedef FILE *FETCH_FILE_HANDLE;
#define FETCH_INVALID_FILE_HANDLE NULL
#endif
 
typedef enum {
  FETCH_STREAM_READ = 0, 
  FETCH_STREAM_DONE = 1, 
  FETCH_STREAM_SKIP = 2  
} fetch_stream_result_t;
 
typedef fetch_stream_result_t (*fetch_file_continue_cb)(void *userdata);
 
#define FETCH_USER_AGENT "libfetch/" FETCH_VERSION_STRING
 
static inline const char *fetch_version(void) { return FETCH_VERSION; }
 
static inline const char *fetch_version_string(void) {
  return FETCH_VERSION_STRING;
}
 
static inline int fetch_version_major(void) { return FETCH_VERSION_MAJOR; }
 
static inline int fetch_version_minor(void) { return FETCH_VERSION_MINOR; }
 
static inline int fetch_version_patch(void) { return FETCH_VERSION_PATCH; }
 
static inline int fetch_version_compare(int major, int minor, int patch) {
  int current = FETCH_VERSION_NUMBER;
  int compare = (major * 10000) + (minor * 100) + patch;
  return current - compare;
}
 
static inline bool fetch_version_at_least(int major, int minor, int patch) {
  return fetch_version_compare(major, minor, patch) >= 0;
}
 
typedef enum {
  FETCH_FLAG_KEEP_ALIVE_DEFAULT = 0,   
  FETCH_FLAG_ACCEPT_INVALID_CERTS = 1, 
  FETCH_FLAG_FOLLOW_REDIRECTS = 2,   
  FETCH_FLAG_ENABLE_COMPRESSION = 3, 
  FETCH_FLAG_ENABLE_COOKIES = 4,     
  FETCH_FLAG_DEBUG_LOGGING = 5,      
} fetch_flag_bit_t;
 
#define FETCH_FLAG_GET(flags, bit) (((flags) >> (bit)) & 1U)
#define FETCH_FLAG_SET(flags, bit) ((flags) | (1U << (bit)))
#define FETCH_FLAG_CLEAR(flags, bit) ((flags) & ~(1U << (bit)))
#define FETCH_FLAG_TOGGLE(flags, bit) ((flags) ^ (1U << (bit)))
 
typedef enum {
  HTTP_METHOD_GET,     
  HTTP_METHOD_HEAD,    
  HTTP_METHOD_POST,    
  HTTP_METHOD_PUT,     
  HTTP_METHOD_DELETE,  
  HTTP_METHOD_CONNECT, 
  HTTP_METHOD_OPTIONS, 
  HTTP_METHOD_TRACE,   
  HTTP_METHOD_PATCH    
} http_method_t;
 
typedef enum {
  FETCH_MODE_CORS,        
  FETCH_MODE_NO_CORS,     
  FETCH_MODE_SAME_ORIGIN, 
  FETCH_MODE_NAVIGATE     
} fetch_mode_t;
 
typedef enum {
  FETCH_CREDENTIALS_OMIT,        
  FETCH_CREDENTIALS_SAME_ORIGIN, 
  FETCH_CREDENTIALS_INCLUDE      
} fetch_credentials_t;
 
typedef enum {
  FETCH_CACHE_DEFAULT,       
  FETCH_CACHE_NO_STORE,      
  FETCH_CACHE_RELOAD,        
  FETCH_CACHE_NO_CACHE,      
  FETCH_CACHE_FORCE_CACHE,   
  FETCH_CACHE_ONLY_IF_CACHED 
} fetch_cache_t;
 
typedef enum {
  FETCH_REDIRECT_FOLLOW, 
  FETCH_REDIRECT_ERROR,  
  FETCH_REDIRECT_MANUAL  
} fetch_redirect_t;
 
typedef enum {
  FETCH_PROMISE_PENDING,   
  FETCH_PROMISE_FULFILLED, 
  FETCH_PROMISE_REJECTED   
} fetch_promise_state_t;
 
typedef enum {
  FETCH_ERROR_NONE = 0,           
  FETCH_ERROR_NETWORK,            
  FETCH_ERROR_TIMEOUT,            
  FETCH_ERROR_INVALID_URL,        
  FETCH_ERROR_INVALID_METHOD,     
  FETCH_ERROR_INVALID_HEADERS,    
  FETCH_ERROR_MEMORY,             
  FETCH_ERROR_ABORTED,            
  FETCH_ERROR_TOO_MANY_REDIRECTS, 
  FETCH_ERROR_CONNECTION_REFUSED, 
  FETCH_ERROR_DNS_RESOLUTION,     
  FETCH_ERROR_PROTOCOL_ERROR      
} fetch_error_t;
 
typedef struct fetch_abort_controller {
  bool aborted;                     
  const char *reason;               
  void (*on_abort)(void *userdata); 
  void *userdata;                   
} fetch_abort_controller_t;
 
typedef struct fetch_headers {
  char **keys;     
  char **values;   
  size_t count;    
  size_t capacity; 
} fetch_headers_t;
 
typedef struct {
  const fetch_headers_t *headers; 
  size_t index;                   
} fetch_headers_iterator_t;
 
typedef enum {
  FETCH_BODY_NONE,      
  FETCH_BODY_TEXT,      
  FETCH_BODY_BINARY,    
  FETCH_BODY_FORM_DATA, 
  FETCH_BODY_JSON,      
  FETCH_BODY_FILE       
} fetch_body_type_t;
 
typedef struct {
  fetch_body_type_t type; 
  union {
    // Memory-based body data (for TEXT, JSON, BINARY, FORM_DATA)
    struct {
      const void *data; 
      size_t size;      
    } memory;
 
    // File streaming data (for FILE type)
    struct {
      FETCH_FILE_HANDLE handle; 
      size_t size;              
      size_t offset;            
      bool close_on_free; 
      fetch_file_continue_cb
          continue_cb; 
      void *userdata;  
    } file;
  } data;
 
  const char *content_type; 
} fetch_body_t;
 
typedef struct fetch_init {
  http_method_t method;     
  fetch_headers_t *headers; 
  fetch_body_t *body;       
  fetch_mode_t mode;        
  fetch_credentials_t credentials; 
  fetch_cache_t cache;             
  fetch_redirect_t redirect;       
  const char *referrer;            
  const char *referrer_policy;     
  const char *integrity;           
  bool keepalive;                  
  fetch_abort_controller_t
      *signal;            
  uint32_t timeout_ms;    
  uint32_t max_redirects; 
} fetch_init_t;
 
typedef struct fetch_response {
  uint16_t status;             
  const char *status_text;     
  bool ok;                     
  bool redirected;             
  const char *url;             
  fetch_headers_t *headers;    
  void *body;                  
  size_t body_size;            
  fetch_body_type_t body_type; 
  fetch_error_t error;         
  const char *error_message;   
} fetch_response_t;
 
typedef void (*fetch_on_fulfilled_cb)(fetch_response_t *response,
                                      void *userdata);
 
typedef void (*fetch_on_rejected_cb)(fetch_error_t error, const char *message,
                                     void *userdata);
 
typedef struct fetch_promise {
  uint64_t promise_id;         
  fetch_promise_state_t state; 
  fetch_response_t *response;  
  fetch_error_t error;         
  const char *error_message;   
  fetch_on_fulfilled_cb on_fulfilled; 
  fetch_on_rejected_cb on_rejected;   
  void *userdata;                     
  void *internal_state;   
  volatile bool detached; 
} fetch_promise_t;
 
typedef struct fetch_url_search_params {
  char **keys;     
  char **values;   
  size_t count;    
  size_t capacity; 
} fetch_url_search_params_t;
 
typedef struct {
  const fetch_url_search_params_t *params; 
  size_t index;                            
} fetch_url_search_params_iterator_t;
 
typedef struct fetch_event_loop fetch_event_loop_t;
 
fetch_response_t *fetch(const char *url, fetch_init_t *init);
 
fetch_promise_t *fetch_async(const char *url, fetch_init_t *init);
 
bool fetch_promise_poll(fetch_promise_t *promise);
 
bool fetch_promise_await(fetch_promise_t *promise, uint32_t timeout_ms);
 
bool fetch_promise_cancel(fetch_promise_t *promise, const char *reason);
 
bool fetch_promise_cancelled(const fetch_promise_t *promise);
 
fetch_response_t *fetch_promise_response(const fetch_promise_t *promise);
 
fetch_promise_state_t fetch_promise_state(const fetch_promise_t *promise);
 
fetch_error_t fetch_promise_error(const fetch_promise_t *promise);
 
const char *fetch_promise_error_message(const fetch_promise_t *promise);
 
bool fetch_promise_pending(const fetch_promise_t *promise);
 
bool fetch_promise_fulfilled(const fetch_promise_t *promise);
 
bool fetch_promise_rejected(const fetch_promise_t *promise);
 
bool fetch_event_loop_start(void);
 
void fetch_event_loop_stop(void);
 
int fetch_event_loop_process(uint32_t timeout_ms);
 
bool fetch_event_loop_is_running(void);
 
fetch_headers_t *fetch_headers_new(void);
 
void fetch_headers_free(fetch_headers_t *headers);
 
void fetch_headers_append(fetch_headers_t *headers, const char *name,
                          const char *value);
 
void fetch_headers_set(fetch_headers_t *headers, const char *name,
                       const char *value);
 
void fetch_headers_delete(fetch_headers_t *headers, const char *name);
 
const char *fetch_headers_get(const fetch_headers_t *headers, const char *name);
 
bool fetch_headers_has(const fetch_headers_t *headers, const char *name);
 
fetch_headers_iterator_t fetch_headers_entries(const fetch_headers_t *headers);
 
bool fetch_headers_next(fetch_headers_iterator_t *iter, const char **key,
                        const char **value);
 
fetch_body_t *fetch_body_text(const char *text);
 
fetch_body_t *fetch_body_json(const char *json);
 
fetch_body_t *fetch_body_binary(const void *data, size_t size,
                                const char *content_type);
 
fetch_body_t *fetch_body_form_data(const char *form_data);
 
fetch_body_t *fetch_body_url_search_params(fetch_url_search_params_t *params);
 
fetch_body_t *fetch_body_file(FETCH_FILE_HANDLE file_handle, size_t size,
                              const char *content_type, bool close_on_free,
                              fetch_file_continue_cb continue_cb,
                              void *userdata);
 
void fetch_body_free(fetch_body_t *body);
 
fetch_url_search_params_t *fetch_url_search_params_new(void);
 
void fetch_url_search_params_free(fetch_url_search_params_t *params);
 
void fetch_url_search_params_append(fetch_url_search_params_t *params,
                                    const char *name, const char *value);
 
void fetch_url_search_params_set(fetch_url_search_params_t *params,
                                 const char *name, const char *value);
 
void fetch_url_search_params_delete(fetch_url_search_params_t *params,
                                    const char *name);
 
const char *fetch_url_search_params_get(const fetch_url_search_params_t *params,
                                        const char *name);
 
bool fetch_url_search_params_has(const fetch_url_search_params_t *params,
                                 const char *name);
 
char *
fetch_url_search_params_to_string(const fetch_url_search_params_t *params);
 
fetch_url_search_params_iterator_t
fetch_url_search_params_entries(const fetch_url_search_params_t *params);
 
bool fetch_url_search_params_next(fetch_url_search_params_iterator_t *iter,
                                  const char **key, const char **value);
 
const char *fetch_response_text(fetch_response_t *response);
 
const void *fetch_response_array_buffer(fetch_response_t *response,
                                        size_t *size);
 
const char *fetch_response_json(fetch_response_t *response);
 
bool fetch_response_ok(const fetch_response_t *response);
 
uint16_t fetch_response_status(const fetch_response_t *response);
 
const char *fetch_response_status_text(const fetch_response_t *response);
 
const char *fetch_response_url(const fetch_response_t *response);
 
fetch_headers_t *fetch_response_headers(const fetch_response_t *response);
 
fetch_response_t *fetch_response_clone(const fetch_response_t *response);
 
void fetch_response_free(fetch_response_t *response);
 
fetch_abort_controller_t *fetch_abort_controller_new(void);
 
void fetch_abort_controller_abort(fetch_abort_controller_t *controller,
                                  const char *reason);
 
bool fetch_abort_controller_aborted(const fetch_abort_controller_t *controller);
 
void fetch_abort_controller_free(fetch_abort_controller_t *controller);
 
fetch_init_t *fetch_init_new(void);
 
void fetch_init_free(fetch_init_t *init);
 
fetch_init_t *fetch_init_method(fetch_init_t *init, http_method_t method);
 
fetch_init_t *fetch_init_headers(fetch_init_t *init, fetch_headers_t *headers);
 
fetch_init_t *fetch_init_body(fetch_init_t *init, fetch_body_t *body);
 
fetch_init_t *fetch_init_timeout(fetch_init_t *init, uint32_t timeout_ms);
 
fetch_init_t *fetch_init_signal(fetch_init_t *init,
                                fetch_abort_controller_t *signal);
 
const char *fetch_method_to_string(http_method_t method);
 
http_method_t fetch_method_from_string(const char *method_str);
 
bool fetch_is_valid_url(const char *url);
 
const char *fetch_error_to_string(fetch_error_t error);
 
typedef struct fetch_config {
  const char *user_agent; 
  const char *origin;     
  cookie_jar_t
      *cookie_jar; 
  uint32_t default_timeout_ms;       
  uint32_t max_connections;          
  uint32_t max_connections_per_host; 
  uint32_t keep_alive_timeout_ms;    
  uint32_t pool_cleanup_interval_ms; 
  uint32_t max_pooled_connections;   
  uint32_t flags; 
} fetch_config_t;
 
static inline bool fetch_config_get_flag(uint32_t flags, fetch_flag_bit_t bit) {
  return FETCH_FLAG_GET(flags, bit) != 0;
}
 
static inline void fetch_config_set_flag(fetch_config_t *config,
                                         fetch_flag_bit_t flag, bool value) {
  if (!config)
    return;
 
  if (value) {
    config->flags = FETCH_FLAG_SET(config->flags, flag);
  } else {
    config->flags = FETCH_FLAG_CLEAR(config->flags, flag);
  }
}
 
static inline fetch_config_t fetch_config_default(void) {
  fetch_config_t config = {.user_agent = FETCH_USER_AGENT,
                           .origin = NULL,
                           .cookie_jar = NULL,
                           .default_timeout_ms = 30000,
                           .max_connections = 1000,
                           .max_connections_per_host = 6,
                           .keep_alive_timeout_ms = 115000,
                           .pool_cleanup_interval_ms = 30000,
                           .max_pooled_connections = 100,
                           .flags = (1U << FETCH_FLAG_KEEP_ALIVE_DEFAULT) |
                                    (1U << FETCH_FLAG_FOLLOW_REDIRECTS) |
                                    (1U << FETCH_FLAG_ENABLE_COMPRESSION) |
                                    (1U << FETCH_FLAG_ENABLE_COOKIES)};
  return config;
}
 
void fetch_global_init(const fetch_config_t *config);
 
void fetch_global_dispose(void);
 
cookie_jar_t *fetch_get_cookie_jar(void);
 
size_t fetch_cookie_jar_count(const char *domain_filter);
 
void fetch_cookie_jar_clear(void);
 
void fetch_disable_cookies(void);
 
cookie_jar_t *fetch_create_cookie_jar(const char *persistent_file);
 
void fetch_cookie_jar_free(cookie_jar_t *jar);
 
bool fetch_save_cookies(const char *filename, cookie_jar_t *jar);
 
bool fetch_load_cookies(const char *filename, cookie_jar_t *jar);
 
void fetch_cookie_jar_print(cookie_jar_t *jar, const char *domain_filter);
 
void fetch_promise_free(fetch_promise_t *promise);
 
#define FETCH_GET(url) fetch(url, NULL)
 
#define FETCH_ASYNC_GET(url) fetch_async(url, NULL)
 
#define FETCH_IS_OK(response)                                                  \
  ((response) != NULL && fetch_response_ok(response))
 
#define FETCH_PROMISE_IS_DONE(promise)                                         \
  ((promise) != NULL && fetch_promise_poll(promise))
 
#define FETCH_TIMEOUT_INFINITE 0    
#define FETCH_TIMEOUT_DEFAULT 30000 
#define FETCH_TIMEOUT_SHORT 5000    
#define FETCH_TIMEOUT_LONG 60000    
#endif /* FETCH_H */