WebKit2GTK+ Web Process Extensions

The multiprocess architecture of WebKit2 brought us a lot of advantages, but it also introduced important challenges, like how to expose some features that now live in the Web Process (DOM, JavaScript, etc.). The UI process API is fully asynchronous to make sure the UI is never blocked, but some APIs like the DOM bindings are synchronous by design. To expose those features that live in the Web Process, WebKit2GTK+ provides a Web Extensions mechanism. A Web Extension is like a plugin for the Web Process, that is loaded at start up, similar to a GTK module or gio extension, but that runs in the Web Process. WebKit2GTK+ exposes a simple low level API that at the moment provides access to three main features:

  • GObject DOM bindings: The exactly same API used in WebKit1 is available in WebKit2.
  • WebKitWebPage::send-request signal: It allows to change any request before it is sent to the server, or even simply prevent it from being sent.
  • Custom JavaScript injection: It provides a signal, equivalent to WebKitWebView::window-object-cleared in WebKit1, to inject custom JavaScript using the JavaScriptCore API. (Since 2.2)

This simple API doesn’t provide any way of communication with the UI Process, so that the user can use any IPC mechanism without interfering with the internal WebKit IPC traffic. Epiphany currently installs a Web Extension to implement some of its features such us pre-filled forms, ads blocker or Do Not Track using D-BUS for the communication between the Web Extension and the UI Process.

How to write a Web Extension?

Web Extensions are shared libraries loaded at run time by the Web Process, so they don’t have a main function, but they have an entry point called by the WebProcess right after the extension is loaded. The initialization function must be called webkit_web_extension_initialize() and it receives a WebKitWebExtension object as parameter. It should also be public, so make sure to use the G_MODULE_EXPORT macro. This is the function to initialize the Web Extension and can be used, for example, to be notified when a web page is created.

static void
web_page_created_callback (WebKitWebExtension *extension,
                           WebKitWebPage      *web_page,
                           gpointer            user_data)
    g_print ("Page %d created for %s\n", 
             webkit_web_page_get_id (web_page),
             webkit_web_page_get_uri (web_page));

webkit_web_extension_initialize (WebKitWebExtension *extension)
    g_signal_connect (extension, "page-created", 
                      G_CALLBACK (web_page_created_callback), 

This would be a minimal Web Extension, it does nothing yet, but it can be compiled and loaded so let’s see how to create a Makefile.am file to build the extension.

webextension_LTLIBRARIES = libmyappwebextension.la
webextensiondir = $(libdir)/MyApp/web-extension
libmyappwebextension_la_SOURCES = my-app-web-extension.c
libmyappwebextension_la_CFLAGS = $(WEB_EXTENSION_CFLAGS)
libmyappwebextension_la_LIBADD = $(WEB_EXTENSION_LIBS)
libmyappwebextension_la_LDFLAGS = -module -avoid-version -no-undefined

The extension will be installed in $(libdir)/MyApp/web-extension so we need to tell WebKit where to find web extensions before the Web Process is spawned. Call webkit_web_context_set_web_extensions_directory() as soon as possible in your application, before any other WebKit call to make sure it’s called before a Web Process is launched. You can create a preprocessor macro in the Makefile.am to pass the value of the Web Extensions directory.

myapp_CPPFLAGS = -DMYAPP_WEB_EXTENSIONS_DIR=\""$(libdir)/MyApp/web-extension"\"

And then in the code

webkit_web_context_set_web_extensions_directory (webkit_web_context_get_default (), 

The Web Extension only needs WebKit2GTK+ to build, so in the configure.ac you can define WEB_EXTENSION_CFLAGS and WEB_EXTENSION_LIBS using pkg-config macros.

PKG_CHECK_MODULES(WEB_EXTENSION, [webkit2gtk-3.0 >= 2.0.0])

This should be enough. You should be able to build and install the Web Extension with you program and see the printf message every time a page is created. But that’s a useless example, let’s see how to use the Web Extensions API to do something useful.

Accessing the DOM

The GObject DOM bindings API available in WebKit1 is also exposed in WebKit2 from the Web Extensions API. We only need to call webkit_web_page_get_dom_document() to get the WebKitDOMDocument of the given web page.

static void
web_page_created_callback (WebKitWebExtension *extension,
                           WebKitWebPage      *web_page,
                           gpointer            user_data)
    WebKitDOMDocument *document;
    gchar             *title;

    document = webkit_web_page_get_dom_document (web_page);
    title = webkit_dom_document_get_title (document);
    g_print ("Page %d created for %s with title %s\n", 
             webkit_web_page_get_id (web_page),
             webkit_web_page_get_uri (web_page),
    g_free (title);

Using WebKitWebPage::send-request signal

Using the Web Extensions API it’s possible to modify the request of any resource before it’s sent to the server, adding HTTP headers or modifying the URI. You can also make WebKit ignore a request, for example to block resources depending on the URI, by simply connecting to the signal and returning TRUE.

static gboolean
web_page_send_request (WebKitWebPage     *web_page,
                       WebKitURIRequest  *request,
                       WebKitURIResponse *redirected_response,
                       gpointer           user_data)
    const char *request_uri;
    const char *page_uri;

    request_uri = webkit_uri_request_get_uri (request);
    page_uri = webkit_web_page_get_uri (web_page);

    return uri_is_an_advertisement (request_uri, page_uri);

static void
web_page_created_callback (WebKitWebExtension *extension,
                           WebKitWebPage      *web_page,
                           gpointer            user_data)
    g_signal_connect_object (web_page, "send-request",
                             G_CALLBACK (web_page_send_request),
                             NULL, 0);

Extending JavaScript

Using the JavaScriptCore API it’s possible to inject custom JavaScript code by connecting to the window-object-cleared signal of the default WebKitScriptWorld. You can get the global JavaScript execution context by calling webkit_frame_get_javascript_context_for_script_world() for the WebKitFrame passed as parameter of the window-object-cleared signal.

static void 
window_object_cleared_callback (WebKitScriptWorld *world, 
                                WebKitWebPage     *web_page, 
                                WebKitFrame       *frame, 
                                gpointer           user_data)
    JSGlobalContextRef jsContext;
    JSObjectRef        globalObject;

    jsContext = webkit_frame_get_javascript_context_for_script_world (frame, world);
    globalObject = JSContextGetGlobalObject (jsContext);

    /* Use JSC API to add the JavaScript code you want */

webkit_web_extension_initialize (WebKitWebExtension *extension)
    g_signal_connect (webkit_script_world_get_default (), 
                      G_CALLBACK (window_object_cleared_callback), 

WebKitGTK+ 2.0.0

After more than two years of development the Igalia WebKit team is proud to announce WebKitGTK+ 2.0.0.

But what’s so special about WebKitGTK+ 2.0?

The WebKit2GTK+ API is now the default one. This means that it’s now considered stable from the API/ABI backwards compatibility point of view, and that the old WebKit1 API is in maintenance mode and kind of deprecated. We will maintain both APIs, but we don’t plan to work on WebKi1 other than fixing bugs.

We encourage everybody to port their existing WebKitGTK+ applications to WebKit2, although we know the WebKit2 GTK+ API is not ready for all applications yet. We will work on adding new API during next release cycle, so let us know if you are missing some API that prevents you from porting your project.

Epiphany, the GNOME Web browser, has been successfully ported to WebKit2 and uses it by default since GNOME 3.8.

What are the benefits of the WebKit2 GTK+ API?

We have talked several times about the advantages of the multi-process architecture of WebKit2, robustness, responsiveness, security, etc. All of the details of the multi-process separation are mostly transparent for the API users, bringing all those benefits for free to any application using WebKit2 GTK+. We have developed the API on top of this multi-process architecture, but also with the experience of several years developing and maintaining the WebKit1 GTK+ API, learning from the mistakes made in the past and keeping the good ideas. As a result, the WebKit2 API is very similar to the WebKi1 in some parts and quite different in others. We started from scratch with the following goals:

  • Simple and easy to use. Instead of porting the WebKit1 API to WebKit2, we decided to add new API on demand. We set some milestones based on porting real applications, adding new API required to port them. This also allowed us to design the API, not only thinking about what we want or need to expose, but also how the applications expect to use the API.
  • Consistency. We have tried hard to be consistent with the names of the functions, signals and properties exposed by the API.
  • Flexibility. When possible, the API allows to use your own implementation of some parts that can be adopted to different platforms. So, you can use your own file chooser, JavaScript dialogs, context menu, print dialog, etc.
  • It works by default. For all those features where a custom implementation can be used, there’s a default implementation in WebKit that just works by default.
  • Unit tests. We have enforced all new patches adding API to WebKit2 GTK+ to include also unit tests, so the whole API is covered by unit tests.

Let’s see the major changes and advantages of this new WebKi2 API.

WebKitWebView is a scrolling widget

For API users this means that WebKitWebView should not be added to a GtkScrolledWindow, the widget is scrollable by itself. Actually this is also the case of the WebKitWebView in WebKit1, but some hacks were introduced to allow the widget to be used inside a GtkScrolledWindow. This caused a lot of headaches due to the synchronization between the internal scrolling and the GTK+ scroll adjustments. So now the main scrollbars are also handled by the WebKitWebView which, among other things, fixed the problem of the double scrollbars in some web sites.

Double scrollbar issue

Embedded HTTP authentication dialog

The default implementation of the HTTP authentication embeds a dialog in the WebView instead of using a real GtkDialog. It’s also integrated with the keyring by default using libsecret.

HTTP authentication dialog

GTK+ 2 plugins (flash)

Plugins also run in a different process that is built with GTK+ 2 to support the most popular plugins like flash that still use GTK+ 2.

MiniBrowser showing a youtube video using flash plugin

Web Inspector

The Web Inspector works automatically in both docked and undocked states without requiring any API call.

Inspector docked

It also has support for remote inspecting.

Remote inspecting

Accelerated compositing

Accelerated compositing is always enabled in WebKit2.

Poster circle

Future plans

During the next release cycle we’ll work on fixing bugs and completing the API, see our RoadMap for further details, but we’ll also explore some other areas not directly related the the API:

  • Multiple web processes support
  • Sandboxing
  • Network Process

WebKitGTK+ Hackfest 2012

This year again the WebKitGTK+ hackfest took place at the Igalia office in A Coruña, and this year again it’s been awesome.

My main goal for the hackfest was to implement an extension system for the web process in WebKit2, that would allow, among other things, to access the DOM, which is the major regression of the WebKit2 GTK+ API. The idea was to use the exactly same GObject DOM bindings API we are currently using in WebKit1, so I moved it to a convenient static library and installed the public headers in its own directory making it shareable between WebKit1 and WebKit2. Once GObject DOM bindings were accessible from WebKit2 I wrote a first patch to implement the web extension system providing a new API for extensions to access the DOM.

I also took advantage of the hackfest time, to re-take a task I had pending for some time, adding an API to WebKit2 to handle SSL errors. I didn’t have time to finish the API, but managed to write a first patch to set a policy for SSL errors. For now it only allows to ignore SSL errors and continue the load or make the load fail in case of SSL errors. The idea is to add a new policy to ask the user what to do.

Even though it was not part of my initial plans for the hackfest I ended up working on the document reading integration in Epiphany. I wrote an initial patch for Epiphany to load documents supported by Evince embedded in the window like a web view. There are still a lot of features to integrate like zooming, searching, printing, etc.

Epiphany showing a PDF document

I set a milestone to switch Epiphany to WebKit2 by default at the end of the hackfest, but I didn’t have time to fix all the regressions. We are a lot closer, though.

This event is impossible without the sponsors, thanks!


SSL certificates information support in Epiphany

Since the Epiphany migration to WebKit, websites with an invalid SSL certificate were marked as untrusted with the unsecure lock icon in the location bar. However, it wasn’t possible to know what was wrong with the certificate nor the certificate details. Using the certificate viewer widget available in gcr, I’ve implemented a dialog to show information about the possible SSL errors and certificate details in Epiphany. This also means Epiphany now depends on gcr.

Epiphany showing an invalid certificate

Epiphany showing an invalid certificate

Epiphany and WebKit2

During the last week, the Igalia WebKit team has been working on adding the initial support for WebKit2 into Epiphany git master. As we did for Devhelp, there’s a configure option (–with-webkit2) that can be used to build Epiphany with WebKit2. The option is disabled by default for now. The WebKit2 GTK+ API is more and more mature and complete, but there are still some important features to implement in order to be able to enable WebKit2 by default in Epiphany. Nevertheless, the main functionality works already and we encourage everybody to give it a try and provide feedback and bug reports. You can also take a look at the Epiphany metabug or the WebKit2 GTK+ API roadmap if you want to help.

Epiphany with WebKit2 playing a random Flash video

Epiphany with WebKit2 playing a random Flash video

The plan is still to have a first stable version of WebKit2 GTK+ API for GNOME 3.6, but Epiphany will switch to WebKit2 by default when we manage to fix all the regressions, hopefully for GNOME 3.8.

GNOME 3.4: WebKit2 and kinetic scrolling

The web at your fingertips

The GNOME Project has released GNOME 3.4, the second major release of GNOME 3. A lot of new features, UI improvements and other enhancements are included in this release, as well as important changes in the development platform. You can see all the details in the release notes.

One of the applications that has received a major revamp is Epiphany, the GNOME Web Browser, not only because of the beautiful new interface, but it also has significant improvements in performance and stability. If Epiphany is not your default browser, give it a try when you upgrade to GNOME 3.4. See Xan‘s and Diego‘s blog posts for more details of the new Web Browser.


GNOME 3.4 includes WebKitGTK+ 1.8.0, the first stable release that contains an initial WebKit2 GTK+ API. It’s disabled by default, though, since it’s still a preliminary version, so you need to build with –enable-webkit2 configure option. It’s already possible to try it out with Devhelp 3.4 which can be optionally built with WebKit2 using –with-webkit2 configure option. If the current API is enough to port your application, give it a try and let us know, you can use the webkit2 devhelp branch as a reference. We’ll provide a migration guide soon too.

Kinetic scrolling

GTK+ 3.4 has finally support for kinetic scrolling in GtkScrolledWindow. I’m very happy to know that the work made by Igalia during the GTK+/Meego Handset integration project has helped Carlos Garnacho to properly integrate kinetic scrolling in GTK+.

What’s next?

During the next development cycle, the Igalia WebKit team will continue to focus on making Epiphany even more awesome, with more UI improvements, and of course porting it to WebKit2.

WebKitGTK+ 2.0 for GNOME 3.6?

That’s the plan! But, what’s exactly WebKitGTK+ 2.0? It will be the first stable release of WebKit2 GTK+ API, leaving the current WebKit GTK+ API in a maintenance mode. WebKit2 GTK+ is not just about multi-process architecture, robustness, stability and all other great things the new WebKit2 model brings, it’s also a redesign of the current WebKitGTK API to make it even more convenient and easier to use.

In the Igalia WebKit team,  we have planned a Roadmap of the tasks we will be actively working on to release WebKitGTK+ 2.0 for GNOME 3.6. Even though unit tests play a very important role in the WebKit2 GTK+ API development, we know that real applications using the API usually reveal issues that the unit tests or test programs like MiniBrowser don’t catch. For that reason, we have set milestones consisting of porting real applications to the new API.

  • GNOME 3.4: Applications using a small part of the API. We will focus on porting Devhelp.
  • GNOME 3.5: With the first unstable releases of the 3.5 cycle we should be able to port applications using the API more extensively. We will focus on porting Yelp.
  • GNOME 3.6: We should be able to port any application using WebKitGTK+ without major regressions. We will focus on porting Epiphany.

This is, of course, a plan, if we eventually don’t manage to achieve the milestones, we will release WebKitGTK+ 1.10 for GNOME 3.6 and current plan will be postponed to GNOME 3.8. Needless to say that any help would be more than welcome 🙂

Porting devhelp to WebKit2

When MiniBrowser was ported to the new WebKit2 GTK+ API, I said we had plans to create a webkit2 branch for epiphany. And we’ll do it as soon as we have enough API, but epiphany uses most of the WebKit API so this is going to take a bit. In the meantime, we have decided to focus on other applications that use a small part of the WebKit API like devhelp, yelp, liferea, etc. Yesterday I pushed a webkit2 branch into the devhelp git repository with some initial commits that allow to use devhelp with WebKit2. Even though WebKit2 is available in the latest WebKit unstable releases, there’s a bug and public headers are not installed, so you need to build WebKit from git to be able to build the devhelp webkit2 branch. The main functionality works, but there are still some features missing that we are currently working on:

  • Policy client: used by devhelp to decide what to do with unknown content and to open links in a new tab with middle click. Martin Robinson is working on Policy Client API for WebKit2, the patches are pretty good and will be pushed soon.
  • Search: We already agreed on the new API and Sergio Villar wrote the patch that will also land soon.
  • Printing: This is not only about adding API, it requires adding support for printing in the Web process too. The main problem is that we need to show the print dialog in the UI process and render pages for printing in the Web process, so we can’t use GtkPrintOperation. We have already patches to implement basic printing support and adding initial API. These patches only work for UNIX, so patches to make it work in win32 would be really appreciated.
  • Editing commands: There’s already a patch to add cut, copy and paste API, but we are discussing the possibility to move to a more generic approach for editing commands.

And here is the mandatory screenshot, although there’s nothing special since WebKit2 changes don’t affect the UI.

Devhelp using WebKit2

Devhelp using WebKit2

We will keep updating the webkit2 branch when new API lands in WebKit until there aren’t regressions. Then we’ll focus on yelp which requires two important challenges: DOM bindings and context menu API.

libgxps 0.2.0

More than a month ago I released libgxps 0.1.0, the first release of libgxps, but for several reasons I ended up not announcing it. I’ve just released a new version that includes a small API break and a lot of new features and improvements, see the release notes for further details. I’ll release evince 3.3.2 next week depending on this new libgxps version (when building with –enable-xps).