cogcore

Safe Rust wrappers for the core Cog/WPE browser API used by Consortium's HMI subsystem.

This crate sits above cogcore-sys. The -sys crate owns raw bindgen output for Cog, GLib/GObject, WPE, and WebKit. This crate provides the small safe layer callers should normally use: object handles, GObject refcounting, Rust string conversion, GError conversion, and a focused browser shell/view API.

Scope

The current wrapper covers the core Cog flow:

• init() for Cog initialization.
• Platform for the global platform and platform setup.
• Shell for shell construction, request handler registration, and shell metadata.
• View and Viewport for view creation, visibility, fullscreen, and viewport membership.
• DirectoryFilesHandler, HostRoutesHandler, and PrefixRoutesHandler for request routing.
• Utility helpers for Cog URI and application ID conversion.

WebKit and WPE types remain opaque in this crate. When integration code needs to cross into WebKit/WPE directly, use the raw pointer escape hatches such as View::as_webkit_ptr() and Platform::view_backend_ptr().

Example

use cogcore::{
    DirectoryFilesHandler, Platform, Shell, View, Viewport, init,
};

fn main() -> cogcore::Result<()> {
    init(None, None)?;

    let shell = Shell::new("consortium-hmi", false)?;
    let platform = Platform::get()?;
    platform.setup(&shell, None)?;

    let viewport = Viewport::new()?;
    let view = View::new()?;
    viewport.add(&view);
    viewport.set_visible_view(&view);
    view.set_visible();

    let files = gio::File::for_path("/opt/consortium/hmi");
    let handler = DirectoryFilesHandler::new(&files)?;
    shell.set_request_handler("app", handler.as_request_handler())?;

    Ok(())
}

Safety Model

Safe wrapper types own one GObject reference and release it on drop. Cloning a wrapper takes another GObject reference. Borrowed pointers returned by Cog are promoted to owned wrapper handles only when the wrapper can safely call g_object_ref.

Returned GError values are copied into GlibError and freed immediately. Returned transfer-full strings are copied into String and released with g_free. Public APIs accept Rust strings and reject interior NUL bytes before calling C.

Platform Notes

Cog/WPE development is Linux-oriented. On macOS, prefer formatting and static review for this crate; do not assume cargo check -p cogcore or cargo test -p cogcore can run without Cog, GLib/GIO, WPE, and WebKit development packages.

Use .github/workflows/cogcore.yml or a Linux machine with the Cog/WebKit stack installed for binding generation and wrapper validation.

Useful validation commands on a suitable Linux host:

cargo check -p cogcore
cargo test -p cogcore
cargo clippy -p cogcore --all-targets