@runanywhere/core 0.16.0

package/ios/Binaries/RACommons.xcframework/ios-arm64/RACommons.framework/Headers/rac_platform_adapter.h

@@ -0,0 +1,340 @@
+/**
+ * @file rac_platform_adapter.h
+ * @brief RunAnywhere Commons - Platform Adapter Interface
+ *
+ * Platform adapter provides callbacks for platform-specific operations.
+ * Swift/Kotlin SDK implements these callbacks and passes them during init.
+ *
+ * NOTE: HTTP networking is delegated to the platform layer (Swift/Kotlin).
+ * The C++ layer only handles orchestration logic.
+ */
+
+#ifndef RAC_PLATFORM_ADAPTER_H
+#define RAC_PLATFORM_ADAPTER_H
+
+#include <RACommons/rac_error.h>
+#include <RACommons/rac_types.h>
+#include <RACommons/rac_model_types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// CALLBACK TYPES (defined outside struct for C compatibility)
+// =============================================================================
+
+/**
+ * HTTP download progress callback type.
+ * @param bytes_downloaded Bytes downloaded so far
+ * @param total_bytes Total bytes to download (0 if unknown)
+ * @param callback_user_data Context passed to http_download
+ */
+typedef void (*rac_http_progress_callback_fn)(int64_t bytes_downloaded, int64_t total_bytes,
+                                              void* callback_user_data);
+
+/**
+ * HTTP download completion callback type.
+ * @param result RAC_SUCCESS or error code
+ * @param downloaded_path Path to downloaded file (NULL on failure)
+ * @param callback_user_data Context passed to http_download
+ */
+typedef void (*rac_http_complete_callback_fn)(rac_result_t result, const char* downloaded_path,
+                                              void* callback_user_data);
+
+/**
+ * Archive extraction progress callback type.
+ * @param files_extracted Number of files extracted so far
+ * @param total_files Total files to extract
+ * @param callback_user_data Context passed to extract_archive
+ */
+typedef void (*rac_extract_progress_callback_fn)(int32_t files_extracted, int32_t total_files,
+                                                 void* callback_user_data);
+
+// =============================================================================
+// PLATFORM ADAPTER STRUCTURE
+// =============================================================================
+
+/**
+ * Platform adapter structure.
+ *
+ * Implements platform-specific operations via callbacks.
+ * The SDK layer (Swift/Kotlin) provides these implementations.
+ */
+typedef struct rac_platform_adapter {
+    // -------------------------------------------------------------------------
+    // File System Operations
+    // -------------------------------------------------------------------------
+
+    /**
+     * Check if a file exists.
+     * @param path File path
+     * @param user_data Platform context
+     * @return RAC_TRUE if file exists, RAC_FALSE otherwise
+     */
+    rac_bool_t (*file_exists)(const char* path, void* user_data);
+
+    /**
+     * Read file contents.
+     * @param path File path
+     * @param out_data Output buffer (caller must free with rac_free)
+     * @param out_size Output file size
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*file_read)(const char* path, void** out_data, size_t* out_size, void* user_data);
+
+    /**
+     * Write file contents.
+     * @param path File path
+     * @param data Data to write
+     * @param size Data size
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*file_write)(const char* path, const void* data, size_t size, void* user_data);
+
+    /**
+     * Delete a file.
+     * @param path File path
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*file_delete)(const char* path, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Secure Storage (Keychain/KeyStore)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Get a value from secure storage.
+     * @param key Key name
+     * @param out_value Output value (caller must free with rac_free)
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, RAC_ERROR_FILE_NOT_FOUND if not found
+     */
+    rac_result_t (*secure_get)(const char* key, char** out_value, void* user_data);
+
+    /**
+     * Set a value in secure storage.
+     * @param key Key name
+     * @param value Value to store
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*secure_set)(const char* key, const char* value, void* user_data);
+
+    /**
+     * Delete a value from secure storage.
+     * @param key Key name
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*secure_delete)(const char* key, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Logging
+    // -------------------------------------------------------------------------
+
+    /**
+     * Log a message.
+     * @param level Log level
+     * @param category Log category (e.g., "ModuleRegistry")
+     * @param message Log message
+     * @param user_data Platform context
+     */
+    void (*log)(rac_log_level_t level, const char* category, const char* message, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Error Tracking (Optional - for Sentry/crash reporting)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Track a structured error for telemetry/crash reporting.
+     * Can be NULL - errors will still be logged but not sent to Sentry.
+     *
+     * Called for non-expected errors (i.e., not cancellations).
+     * The JSON string contains full error details including stack trace.
+     *
+     * @param error_json JSON representation of the structured error
+     * @param user_data Platform context
+     */
+    void (*track_error)(const char* error_json, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Clock
+    // -------------------------------------------------------------------------
+
+    /**
+     * Get current time in milliseconds since Unix epoch.
+     * @param user_data Platform context
+     * @return Current time in milliseconds
+     */
+    int64_t (*now_ms)(void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Memory Info
+    // -------------------------------------------------------------------------
+
+    /**
+     * Get memory information.
+     * @param out_info Output memory info structure
+     * @param user_data Platform context
+     * @return RAC_SUCCESS on success, error code on failure
+     */
+    rac_result_t (*get_memory_info)(rac_memory_info_t* out_info, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // HTTP Download (Optional - can be NULL)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Start an HTTP download.
+     * Can be NULL - download orchestration in C++ will call back to Swift/Kotlin.
+     *
+     * @param url URL to download from
+     * @param destination_path Where to save the downloaded file
+     * @param progress_callback Progress callback (can be NULL)
+     * @param complete_callback Completion callback
+     * @param callback_user_data User context for callbacks
+     * @param out_task_id Output: Task ID for cancellation (owned, must be freed)
+     * @param user_data Platform context
+     * @return RAC_SUCCESS if download started, error code otherwise
+     */
+    rac_result_t (*http_download)(const char* url, const char* destination_path,
+                                  rac_http_progress_callback_fn progress_callback,
+                                  rac_http_complete_callback_fn complete_callback,
+                                  void* callback_user_data, char** out_task_id, void* user_data);
+
+    /**
+     * Cancel an HTTP download.
+     * Can be NULL.
+     *
+     * @param task_id Task ID returned from http_download
+     * @param user_data Platform context
+     * @return RAC_SUCCESS if cancelled, error code otherwise
+     */
+    rac_result_t (*http_download_cancel)(const char* task_id, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // Archive Extraction (Optional - can be NULL)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Extract an archive (ZIP or TAR).
+     * Can be NULL - extraction will be handled by Swift/Kotlin.
+     *
+     * @param archive_path Path to the archive
+     * @param destination_dir Where to extract files
+     * @param progress_callback Progress callback (can be NULL)
+     * @param callback_user_data User context for callback
+     * @param user_data Platform context
+     * @return RAC_SUCCESS if extracted, error code otherwise
+     */
+    rac_result_t (*extract_archive)(const char* archive_path, const char* destination_dir,
+                                    rac_extract_progress_callback_fn progress_callback,
+                                    void* callback_user_data, void* user_data);
+
+    // -------------------------------------------------------------------------
+    // User Data
+    // -------------------------------------------------------------------------
+
+    /** Platform-specific context passed to all callbacks */
+    void* user_data;
+
+} rac_platform_adapter_t;
+
+// =============================================================================
+// PLATFORM ADAPTER API
+// =============================================================================
+
+/**
+ * Sets the platform adapter.
+ *
+ * Called during rac_init() - the adapter pointer must remain valid
+ * until rac_shutdown() is called.
+ *
+ * @param adapter Platform adapter (must not be NULL)
+ * @return RAC_SUCCESS on success, error code on failure
+ */
+RAC_API rac_result_t rac_set_platform_adapter(const rac_platform_adapter_t* adapter);
+
+/**
+ * Gets the current platform adapter.
+ *
+ * @return The current adapter, or NULL if not set
+ */
+RAC_API const rac_platform_adapter_t* rac_get_platform_adapter(void);
+
+// =============================================================================
+// CONVENIENCE FUNCTIONS (use platform adapter internally)
+// =============================================================================
+
+/**
+ * Log a message using the platform adapter.
+ * @param level Log level
+ * @param category Category string
+ * @param message Message string
+ */
+RAC_API void rac_log(rac_log_level_t level, const char* category, const char* message);
+
+/**
+ * Get current time in milliseconds.
+ * @return Current time in milliseconds since epoch
+ */
+RAC_API int64_t rac_get_current_time_ms(void);
+
+/**
+ * Start an HTTP download using the platform adapter.
+ * Returns RAC_ERROR_NOT_SUPPORTED if http_download callback is NULL.
+ *
+ * @param url URL to download
+ * @param destination_path Where to save
+ * @param progress_callback Progress callback (can be NULL)
+ * @param complete_callback Completion callback
+ * @param callback_user_data User data for callbacks
+ * @param out_task_id Output: Task ID (owned, must be freed)
+ * @return RAC_SUCCESS if started, error code otherwise
+ */
+RAC_API rac_result_t rac_http_download(const char* url, const char* destination_path,
+                                       rac_http_progress_callback_fn progress_callback,
+                                       rac_http_complete_callback_fn complete_callback,
+                                       void* callback_user_data, char** out_task_id);
+
+/**
+ * Cancel an HTTP download.
+ * Returns RAC_ERROR_NOT_SUPPORTED if http_download_cancel callback is NULL.
+ *
+ * @param task_id Task ID to cancel
+ * @return RAC_SUCCESS if cancelled, error code otherwise
+ */
+RAC_API rac_result_t rac_http_download_cancel(const char* task_id);
+
+/**
+ * Extract an archive using the platform adapter.
+ * Returns RAC_ERROR_NOT_SUPPORTED if extract_archive callback is NULL.
+ *
+ * @param archive_path Path to archive
+ * @param destination_dir Where to extract
+ * @param progress_callback Progress callback (can be NULL)
+ * @param callback_user_data User data for callback
+ * @return RAC_SUCCESS if extracted, error code otherwise
+ */
+RAC_API rac_result_t rac_extract_archive(const char* archive_path, const char* destination_dir,
+                                         rac_extract_progress_callback_fn progress_callback,
+                                         void* callback_user_data);
+
+/**
+ * Check if a model framework is a platform service (Swift-native).
+ * Platform services are handled via service registry callbacks, not C++ backends.
+ *
+ * @param framework Framework to check
+ * @return RAC_TRUE if platform service, RAC_FALSE if C++ backend
+ */
+RAC_API rac_bool_t rac_framework_is_platform_service(rac_inference_framework_t framework);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* RAC_PLATFORM_ADAPTER_H */

package/ios/Binaries/RACommons.xcframework/ios-arm64/RACommons.framework/Headers/rac_sdk_state.h

@@ -0,0 +1,292 @@
+/**
+ * @file rac_sdk_state.h
+ * @brief Centralized SDK state management (C++ equivalent of ServiceContainer)
+ *
+ * This is the single source of truth for all SDK runtime state.
+ * Platform SDKs (Swift, Kotlin, Flutter) should query state from here
+ * rather than maintaining their own copies.
+ *
+ * Pattern mirrors Swift's ServiceContainer:
+ * - Singleton access via rac_state_get_instance()
+ * - Lazy initialization for sub-components
+ * - Thread-safe access via internal mutex
+ * - Reset capability for testing
+ *
+ * State Categories:
+ * 1. Auth State     - Tokens, user/org IDs, authentication status
+ * 2. Device State   - Device ID, registration status
+ * 3. Environment    - SDK environment, API key, base URL
+ * 4. Services       - Telemetry manager, model registry handles
+ */
+
+#ifndef RAC_SDK_STATE_H
+#define RAC_SDK_STATE_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include <RACommons/rac_types.h>                          // For rac_result_t, RAC_SUCCESS
+#include <RACommons/rac_environment.h>  // For rac_environment_t
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// =============================================================================
+// State Structure (Opaque - internal structure hidden from C API)
+// =============================================================================
+
+/**
+ * @brief Opaque handle to SDK state
+ *
+ * The internal structure is hidden to allow C++ implementation
+ * while exposing a clean C API for platform interop.
+ */
+typedef struct rac_sdk_state* rac_sdk_state_handle_t;
+
+// =============================================================================
+// Auth Data Input Structure (Public - for platform to populate)
+// =============================================================================
+
+/**
+ * @brief Authentication data input
+ *
+ * Platforms use this to set auth state after successful HTTP authentication.
+ * C++ copies the data internally and manages lifetime.
+ *
+ * Note: This is distinct from rac_auth_state_t in rac_auth_manager.h which
+ * is the internal state structure.
+ */
+typedef struct {
+    const char* access_token;
+    const char* refresh_token;
+    int64_t expires_at_unix;  // Unix timestamp (seconds)
+    const char* user_id;      // Nullable
+    const char* organization_id;
+    const char* device_id;
+} rac_auth_data_t;
+
+// =============================================================================
+// Singleton Access
+// =============================================================================
+
+/**
+ * @brief Get the singleton SDK state instance
+ *
+ * Creates the instance on first call (lazy initialization).
+ * Thread-safe.
+ *
+ * @return Handle to the SDK state (never NULL after first call)
+ */
+rac_sdk_state_handle_t rac_state_get_instance(void);
+
+// =============================================================================
+// Initialization & Lifecycle
+// =============================================================================
+
+/**
+ * @brief Initialize SDK state with configuration
+ *
+ * Called during SDK initialization. Sets up environment and base config.
+ *
+ * @param env The SDK environment (development, staging, production)
+ * @param api_key The API key (copied internally)
+ * @param base_url The base URL (copied internally)
+ * @param device_id The persistent device ID (copied internally)
+ * @return RAC_SUCCESS on success
+ */
+rac_result_t rac_state_initialize(rac_environment_t env, const char* api_key, const char* base_url,
+                                  const char* device_id);
+
+/**
+ * @brief Check if SDK state is initialized
+ * @return true if initialized
+ */
+bool rac_state_is_initialized(void);
+
+/**
+ * @brief Reset all state (for testing or re-initialization)
+ *
+ * Clears all state including auth tokens, handles, etc.
+ * Does NOT free the singleton - just resets to initial state.
+ */
+void rac_state_reset(void);
+
+/**
+ * @brief Shutdown and free all resources
+ *
+ * Called during SDK shutdown. Frees all memory and destroys handles.
+ */
+void rac_state_shutdown(void);
+
+// =============================================================================
+// Environment Queries
+// =============================================================================
+
+/**
+ * @brief Get current environment
+ * @return The SDK environment
+ */
+rac_environment_t rac_state_get_environment(void);
+
+/**
+ * @brief Get base URL
+ * @return The base URL string (do not free)
+ */
+const char* rac_state_get_base_url(void);
+
+/**
+ * @brief Get API key
+ * @return The API key string (do not free)
+ */
+const char* rac_state_get_api_key(void);
+
+/**
+ * @brief Get device ID
+ * @return The device ID string (do not free)
+ */
+const char* rac_state_get_device_id(void);
+
+// =============================================================================
+// Auth State Management
+// =============================================================================
+
+/**
+ * @brief Set authentication state after successful auth
+ *
+ * Called by platform after HTTP auth response is received.
+ * Copies all strings internally.
+ *
+ * @param auth The auth data to set
+ * @return RAC_SUCCESS on success
+ */
+rac_result_t rac_state_set_auth(const rac_auth_data_t* auth);
+
+/**
+ * @brief Get current access token
+ * @return Access token string or NULL if not authenticated (do not free)
+ */
+const char* rac_state_get_access_token(void);
+
+/**
+ * @brief Get current refresh token
+ * @return Refresh token string or NULL (do not free)
+ */
+const char* rac_state_get_refresh_token(void);
+
+/**
+ * @brief Check if currently authenticated
+ * @return true if authenticated with valid (non-expired) token
+ */
+bool rac_state_is_authenticated(void);
+
+/**
+ * @brief Check if token needs refresh
+ *
+ * Returns true if token expires within the next 60 seconds.
+ *
+ * @return true if refresh is needed
+ */
+bool rac_state_token_needs_refresh(void);
+
+/**
+ * @brief Get token expiry timestamp
+ * @return Unix timestamp (seconds) when token expires, or 0 if not set
+ */
+int64_t rac_state_get_token_expires_at(void);
+
+/**
+ * @brief Get user ID
+ * @return User ID string or NULL (do not free)
+ */
+const char* rac_state_get_user_id(void);
+
+/**
+ * @brief Get organization ID
+ * @return Organization ID string or NULL (do not free)
+ */
+const char* rac_state_get_organization_id(void);
+
+/**
+ * @brief Clear authentication state
+ *
+ * Called on logout or auth failure. Clears tokens but not device/env config.
+ */
+void rac_state_clear_auth(void);
+
+// =============================================================================
+// Device State Management
+// =============================================================================
+
+/**
+ * @brief Set device registration status
+ * @param registered Whether device is registered with backend
+ */
+void rac_state_set_device_registered(bool registered);
+
+/**
+ * @brief Check if device is registered
+ * @return true if device has been registered
+ */
+bool rac_state_is_device_registered(void);
+
+// =============================================================================
+// State Change Callbacks (for platform observers)
+// =============================================================================
+
+/**
+ * @brief Callback type for auth state changes
+ * @param is_authenticated Current auth status
+ * @param user_data User-provided context
+ */
+typedef void (*rac_auth_changed_callback_t)(bool is_authenticated, void* user_data);
+
+/**
+ * @brief Register callback for auth state changes
+ *
+ * Called whenever auth state changes (login, logout, token refresh).
+ *
+ * @param callback The callback function (NULL to unregister)
+ * @param user_data Context passed to callback
+ */
+void rac_state_on_auth_changed(rac_auth_changed_callback_t callback, void* user_data);
+
+// =============================================================================
+// Persistence Bridge (Platform implements secure storage)
+// =============================================================================
+
+/**
+ * @brief Callback type for persisting state to secure storage
+ * @param key The key to store under
+ * @param value The value to store (NULL to delete)
+ * @param user_data User-provided context
+ */
+typedef void (*rac_persist_callback_t)(const char* key, const char* value, void* user_data);
+
+/**
+ * @brief Callback type for loading state from secure storage
+ * @param key The key to load
+ * @param user_data User-provided context
+ * @return The stored value or NULL (caller must NOT free)
+ */
+typedef const char* (*rac_load_callback_t)(const char* key, void* user_data);
+
+/**
+ * @brief Register callbacks for secure storage
+ *
+ * Platform implements these to persist to Keychain/KeyStore.
+ * C++ calls persist_callback when state changes.
+ * C++ calls load_callback during initialization.
+ *
+ * @param persist Callback to persist a value
+ * @param load Callback to load a value
+ * @param user_data Context passed to callbacks
+ */
+void rac_state_set_persistence_callbacks(rac_persist_callback_t persist, rac_load_callback_t load,
+                                         void* user_data);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // RAC_SDK_STATE_H