WebView URL filtering #3442

t-arn · 2025-05-13T11:45:37Z

This PR aims to implement URL filtering for WebView on Windows and Android.
Possible use cases are:

preventing users from navigating off the site intended to be handled by your application's WebView
preventing users from navigating to known malicious web sites

PR Checklist:

All new features have been tested
All new features have been documented
I have read the CONTRIBUTING.md file
I will abide by the code of conduct

* implented on_navigation_started for android * extended the webview example

* applied black

freakboy3742

Thanks for the PR; I've flagged a few issues inline, and the test suite is obviously failing on most platforms (although it looks like the reason for the failure is something that won't be an issue once you've addressed one of the comments inline).

android/src/toga_android/widgets/webview.py

freakboy3742 · 2025-05-13T12:27:13Z

core/src/toga/widgets/webview.py

        url: str | None = None,
        content: str | None = None,
        user_agent: str | None = None,
+        on_navigation_starting=None,


This needs a type declaration (if only for documentation purposes)

OK, added type declaration

examples/webview/pyproject.toml

freakboy3742 · 2025-05-13T12:30:20Z

examples/webview/webview/app.py

+            allow = False
+            message = f"Navigation not allowed to: {url}"
+            dialog = toga.InfoDialog("on_navigation_starting()", message)
+            asyncio.create_task(self.dialog(dialog))


It might be easier to make on_navigation_starting an async callback, and then await the response.

The example app now has both, a synchronous and an async handler

freakboy3742 · 2025-05-13T12:32:40Z

android/src/toga_android/widgets/webview.py

+            event = TogaNavigationEvent(webresourcerequest)
+            allow = self.webview_impl.interface.on_navigation_starting(
+                webresourcerequest.getUrl().toString()
+            )


I haven't checked, but this could be a problem if on_navigation_starting is an async callback, because the returned value will be a future.

freakboy3742 · 2025-05-13T12:33:49Z

examples/webview/webview/app.py

            style=Pack(flex=1),
        )
+        # activate web navigation filtering on supported platforms
+        if getattr(self.webview._impl, "SUPPORTS_ON_NAVIGATION_STARTING", True):


Good instinct, but it's fine for the example to raise a warning if a feature isn't available.

winforms/src/toga_winforms/widgets/webview.py

freakboy3742 · 2025-05-13T12:35:01Z

winforms/src/toga_winforms/widgets/webview.py

+    def winforms_navigation_starting(self, sender, event):
+        # print(f"winforms_navigation_starting: {event.Uri}")
+        if self.interface.on_navigation_starting:
+            allow = self.interface.on_navigation_starting(event.Uri)


As with the Android version, this needs to handle a Future being returned.

I'm not quite sure, how to do this. Is there a similar case in the code base where I could get some inspiration?

t-arn · 2025-05-13T13:16:11Z

@freakboy3742 I wonder if it is possible to make the on_navigation_starting handler async when it is being called by a native event. Aren't those native events always synchronous?

freakboy3742 · 2025-05-13T13:19:36Z

@freakboy3742 I wonder if it is possible to make the on_navigation_starting handler async when it is being called by a native event. Aren't those native events always synchronous?

Yes, native event handlers are always synchronous - but Toga events must be able to be defined asynchronously. That's why they return a future; we need to make sure that if a future is returned, we wait for that future.

* added type declaration for handler * added WeakrefCallable wrapper

…_navigation_starting handlers

t-arn · 2025-06-11T17:21:34Z

@freakboy3742 I implemented support for synchronous and asynchronous on_navigation_starting handlers for Windows. The code still contains a lot of print statements for easier debugging. If you approve of this approach, I'll implement something similar for Android and clean up the code.

freakboy3742

I'm not sure I understand the approach you've taken here.

Firstly, I'm not sure why the cached "allowed" and "not allowed" URL lists is required. It seems to undermine the ability to make per-request based decisions on whether a navigation is required, which is the point of having a callback.

Secondly, the general approach of "if async, cancel the request, and force a URL load if the async result succeeds" makes sense, but the way it gets to the actual resolution seems... convoluted.

wrapped_handler takes a function or co-routine, and guarantees that it will be invoked on the event loop. It already has a an existing cleanup method that can be used to attach "on completion" logic. There's no need to have a whole standalone "attach completion callback to result" handler - it can be baked into the cleanup method when the handler is installed.

t-arn · 2025-06-12T19:00:25Z

@freakboy3742 The "allowed" and "not allowed" lists are meant to cache the user's decision whether to allow the URL or not. I think, the user will not want to be asked for the same URL again and again.

As for setting the callback method: I didn't realize that wrapped_handler already has the "on completion" functionality. I'll rewrite the code and use the cleanup method.

t-arn · 2025-06-12T22:18:10Z

We could make it configurable whether the user's decisions should be saved, for example by setting WebView.save_user_url_permissions=True before setting the on_navigation_starting handler. What do you think? Should the default be True or False?

freakboy3742 · 2025-06-12T22:29:40Z

We could make it configurable whether the user's decisions should be saved, for example by setting WebView.save_user_url_permissions=True before setting the on_navigation_starting handler. What do you think? Should the default be True or False?

I see no practical use for that API. A method that returns False for https://foobar.com will always return False for that URL. There's no need to cache it.

If the intention is to allow user interaction on specific URLs, and cache answers - that's a decision the developer can make if that feature makes sense to have in an app. If nothing else, any caching scheme like that would need to have stored user preferences, a user-clearable cache, and more - so having it baked into Toga seems like massive overreach.

…handler

t-arn · 2025-06-13T14:31:14Z

@freakboy3742 I refactored and simplified the Winforms code by using the cleanup method of wrapped_handler

freakboy3742

This looks a lot better. There's obviously still a lot of debug to clean up, and I've flagged one way to clean up the cleanup handler even more - but the bones of this are lot closer to something I can see being merged.

The one big outstanding question is the need for the staticProxy on WebView, and whether there's any way to make this opt-in if you want navigation callbacks.

freakboy3742 · 2025-06-14T09:29:12Z

core/src/toga/widgets/webview.py

+
+    def on_navigation_starting_callback(self, widget, result):
+        try:
+            url = widget._requested_url


I'm pretty sure this wouldn't be needed if this callback method was an inner method inside on_navigation_starting. That way, it could; be a closure over the url argument. See how Window.on_close is implemented - that inner cleanup method is a closure over handler.

t-arn · 2025-06-16T15:22:33Z

@freakboy3742 I defined on_navigation_starting cleanup method as an inner method, but the url parameter is always None inside cleanup. Is there something wrong with how I changed the code?

The webview._requested_url is still there and set, but not used anymore. I will remove it when the url parameter is working, but currently I don't see how to make it work without webview._requested_url

freakboy3742 · 2025-06-16T23:33:32Z

@freakboy3742 I defined on_navigation_starting cleanup method as an inner method, but the url parameter is always None inside cleanup. Is there something wrong with how I changed the code?

The webview._requested_url is still there and set, but not used anymore. I will remove it when the url parameter is working, but currently I don't see how to make it work without webview._requested_url

Ah - on closer inspection - the url argument to on_navigation_started will alway be None - because the method is a setter. It's not invoked when the navigation starts; it's invoked when the handler is installed - so url will always be None (and, in fact, there's no way to pass in anything to that argument at all).

So - I suspect what is needed here is a modification to wrapped_handler so that the cleanup method also accepts the *args and **kwargs passed to the event handler (in this case, url). AFAICT, all the existing uses of cleanup don't use any additional kwargs on their events - this would be the first usage on a handler that has arguments in addition to the widget.

t-arn · 2025-10-07T16:40:45Z

@freakboy3742

So - I suspect what is needed here is a modification to wrapped_handler so that the cleanup method also accepts the *args and **kwargs passed to the event handler (in this case, url)

How would this change help me? The cleanup method is also set when setting the on_navigation_handler. At this point, the url to be checked is not known yet. The url is only known, when the on_navigation_handler is actually called from the native event. Or do I misunderstand something here?

freakboy3742 · 2025-10-07T23:56:27Z

@freakboy3742

So - I suspect what is needed here is a modification to wrapped_handler so that the cleanup method also accepts the *args and **kwargs passed to the event handler (in this case, url)

How would this change help me? The cleanup method is also set when setting the on_navigation_handler. At this point, the url to be checked is not known yet. The url is only known, when the on_navigation_handler is actually called from the native event. Or do I misunderstand something here?

What I'm saying is that wrapped_handler needs to be modified so that the cleanup method is invoked with the same args and kwargs as the actual navigation handler. The URL doesn't need to be known at time of definition - it's an argument to the cleanup handler, populated when the navigation handler completes.

…he cleanup method

t-arn · 2025-11-05T08:57:14Z

@freakboy3742 I now modified wrapped_handler and handler_with_cleanup to pass the kwargs to the cleanup method. I am not sure if the change in wrapped_handler is really needed. It's the change in handler_with_cleanup which is important. But for consistency reasons, I also made the change in wrapped_handler.

The URL filtering now works fine with synchronous and asynchronous handlers. The current example code uses the asynchronous handler.

The code still contains a lot of debugging output. If you generally approve of the way taken to implement the URL filtering, I will cleanup the code and finalise the PR.

freakboy3742 · 2025-11-05T22:33:19Z

Thanks for those updates; four things that stood out:

We've recently moved out documentation to Markdown; so the changenote now needs to be a .md file, not a .rst file - but I saw a couple of other RST bits in the doc changes (like using double backticks for literals)
The docs build is currently breaking; it looks like a spelling issue (I think using WebView rather than webview will fix that?)
There's a merge conflict with the webview example
The handler cleanup changes will need tests - that probably won't be picked up by coverage, but it's an obvious gap that isn't being tested.

There's also the outstanding question from a past review; the answer to that question will be fairly significant on whether this PR can be landed at all.

t-arn · 2025-11-07T06:20:55Z

@freakboy3742 Here's the answer to the outstanding question regarding Android:
The changes in Android's WebView cause an app crash when the staticProxy is missing in pyproject.toml, even when I use the unmodified example code from main :-(

This error is shown in the log on app start:
E/AndroidRuntime: FATAL EXCEPTION: main
E/AndroidRuntime: Process: org.beeware.toga.examples.webview, PID: 28905
E/AndroidRuntime: java.lang.RuntimeException: Unable to start activity ComponentInfo{org.beeware.toga.examples.webview/org.beeware.android.MainActivity}: com.chaquo.python.PyException: java.lang.NoClassDefFoundError: toga_android.widgets.webview.TogaWebClient

So, we cannot merge this PR until Toga itself can declare a list of classes that need a static proxy.

How do we proceed? Should I remove the changes in Android and just finalize the PR for winforms?
I would then create a new PR with only the Android changes (async handlers are yet to be implemented there) and a feature request for Toga and Briefcase?

freakboy3742 · 2025-11-10T08:42:36Z

So, we cannot merge this PR until Toga itself can declare a list of classes that need a static proxy.

Ok - that's going to be a blocker then. We can't add code to the definition of WebView that prevents an Android app from working at all.

How do we proceed? Should I remove the changes in Android and just finalize the PR for winforms? I would then create a new PR with only the Android changes (async handlers are yet to be implemented there) and a feature request for Toga and Briefcase?

It sounds like we might need to take that approach. Android's WebView is already missing features because of the need for a static proxy (there's no on_load_url callback support); this becomes another feature that needs to be documented in the same way.

Working out how to represent the static_proxy requirements of Android apps so that Briefcase (and other tools) are able to satisfy that requirement is a bigger task - but definitely one that requires a solution.

mhsmith · 2025-11-10T09:12:25Z

chaquo/chaquopy#881 covers the general issue.

For this PR, I think it should be possible to make the Android feature conditional on the build_gradle_extra_content being present. You didn't include the full stack trace of the exception, but I think it probably arises from the class statement containing the static_proxy call, in which case you can surround that with an exception handler.

t-arn · 2025-11-10T16:11:13Z

@mhsmith Many thanks for your response! Following your advice, I now moved the class TogaWebClient(static_proxy(WebViewClient)) into a separate module and I import it like this:

class WebView(Widget):
    SUPPORTS_ON_WEBVIEW_LOAD = False

    def create(self):
        self.native = A_WebView(self._native_activity)
        try:
            from .webview_static_proxy import TogaWebClient
            client = TogaWebClient(self)
        except BaseException as ex:
            SUPPORTS_ON_NAVIGATION_STARTING = False
            client = WebViewClient()
            msg  = 'chaquopy.defaultConfig.staticProxy("toga_android.widgets.webview_static_proxy") '
            msg += 'missing in pyproject.toml section "build_gradle_extra_content"\n'
            msg += 'on_navigation_starting handler is therefore not available'
            print(msg)
        # Set a WebViewClient so that new links open in this activity,
        # rather than triggering the phone's web browser.
        self.native.setWebViewClient(client)

This now works with and without the staticProxy setting in pyproject.toml :-)
When the setting is missing, following messages are logged on app start:

I/python.stdout: chaquopy.defaultConfig.staticProxy("toga_android.widgets.webview_static_proxy") missing in pyproject.toml section "build_gradle_extra_content"
I/python.stdout: on_navigation_starting handler is therefore not available

But the webview example works (without the URL filtering)

I will now add the async handler for Android as well, clean up the code and add tests for the changed cleanup handler.
How do I write such a test for the dummy backend that in fact never fires the on_navigation_starting event??

…yproject.toml * improve docstring for on_navigation_starting * updated app.py to include the latest changes from main

freakboy3742

A few comments inline

The documentation for WebView will need to detail the requirements of the Android implementation.
At the risk of engaging in scope creep - the reason Android doesn't support on_webview_load handlers is that we didn't have a static proxy for the client; if we're able to overcome this now as an optional thing, we might as well add that feature while we're at it.
The testbed app will also need the static declaration, and tests to give coverage.

Regarding the tests for dummy; we need to add a "faked" implementation of URL navigation blocking. We don't need to actually load a URL - we just need to track which URL has been loaded; and provide the hooks in the backend to not load if the navigation handler rejects the request. The tests then exercise all the relevant cases - at a first pass, that's:

no handler
a sync handler that returns True
a sync handler that returns False
an async handler that returns True
an async handler that returns False

There may be some others to cover edge cases of error handling.

freakboy3742 · 2025-11-11T00:44:34Z

android/src/toga_android/widgets/webview_static_proxy.py

+        return False
+
+
+# TogaWebClient


What is this line for?

It's part of my personal coding style (it marks the end of the class code)

I removed the line

freakboy3742 · 2025-11-11T00:45:46Z

android/src/toga_android/widgets/webview.py

+            from .webview_static_proxy import TogaWebClient
+
+            client = TogaWebClient(self)
+        except BaseException:


This seems like an oddly low-level exception to be raising - is there nothing more specific we can catch?

FYI: Java exceptions can be imported with a from ... import statement and then used in an except statement just like a Python exception.

I replaced it with an explicit NoClassDefFoundError

freakboy3742 · 2025-11-11T00:49:52Z

android/src/toga_android/widgets/webview.py

+            msg = "chaquopy.defaultConfig.staticProxy"
+            msg += '("toga_android.widgets.webview_static_proxy") '
+            msg += 'missing in pyproject.toml section "build_gradle_extra_content"\n'
+            msg += "on_navigation_starting handler is therefore not available"


A multiline-string would be a better option here; see how GTK's webview handles similar long strings.

However, it would also be preferable to only output this warning if the user actually has an on_navigation_starting handler. Outputting the message when the handler is set would make more sense to me.

freakboy3742 · 2025-11-11T00:51:01Z

core/src/toga/handlers.py

        if cleanup:
            try:
-                cleanup(interface, result)
+                cleanup(interface, result, **kwargs)


It occurs to me that we should probably be including *args as well here.

OK, added *args

freakboy3742 · 2025-11-11T00:52:57Z

core/src/toga/widgets/webview.py


+        # If URL is allowed by user interaction or user on_navigation_starting
+        # handler, the count will be set to 0
+        self._url_count = 0


I'm confused why this is a "count". All the uses are a simple boolean, not "counting" anything.

OK, changed to boolean

freakboy3742 · 2025-11-11T00:56:46Z

core/src/toga/widgets/webview.py

        return await loaded_future

+    @property
+    def on_navigation_starting(self):


Suggested change

def on_navigation_starting(self):

def on_navigation_starting(self) -> OnNavigationStartingHandler:

freakboy3742 · 2025-11-11T00:57:21Z

core/src/toga/widgets/webview.py

+
+        :returns: The function ``callable`` that is called by this navigation event.


We don't need to document the return value; that's part of the type declaration for properties.

Suggested change

:returns: The function ``callable`` that is called by this navigation event.

freakboy3742 · 2025-11-11T00:58:09Z

core/src/toga/widgets/webview.py

+                msg = f"on_navigation_starting.cleanup, url={url}, "
+                msg += f"result={str(result)}"
+                print(msg)


I'm assuming this is stray debug.

Suggested change

msg = f"on_navigation_starting.cleanup, url={url}, "

msg += f"result={str(result)}"

print(msg)

Yes, and there are a lot more debugging prints. I'll remove them when everything is working as expected.

Now removed all debugging prints

t-arn · 2025-11-11T10:06:40Z

@mhsmith What is the minimal Python Exception/Error that needs to be catched to handle Java ClassNotFoundException? I tried AttributeError and that did not catch the Java Exception

mhsmith · 2025-11-11T16:26:53Z

Like this:

from java.lang import NoClassDefFoundError

try:
    ...
except NoClassDefFoundError:
    ...

t-arn · 2025-11-11T22:02:45Z

@mhsmith Thank you, I'll try this

* fixed too long lines * set asynchronous handler in example app

* adjusted WebView documentation for Android's staticProxy * added Android staticProxy for testbed application * removed debugging prints

t-arn added 4 commits May 13, 2025 07:34

* implented on_navigation_started for winforms

a476f73

* implented on_navigation_started for android * extended the webview example

* fixed some issues

23e2747

* added change note

4c6777d

* applied black

fixed pre-commit issue

4849755

freakboy3742 requested changes May 13, 2025

View reviewed changes

removed unnecessary set_on_navigation_starting() method

7f335d6

t-arn added 2 commits May 26, 2025 08:12

* removed unnecessary TogaNavigationEvent

a209b71

* added type declaration for handler * added WeakrefCallable wrapper

* windows implementation now supports synchronous and asynchronous on…

c6119ba

…_navigation_starting handlers

freakboy3742 requested changes Jun 12, 2025

View reviewed changes

refactored the code for Windows to use the cleanup method of wrapped_…

98ec9fd

…handler

freakboy3742 requested changes Jun 14, 2025

View reviewed changes

defined on_navigation_starting cleanup method as inner method

39af762

freakboy3742 mentioned this pull request Jun 18, 2025

External href links are death traps beeware/podium#36

Open

t-arn added 2 commits November 5, 2025 09:42

extended wrapped_handler and handler_with_cleanup to pass kwargs to t…

44814b2

…he cleanup method

Renamed the class of the WebView example to match the current code

951a94b

* fixed calling the on_navigation_starting handler on Android

d7751b2

mhsmith mentioned this pull request Nov 10, 2025

Allow a package's static_proxy modules to be declared using metadata chaquo/chaquopy#881

Open

t-arn and others added 3 commits November 10, 2025 17:50

* fixed app crash on Android when staticProxy setting is missing in p…

8830607

…yproject.toml * improve docstring for on_navigation_starting * updated app.py to include the latest changes from main

Merge branch 'main' into webview_tarn_323ec36

81fd425

fixed staticProxy in pyproject.toml

0483945

freakboy3742 requested changes Nov 11, 2025

View reviewed changes

t-arn added 6 commits November 17, 2025 17:33

adjusted test_handlers.py for the changed cleanup handler

6fde361

Applied changes as requested by review

2251c6d

* added asynchronous on_navigation_starting handler for Android

0c9072f

* fixed too long lines * set asynchronous handler in example app

fixed trailing blanks

8d70393

fixed tests for the added *args parameter passed to handler cleanup

7862ff8

* fixed call to handler cleanup

82ebcf0

* adjusted WebView documentation for Android's staticProxy * added Android staticProxy for testbed application * removed debugging prints

	def on_navigation_starting(self):
	def on_navigation_starting(self) -> OnNavigationStartingHandler:


		:returns: The function ``callable`` that is called by this navigation event.

	msg = f"on_navigation_starting.cleanup, url={url}, "
	msg += f"result={str(result)}"
	print(msg)

Uh oh!

WebView URL filtering #3442

Are you sure you want to change the base?

WebView URL filtering #3442

Uh oh!

Conversation

t-arn commented May 13, 2025

PR Checklist:

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-arn commented May 13, 2025

Uh oh!

freakboy3742 commented May 13, 2025

Uh oh!

t-arn commented Jun 11, 2025

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

t-arn commented Jun 12, 2025

Uh oh!

t-arn commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

freakboy3742 commented Jun 12, 2025

Uh oh!

t-arn commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-arn commented Jun 16, 2025

Uh oh!

freakboy3742 commented Jun 16, 2025

Uh oh!

t-arn commented Oct 7, 2025

Uh oh!

freakboy3742 commented Oct 7, 2025

Uh oh!

t-arn commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

freakboy3742 commented Nov 5, 2025

Uh oh!

t-arn commented Nov 7, 2025

Uh oh!

freakboy3742 commented Nov 10, 2025

Uh oh!

mhsmith commented Nov 10, 2025

Uh oh!

t-arn commented Nov 10, 2025

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

t-arn commented Jun 12, 2025 •

edited

Loading

t-arn commented Jun 13, 2025 •

edited

Loading

t-arn commented Nov 5, 2025 •

edited

Loading