1548467 - Introduce navigation API for the Network panel

Status: NEW

(WebExtensions :: Developer Tools, enhancement, P3)

Description

[Jan Honza Odvarko [:Honza] (always need-info? me)]

One of the requirements coming from add-on developers (WebHint) is a way to navigate the user to the Network panel and select specific request for further inspection.

I can't find any existing API (or similar for other panels), so it looks like we would have to introduce something new.

I can imagine something like as follows:

devtools.network.inspect(...)

Some open questions:

• How to specify what request should be selected? Note that there might be more requests with the same URL.
• It could also be useful to specify what side panel should be selected.
• It could also be useful to specify what header/cookie/param should be selected.
• Something else?
• Given request doesn't have to be recorded

The Console panel also shows HTTP requests, so we might want to reuse the API somehow.

Honza

Comment 1

[Jan Honza Odvarko [:Honza] (always need-info? me)]

@Luca, what do you think?

Honza

Comment 2

[Jan Honza Odvarko [:Honza] (always need-info? me)]

@Tony, how does that sound?

Honza

Comment 3

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Note that there is existing inspect() API (Console utility) for inspecting JS Objects/functions. Opens and selects the specified element or object in the appropriate panel: either the Elements panel for DOM elements or the Profiles panel for JavaScript heap objects.

Not particularly useful for HTTP requests (except of XHRs?), but can be an inspiration of what already exists.

Honza

Comment 4

[Tony Ross [:antross]]

Thanks for kicking this off @Honza!

I think something like devtools.network.inspect() sounds good.

• How to specify what request should be selected? Note that there might be more requests with the same URL.

What do you think about the URL plus startedDateTime from the HAR entry? I figure the time can be optional and would default to showing the first entry with a matching URL otherwise.

Passing the exact HAR entry from devtools.network.onRequestFinished back would also be an option and a bit closer to the spirit of the inspect API in the Console, though that might prove cumbersome to use in practice.

• It could also be useful to specify what header/cookie/param should be selected.

This would be particularly useful for the webhint case as we usually have a specific header we're providing feedback about. Also nice if this automatically selects the correct panel based on the type of data provided.

• It could also be useful to specify what side panel should be selected.

If the correct panel gets selected automatically based on provided data we likely wouldn't make as much use of this, but I can see it potentially being useful to others.

---

I'm not tied to a specific signature, but here's one possible way I could see calling it:

devtools.network.inspect('https://webhint.io/', {
    select: { header: 'Content-Type' },
    startedDateTime: '2019-05-09T12:26:26.672-05:00'
});

Comment 5

[Luca Greco [:rpl] [:luca] [:lgreco]]

(In reply to Jan Honza Odvarko [:Honza] (always need-info? me) from comment #1)

@Luca, what do you think?

Honza

Apologies for the time I needed to get to this and think a bit about it.

I definitely agree that it would be an useful feature, and from my point of view it would make sense to give devtools extensions the ability to "link" to the integrated network panel when needed (as they can "link" to the element in the inspector panel).

As you both already mentioned, one thing that we need to figure out first is how to reasonably expose the feature, given that unlike the inspect(...) console helper (which is executed in a context where the target object actually exist and we can be sure to select the same object in the inspector), we don't have a specific object reference to refer to.

I may also be worth to take into account that inspect(...) is also (kind of) paired with two other features:

• $0 will reference the currently selected element (in a js code snippet executed using browser.devtools.inspectedWindow.eval)
• the browser.devtools.panels.elements.onSelectionChanged API event is fired when the currently selected element in the inspector panel is being changed

And so it seems to me that browser.devtools.panels.network could be another possible API namespace where the new API method may fit, e.g. how about the following set of API methods and events?

• browser.devtools.panels.network.select(...).then((selectedHARRequest) => {...}), to select the first request/response which match with the options provided (e.g. it may just be a set of property that should match in the simpler case, and it should likely also support some other matching mechanisms, like the start datetime example above)
• browser.devtools.panels.network.onSelectionChanged.addListener((selectedHARRequest) => {...}), an event fired when a request/response is selected in the network panel
• browser.devtools.panels.network.getSelected().then((selectedHARRequest) => {...}), to retrieve the request currently selected in the network panel programmatically

The browser.devtools.panels.network API namespace doesn't exist yet (the only existing property in browser.devtools.panels is currently elements, that represents the inspector panel), which may be actually a good thing because another detail that we may need to take into account is that this API namespace is shared with the Chrome Extensions API.

I'm going to needinfo mconca on this issue to get his opinion about this (the new API method/methods and the above details about a potential chrome-compatibility issue we may need to take into account).

Comment 6

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Thanks Luca for the input, the API suggestion make good sense to me.

Honza

Comment 7

[Mike Conca [:mconca]]

I think creating a devtools.panels.network namespace makes a lot of sense, and the draft API that Luca proposed seems like a great start. There is no equivalent namespace on Chrome right now, which runs the risk of the Google team coming in and eventually implementing something different into this namespace. Nevertheless, I'm comfortable with Firefox taking the lead on this in order to increase the set of robust web development tools in Firefox.

+1

Comment 8

[Jan Honza Odvarko [:Honza] (always need-info? me)]

Some more analysis of the APIs:

• browser.devtools.panels.network.select(...).then((selectedHARRequest) => {...})

Another question is related to arguments passed to the select function. It should be flexible enough, so it can be used to identify the request to be selected using various metrics.

• URL (but there can be more requests with the same URL)
• startDateTime
• HTTP header
• etc. (anything from HAR)

Since it can be basically anything that is collected in HAR - the structure could follow the HAR spec. So, if the user passes directly a HAR entry [1] it should select the right request in the list.

[1] http://janodvarko.cz/blog/har-12-spec/#entries

What Tony sketched in comment #4 - already corresponds to the HAR spec (I just removed the select prop).

Some examples:

#1) Select a request by URL

devtools.network.select('https://www.mozilla.org');

#2) Select a request by URL and startDateTime

devtools.network.select('https://www.mozilla.org', {
    startedDateTime: '2019-05-09T12:26:26.672-05:00'
});

#3) Select a request by URL and HTTP header

devtools.network.select('https://www.mozilla.org', {
    response: {
        headers: [{
          "name": "my-header",
          "value": "specific value"
        }]
    }
});

Notes:

• In case there are more requests matching the provided props - the first one would be selected. Or all of them if multiselection is supported.
• If there is no matching request, the panel should still be selected and there might be an optional UI feedback (an error/warning message) informing the user that specified request doesn't exist.
• The first argument is a bit redundant, since the URL is also presented in HAR and could be passed in through the second argument. But, it feels like URL will mostly be used and it simplify the API.
• If HTTP header is used - the Network panel can optionally select the right side panel and perhaps even highlight the right header. The same applies on Cookies, URL Query parameters, etc.

As a future step, we could also support an existing JSON query language that could allow e.g.: selecting all requests that started in specific time range. Such thing would be possible without changing the API design itself.

Honza

Comment 9

[:Harald Kirschner :digitarald]

LGTM on the select API!

Just adding my input on prioritization, the additional 2 APIs to get current selection make most sense when Network has an extensible sidepanel – so we should punt on them for now.

Comment 10

[Jan Honza Odvarko [:Honza] (always need-info? me)]

(In reply to :Harald Kirschner :digitarald from comment #9)

LGTM on the select API!

Just adding my input on prioritization, the additional 2 APIs to get current selection make most sense when Network has an extensible sidepanel – so we should punt on them for now.

Agreed, can be done as a follow up.

Honza