netwerk/docs/url_parsers.md

   1 # URL Parsers
   2
   3 ```{warning}
   4 In order to ensure thread safety it is important that all of the objects and interfaces of URI objects are immutable.
   5 If you are implementing a new URI type, please make sure that none of the type's public methods change the URL.
   6 ```
   7
   8 ##  Definitions
   9 - URI - Uniform Resource Identifier
  10 - URL - Uniform Resource Locator
  11
  12 These two terms are used interchangeably throughout the codebase and essentially represent the same thing - a string of characters that represents a specific resource.
  13
  14 ## Motivation
  15
  16 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).
  17
  18 ## Interfaces
  19 - [nsIURI](https://searchfox.org/mozilla-central/source/netwerk/base/nsIURI.idl)
  20     - 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.
  21 - [nsIURL](https://searchfox.org/mozilla-central/source/netwerk/base/nsIURL.idl)
  22     - Defines a structure for the URI's path (directory, fileName, fileBaseName, fileExtension)
  23 - [nsIFileURL](https://searchfox.org/mozilla-central/source/netwerk/base/nsIFileURL.idl)
  24     - Has a file attribute of type `nsIFile`
  25     - Used for local protocols to access the file represented by the `nsIURI`
  26 - [nsIMozIconURI](https://searchfox.org/mozilla-central/source/image/nsIIconURI.idl)
  27     - Used to represent an icon. Contains additional attributes such as the size and contentType or state of the URL.
  28 - [nsIJARURI](https://searchfox.org/mozilla-central/source/modules/libjar/nsIJARURI.idl)
  29     - Used to represent a resource inside of a JAR (zip archive) file.
  30     - 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.
  31 - [nsIStandardURL](https://searchfox.org/mozilla-central/source/netwerk/base/nsIStandardURL.idl)
  32     - Defines a few constant flags used to determine the type of the URL. No other attributes.
  33 - [nsINestedURI](https://searchfox.org/mozilla-central/source/netwerk/base/nsINestedURI.idl)
  34     - Defines `innerURI` and `innermostURI`.
  35     - `innermostURI` is just a helper - one could also get it by going through `innerURI` repeatedly until the attribute no longer QIs to nsINestedURI.
  36 - [nsISensitiveInfoHiddenURI](https://searchfox.org/mozilla-central/source/netwerk/base/nsISensitiveInfoHiddenURI.idl)
  37     - 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.
  38
  39 ### Diagram of Interfaces
  40 ```{mermaid}
  41 classDiagram
  42 nsISupports <-- nsIURI
  43 nsIURI <-- nsIURL
  44 nsIURL <-- nsIFileURL
  45 nsIURI <-- nsIMozIconURI
  46 nsIURL <-- nsIJARURI
  47 nsISupports <-- nsIStandardURL
  48 nsISupports <-- nsINestedURI
  49 nsISupports <-- nsISensitiveInfoHiddenURI
  50 ```
  51
  52 ### Mutation
  53
  54 To ensure thread safety all implementations of nsIURI must be immutable.
  55 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`.
  56
  57 - [nsIURIMutator](https://searchfox.org/mozilla-central/source/netwerk/base/nsIURIMutator.idl)
  58     - This interface contains a series of setters that can be used to mutate and/or construct a `nsIURI`
  59
  60
  61 ### Additional Interfaces
  62
  63 - [nsISerializable](https://searchfox.org/mozilla-central/source/xpcom/ds/nsISerializable.idl)
  64     - Allows us to serialize and deserialize URL objects into strings for persistent storage (such as session restore).
  65
  66 ## Implementations
  67 - [nsStandardURL](https://searchfox.org/mozilla-central/source/netwerk/base/nsStandardURL.h)
  68 - [SubstitutingURL](https://searchfox.org/mozilla-central/source/netwerk/protocol/res/SubstitutingURL.h)
  69     - overrides nsStandardURL::GetFile to provide nsIFile resolution.
  70     - This allows us to map URLs such as `resource://gre/actors/RemotePageChild.sys.mjs` to the actual file on the disk.
  71 - [nsMozIconURI](https://searchfox.org/mozilla-central/source/image/decoders/icon/nsIconURI.h)
  72     - Used to represent icon URLs
  73 - [nsSimpleURI](https://searchfox.org/mozilla-central/source/netwerk/base/nsSimpleURI.h)
  74     - Used for simple URIs that normally don't have an authority (username, password, host, port)
  75 - [nsSimpleNestedURI](https://searchfox.org/mozilla-central/source/netwerk/base/nsSimpleNestedURI.h)
  76     - eg. `view-source:http://example.com/path`
  77     - Normally only the extra scheme of the nestedURI is relevant (eg. `view-source:`)
  78     - Most of the getter/setters are delegated to the innerURI
  79 - [nsNestedAboutURI](https://searchfox.org/mozilla-central/source/netwerk/protocol/about/nsAboutProtocolHandler.h)
  80     - Similar to nsSimpleNestedURI, but has an extra `mBaseURI` member that allows us to propagate the base URI to about:blank correctly`
  81 - [BlobURL](https://searchfox.org/mozilla-central/source/dom/file/uri/BlobURL.h)
  82     - Used for javascript blobs
  83     - Similar to nsSimpleURI, but also has a revoked field.
  84 - [DefaultURI](https://searchfox.org/mozilla-central/source/netwerk/base/DefaultURI.h)
  85     - This class wraps an object parsed by the `rust-url` crate.
  86     - 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.
  87 - [nsJSURI](https://searchfox.org/mozilla-central/source/dom/jsurl/nsJSProtocolHandler.h)
  88     - Used to represent javascript code (eg. `javascript:alert('hello')`)
  89 - [nsJARURI](https://searchfox.org/mozilla-central/source/modules/libjar/nsJARURI.h)
  90     - Used to represent resources inside of JAR files.
  91
  92 ### Diagram of Implementations
  93
  94 ```{mermaid}
  95 classDiagram
  96 nsSimpleURI o-- BlobURL
  97 nsIMozIconURI o-- nsMozIconURI
  98 nsIFileURL o-- nsStandardURL
  99 nsIStandardURL o-- nsStandardURL
 100 nsISensitiveInfoHiddenURI o-- nsStandardURL
 101 nsStandardURL o-- SubstitutingURL
 102 nsIURI o-- nsSimpleURI
 103 nsSimpleURI o-- nsSimpleNestedURI
 104 nsSimpleNestedURI o-- nsNestedAboutURI
 105
 106 nsIURI o-- DefaultURI
 107
 108 nsSimpleURI o-- nsJSURI
 109
 110 nsINestedURI o-- nsJARURI
 111 nsIJARURI o-- nsJARURI
 112 ```
 113
 114 ## Class and Interface Diagram
 115
 116 ```{mermaid}
 117 classDiagram
 118 nsISupports <-- nsIURI
 119 nsIURI <-- nsIURL
 120 nsIURL <-- nsIFileURL
 121 nsIURI <-- nsIMozIconURI
 122 nsIURL <-- nsIJARURI
 123 nsISupports <-- nsIStandardURL
 124 nsISupports <-- nsINestedURI
 125 nsISupports <-- nsISensitiveInfoHiddenURI
 126
 127 %% classes
 128
 129 nsSimpleURI o-- BlobURL
 130 nsSimpleURI o-- nsJSURI
 131 nsIMozIconURI o-- nsMozIconURI
 132 nsIFileURL o-- nsStandardURL
 133 nsIStandardURL o-- nsStandardURL
 134 nsISensitiveInfoHiddenURI o-- nsStandardURL
 135 nsStandardURL o-- SubstitutingURL
 136 nsIURI o-- nsSimpleURI
 137 nsINestedURI o-- nsJARURI
 138 nsIJARURI o-- nsJARURI
 139 nsSimpleURI o-- nsSimpleNestedURI
 140 nsSimpleNestedURI o-- nsNestedAboutURI
 141 nsIURI o-- DefaultURI
 142
 143 ```