Skip to content

Instantly share code, notes, and snippets.

@valenting

valenting/URL parsers.md

Last active August 16, 2022 15:57
Show Gist options
  • Save valenting/2834405b9b85e4b3a3f8550164c225b4 to your computer and use it in GitHub Desktop.
Save valenting/2834405b9b85e4b3a3f8550164c225b4 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
uri-setters.md

Setters in IDL

nsIURI setters

  • nsIURI.spec bug 1431204
  • nsIURI.scheme
  • nsIURI.userPass
  • nsIURI.username
  • nsIURI.password
  • nsIURI.hostPort
  • nsIURI.setHostAndPort()
  • nsIURI.host
  • nsIURI.port
  • nsIURI.pathQueryRef
  • nsIURI.ref
  • nsIURI.filePath
  • nsIURI.query
  • nsIURI.setQueryWithEncoding

nsIURL setters

  • nsIURL.directory
  • nsIURL.fileName
  • nsIURL.fileBaseName
  • nsIURL.fileExtension

nsIFileURL setters

  • nsIFileURL.file

nsIStandardURL setters bug 1432187

  • nsIStandardURL.init
  • nsIStandardURL.setDefaultPort()

nsIMutable setters

  • nsIMutable.mutable

nsISerializable setters

nsIIPCSerializableURI setters

nsIJARURI setters

  • nsIJARURI.JAREntry

nsIMozIconURI setters

  • nsIMozIconURI.iconURL
  • nsIMozIconURI.imageSize
  • nsIMozIconURI.contentType

nsIWeakReference setters

Classes implementing nsIURI

Interfaces implemented by nsIURI objects

nsStandardURL

nsIFileURL -> nsIURL -> nsIURI -> nsISupports nsIStandardURL -> nsIMutable -> nsISupports nsISerializable -> nsISupports nsIClassInfo -> nsISupports nsISizeOf -> nsISupports nsIIPCSerializableURI -> nsISupports nsISensitiveInfoHiddenURI -> nsISupports

nsSimpleURI

nsIURI -> nsISupports nsISerializable -> nsISupports nsIClassInfo -> nsISupports nsIMutable -> nsISupports nsISizeOf -> nsISupports nsIIPCSerializableURI -> nsISupports

nsSimpleNestedURI: (extends nsSimpleURI)

nsINestedURI -> nsISupports

nsNestedAboutURI: (extends nsSimpleNestedURI)

SubstitutingURL: (extends nsStandardURL)

nsJARURI

nsIJARURI -> nsIURL -> nsIURI -> nsISupports nsISerializale -> nsISupports nsIClassInfo -> nsISupports nsINestedURI -> nsISupports nsIIPCSerializableURI -> nsISupports

NullPrincipalURI

nsIURI -> nsISupports nsISizeOf -> nsISupports nsIIPCSerializableURI -> nsISupports

nsMozIconURI

nsIMozIconURI -> nsIURI -> nsISupports nsIIPCSerializableURI -> nsISupports nsINestedURI -> nsISupports

nsHostObjectURI: (extends nsSimpleURI)

nsIURIWithPrincipal -> nsISupports nsIURIWithBlobImpl -> nsISupports nsSupportsWeakReference -> nsISupportsWeakReference -> nsISupports (!!) void ForgetBlobImpl() (!!)

Protocol handlers:

nsIProtocolHandler GenericProtocolHandler [deleted 1420622] FeedProtocolHandler [deleted 1420622] PodCastProtocolHandler [deleted 1420622] nsChromeProtocolHandler ProtocolHandler // test_no_remote_registration.js nsHostObjectProtocolHandler -> nsFontTableProtocolHandler -> nsBlobProtocolHandler nsJSProtocolHandler nsIconProtocolHandler nsJARProtocolHandler nsAboutProtocolHandler nsDataHandler nsFileProtocolHandler nsGIOProtocolHandler nsHttpHandler ExtensionProtocolHandler SubstitutingProtocolHandler nsResProtocolHandler nsViewSourceHandler BaseWebSocketChannel WebSocketChannelChild nsWyciwygProtocolHandler CustomProtocolHandler // browser_nsIFormPOSTActionChannel.js ProtocolHandler // test_1351443-missing-NewChannel2.js ProtocolHandler // test_bug894586.js TestProtocolHandler // test_protocolproxyservice.js PageIconProtocolHandler mozProtocolHandler nsHostObjectProtocolHandler nsAnnoProtocolHandler PageThumbsProtocol nsExternalProtocolHandler nsAndroidProtocolHandler

nsIProtocolHandlerWithDynamicFlags nsISubstitutingProtocolHandler nsIJARProtocolHandler nsIExternalProtocolHandler nsIProxiedProtocolHandler nsIHttpProtocolHandler

Raw
URL parsers.md

Intro

Definitions

  • URI - Uniform Resource Identifier
  • URL - Uniform Resource Locator

These two terms are used interchangeably throughout the codebase and essentially represent the same thing - a string of characters that represents a specific resource.

In order to ensure thread safety it is important that all of the objects and interfaces of URI objects are immutable.
If you are implementing a new URI type, please make sure that none of the type's public methods change the URL.

Motivation

While we could simply pass strings around and leave it to the final consumer to deal with it, that creates a burden for the consumer and would probably be inefficient. Instead we parse the string into a nsIURI object as soon as possible and pass that object through function calls. This allows the consumer to easily extract only the part of the string they are interested in (eg. the hostname or the path).

interfaces

  • nsIURI
    • This is the most important interface for URI parsing. It contains a series of readonly attributes that consumers can use to extract information from the URI.
  • nsIURL
    • Defines a structure for the URI's path (directory, fileName, fileBaseName, fileExtension)
  • nsIFileURL
    • Has a file attribute of type nsIFile
    • Used for local protocols to access the file represented by the nsIURI
  • nsIMozIconURI
    • Used to represent an icon. Contains additional attributes such as the size and contentType or state of the URL.
  • nsIJARURI
    • Used to represent a resource inside of a JAR (zip archive) file.
    • For example jar:http://www.example.com/blue.jar!/ocean.html represents the /ocean.html resource located inside the blue.jar archive that can be fetched via HTTP from example.com.
  • nsIStandardURL
    • Defines a few constant flags used to determine the type of the URL. No other attributes.
  • nsINestedURI
    • Defines innerURI and innermostURI.
    • innermostURI is just a helper - one could also get it by going through innerURI repeatedly until the attribute no longer QIs to nsINestedURI.
  • nsISensitiveInfoHiddenURI
    • Objects that implement this interface will have a getSensitiveInfoHiddenSpec() method that returns the spec of the URI with sensitive info (such as the password) replaced by the * symbol.
classDiagram  
nsISupports <-- nsIURI
nsIURI <-- nsIURL
nsIURL <-- nsIFileURL
nsIURI <-- nsIMozIconURI
nsIURL <-- nsIJARURI
nsISupports <-- nsIStandardURL
nsISupports <-- nsINestedURI
nsISupports <-- nsISensitiveInfoHiddenURI
  • nsIURIMutator
    • This interface contains a series of setters that can be used to mutate and/or construct a nsIURI
    • To ensure thread safety all implementations of nsIURI must be immutable. To change a URI the consumer must call nsIURI.mutate() which returns a nsIMutator. The nsIMutator has several setter methods that can be used change attributes on the concrete object. Once done changing the object, the consumer will call nsIMutator.finalize() to obtain an immutable nsIURI.

Implementations

  • nsStandardURL
  • SubstitutingURL
    • overrides nsStandardURL::GetFile to provide nsIFile resolution.
    • This allows us to map URLs such as resource://gre/actors/RemotePageChild.jsm to the actual file on the disk.
  • nsMozIconURI
    • Used to represent icon URLs
  • nsSimpleURI
    • Used for simple URIs that normally don't have an authority (username, password, host, port)
  • nsSimpleNestedURI
    • eg. `view-source:http://example.com/path
    • Normally only the extra scheme of the nestedURI is relevant view-source:
    • Most of the getter/setters are delegated to the innerURI
  • nsNestedAboutURI
    • Similar to nsSimpleNestedURI, but has an extra mBaseURI member that allows us to propagate the base URI to about:blank correctly`
  • BlobURL
    • Used for javascript blobs
    • Similar to nsSimpleURI, but also has a revoked field.
  • DefaultURI
    • This class wraps an object parsed by the rust-url crate.
    • While not yet enabled by default, due to small bugs in that parser, the plan is to eventually use this implementation for all unknown protocols that don't have their own URL parser.
  • nsJSURI
    • Used to represent javascript code (eg. javascript:alert('hello'))
  • nsJARURI
    • Used to represent resources inside of JAR files.
classDiagram
nsSimpleURI o-- BlobURL
nsIMozIconURI o-- nsMozIconURI
nsIFileURL o-- nsStandardURL
nsIStandardURL o-- nsStandardURL
nsISensitiveInfoHiddenURI o-- nsStandardURL
nsStandardURL o-- SubstitutingURL
nsIURI o-- nsSimpleURI
nsSimpleURI o-- nsSimpleNestedURI
nsSimpleNestedURI o-- nsNestedAboutURI

nsIURI o-- DefaultURI

nsSimpleURI o-- nsJSURI

nsINestedURI o-- nsJARURI
nsIJARURI o-- nsJARURI

Together

classDiagram  
nsISupports <-- nsIURI
nsIURI <-- nsIURL
nsIURL <-- nsIFileURL
nsIURI <-- nsIMozIconURI
nsIURL <-- nsIJARURI
nsISupports <-- nsIStandardURL
nsISupports <-- nsINestedURI
nsISupports <-- nsISensitiveInfoHiddenURI

%% classes

nsSimpleURI o-- BlobURL
nsSimpleURI o-- nsJSURI
nsIMozIconURI o-- nsMozIconURI
nsIFileURL o-- nsStandardURL
nsIStandardURL o-- nsStandardURL
nsISensitiveInfoHiddenURI o-- nsStandardURL
nsStandardURL o-- SubstitutingURL
nsIURI o-- nsSimpleURI
nsINestedURI o-- nsJARURI
nsIJARURI o-- nsJARURI
nsSimpleURI o-- nsSimpleNestedURI
nsSimpleNestedURI o-- nsNestedAboutURI
nsIURI o-- DefaultURI
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment