flutter/shorebird-updater
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: split C API into Dart and engine surfaces (#350)

Browse Source 
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`).
This commit is contained in:
Eric Seidel
2026-05-04 15:56:09 -07:00
committed by GitHub
parent 10aaca0f8b
commit 34509fca3c
20 changed files with 1407 additions and 1018 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
@@ -41,7 +41,7 @@ Design principle: "fail open" — always fall back to the currently installed ve
## Key Details
- C header (`include/updater.h`) is auto-generated by `cbindgen` via `build.rs` — don't edit manually.
- C headers (`include/updater_dart.h` for the ffigen-consumed Dart-stable surface, `include/updater_engine.h` for the engine-internal surface) are auto-generated by `cbindgen` via `build.rs` — don't edit manually. The two configs live at `library/cbindgen_dart.toml` and `library/cbindgen_engine.toml`.
- Dart FFI bindings (`updater_bindings.g.dart`) are generated by `ffigen` — don't edit manually.
- Library builds as three crate types: `lib` (Rust tests), `cdylib` (Dart FFI testing), `staticlib` (engine linking).
- Boot state machine docs: `docs/boot_state_machine.md`.
library/build.rs
+40 -8
View File
@@ -1,25 +1,57 @@
extern crate cbindgen;
use std::env;
use std::path::{Path, PathBuf};
// See:
// <https://github.com/eqrion/cbindgen/blob/master/docs.md#buildrs>
// <https://doc.rust-lang.org/cargo/reference/build-scripts.html>
// <https://doc.rust-lang.org/cargo/reference/build-script-examples.html>
fn main() {
let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
let crate_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
// Should this write to the out dir (target) instead?
let result = cbindgen::generate(crate_dir);
// Each header is generated from a single source file. cbindgen scans
// exactly that file and emits the `pub extern "C"` items it defines plus
// the C types they reference. Since each bucket file is self-contained
// (defines its own types), there is no cross-bucket leak and no need for
// exclusion lists in the cbindgen configs.
generate_header(
&crate_dir,
"cbindgen_dart.toml",
"src/c_api/dart.rs",
"include/updater_dart.h",
);
generate_header(
&crate_dir,
"cbindgen_engine.toml",
"src/c_api/engine.rs",
"include/updater_engine.h",
);
}
fn generate_header(crate_dir: &Path, config_name: &str, src_relative: &str, output_path: &str) {
let config_path = crate_dir.join(config_name);
let config = match cbindgen::Config::from_file(&config_path) {
Ok(config) => config,
Err(e) => {
println!("cargo:warning=Error loading {}: {e}", config_path.display());
return;
}
};
let src_path = crate_dir.join(src_relative);
let result = cbindgen::Builder::new()
.with_src(&src_path)
.with_config(config)
.generate();
match result {
Ok(contents) => {
contents.write_to_file("include/updater.h");
contents.write_to_file(output_path);
}
Err(e) => {
println!("cargo:warning=Error generating bindings: {e}");
// If we were to exit 1 here we would stop local rust
// analysis from working. So we just print the error
// and continue.
println!("cargo:warning=Error generating {output_path}: {e}");
// We don't exit non-zero here so local rust-analyzer keeps
// working when cbindgen has an issue.
}
}
}
library/cbindgen.toml
-20
View File
@@ -1,20 +0,0 @@
# See https://github.com/eqrion/cbindgen/blob/master/docs.md#cbindgentoml
# for detailed documentation of every option here.
language = "C"
include_guard = "updater_h"
autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
cpp_compat = true
line_length = 80
# I don't know if these are required to export the shorebird_ symbols
# since I've hit multiple levels of export trouble in libflutter.so.
# But I'm leaving them here for now.
after_includes = """
#ifdef _WIN32
#define SHOREBIRD_EXPORT __declspec(dllexport)
#else
#define SHOREBIRD_EXPORT __attribute__((visibility("default")))
#endif
"""
[fn]
prefix = "SHOREBIRD_EXPORT"
library/cbindgen_dart.toml
+30
View File
@@ -0,0 +1,30 @@
# cbindgen configuration for the Dart-stable C surface.
#
# Output: include/updater_dart.h — consumed by ffigen in
# shorebird_code_push. Anything reachable from this header is part of the
# package's public ABI; do not break changes here without bumping the
# package version.
#
# build.rs runs cbindgen with `with_src("src/c_api/dart.rs")`, so cbindgen
# scans exactly that one file and emits the `pub extern "C"` items it
# defines plus the types they reference. Items defined in
# `src/c_api/engine.rs` cannot leak into this header. No exclude/include
# lists needed.
#
# See https://github.com/eqrion/cbindgen/blob/master/docs.md#cbindgentoml
language = "C"
include_guard = "updater_dart_h"
autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
cpp_compat = true
line_length = 80
after_includes = """
#ifdef _WIN32
#define SHOREBIRD_EXPORT __declspec(dllexport)
#else
#define SHOREBIRD_EXPORT __attribute__((visibility("default")))
#endif
"""
[fn]
prefix = "SHOREBIRD_EXPORT"
library/cbindgen_engine.toml
+30
View File
@@ -0,0 +1,30 @@
# cbindgen configuration for the engine-internal C surface.
#
# Output: include/updater_engine.h — consumed only by Shorebird's Flutter
# engine fork. No stability guarantee; both sides ship together as part of
# the engine, so this surface changes freely as the engine integration
# evolves.
#
# build.rs runs cbindgen with `with_src("src/c_api/engine.rs")`, so cbindgen
# scans exactly that one file and emits the `pub extern "C"` items it
# defines plus the types they reference. Items defined in
# `src/c_api/dart.rs` cannot leak into this header. No exclude/include
# lists needed.
#
# See https://github.com/eqrion/cbindgen/blob/master/docs.md#cbindgentoml
language = "C"
include_guard = "updater_engine_h"
autogen_warning = "/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */"
cpp_compat = true
line_length = 80
after_includes = """
#ifdef _WIN32
#define SHOREBIRD_EXPORT __declspec(dllexport)
#else
#define SHOREBIRD_EXPORT __attribute__((visibility("default")))
#endif
"""
[fn]
prefix = "SHOREBIRD_EXPORT"
library/include/updater.h
-248
View File
@@ -1,248 +0,0 @@
#ifndef updater_h
#define updater_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
/**
* An unknown error occurred while updating. The update was not installed.
* This is a catch-all for errors that don't fit into the other categories.
*/
#define SHOREBIRD_UPDATE_ERROR -1
/**
* No update is available (e.g. the app is already up-to-date)
*/
#define SHOREBIRD_NO_UPDATE 0
/**
* An update was installed successfully. It will boot from the update on the
* next app launch.
*/
#define SHOREBIRD_UPDATE_INSTALLED 1
/**
* An error occurred while updating. The update was not installed.
*/
#define SHOREBIRD_UPDATE_HAD_ERROR 2
/**
* The downloaded patch was not installed because it was invalid.
*/
#define SHOREBIRD_UPDATE_IS_BAD_PATCH 3
/**
* Another update was already in progress when this call was made. The
* already-running update will continue; the caller did not start a new one.
* This is a benign outcome, not an error.
*/
#define SHOREBIRD_UPDATE_IN_PROGRESS 4
/**
* Struct containing configuration parameters for the updater.
* Passed to all updater functions.
* 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;
typedef struct UpdateResult {
int32_t status;
const char *message;
} UpdateResult;
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* Configures 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);
/**
* The currently running patch number, or 0 if the release has not been
* patched. The internal name for this concept is `running_patch`; the
* FFI symbol keeps the historical `current_boot_patch_number` spelling
* because Flutter Engine links against it.
*/
SHOREBIRD_EXPORT uintptr_t shorebird_current_boot_patch_number(void);
/**
* The patch number that will boot on the next run of the app, or 0 if there is
* no next patch.
*/
SHOREBIRD_EXPORT uintptr_t shorebird_next_boot_patch_number(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.
*/
SHOREBIRD_EXPORT char *shorebird_next_boot_patch_path(void);
/**
* 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);
/**
* Frees an `UpdateResult` previously returned by `shorebird_check_for_update`.
*
* # Safety
*
* `result` must be a valid pointer returned by `shorebird_check_for_update`,
* or null (in which case this is a no-op).
*/
SHOREBIRD_EXPORT void shorebird_free_update_result(struct UpdateResult *result);
/**
* Check for an update. Returns true if an update is available.
*/
SHOREBIRD_EXPORT bool shorebird_check_for_update(void);
/**
* Check for an update on the first non-null channel of:
* 1. `c_channel`
* 2. The channel specified in shorebird.yaml
* 3. The default "stable" channel
*
* Returns true if an update exists that has not yet been downloaded.
*/
SHOREBIRD_EXPORT
bool shorebird_check_for_downloadable_update(const char *c_channel);
/**
* Synchronously download an update if one is available.
*/
SHOREBIRD_EXPORT void shorebird_update(void);
/**
* Synchronously download an update on the first non-null channel of:
* 1. `c_channel`
* 2. The channel specified in shorebird.yaml
* 3. The default "stable" channel
*
* Returns an [UpdateResult] indicating whether the update was successful.
*/
SHOREBIRD_EXPORT
const struct UpdateResult *shorebird_update_with_result(const char *c_channel);
/**
* 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. This will mark the current
* as having been launched successfully. We don't currently do anything
* with this information, but it could be used to record a point at which
* we will not roll back from.
*
* This is not currently wired up to be called from the Engine. It's unclear
* where best to connect it. Expo waits 5 seconds after the app launches
* and then marks the launch as successful. We could do something similar.
*/
SHOREBIRD_EXPORT void shorebird_report_launch_success(void);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif /* updater_h */
library/include/updater_dart.h
+113
View File
@@ -0,0 +1,113 @@
#ifndef updater_dart_h
#define updater_dart_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
/**
* An unknown error occurred while updating. The update was not installed.
* This is a catch-all for errors that don't fit into the other categories.
*/
#define SHOREBIRD_UPDATE_ERROR -1
/**
* No update is available (e.g. the app is already up-to-date)
*/
#define SHOREBIRD_NO_UPDATE 0
/**
* An update was installed successfully. It will boot from the update on the
* next app launch.
*/
#define SHOREBIRD_UPDATE_INSTALLED 1
/**
* An error occurred while updating. The update was not installed.
*/
#define SHOREBIRD_UPDATE_HAD_ERROR 2
/**
* The downloaded patch was not installed because it was invalid.
*/
#define SHOREBIRD_UPDATE_IS_BAD_PATCH 3
/**
* Another update was already in progress when this call was made. The
* already-running update will continue; the caller did not start a new one.
* This is a benign outcome, not an error.
*/
#define SHOREBIRD_UPDATE_IN_PROGRESS 4
typedef struct UpdateResult {
int32_t status;
const char *message;
} UpdateResult;
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* The currently running patch number, or 0 if the release has not been
* patched. The internal name for this concept is `running_patch`; the
* FFI symbol keeps the historical `current_boot_patch_number` spelling
* because the Flutter Engine and existing pub releases of
* `shorebird_code_push` link against it.
*/
SHOREBIRD_EXPORT uintptr_t shorebird_current_boot_patch_number(void);
/**
* The patch number that will boot on the next run of the app, or 0 if there is
* no next patch.
*/
SHOREBIRD_EXPORT uintptr_t shorebird_next_boot_patch_number(void);
/**
* Check for an update on the first non-null channel of:
* 1. `c_channel`
* 2. The channel specified in shorebird.yaml
* 3. The default "stable" channel
*
* Returns true if an update exists that has not yet been downloaded.
*/
SHOREBIRD_EXPORT
bool shorebird_check_for_downloadable_update(const char *c_channel);
/**
* Synchronously download an update on the first non-null channel of:
* 1. `c_channel`
* 2. The channel specified in shorebird.yaml
* 3. The default "stable" channel
*
* Returns an [UpdateResult] indicating whether the update was successful.
*/
SHOREBIRD_EXPORT
const struct UpdateResult *shorebird_update_with_result(const char *c_channel);
/**
* Frees an `UpdateResult` previously returned by
* `shorebird_update_with_result`. Frees the embedded `message` string and
* the result allocation itself.
*
* # Safety
*
* `result` must be a valid pointer returned by `shorebird_update_with_result`,
* or null (in which case this is a no-op).
*/
SHOREBIRD_EXPORT void shorebird_free_update_result(struct UpdateResult *result);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif /* updater_dart_h */
library/include/updater_engine.h
+151
View File
@@ -0,0 +1,151 @@
#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 */
library/src/c_api/c_file.rs
+1 -1
View File
@@ -2,7 +2,7 @@ use std::io::{Read, Seek};
use crate::{ExternalFileProvider, ReadSeek};
use super::FileCallbacks;
use super::engine::FileCallbacks;
struct CFile {
file_callbacks: FileCallbacks,
library/src/c_api/dart.rs
+138
View File
@@ -0,0 +1,138 @@
//! Dart-stable C API surface.
//!
//! These symbols are consumed by `package:shorebird_code_push` via FFI. The
//! header generated for this module (`include/updater_dart.h`) is the input
//! to ffigen, so anything declared here is part of the package's public ABI.
//! Do not break changes here without bumping the package version.
//!
//! cbindgen reads this file directly (see `build.rs`) and emits exactly the
//! `pub extern "C"` items found here plus the types they reference. Adding
//! a function to this file automatically adds it to the Dart header — no
//! cbindgen-config update required. Conversely, anything declared in
//! `c_api::engine` cannot leak into this header.
//!
//! For symbols consumed only by Shorebird's Flutter engine, see
//! `c_api::engine` — that surface is unstable and changes freely.
use std::os::raw::c_char;
use super::{allocate_c_string, free_c_string, log_on_error, to_rust_option};
use crate::{updater, UpdateStatus};
/// An unknown error occurred while updating. The update was not installed.
/// This is a catch-all for errors that don't fit into the other categories.
pub const SHOREBIRD_UPDATE_ERROR: i32 = -1;
/// No update is available (e.g. the app is already up-to-date)
pub const SHOREBIRD_NO_UPDATE: i32 = 0;
/// An update was installed successfully. It will boot from the update on the
/// next app launch.
pub const SHOREBIRD_UPDATE_INSTALLED: i32 = 1;
/// An error occurred while updating. The update was not installed.
pub const SHOREBIRD_UPDATE_HAD_ERROR: i32 = 2;
/// The downloaded patch was not installed because it was invalid.
pub const SHOREBIRD_UPDATE_IS_BAD_PATCH: i32 = 3;
/// Another update was already in progress when this call was made. The
/// already-running update will continue; the caller did not start a new one.
/// This is a benign outcome, not an error.
pub const SHOREBIRD_UPDATE_IN_PROGRESS: i32 = 4;
#[repr(C)]
pub struct UpdateResult {
pub status: i32,
pub message: *const libc::c_char,
}
fn to_update_result(status: anyhow::Result<UpdateStatus>) -> UpdateResult {
match status {
Ok(status) => {
let message = status.to_string();
UpdateResult {
status: status as i32,
message: allocate_c_string(message.as_str()).unwrap_or(std::ptr::null_mut()),
}
}
Err(err) => UpdateResult {
status: SHOREBIRD_UPDATE_ERROR,
message: allocate_c_string(&err.to_string()).unwrap_or(std::ptr::null_mut()),
},
}
}
/// The currently running patch number, or 0 if the release has not been
/// patched. The internal name for this concept is `running_patch`; the
/// FFI symbol keeps the historical `current_boot_patch_number` spelling
/// because the Flutter Engine and existing pub releases of
/// `shorebird_code_push` link against it.
#[no_mangle]
pub extern "C" fn shorebird_current_boot_patch_number() -> usize {
log_on_error(
|| Ok(updater::running_patch()?.map_or(0, |p| p.number)),
"fetching running_patch_number",
0,
)
}
/// The patch number that will boot on the next run of the app, or 0 if there is
/// no next patch.
#[no_mangle]
pub extern "C" fn shorebird_next_boot_patch_number() -> usize {
log_on_error(
|| Ok(updater::next_boot_patch()?.map_or(0, |p| p.number)),
"fetching next_boot_patch_number",
0,
)
}
/// Check for an update on the first non-null channel of:
/// 1. `c_channel`
/// 2. The channel specified in shorebird.yaml
/// 3. The default "stable" channel
///
/// Returns true if an update exists that has not yet been downloaded.
#[no_mangle]
pub extern "C" fn shorebird_check_for_downloadable_update(c_channel: *const c_char) -> bool {
log_on_error(
|| {
let channel = to_rust_option(c_channel)?;
updater::check_for_downloadable_update(channel.as_deref())
},
"checking for update",
false,
)
}
/// Synchronously download an update on the first non-null channel of:
/// 1. `c_channel`
/// 2. The channel specified in shorebird.yaml
/// 3. The default "stable" channel
///
/// Returns an [UpdateResult] indicating whether the update was successful.
#[no_mangle]
pub extern "C" fn shorebird_update_with_result(c_channel: *const c_char) -> *const UpdateResult {
let result = match to_rust_option(c_channel) {
Ok(channel) => to_update_result(updater::update(channel.as_deref())),
Err(err) => to_update_result(Err(err)),
};
Box::into_raw(Box::new(result))
}
/// Frees an `UpdateResult` previously returned by
/// `shorebird_update_with_result`. Frees the embedded `message` string and
/// the result allocation itself.
///
/// # Safety
///
/// `result` must be a valid pointer returned by `shorebird_update_with_result`,
/// or null (in which case this is a no-op).
#[no_mangle]
pub unsafe extern "C" fn shorebird_free_update_result(result: *mut UpdateResult) {
if result.is_null() {
return;
}
let result = unsafe { Box::from_raw(result) };
unsafe { free_c_string(result.message) };
}
library/src/c_api/engine.rs
+220
View File
@@ -0,0 +1,220 @@
//! Engine-internal C API surface.
//!
//! These symbols are consumed by Shorebird's Flutter engine
//! (`flutter::shorebird::Updater` in `shell/common/shorebird/updater.cc`) and
//! by no other public consumer. Both sides ship together as part of the
//! engine, so this surface has no stability guarantee — change freely as the
//! engine integration evolves.
//!
//! cbindgen reads this file directly (see `build.rs`) and emits exactly the
//! `pub extern "C"` items found here plus the types they reference. Adding
//! a function to this file automatically adds it to the engine header — no
//! cbindgen-config update required. Conversely, anything declared in
//! `c_api::dart` cannot leak into this header.
//!
//! For the stable Dart surface consumed by `package:shorebird_code_push`,
//! see `c_api::dart`.
use std::os::raw::c_char;
use std::path::PathBuf;
use super::{allocate_c_string, free_c_string, log_on_error, to_rust};
use crate::c_api::c_file::CFileProvider;
use crate::updater;
/// Struct containing configuration parameters for the updater.
/// Passed to `shorebird_init`.
/// NOTE: If this struct is changed all language bindings must be updated.
#[repr(C)]
pub 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.
pub release_version: *const libc::c_char,
/// 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.
pub original_libapp_paths: *const *const libc::c_char,
/// Length of the original_libapp_paths array.
pub original_libapp_paths_size: libc::c_int,
/// Path to app storage directory where the updater will store serialized
/// state and other data that persists between releases.
pub app_storage_dir: *const libc::c_char,
/// Path to cache directory where the updater will store downloaded
/// artifacts and data that can be deleted when a new release is detected.
pub code_cache_dir: *const libc::c_char,
}
#[derive(Clone, Copy, Debug)]
#[repr(C)]
pub struct FileCallbacks {
/// Opens the "file" (actually an in-memory buffer) and returns a handle.
pub open: extern "C" fn() -> *mut libc::c_void,
/// Reads count bytes from the file into buffer. Returns the number of
/// bytes read.
pub read: extern "C" fn(file_handle: *mut libc::c_void, buffer: *mut u8, count: usize) -> usize,
/// 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.
pub seek: extern "C" fn(file_handle: *mut libc::c_void, offset: i64, whence: i32) -> i64,
/// Closes and frees the file handle.
pub close: extern "C" fn(file_handle: *mut libc::c_void),
}
fn to_rust_vector(
c_array: *const *const libc::c_char,
size: libc::c_int,
) -> anyhow::Result<Vec<String>> {
let mut result = Vec::new();
for i in 0..size {
let c_string = unsafe { *c_array.offset(i as isize) };
result.push(to_rust(c_string)?);
}
Ok(result)
}
fn app_config_from_c(c_params: *const AppParameters) -> anyhow::Result<updater::AppConfig> {
anyhow::ensure!(
!c_params.is_null(),
"Null parameters passed to app_config_from_c"
);
let c_params_ref = unsafe { &*c_params };
Ok(updater::AppConfig {
app_storage_dir: to_rust(c_params_ref.app_storage_dir)?,
code_cache_dir: to_rust(c_params_ref.code_cache_dir)?,
release_version: to_rust(c_params_ref.release_version)?,
original_libapp_paths: to_rust_vector(
c_params_ref.original_libapp_paths,
c_params_ref.original_libapp_paths_size,
)?,
})
}
fn path_to_c_string(path: Option<PathBuf>) -> anyhow::Result<*mut c_char> {
Ok(match path {
Some(v) => allocate_c_string(v.to_str().unwrap())?,
None => std::ptr::null_mut(),
})
}
/// 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.
#[no_mangle]
pub unsafe extern "C" fn shorebird_free_string(c_string: *const c_char) {
unsafe { free_c_string(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.
#[no_mangle]
pub extern "C" fn shorebird_init(
c_params: *const AppParameters,
c_file_callbacks: FileCallbacks,
c_yaml: *const libc::c_char,
) -> bool {
log_on_error(
|| {
let config = app_config_from_c(c_params)?;
let file_provider = Box::new(CFileProvider {
file_callbacks: c_file_callbacks,
});
let yaml_string = to_rust(c_yaml)?;
updater::init(config, file_provider, &yaml_string)?;
Ok(true)
},
"initializing updater",
false,
)
}
/// Returns if the app should run the updater automatically on launch.
#[no_mangle]
pub extern "C" fn shorebird_should_auto_update() -> bool {
log_on_error(
updater::should_auto_update,
"fetching update behavior",
true,
)
}
/// 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.
#[no_mangle]
pub extern "C" fn shorebird_validate_next_boot_patch() {
log_on_error(
updater::validate_next_boot_patch,
"validating next_boot_patch",
(),
);
}
/// 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`.
#[no_mangle]
pub extern "C" fn shorebird_next_boot_patch_path() -> *mut c_char {
log_on_error(
|| {
let maybe_path = updater::next_boot_patch()?.map(|p| p.path);
path_to_c_string(maybe_path)
},
"fetching next_boot_patch_path",
std::ptr::null_mut(),
)
}
/// Start a thread to download an update if one is available.
#[no_mangle]
pub extern "C" fn shorebird_start_update_thread() {
updater::start_update_thread();
}
/// 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`.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_start() {
log_on_error(updater::report_launch_start, "reporting launch start", ());
}
/// 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.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_failure() {
log_on_error(
updater::report_launch_failure,
"reporting launch failure",
(),
);
}
/// 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.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_success() {
log_on_error(
updater::report_launch_success,
"reporting launch success",
(),
);
}
library/src/c_api/mod.rs
+131 -376
View File
@@ -1,106 +1,41 @@
// This file handles translating the updater library's types into C types.
// Currently manually prefixing all functions with "shorebird_" to avoid
// name collisions with other libraries.
// `cbindgen:prefix-with-name` could do this for us.
/// This file contains the C API for the updater library.
/// It is intended to be used by language bindings, and is not intended to be
/// used directly by Rust code.
/// The C API is not stable and may change at any time.
/// You can see usage of this API in Shorebird's Flutter engine:
/// <https://github.com/shorebirdtech/engine/blob/shorebird/dev/shell/common/shorebird.cc>
// This module translates the updater library's types into C types.
//
// The C surface is split into two submodules, each fully self-contained:
// - `dart` — stable surface consumed by `package:shorebird_code_push`
// (header: `include/updater_dart.h`, driven by ffigen).
// - `engine` — surface consumed only by Shorebird's Flutter engine
// (header: `include/updater_engine.h`, no stability guarantee).
//
// Each submodule defines the `pub extern "C"` items it exports plus any C
// types those items reference. cbindgen scans the submodule files directly
// (see `build.rs`) — there is no cross-bucket exclusion list, and a new
// function added to one bucket cannot leak into the other bucket's header.
//
// Items in this file are private Rust helpers shared between the two
// buckets. They are not `extern "C"`, so cbindgen never emits them.
//
// Engine-side usage lives at `engine/src/flutter/shell/common/shorebird/updater.cc`
// in the Shorebird Flutter monorepo: <https://github.com/shorebirdtech/flutter>.
use std::ffi::{CStr, CString};
use std::os::raw::c_char;
use std::path::PathBuf;
use crate::{updater, UpdateStatus};
use self::c_file::CFileProvider;
mod c_file;
pub mod dart;
pub mod engine;
/// Struct containing configuration parameters for the updater.
/// Passed to all updater functions.
/// NOTE: If this struct is changed all language bindings must be updated.
#[repr(C)]
pub 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.
pub release_version: *const libc::c_char,
/// 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.
pub original_libapp_paths: *const *const libc::c_char,
/// Length of the original_libapp_paths array.
pub original_libapp_paths_size: libc::c_int,
/// Path to app storage directory where the updater will store serialized
/// state and other data that persists between releases.
pub app_storage_dir: *const libc::c_char,
/// Path to cache directory where the updater will store downloaded
/// artifacts and data that can be deleted when a new release is detected.
pub code_cache_dir: *const libc::c_char,
}
/// An unknown error occurred while updating. The update was not installed.
/// This is a catch-all for errors that don't fit into the other categories.
pub const SHOREBIRD_UPDATE_ERROR: i32 = -1;
/// No update is available (e.g. the app is already up-to-date)
pub const SHOREBIRD_NO_UPDATE: i32 = 0;
/// An update was installed successfully. It will boot from the update on the
/// next app launch.
pub const SHOREBIRD_UPDATE_INSTALLED: i32 = 1;
/// An error occurred while updating. The update was not installed.
pub const SHOREBIRD_UPDATE_HAD_ERROR: i32 = 2;
/// The downloaded patch was not installed because it was invalid.
pub const SHOREBIRD_UPDATE_IS_BAD_PATCH: i32 = 3;
/// Another update was already in progress when this call was made. The
/// already-running update will continue; the caller did not start a new one.
/// This is a benign outcome, not an error.
pub const SHOREBIRD_UPDATE_IN_PROGRESS: i32 = 4;
#[repr(C)]
pub struct UpdateResult {
pub status: i32,
pub message: *const libc::c_char,
}
#[derive(Clone, Copy, Debug)]
#[repr(C)]
pub struct FileCallbacks {
/// Opens the "file" (actually an in-memory buffer) and returns a handle.
pub open: extern "C" fn() -> *mut libc::c_void,
/// Reads count bytes from the file into buffer. Returns the number of
/// bytes read.
pub read: extern "C" fn(file_handle: *mut libc::c_void, buffer: *mut u8, count: usize) -> usize,
/// 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.
pub seek: extern "C" fn(file_handle: *mut libc::c_void, offset: i64, whence: i32) -> i64,
/// Closes and frees the file handle.
pub close: extern "C" fn(file_handle: *mut libc::c_void),
}
#[cfg(test)]
pub use self::dart::*;
#[cfg(test)]
pub use self::engine::*;
/// Converts a C string to a Rust string, does not free the C string.
fn to_rust(c_string: *const libc::c_char) -> anyhow::Result<String> {
pub(super) fn to_rust(c_string: *const libc::c_char) -> anyhow::Result<String> {
anyhow::ensure!(!c_string.is_null(), "Null string passed to to_rust");
let c_str = unsafe { CStr::from_ptr(c_string) };
Ok(c_str.to_str()?.to_string())
}
fn to_rust_option(c_string: *const c_char) -> anyhow::Result<Option<String>> {
pub(super) fn to_rust_option(c_string: *const c_char) -> anyhow::Result<Option<String>> {
if c_string.is_null() {
return Ok(None);
}
@@ -108,168 +43,21 @@ fn to_rust_option(c_string: *const c_char) -> anyhow::Result<Option<String>> {
}
/// Converts a Rust string to a C string, caller must free the C string.
fn allocate_c_string(rust_string: &str) -> anyhow::Result<*mut c_char> {
pub(super) fn allocate_c_string(rust_string: &str) -> anyhow::Result<*mut c_char> {
let c_str = CString::new(rust_string)?;
Ok(c_str.into_raw())
}
fn to_rust_vector(
c_array: *const *const libc::c_char,
size: libc::c_int,
) -> anyhow::Result<Vec<String>> {
let mut result = Vec::new();
for i in 0..size {
let c_string = unsafe { *c_array.offset(i as isize) };
result.push(to_rust(c_string)?);
}
Ok(result)
}
fn app_config_from_c(c_params: *const AppParameters) -> anyhow::Result<updater::AppConfig> {
anyhow::ensure!(
!c_params.is_null(),
"Null parameters passed to app_config_from_c"
);
let c_params_ref = unsafe { &*c_params };
Ok(updater::AppConfig {
app_storage_dir: to_rust(c_params_ref.app_storage_dir)?,
code_cache_dir: to_rust(c_params_ref.code_cache_dir)?,
release_version: to_rust(c_params_ref.release_version)?,
original_libapp_paths: to_rust_vector(
c_params_ref.original_libapp_paths,
c_params_ref.original_libapp_paths_size,
)?,
})
}
/// Helper function to log errors instead of panicking or returning a result.
fn log_on_error<F, R>(f: F, context: &str, error_result: R) -> R
where
F: FnOnce() -> Result<R, anyhow::Error>,
{
f().unwrap_or_else(|e| {
shorebird_error!("Error {}: {:?}", context, e);
error_result
})
}
/// Configures 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.
#[no_mangle]
pub extern "C" fn shorebird_init(
c_params: *const AppParameters,
c_file_callbacks: FileCallbacks,
c_yaml: *const libc::c_char,
) -> bool {
log_on_error(
|| {
let config = app_config_from_c(c_params)?;
let file_provider = Box::new(CFileProvider {
file_callbacks: c_file_callbacks,
});
let yaml_string = to_rust(c_yaml)?;
updater::init(config, file_provider, &yaml_string)?;
Ok(true)
},
"initializing updater",
false,
)
}
/// Returns if the app should run the updater automatically on launch.
#[no_mangle]
pub extern "C" fn shorebird_should_auto_update() -> bool {
log_on_error(
updater::should_auto_update,
"fetching update behavior",
true,
)
}
/// The currently running patch number, or 0 if the release has not been
/// patched. The internal name for this concept is `running_patch`; the
/// FFI symbol keeps the historical `current_boot_patch_number` spelling
/// because Flutter Engine links against it.
#[no_mangle]
pub extern "C" fn shorebird_current_boot_patch_number() -> usize {
log_on_error(
|| Ok(updater::running_patch()?.map_or(0, |p| p.number)),
"fetching running_patch_number",
0,
)
}
/// The patch number that will boot on the next run of the app, or 0 if there is
/// no next patch.
#[no_mangle]
pub extern "C" fn shorebird_next_boot_patch_number() -> usize {
log_on_error(
|| Ok(updater::next_boot_patch()?.map_or(0, |p| p.number)),
"fetching next_boot_patch_number",
0,
)
}
fn path_to_c_string(path: Option<PathBuf>) -> anyhow::Result<*mut c_char> {
Ok(match path {
Some(v) => allocate_c_string(v.to_str().unwrap())?,
None => std::ptr::null_mut(),
})
}
fn to_update_result(status: anyhow::Result<UpdateStatus>) -> UpdateResult {
let result = match status {
Ok(status) => {
let message = status.to_string();
return UpdateResult {
status: status as i32,
message: allocate_c_string(message.as_str()).unwrap_or(std::ptr::null_mut()),
};
}
Err(err) => UpdateResult {
status: SHOREBIRD_UPDATE_ERROR,
message: allocate_c_string(&err.to_string()).unwrap_or(std::ptr::null_mut()),
},
};
result
}
/// 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.
#[no_mangle]
pub extern "C" fn shorebird_validate_next_boot_patch() {
log_on_error(
updater::validate_next_boot_patch,
"validating next_boot_patch",
(),
);
}
/// The path to the patch that will boot on the next run of the app, or NULL if
/// there is no next patch.
#[no_mangle]
pub extern "C" fn shorebird_next_boot_patch_path() -> *mut c_char {
log_on_error(
|| {
let maybe_path = updater::next_boot_patch()?.map(|p| p.path);
path_to_c_string(maybe_path)
},
"fetching next_boot_patch_path",
std::ptr::null_mut(),
)
}
/// Free a string returned by the updater library.
/// Drops a C string previously allocated by `allocate_c_string`. No-op on
/// null. Callable by both buckets — `engine::shorebird_free_string` and
/// `dart::shorebird_free_update_result` both delegate here so the
/// CString-from-raw unsafe ownership logic lives in one place.
///
/// # Safety
///
/// If this function is called with a non-null pointer, it must be a pointer
/// returned by the updater library.
#[no_mangle]
pub unsafe extern "C" fn shorebird_free_string(c_string: *const c_char) {
/// `c_string` must be null or a pointer previously returned by
/// `allocate_c_string` and not yet freed.
pub(super) unsafe fn free_c_string(c_string: *const c_char) {
if c_string.is_null() {
return;
}
@@ -278,124 +66,15 @@ pub unsafe extern "C" fn shorebird_free_string(c_string: *const c_char) {
}
}
/// Frees an `UpdateResult` previously returned by `shorebird_check_for_update`.
///
/// # Safety
///
/// `result` must be a valid pointer returned by `shorebird_check_for_update`,
/// or null (in which case this is a no-op).
#[no_mangle]
pub unsafe extern "C" fn shorebird_free_update_result(result: *mut UpdateResult) {
if result.is_null() {
return;
}
let message = (*result).message;
if !message.is_null() {
shorebird_free_string(message);
}
unsafe {
drop(Box::from_raw(result));
}
}
/// Check for an update. Returns true if an update is available.
#[no_mangle]
pub extern "C" fn shorebird_check_for_update() -> bool {
log_on_error(
|| updater::check_for_downloadable_update(None),
"checking for update",
false,
)
}
/// Check for an update on the first non-null channel of:
/// 1. `c_channel`
/// 2. The channel specified in shorebird.yaml
/// 3. The default "stable" channel
///
/// Returns true if an update exists that has not yet been downloaded.
#[no_mangle]
pub extern "C" fn shorebird_check_for_downloadable_update(c_channel: *const c_char) -> bool {
log_on_error(
|| {
let channel = to_rust_option(c_channel)?;
updater::check_for_downloadable_update(channel.as_deref())
},
"checking for update",
false,
)
}
/// Synchronously download an update if one is available.
#[no_mangle]
pub extern "C" fn shorebird_update() {
log_on_error(
|| updater::update(None).map(|result| shorebird_info!("Update result: {}", result)),
"downloading update",
(),
);
}
/// Synchronously download an update on the first non-null channel of:
/// 1. `c_channel`
/// 2. The channel specified in shorebird.yaml
/// 3. The default "stable" channel
///
/// Returns an [UpdateResult] indicating whether the update was successful.
#[no_mangle]
pub extern "C" fn shorebird_update_with_result(c_channel: *const c_char) -> *const UpdateResult {
let channel = to_rust_option(c_channel);
let result = match channel {
Ok(channel) => to_update_result(updater::update(channel.as_deref())),
Err(err) => to_update_result(Err(err)),
};
Box::into_raw(Box::new(result))
}
/// Start a thread to download an update if one is available.
#[no_mangle]
pub extern "C" fn shorebird_start_update_thread() {
updater::start_update_thread();
}
/// 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`.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_start() {
log_on_error(updater::report_launch_start, "reporting launch start", ());
}
/// 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.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_failure() {
log_on_error(
updater::report_launch_failure,
"reporting launch failure",
(),
);
}
/// Report that the app launched successfully. This will mark the current
/// as having been launched successfully. We don't currently do anything
/// with this information, but it could be used to record a point at which
/// we will not roll back from.
///
/// This is not currently wired up to be called from the Engine. It's unclear
/// where best to connect it. Expo waits 5 seconds after the app launches
/// and then marks the launch as successful. We could do something similar.
#[no_mangle]
pub extern "C" fn shorebird_report_launch_success() {
log_on_error(
updater::report_launch_success,
"reporting launch success",
(),
);
/// Helper function to log errors instead of panicking or returning a result.
pub(super) fn log_on_error<F, R>(f: F, context: &str, error_result: R) -> R
where
F: FnOnce() -> Result<R, anyhow::Error>,
{
f().unwrap_or_else(|e| {
shorebird_error!("Error {}: {:?}", context, e);
error_result
})
}
#[cfg(test)]
@@ -407,6 +86,7 @@ mod test {
UNEXPECTED_REPORT,
},
test_utils::write_fake_apk,
updater,
};
use anyhow::Ok;
use serial_test::serial;
@@ -451,13 +131,13 @@ mod test {
// libapp_path is currently Android-style with a virtual path
// of at least 3 directories in depth ending in libapp.so.
fn parameters(tmp_dir: &TempDir, libapp_path: &str) -> super::AppParameters {
fn parameters(tmp_dir: &TempDir, libapp_path: &str) -> AppParameters {
let cache_dir = tmp_dir.path().to_str().unwrap().to_string();
let app_paths_vec = vec![libapp_path.to_owned()];
let app_paths_size = app_paths_vec.len() as i32;
let app_paths = c_array(app_paths_vec);
super::AppParameters {
AppParameters {
app_storage_dir: c_string(&cache_dir),
code_cache_dir: c_string(&cache_dir),
release_version: c_string("1.0.0"),
@@ -466,7 +146,7 @@ mod test {
}
}
fn free_parameters(params: super::AppParameters) {
fn free_parameters(params: AppParameters) {
free_c_string(params.app_storage_dir as *mut libc::c_char);
free_c_string(params.code_cache_dir as *mut libc::c_char);
free_c_string(params.release_version as *mut libc::c_char);
@@ -476,6 +156,18 @@ mod test {
)
}
/// Run `shorebird_update_with_result` with the given channel, assert the
/// status equals `expected`, then free the result. Replaces uses of the
/// retired `shorebird_update()` helper inside tests that don't otherwise
/// inspect the result.
fn run_update_expecting(channel: *const c_char, expected: i32) {
let result = shorebird_update_with_result(channel);
unsafe {
assert_eq!(result.read().status, expected);
shorebird_free_update_result(result as *mut UpdateResult);
}
}
/// A precomputed bidiff patch artifact along with the inputs that
/// produced it. Generate one with:
/// cargo run --bin string_patch -- "<base>" "<new>"
@@ -572,6 +264,68 @@ mod test {
));
}
/// Exercises the `to_rust_vector` failure path in
/// `app_config_from_c` (engine.rs). All scalar fields are valid, but
/// the libapp_paths array contains a null entry — `to_rust` rejects
/// null and the `?` propagates. Without this test the array-conversion
/// branch is never reached because `init_with_null_app_parameters`
/// fails earlier on the scalar fields.
#[serial]
#[test]
fn init_with_null_libapp_path_in_array() {
testing_reset_config();
let tmp_dir = TempDir::new().unwrap();
let cache_dir = tmp_dir.path().to_str().unwrap().to_string();
let null_path: *const libc::c_char = std::ptr::null();
let paths_array = [null_path];
let c_params = AppParameters {
app_storage_dir: c_string(&cache_dir),
code_cache_dir: c_string(&cache_dir),
release_version: c_string("1.0.0"),
original_libapp_paths: paths_array.as_ptr(),
original_libapp_paths_size: 1,
};
let c_yaml = c_string("app_id: foo");
assert!(!shorebird_init(&c_params, FileCallbacks::new(), c_yaml));
free_c_string(c_yaml);
free_c_string(c_params.app_storage_dir as *mut libc::c_char);
free_c_string(c_params.code_cache_dir as *mut libc::c_char);
free_c_string(c_params.release_version as *mut libc::c_char);
}
/// Exercises the `Err` arm of the channel decode in
/// `shorebird_update_with_result` (dart.rs). The channel pointer is
/// non-null (so `to_rust_option` doesn't short-circuit to `Ok(None)`),
/// but contains invalid UTF-8, so `CStr::to_str()` returns an error
/// that propagates into `to_update_result(Err(_))`.
#[serial]
#[test]
fn update_with_result_with_invalid_utf8_channel() {
testing_reset_config();
let tmp_dir = TempDir::new().unwrap();
let fake_libapp_path = tmp_dir.path().join("lib/arch/libapp.so");
let c_params = parameters(&tmp_dir, fake_libapp_path.to_str().unwrap());
let c_yaml = c_string("app_id: foo");
assert!(shorebird_init(&c_params, FileCallbacks::new(), c_yaml));
free_c_string(c_yaml);
free_parameters(c_params);
// 0xFF is an invalid UTF-8 start byte. CStr::from_ptr accepts it
// (C strings are null-terminated bytes, no encoding) but the
// to_str() conversion fails — which is the path we're covering.
let bad_bytes: [u8; 4] = [0xFF, 0xFE, 0xFD, 0];
let result = shorebird_update_with_result(bad_bytes.as_ptr() as *const c_char);
unsafe {
assert_eq!(result.read().status, SHOREBIRD_UPDATE_ERROR);
shorebird_free_update_result(result as *mut UpdateResult);
}
}
#[serial]
#[test]
fn init_with_bad_yaml() {
@@ -683,7 +437,7 @@ mod test {
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
// Go ahead and do the update.
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
assert_eq!(shorebird_current_boot_patch_number(), 0);
assert_eq!(shorebird_next_boot_patch_number(), 1);
@@ -931,7 +685,7 @@ mod test {
// There is an update available.
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
// Go ahead and do the update.
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
// Ensure we have not yet updated the current patch.
assert_eq!(shorebird_current_boot_patch_number(), 0);
@@ -992,7 +746,7 @@ mod test {
);
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
shorebird_report_launch_start();
shorebird_report_launch_success();
@@ -1076,7 +830,7 @@ mod test {
|_url, _event| Ok(()),
);
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
shorebird_report_launch_start();
shorebird_report_launch_success();
assert_eq!(shorebird_current_boot_patch_number(), 1);
@@ -1125,8 +879,9 @@ mod test {
/// Patch-to-patch rollback: device on patch 2, server rolls back to
/// patch 1 (sends rollback signal AND a downloadable replacement).
/// `check_for_downloadable_update` returns true (replacement available),
/// and after `update()` installs patch 1, the running session sees
/// `current=2, next=1` — the signal Dart needs for `restartRequired`.
/// and after `update_with_result` installs patch 1, the running session
/// sees `current=2, next=1` — the signal Dart needs for
/// `restartRequired`.
#[serial]
#[test]
fn rollback_patch_to_patch_reports_current_and_next_distinctly() {
@@ -1163,7 +918,7 @@ mod test {
|_url, _event| Ok(()),
);
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
shorebird_report_launch_start();
shorebird_report_launch_success();
assert_eq!(shorebird_current_boot_patch_number(), 2);
@@ -1187,7 +942,7 @@ mod test {
|_url, _event| Ok(()),
);
assert!(shorebird_check_for_downloadable_update(std::ptr::null()));
shorebird_update();
run_update_expecting(std::ptr::null(), SHOREBIRD_UPDATE_INSTALLED);
// Running process is still on patch 2; next boot will be patch 1.
assert_eq!(shorebird_current_boot_patch_number(), 2);
shorebird_code_push/CHANGELOG.md
+4
View File
@@ -1,3 +1,7 @@
# 2.0.7
- chore: internal cleanup; no public API changes.
# 2.0.6
- fix: `checkForUpdate` now reports `restartRequired` when the current patch
shorebird_code_push/CONTRIBUTING.md
+11 -6
View File
@@ -11,11 +11,16 @@ Flutter engine) via FFI.
For an Updater function to be visible to the Dart code, it must:
1. Be declared in c_api.rs as `pub extern "C"`.
1. This will add the function to the `library/include/updater.h` header
file, which is generated by [cbindgen](https://github.com/mozilla/cbindgen)
when the Updater is built.
1. Be declared in `library/src/c_api/dart.rs` as `pub extern "C"` (the
Dart-stable surface). Functions only meant for the Flutter engine go in
`library/src/c_api/engine.rs` instead and will not appear in the Dart
bindings.
1. The two buckets emit `library/include/updater_dart.h` and
`library/include/updater_engine.h` respectively, generated by
[cbindgen](https://github.com/mozilla/cbindgen) when the Updater is
built.
1. Be included in the generated ffi bindings. These can be regenerated using
`dart run ffigen`.
`dart run ffigen`. ffigen reads only `updater_dart.h`, so engine-only
symbols are not bound.
1. Android specific: be listed in
https://github.com/shorebirdtech/engine/blob/main/shell/platform/android/android_exports.lst
https://github.com/shorebirdtech/flutter/blob/shorebird/dev/engine/src/flutter/shell/platform/android/android_exports.lst
shorebird_code_push/lib/src/generated/updater_bindings.g.dart
+499 -268
View File
File diff suppressed because it is too large Load Diff
shorebird_code_push/lib/src/shorebird_updater_io.dart
+1 -25
View File
@@ -95,15 +95,7 @@ class ShorebirdUpdaterImpl implements ShorebirdUpdater {
Future<void> update({UpdateTrack? track}) async {
if (!_isAvailable) return;
Pointer<UpdateResult> result = nullptr;
try {
result = await _run(() => _updater.update(track: track));
// Explicitly catch all errors/exceptions to ensure we gracefully fallback.
// ignore: avoid_catches_without_on_clauses
} catch (_) {
return _legacyFallback();
}
final result = await _run(() => _updater.update(track: track));
const unknownErrorMessage = 'An unknown error occurred.';
@@ -138,22 +130,6 @@ class ShorebirdUpdaterImpl implements ShorebirdUpdater {
_updater.freeUpdateResult(result);
}
}
// Fallback to downloadUpdate if update is not available.
Future<void> _legacyFallback() async {
await _run(_updater.downloadUpdate);
final (current, next) = await (readCurrentPatch(), readNextPatch()).wait;
final status = next != null && current?.number != next.number
? UpdateStatus.restartRequired
: UpdateStatus.upToDate;
if (status == UpdateStatus.restartRequired) return;
throw const UpdateException(
message: '''
Downloading update failed but reason is unknown due to legacy updater.
Please upgrade the Shorebird Engine for improved error messages.''',
reason: UpdateFailureReason.unknown,
);
}
}
extension on int {
shorebird_code_push/lib/src/updater.dart
-5
View File
@@ -26,11 +26,6 @@ class Updater {
/// currentPatchNumber if no new patch is available.
int nextPatchNumber() => bindings.shorebird_next_boot_patch_number();
/// Downloads the latest patch, if available.
void downloadUpdate() => bindings.shorebird_update();
// New Methods added to support v2.0.0 of the Dart APIs //
/// Whether a new patch is available for download.
bool checkForDownloadableUpdate({UpdateTrack? track}) =>
bindings.shorebird_check_for_downloadable_update(
shorebird_code_push/pubspec.yaml
+6 -2
View File
@@ -1,6 +1,6 @@
name: shorebird_code_push
description: Check for and download Shorebird code push updates from your app.
version: 2.0.6
version: 2.0.7
homepage: https://shorebird.dev
repository: https://github.com/shorebirdtech/updater/tree/main/shorebird_code_push
@@ -22,7 +22,11 @@ ffigen:
output: "lib/src/generated/updater_bindings.g.dart"
name: "UpdaterBindings"
headers:
# Only the Dart-stable surface drives ffigen. Engine-only symbols live in
# ../library/include/updater_engine.h and must NOT be reachable from the
# generated bindings — the package's public ABI is exactly what this file
# exposes.
entry-points:
- "../library/include/updater.h"
- "../library/include/updater_dart.h"
preamble: |
// ignore_for_file: unused_element, unused_field
shorebird_code_push/test/src/shorebird_updater_io_test.dart
+26 -47
View File
@@ -354,7 +354,7 @@ void main() {
overridePrint((_) async {
shorebirdUpdater = ShorebirdUpdaterImpl(updater: updater, run: run);
await expectLater(shorebirdUpdater.update(), completes);
verifyNever(updater.downloadUpdate);
verifyNever(() => updater.update());
}),
);
});
@@ -387,6 +387,31 @@ void main() {
});
});
group('when the FFI call throws', () {
// Pre-2.0.7 the package wrapped this call in a try/catch and routed
// throws into a legacy fallback that called the now-removed
// shorebird_update symbol. The fallback was unreachable under the
// package's flutter: >=3.24.5 constraint, so it was deleted along
// with the symbol. The replacement contract: any unexpected throw
// from the FFI propagates to the caller, and freeUpdateResult is
// not invoked (we never received a pointer to free).
setUp(() {
when(() => updater.currentPatchNumber()).thenReturn(0);
when(() => updater.update()).thenThrow(Exception('boom'));
shorebirdUpdater = ShorebirdUpdaterImpl(updater: updater, run: run);
});
test('propagates the exception and does not call freeUpdateResult',
() async {
await expectLater(
shorebirdUpdater.update(),
throwsA(isA<Exception>()),
);
verify(() => updater.update()).called(1);
verifyNever(() => updater.freeUpdateResult(any()));
});
});
group('when no update is available', () {
setUp(() {
when(() => updater.currentPatchNumber()).thenReturn(0);
@@ -540,52 +565,6 @@ void main() {
});
});
group('when an outdated version of the engine is used', () {
setUp(() {
when(updater.currentPatchNumber).thenReturn(0);
when(updater.nextPatchNumber).thenReturn(1);
when(() => updater.update()).thenThrow(Exception('oops'));
shorebirdUpdater = ShorebirdUpdaterImpl(updater: updater, run: run);
});
test('falls back to downloadUpdate', () async {
await expectLater(shorebirdUpdater.update(), completes);
verify(updater.update).called(1);
verify(updater.downloadUpdate).called(1);
verifyNever(() => updater.freeUpdateResult(any()));
});
group('when update fails', () {
setUp(() {
when(updater.currentPatchNumber).thenReturn(0);
when(updater.nextPatchNumber).thenReturn(0);
shorebirdUpdater = ShorebirdUpdaterImpl(updater: updater, run: run);
});
test('throws if legacy update fails', () async {
await expectLater(
shorebirdUpdater.update,
throwsA(
isA<UpdateException>().having(
(e) => e.message,
'message',
'''
Downloading update failed but reason is unknown due to legacy updater.
Please upgrade the Shorebird Engine for improved error messages.''',
).having(
(e) => e.reason,
'reason',
UpdateFailureReason.unknown,
),
),
);
verify(updater.update).called(1);
verify(updater.downloadUpdate).called(1);
verifyNever(() => updater.freeUpdateResult(any()));
});
});
});
group('when an unsupported status code is returned', () {
setUp(() {
when(() => updater.currentPatchNumber()).thenReturn(0);
shorebird_code_push/test/src/updater_test.dart
+5 -11
View File
@@ -30,7 +30,7 @@ void main() {
});
group('currentPatchNumber', () {
test('forwards the result of shorebird_next_boot_patch_number', () {
test('forwards the result of shorebird_current_boot_patch_number', () {
when(
() => updaterBindings.shorebird_current_boot_patch_number(),
).thenReturn(123);
@@ -40,7 +40,8 @@ void main() {
});
group('checkForDownloadableUpdate', () {
test('forwards the result of shorebird_check_for_update', () {
test('forwards the result of shorebird_check_for_downloadable_update',
() {
when(
() => updaterBindings.shorebird_check_for_downloadable_update(
nullptr,
@@ -65,7 +66,8 @@ void main() {
).thenReturn(true);
});
test('forwards the result of shorebird_check_for_update', () {
test('forwards the result of shorebird_check_for_downloadable_update',
() {
expect(
updater.checkForDownloadableUpdate(track: UpdateTrack.beta),
isTrue,
@@ -101,14 +103,6 @@ void main() {
});
});
group('downloadUpdate', () {
test('calls bindings.shorebird_update', () {
when(() => updaterBindings.shorebird_update()).thenReturn(null);
updater.downloadUpdate();
verify(() => updaterBindings.shorebird_update()).called(1);
});
});
group('update', () {
test('calls bindings.shorebird_update_with_result', () {
when(