doc-utils.js (6440B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 "use strict"; 6 7 const { 8 SUPPORTED_HTTP_CODES, 9 } = require("resource://devtools/client/netmonitor/src/constants.js"); 10 const { getMdnLinkParams } = ChromeUtils.importESModule( 11 "resource://devtools/shared/mdn.mjs" 12 ); 13 /** 14 * A mapping of header names to external documentation. Any header included 15 * here will show a MDN link alongside it. 16 */ 17 const SUPPORTED_HEADERS = [ 18 "Accept", 19 "Accept-Charset", 20 "Accept-Encoding", 21 "Accept-Language", 22 "Accept-Ranges", 23 "Access-Control-Allow-Credentials", 24 "Access-Control-Allow-Headers", 25 "Access-Control-Allow-Methods", 26 "Access-Control-Allow-Origin", 27 "Access-Control-Expose-Headers", 28 "Access-Control-Max-Age", 29 "Access-Control-Request-Headers", 30 "Access-Control-Request-Method", 31 "Activate-Storage-Access", 32 "Age", 33 "Allow", 34 "Alt-Svc", 35 "Alt-Used", 36 "Authorization", 37 "Cache-Control", 38 "Clear-Site-Data", 39 "Connection", 40 "Content-Disposition", 41 "Content-Encoding", 42 "Content-Language", 43 "Content-Length", 44 "Content-Location", 45 "Content-Range", 46 "Content-Security-Policy", 47 "Content-Security-Policy-Report-Only", 48 "Content-Type", 49 "Cookie", 50 "Cookie2", 51 "Cross-Origin-Embedder-Policy", 52 "Cross-Origin-Opener-Policy", 53 "Cross-Origin-Resource-Policy", 54 "DNT", 55 "Date", 56 "ETag", 57 "Early-Data", 58 "Expect", 59 "Expect-CT", 60 "Expires", 61 "Feature-Policy", 62 "Forwarded", 63 "From", 64 "Host", 65 "If-Match", 66 "If-Modified-Since", 67 "If-None-Match", 68 "If-Range", 69 "If-Unmodified-Since", 70 "Keep-Alive", 71 "Last-Modified", 72 "Link", 73 "Location", 74 "Origin", 75 "Origin-Agent-Cluster", 76 "Permissions-Policy", 77 "Pragma", 78 "Priority", 79 "Proxy-Authenticate", 80 "Proxy-Authorization", 81 "Public-Key-Pins", 82 "Public-Key-Pins-Report-Only", 83 "Range", 84 "Referer", 85 "Referrer-Policy", 86 "Refresh", 87 "Report-To", 88 "Reporting-Endpoints", 89 "Retry-After", 90 "Save-Data", 91 "Sec-Fetch-Dest", 92 "Sec-Fetch-Mode", 93 "Sec-Fetch-Site", 94 "Sec-Fetch-Storage-Access", 95 "Sec-Fetch-User", 96 "Sec-GPC", 97 "Sec-WebSocket-Accept", 98 "Sec-WebSocket-Extensions", 99 "Sec-WebSocket-Key", 100 "Sec-WebSocket-Protocol", 101 "Sec-WebSocket-Version", 102 "Server", 103 "Server-Timing", 104 "Set-Cookie", 105 "Set-Cookie2", 106 "SourceMap", 107 "Strict-Transport-Security", 108 "TE", 109 "Timing-Allow-Origin", 110 "Tk", 111 "Trailer", 112 "Transfer-Encoding", 113 "Upgrade", 114 "Upgrade-Insecure-Requests", 115 "User-Agent", 116 "Vary", 117 "Via", 118 "WWW-Authenticate", 119 "Warning", 120 "X-Content-Type-Options", 121 "X-DNS-Prefetch-Control", 122 "X-Forwarded-For", 123 "X-Forwarded-Host", 124 "X-Forwarded-Proto", 125 "X-Frame-Options", 126 "X-XSS-Protection", 127 ]; 128 129 const MDN_URL = "https://developer.mozilla.org/docs/"; 130 const MDN_STATUS_CODES_LIST_URL = `${MDN_URL}Web/HTTP/Reference/Status`; 131 const getGAParams = (panelId = "netmonitor") => { 132 return `?` + getMdnLinkParams(`devtools-${panelId}`); 133 }; 134 135 // Base URL to DevTools user docs 136 const USER_DOC_URL = "https://firefox-source-docs.mozilla.org/devtools-user/"; 137 138 /** 139 * Get the MDN URL for the specified header. 140 * 141 * @param {string} header Name of the header for the baseURL to use. 142 * 143 * @return {string} The MDN URL for the header, or null if not available. 144 */ 145 function getHeadersURL(header) { 146 const lowerCaseHeader = header.toLowerCase(); 147 const idx = SUPPORTED_HEADERS.findIndex( 148 item => item.toLowerCase() === lowerCaseHeader 149 ); 150 return idx > -1 151 ? `${MDN_URL}Web/HTTP/Reference/Headers/${SUPPORTED_HEADERS[idx] + getGAParams()}` 152 : null; 153 } 154 155 /** 156 * Get the MDN URL for the specified HTTP status code. 157 * 158 * @param {string} HTTP status code for the baseURL to use. 159 * 160 * @return {string} The MDN URL for the HTTP status code, or null if not available. 161 */ 162 function getHTTPStatusCodeURL(statusCode, panelId) { 163 return ( 164 (SUPPORTED_HTTP_CODES.includes(statusCode) 165 ? `${MDN_URL}Web/HTTP/Reference/Status/${statusCode}` 166 : MDN_STATUS_CODES_LIST_URL) + getGAParams(panelId) 167 ); 168 } 169 170 /** 171 * Get the URL of the Timings tag for Network Monitor. 172 * 173 * @return {string} the URL of the Timings tag for Network Monitor. 174 */ 175 function getNetMonitorTimingsURL() { 176 return `${USER_DOC_URL}network_monitor/request_details/#network-monitor-request-details-timings-tab`; 177 } 178 179 /** 180 * Get the URL for Performance Analysis 181 * 182 * @return {string} The URL for the documentation of Performance Analysis. 183 */ 184 function getPerformanceAnalysisURL() { 185 return `${USER_DOC_URL}network_monitor/performance_analysis/`; 186 } 187 188 /** 189 * Get the URL for Filter box 190 * 191 * @return {string} The URL for the documentation of Filter box. 192 */ 193 function getFilterBoxURL() { 194 return `${USER_DOC_URL}network_monitor/request_list/#filtering-by-properties`; 195 } 196 197 /** 198 * Get the MDN URL for Tracking Protection 199 * 200 * @return {string} The MDN URL for the documentation of Tracking Protection. 201 */ 202 function getTrackingProtectionURL() { 203 return `${MDN_URL}Web/Privacy/Guides/Firefox_tracking_protection${getGAParams()}`; 204 } 205 206 /** 207 * Get the MDN URL for CORS error reason, falls back to generic cors error page 208 * if reason is not understood. 209 * 210 * @param {int} reason: Blocked Reason message from `netmonitor/src/constants.js` 211 * 212 * @returns {string} the MDN URL for the documentation of CORS errors 213 */ 214 function getCORSErrorURL(reason) { 215 // Map from blocked reasons from netmonitor/src/constants.js to the correct 216 // URL fragment to append to MDN_URL 217 const reasonMap = new Map([ 218 [1001, "CORSDisabled"], 219 [1002, "CORSDidNotSucceed"], 220 [1003, "CORSRequestNotHttp"], 221 [1004, "CORSMultipleAllowOriginNotAllowed"], 222 [1005, "CORSMissingAllowOrigin"], 223 [1006, "CORSNotSupportingCredentials"], 224 [1007, "CORSAllowOriginNotMatchingOrigin"], 225 [1008, "CORSMIssingAllowCredentials"], 226 [1009, "CORSOriginHeaderNotAdded"], 227 [1010, "CORSExternalRedirectNotAllowed"], 228 [1011, "CORSPreflightDidNotSucceed"], 229 [1012, "CORSInvalidAllowMethod"], 230 [1013, "CORSMethodNotFound"], 231 [1014, "CORSInvalidAllowHeader"], 232 [1015, "CORSMissingAllowHeaderFromPreflight"], 233 ]); 234 const urlFrag = reasonMap.get(reason) || ""; 235 return `${MDN_URL}Web/HTTP/Guides/CORS/Errors/${urlFrag}`; 236 } 237 238 module.exports = { 239 getHeadersURL, 240 getHTTPStatusCodeURL, 241 getNetMonitorTimingsURL, 242 getPerformanceAnalysisURL, 243 getFilterBoxURL, 244 getTrackingProtectionURL, 245 getCORSErrorURL, 246 };