///|
/// Creates an extension host for a webview.
/// Most callers should prefer `extension_host(webview)` so the default cached
/// host is reused across helper layers.
pub fn ExtensionHost::new(webview : @webview.Webview) -> ExtensionHost {
make_extension_host(webview)
}
///|
/// Returns the default extension host attached to this webview.
/// The host is created lazily and cached with the default op runtime so later
/// extension installs share one consistent bridge.
pub fn extension_host(webview : @webview.Webview) -> ExtensionHost {
let runtime = op_runtime(webview)
match runtime.extension_host_cache() {
Some(host) => host
None => {
let host = make_extension_host(
webview,
default_runtime_cache=Some(runtime),
)
runtime.cache_extension_host(host)
host
}
}
}
///|
/// Installs an extension into the webview's default extension host.
/// This is the simplest way to expose one extension on a raw `@webview.Webview`
/// without manually managing host lifetime.
pub fn install_extension(
webview : @webview.Webview,
extension : Extension,
) -> Unit {
extension_host(webview).install(extension)
}
///|
/// Emits an extension-scoped event from the webview's default extension host.
/// The event is serialized once and forwarded to JavaScript listeners under the
/// extension's namespace and event name.
pub fn[Payload : ToJson] emit_extension(
webview : @webview.Webview,
extension_namespace : String,
event_name : String,
payload : Payload,
) -> Unit {
extension_host(webview).emit(extension_namespace, event_name, payload)
}
///|
/// Installs an extension into the host.
/// Reserved namespaces plus duplicate ids or namespaces are rejected before
/// JavaScript helpers, ops, and lifecycle hooks are registered.
pub fn ExtensionHost::install(
self : ExtensionHost,
extension : Extension,
) -> Unit {
guard extension.id.trim().to_owned() != "" else {
abort("ExtensionHost::install: extension id must not be empty")
}
guard extension.js_namespace.trim().to_owned() != "" else {
abort("ExtensionHost::install: extension namespace must not be empty")
}
guard !extension_namespace_is_reserved(extension.js_namespace) else {
abort(
"ExtensionHost::install: reserved extension namespace: " +
extension.js_namespace,
)
}
guard self.extension_ids.get(extension.id) is None else {
abort(
"ExtensionHost::install: extension already installed: " + extension.id,
)
}
guard self.extension_namespaces.get(extension.js_namespace) is None else {
abort(
"ExtensionHost::install: extension namespace already installed: " +
extension.js_namespace,
)
}
let context = ExtensionContext::{
host: self,
extension_id: extension.id,
extension_namespace: extension.js_namespace,
}
self.extension_ids.set(extension.id, extension.js_namespace)
self.extension_namespaces.set(extension.js_namespace, extension.id)
self.destroy_hooks.set(extension.id, fn() { (extension.on_destroy)(context) })
install_extension_namespace(self.webview, extension.js_namespace)
(extension.register)(context)
install_extension_scripts(self.webview, extension.scripts())
(extension.on_install)(context)
}
///|
/// Emits an extension-scoped event from the host to JavaScript.
/// The payload is converted to JSON and dispatched on the owning webview's main
/// event loop so JavaScript observers receive it safely.
pub fn[Payload : ToJson] ExtensionHost::emit(
self : ExtensionHost,
extension_namespace : String,
event_name : String,
payload : Payload,
) -> Unit {
match validate_extension_event_target(extension_namespace, event_name) {
Err(error) => abort(error)
Ok(_) => ()
}
guard self.extension_namespaces.get(extension_namespace) is Some(_) else {
abort(
"ExtensionHost::emit: extension namespace is not installed: " +
extension_namespace,
)
}
let payload_json = ToJson::to_json(payload).stringify()
let script = make_extension_emit_script(
extension_namespace, event_name, payload_json,
)
self.webview.dispatch(fn() { self.webview.eval(script) })
}
///|
/// Drops all registered extension metadata.
/// Registered destroy hooks run before caches are cleared so extensions can
/// release native resources in a predictable order.
pub fn ExtensionHost::destroy(self : ExtensionHost) -> Unit {
match self.default_runtime_cache {
Some(runtime) => runtime.clear_extension_host_cache()
None => ()
}
self.webview.unregister_destroy_hook(self.destroy_hook_name)
for _, hook in self.destroy_hooks {
hook()
}
self.extension_ids.clear()
self.extension_namespaces.clear()
self.apis.clear()
self.destroy_hooks.clear()
}
///|
/// Runs the underlying webview loop.
/// This is a convenience passthrough for code that already holds an
/// `ExtensionHost` rather than the raw webview.
pub fn ExtensionHost::run(self : ExtensionHost) -> Unit {
self.webview.run()
}
///|
/// Reserves an API name for one extension namespace and returns its fully
/// qualified op name.
fn ExtensionContext::register_api(
self : ExtensionContext,
api_name : String,
) -> String {
match validate_extension_api_name(self.extension_namespace, api_name) {
Err(error) => abort(error)
Ok(_) => ()
}
let registry_key = extension_api_registry_key(
self.extension_namespace,
api_name,
)
guard self.host.apis.get(registry_key) is None else {
abort(
"ExtensionContext::register_api: API already registered: " +
self.extension_namespace +
"." +
api_name,
)
}
self.host.apis.set(registry_key, true)
extension_op_name(self.extension_namespace, api_name)
}
///|
/// Creates a host wrapper and attaches its destroy hook to the owning webview.
fn make_extension_host(
webview : @webview.Webview,
default_runtime_cache? : OpRuntime? = None,
) -> ExtensionHost {
let destroy_hook_name = extension_host_destroy_hook_name()
let host = ExtensionHost::{
webview,
extension_ids: {},
extension_namespaces: {},
apis: {},
destroy_hooks: {},
destroy_hook_name,
default_runtime_cache,
}
let _ = op_runtime(webview)
webview.register_destroy_hook(destroy_hook_name, fn() { host.destroy() })
host
}
///|
/// Builds a unique registry key for one extension namespace and API pair.
fn extension_api_registry_key(
extension_namespace : String,
api_name : String,
) -> String {
extension_namespace + "\u0000" + api_name
}
///|
/// Converts an extension namespace/API pair into the runtime op binding name.
fn extension_op_name(extension_namespace : String, api_name : String) -> String {
"ext:" + extension_namespace + "/" + api_name
}
///|
fn validate_extension_api_name(
extension_namespace : String,
api_name : String,
) -> Result[Unit, String] {
guard api_name.trim().to_owned() != "" else {
return Err(
"ExtensionContext::register_api: API name must not be empty: " +
extension_namespace,
)
}
guard !extension_is_reserved_api_name(api_name) else {
return Err(
"ExtensionContext::register_api: reserved API name: " +
extension_namespace +
"." +
api_name,
)
}
Ok(())
}
///|
fn validate_extension_event_target(
extension_namespace : String,
event_name : String,
) -> Result[Unit, String] {
guard extension_namespace.trim().to_owned() != "" else {
return Err("extension event namespace must not be empty")
}
guard event_name.trim().to_owned() != "" else {
return Err("extension event name must not be empty: " + extension_namespace)
}
Ok(())
}
///|
/// Returns the destroy hook name used by the default extension host.
fn extension_host_destroy_hook_name() -> String {
"extension-host"
}
///|
/// Rejects JavaScript property names that would be unsafe to expose on `window.__MoonBit__`.
fn extension_is_disallowed_js_property_name(name : String) -> Bool {
name.has_prefix("@@") ||
name == "__proto__" ||
name == "prototype" ||
name == "constructor"
}
///|
/// Returns whether an extension namespace is reserved.
fn extension_namespace_is_reserved(extension_namespace : String) -> Bool {
extension_is_disallowed_js_property_name(extension_namespace)
}
///|
/// Returns whether an extension API name is reserved.
fn extension_is_reserved_api_name(api_name : String) -> Bool {
extension_is_disallowed_js_property_name(api_name)
}