zerobus.h

/* Zerobus C FFI Interface */

#ifndef ZEROBUS_H
#define ZEROBUS_H

#pragma once

/* Generated with cbindgen:0.27.0 */

/* Warning: This file is autogenerated by cbindgen. Don't modify this manually. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

#ifdef __cplusplus
namespace zerobus {
#endif  // __cplusplus

/**
 * A single header key-value pair for C FFI
 */
typedef struct CHeader {
  char *key;
  char *value;
} CHeader;

/**
 * A collection of headers returned from Go callback
 */
typedef struct CHeaders {
  struct CHeader *headers;
  uintptr_t count;
  char *error_message;
} CHeaders;

typedef struct CZerobusSdk {
  uint8_t _private[0];
} CZerobusSdk;

typedef struct CResult {
  bool success;
  char *error_message;
  bool is_retryable;
} CResult;

typedef struct CZerobusStream {
  uint8_t _private[0];
} CZerobusStream;

typedef struct CStreamConfigurationOptions {
  uintptr_t max_inflight_requests;
  bool recovery;
  uint64_t recovery_timeout_ms;
  uint64_t recovery_backoff_ms;
  uint32_t recovery_retries;
  uint64_t server_lack_of_ack_timeout_ms;
  uint64_t flush_timeout_ms;
  int32_t record_type;
  uint64_t stream_paused_max_wait_time_ms;
  bool has_stream_paused_max_wait_time_ms;
  uint64_t callback_max_wait_time_ms;
  bool has_callback_max_wait_time_ms;
} CStreamConfigurationOptions;

/**
 * Function pointer type for the headers provider callback
 * The callback should return a CHeaders struct
 * The caller is responsible for freeing the returned CHeaders using zerobus_free_headers
 */
typedef struct CHeaders (*HeadersProviderCallback)(void *user_data);

/**
 * Represents a single record (either Proto or JSON)
 */
typedef struct CRecord {
  bool is_json;
  uint8_t *data;
  uintptr_t data_len;
} CRecord;

/**
 * Represents an array of records
 */
typedef struct CRecordArray {
  struct CRecord *records;
  uintptr_t len;
} CRecordArray;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Free headers returned from callback
 */
void zerobus_free_headers(struct CHeaders headers);

/**
 * Create a new ZerobusSdk instance
 * Returns NULL on error. Check the result parameter for error details.
 */
struct CZerobusSdk *zerobus_sdk_new(const char *zerobus_endpoint,
                                    const char *unity_catalog_url,
                                    struct CResult *result);

/**
 * Free the SDK instance
 */
void zerobus_sdk_free(struct CZerobusSdk *sdk);

/**
 * Set whether to use TLS for connections
 * This should be set to false when using HTTP endpoints (e.g., for testing)
 */
void zerobus_sdk_set_use_tls(struct CZerobusSdk *sdk, bool use_tls);

/**
 * Create a stream with OAuth authentication
 * descriptor_proto_bytes: protobuf-encoded DescriptorProto (can be NULL for JSON streams)
 */
struct CZerobusStream *zerobus_sdk_create_stream(struct CZerobusSdk *sdk,
                                                 const char *table_name,
                                                 const uint8_t *descriptor_proto_bytes,
                                                 uintptr_t descriptor_proto_len,
                                                 const char *client_id,
                                                 const char *client_secret,
                                                 const struct CStreamConfigurationOptions *options,
                                                 struct CResult *result);

/**
 * Create a stream with a custom headers provider callback
 * This allows you to provide custom authentication headers via a Go callback function
 */
struct CZerobusStream *zerobus_sdk_create_stream_with_headers_provider(struct CZerobusSdk *sdk,
                                                                       const char *table_name,
                                                                       const uint8_t *descriptor_proto_bytes,
                                                                       uintptr_t descriptor_proto_len,
                                                                       HeadersProviderCallback headers_callback,
                                                                       void *user_data,
                                                                       const struct CStreamConfigurationOptions *options,
                                                                       struct CResult *result);

/**
 * Free a stream instance
 */
void zerobus_stream_free(struct CZerobusStream *stream);

/**
 * Ingest a record (protobuf encoded)
 * Returns the offset directly
 * Returns -1 on error
 */
int64_t zerobus_stream_ingest_proto_record(struct CZerobusStream *stream,
                                           const uint8_t *data,
                                           uintptr_t data_len,
                                           struct CResult *result);

/**
 * Ingest a JSON record
 * Returns the offset directly
 * Returns -1 on error
 */
int64_t zerobus_stream_ingest_json_record(struct CZerobusStream *stream,
                                          const char *json_data,
                                          struct CResult *result);

/**
 * Ingest a batch of protobuf records
 * Returns the offset of the last record in the batch, or -1 on error
 * Returns -2 if batch is empty
 */
int64_t zerobus_stream_ingest_proto_records(struct CZerobusStream *stream,
                                            const uint8_t *const *records,
                                            const uintptr_t *record_lens,
                                            uintptr_t num_records,
                                            struct CResult *result);

/**
 * Ingest a batch of JSON records
 * Returns the offset of the last record in the batch, or -1 on error
 * Returns -2 if batch is empty
 */
int64_t zerobus_stream_ingest_json_records(struct CZerobusStream *stream,
                                           const char *const *json_records,
                                           uintptr_t num_records,
                                           struct CResult *result);

/**
 * Wait for a specific offset to be acknowledged by the server
 */
bool zerobus_stream_wait_for_offset(struct CZerobusStream *stream,
                                    int64_t offset,
                                    struct CResult *result);

/**
 * Flush all pending records
 */
bool zerobus_stream_flush(struct CZerobusStream *stream, struct CResult *result);

/**
 * Get unacknowledged records from a closed stream
 * Returns a CRecordArray that must be freed with zerobus_free_record_array
 */
struct CRecordArray zerobus_stream_get_unacked_records(struct CZerobusStream *stream,
                                                       struct CResult *result);

/**
 * Free a CRecordArray returned by zerobus_stream_get_unacked_records
 */
void zerobus_free_record_array(struct CRecordArray array);

/**
 * Close the stream gracefully
 */
bool zerobus_stream_close(struct CZerobusStream *stream, struct CResult *result);

/**
 * Free error message string
 */
void zerobus_free_error_message(char *message);

/**
 * Get default configuration options
 */
struct CStreamConfigurationOptions zerobus_get_default_config(void);

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

#ifdef __cplusplus
}  // namespace zerobus
#endif  // __cplusplus

#endif  /* ZEROBUS_H */