268661 - The URLTYPE flags on nsIStandardURL should be better documented

Status: RESOLVED WORKSFORME

(Core :: Networking, defect)

Description

[timeless]

<timeless> is it not possible to have a ported no auth url?
* timeless wonders if gopher supports auth
<bz> timeless: yes?
<timeless> hey, i'm looking for some way to have a ported noauth url
<timeless> i had to look a bit off the beaten track
<bz> timeless: so...
<bz> timeless: what does NO_AUTHORITY really mean, eh?
<timeless> don't ask me
<timeless> i don't read docs, because i presume docs don't exist :)

redactor's note: it doesn't, hence this bug.

<bz> timeless:
http://lxr.mozilla.org/seamonkey/source/netwerk/base/public/nsIStandardURL.idl#54
<bz> timeless: it affects how the URL is parsed, basically
<bz> timeless: and by definition NO_AUTHORITY means no port
<bz> timeless: gopher does not use NO_AUTHORITY
<timeless> bz: oh
<timeless> so it really means no host
<bz> timeless: yes
<bz> timeless:
http://lxr.mozilla.org/seamonkey/source/netwerk/base/src/nsStandardURL.cpp#1329
<timeless> bz: why doesn't it say that? :)
<bz> timeless: heh.  File a bug?  ;)

Comment 1

[Darin Fisher]

URLTYPE_NO_AUTHORITY means that the URL does not have an authority section.  The
authority section is defined in RFC 2396, and is clear from:

  <scheme>://<authority><path>?<query>

So, if there is no authority, then there is no host, port, username, or password.

This is well documented in nsIURLParser.idl FWIW.  Where do you get the idea
that gopher URLs can have a post but not a host?  Our code certainly doesn't
handle that case at all.


> <bz> timeless: and by definition NO_AUTHORITY means no port
> <bz> timeless: gopher does not use NO_AUTHORITY
> <timeless> bz: oh
> <timeless> so it really means no host
> <bz> timeless: yes

Uhm... no.  The authority section of a URL is not equal to the host ;-)

Comment 2

[Christian :Biesinger (don't email me, ping me on IRC)]

note that 1) file uris can have a host (though mozilla does not implement that
usefully) and 2)
http://lxr.mozilla.org/seamonkey/source/netwerk/base/public/nsIStandardURL.idl#74
shows a NO_AUTHORITY url w/ a host

Comment 3

[Darin Fisher]

> note that 1) file uris can have a host (though mozilla does not implement that
> usefully) and 2) <link> shows a NO_AUTHORITY url w/ a host

biesi: Yes and no.  file: URLs have the NO_AUTHORITY flag set because we want
the parser to almost always treat what looks like an authority as part of the
path.  As you can see from the comments in nsIStandardURL.idl, there is only one
case where the authority section is treated as an actual authority section.

nsStandardURL does not let you modify the host of a NO_AUTHORITY URL.  That
would probably need to change if we ever started supporting the authority
section of a file URL.  Maybe it would be more correct to define a URLTYPE_FILE
and then make URLTYPE_NO_AUTHORITY really mean no authority.

Comment 4

[Boris Zbarsky [:bzbarsky]]

Darin, comment 0 is incredibly unclear... what this bug was filed on is that
nsIStandardURL doesn't clearly document what the flags mean.  The fact that
nsIURLParser documents what "authority" means is no help because nsIStandardURL
does not mention nsIURLParser.

So the simplest way to address the documentation issue may be to simply explain
in nsIStandardURL.idl how the flags will affect the nsIURLParser invocation...

Comment 5

[Darin Fisher]

bz: ah, yes..  i agree.

Comment 6

[Mike Kaply [:mkaply]]

Is the documentation here enough?

https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIStandardURL#Constants

Comment 7

[Patrick McManus [:mcmanus]]

based on comment 6