Eric Seidel
34509fca3c
The C surface in `library/src/c_api` was a single bucket of `pub extern "C"` functions covering both consumers — `package:shorebird_code_push` (via ffigen) and Shorebird's Flutter engine fork (via direct C++ link). That made it hard to reason about which symbols are stable ABI versus internal, and ffigen was generating bindings for engine-only symbols that no Dart code calls. Split into two self-contained submodules and two cbindgen-generated headers: - `c_api::dart` → `include/updater_dart.h` (stable ABI; ffigen entry point). Defines `UpdateResult`, the `SHOREBIRD_*` status constants, and the five Dart-stable functions: `shorebird_current_boot_patch_number`, `shorebird_next_boot_patch_number`, `shorebird_check_for_downloadable_update`, `shorebird_update_with_result`, `shorebird_free_update_result`. - `c_api::engine` → `include/updater_engine.h` (no stability guarantee). Defines `AppParameters`, `FileCallbacks`, and the engine-only functions: `shorebird_init`, `shorebird_should_auto_update`, `shorebird_validate_next_boot_patch`, `shorebird_next_boot_patch_path`, `shorebird_free_string`, `shorebird_start_update_thread`, and the `shorebird_report_launch_*` trio. Each bucket file is self-contained: cbindgen scans only the file (`with_src` in build.rs) and emits the items it defines plus the C types they reference. There are no exclude/include lists in the cbindgen configs — adding a function to one bucket automatically lands it in the right header, and items in the other bucket cannot leak. `mod.rs` shrinks to a thin layer of private helpers shared by both buckets (`to_rust`, `allocate_c_string`, `free_c_string`, `log_on_error`) plus the test module. `include/updater.h` is removed; consumers include the specific header for their use case. The Flutter engine's `shell/common/shorebird/updater.cc` will be updated in a follow-up engine-repo PR to include `updater_engine.h` directly. Also drops two retired Dart-side symbols: - `shorebird_update` (replaced by `shorebird_update_with_result` in the Dart 2.0 rewrite, Nov 2024). - `shorebird_check_for_update` (replaced by `shorebird_check_for_downloadable_update` in the same rewrite). The shorebird_code_push package's `_legacyFallback` was the only path that still called `shorebird_update`. The package's `flutter: >=3.24.5` constraint guarantees the engine has `shorebird_update_with_result`, so the fallback was unreachable in practice. Removing it lets us drop the ABI symbol. Bumps shorebird_code_push to 2.0.7. Bindings regenerated via ffigen now contain only the five Dart-stable symbols. Follow-up engine PR will: include `updater_engine.h` instead of the removed `updater.h`; clean up `android_exports.lst` (drop the ghost `shorebird_active_path` and `shorebird_active_patch_number` exports, drop `shorebird_check_for_update`).
152 lines
4.7 KiB
C
152 lines
4.7 KiB
C
#ifndef updater_engine_h
|
|
#define updater_engine_h
|
|
|
|
/* 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 _WIN32
|
|
#define SHOREBIRD_EXPORT __declspec(dllexport)
|
|
#else
|
|
#define SHOREBIRD_EXPORT __attribute__((visibility("default")))
|
|
#endif
|
|
|
|
|
|
/**
|
|
* Struct containing configuration parameters for the updater.
|
|
* Passed to `shorebird_init`.
|
|
* NOTE: If this struct is changed all language bindings must be updated.
|
|
*/
|
|
typedef struct AppParameters {
|
|
/**
|
|
* release_version, required. Named version of the app, off of which
|
|
* updates are based. Can be either a version number or a hash.
|
|
*/
|
|
const char *release_version;
|
|
/**
|
|
* Array of paths to the original aot library, required. For Flutter apps
|
|
* these are the paths to the bundled libapp.so. May be used for
|
|
* compression downloaded artifacts.
|
|
*/
|
|
const char *const *original_libapp_paths;
|
|
/**
|
|
* Length of the original_libapp_paths array.
|
|
*/
|
|
int original_libapp_paths_size;
|
|
/**
|
|
* Path to app storage directory where the updater will store serialized
|
|
* state and other data that persists between releases.
|
|
*/
|
|
const char *app_storage_dir;
|
|
/**
|
|
* Path to cache directory where the updater will store downloaded
|
|
* artifacts and data that can be deleted when a new release is detected.
|
|
*/
|
|
const char *code_cache_dir;
|
|
} AppParameters;
|
|
|
|
typedef struct FileCallbacks {
|
|
/**
|
|
* Opens the "file" (actually an in-memory buffer) and returns a handle.
|
|
*/
|
|
void *(*open)(void);
|
|
/**
|
|
* Reads count bytes from the file into buffer. Returns the number of
|
|
* bytes read.
|
|
*/
|
|
uintptr_t (*read)(void *file_handle, uint8_t *buffer, uintptr_t count);
|
|
/**
|
|
* Moves the file pointer to the given offset relative from whence (one of
|
|
* libc::SEEK_SET, libc::SEEK_CUR, or libc::SEEK_END). Returns the new
|
|
* offset relative to the start of the file.
|
|
*/
|
|
int64_t (*seek)(void *file_handle, int64_t offset, int32_t whence);
|
|
/**
|
|
* Closes and frees the file handle.
|
|
*/
|
|
void (*close)(void *file_handle);
|
|
} FileCallbacks;
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif // __cplusplus
|
|
|
|
/**
|
|
* Free a string returned by the updater library.
|
|
*
|
|
* # Safety
|
|
*
|
|
* If this function is called with a non-null pointer, it must be a pointer
|
|
* returned by the updater library.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_free_string(const char *c_string);
|
|
|
|
/**
|
|
* Configures the updater. First parameter is a struct containing
|
|
* configuration from the running app. Second parameter is a YAML string
|
|
* containing configuration compiled into the app. Returns true on success
|
|
* and false on failure. If false is returned, the updater library will not
|
|
* be usable.
|
|
*/
|
|
SHOREBIRD_EXPORT
|
|
bool shorebird_init(const struct AppParameters *c_params,
|
|
struct FileCallbacks c_file_callbacks,
|
|
const char *c_yaml);
|
|
|
|
/**
|
|
* Returns if the app should run the updater automatically on launch.
|
|
*/
|
|
SHOREBIRD_EXPORT bool shorebird_should_auto_update(void);
|
|
|
|
/**
|
|
* Performs integrity checks on the next boot patch. If the patch fails
|
|
* these checks, the patch will be deleted and the next boot patch will be
|
|
* set to the last successfully booted patch or the base release if there is
|
|
* no last successfully booted patch.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_validate_next_boot_patch(void);
|
|
|
|
/**
|
|
* The path to the patch that will boot on the next run of the app, or NULL
|
|
* if there is no next patch. The caller must free the returned string with
|
|
* `shorebird_free_string`.
|
|
*/
|
|
SHOREBIRD_EXPORT char *shorebird_next_boot_patch_path(void);
|
|
|
|
/**
|
|
* Start a thread to download an update if one is available.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_start_update_thread(void);
|
|
|
|
/**
|
|
* Tell the updater that we're launching from what it told us was the
|
|
* next patch to boot from. This will copy the next boot patch to be the
|
|
* `current_boot` patch.
|
|
*
|
|
* It is required to call this function before calling
|
|
* `shorebird_report_launch_success` or `shorebird_report_launch_failure`.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_report_launch_start(void);
|
|
|
|
/**
|
|
* Report that the app failed to launch. This will cause the updater to
|
|
* attempt to roll back to the previous version if this version has not been
|
|
* launched successfully before.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_report_launch_failure(void);
|
|
|
|
/**
|
|
* Report that the app launched successfully. The Shell constructor calls
|
|
* this once per process when the VM has finished booting; it pairs with
|
|
* `shorebird_report_launch_start` to mark a patch as having booted cleanly.
|
|
*/
|
|
SHOREBIRD_EXPORT void shorebird_report_launch_success(void);
|
|
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif // __cplusplus
|
|
|
|
#endif /* updater_engine_h */
|