Clarify that there are two distinct types of cf object

ispivey · ispivey · commit ac0be79d607a · 2020-05-10T12:37:44.000-05:00
Fixes cloudflare#15. There are two distinct cf objects serves associated with a Request: 1. On an eyeball Request attached to a FetchEvent, the cf property contains metadata about the request, provided by Cloudflare's edge. 2. As part of a dictionary of configuration passed to the Request constructor, the cf property allows a user to control certain Cloudflare functionality that can be applied to said Request, like image resizing. While those two things are both objects in a dictionary with the key "cf", they are otherwise distinct. This change makes these two types explicitly different, and specifies that a Request constructor's RequestInit dict can have a "cf" property that is either (1) or (2). Previously, passing a Request object as the `init` arg to the Request constructor failed, because an eyeball request's cf prop did not have the same shape as (2).
diff --git a/index.d.ts b/index.d.ts
@@ -2,157 +2,169 @@ interface FetchEvent {
   passThroughOnException: () => void
 }
 
-interface RequestInit {
-  cf?: {
-    cacheEverything?: boolean
-    scrapeShield?: boolean
-    apps?: boolean
-    image?: {
-      /**
-       * Maximum width in image pixels. The value must be an integer.
-       */
-      width?: number
-      /**
-       * Maximum height in image pixels.
-       */
-      height?: number
-      /**
-       * Resizing mode as a string. It affects interpretation of width and height
-       * options:
-       *  - scale-down: Similar to contain, but the image is never enlarged. If
-       *    the image is larger than given width or height, it will be resized.
-       *    Otherwise its original size will be kept.
-       *  - contain: Resizes to maximum size that fits within the given width and
-       *    height. If only a single dimension is given (e.g. only width), the
-       *    image will be shrunk or enlarged to exactly match that dimension.
-       *    Aspect ratio is always preserved.
-       *  - cover: Resizes (shrinks or enlarges) to fill the entire area of width
-       *    and height. If the image has an aspect ratio different from the ratio
-       *    of width and height, it will be cropped to fit.
-       */
-      fit?: 'scale-down' | 'contain' | 'cover'
-      /**
-       * When cropping with fit: "cover", this defines the side or point that should
-       * be left uncropped. The value is either a string
-       * "left", "right", "top", "bottom" or "center" (the default),
-       * or an object {x, y} containing focal point coordinates in the original
-       * image expressed as fractions ranging from 0.0 (top or left) to 1.0
-       * (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will
-       * crop bottom or left and right sides as necessary, but won’t crop anything
-       * from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to
-       * preserve as much as possible around a point at 20% of the height of the
-       * source image.
-       */
-      gravity?: 'left' | 'right' | 'top' | 'bottom' | 'center' | { x: number; y: number }
-      /**
-       * Quality setting from 1-100 (useful values are in 60-90 range). Lower values
-       * make images look worse, but load faster. The default is 85. It applies only
-       * to JPEG and WebP images. It doesn’t have any effect on PNG.
-       */
-      quality?: number
-      /**
-       * Output format to generate. It can be:
-       *  - webp: generate images in Google WebP format. Set quality to 100 to get
-       *    the WebP-lossles format.
-       *  - json: instead of generating an image, outputs information about the
-       *    image, in JSON format. The JSON object will contain image size
-       *    (before and after resizing), source image’s MIME type, file size, etc.
-       */
-      format?: 'webp' | 'json'
-    }
-    minify?: {
-      javascript?: boolean
-      css?: boolean
-      html?: boolean
-    }
-    mirage?: boolean
-    /**
-     * Redirects the request to an alternate origin server. You can use this,
-     * for example, to implement load balancing across several origins.
-     * (e.g.us-east.example.com)
-     *
-     * Note - For security reasons, the hostname set in resolveOverride must
-     * be proxied on the same Cloudflare zone of the incoming request.
-     * Otherwise, the setting is ignored. CNAME hosts are allowed, so to
-     * resolve to a host under a different domain or a DNS only domain first
-     * declare a CNAME record within your own zone’s DNS mapping to the
-     * external hostname, set proxy on Cloudflare, then set resolveOverride
-     * to point to that CNAME record.
-     */
-    resolveOverride?: string
-  }
-}
-
-declare function addEventListener(
-  type: 'fetch',
-  handler: (event: FetchEvent) => void,
-): void
-
-interface Request {
-  /**
-   * In addition to the properties on the standard Request object,
-   * you can use a request.cf object to control how Cloudflare
-   * features are applied as well as other custom information provided
-   * by Cloudflare.
+interface CfRequestInit {
+   /**
+   * In addition to the properties you can set in the RequestInit dict
+   * that you pass as an argument to the Request constructor, you can
+   * set certain properties of a `cf` object to control how Cloudflare
+   * features are applied to that new Request.
    *
-   * Note: Currently, settings in the cf object cannot be tested in the
+   * Note: Currently, these properties cannot be tested in the
    * playground.
    */
-  cf: {
-    /**
-     *  (e.g. 395747)
-     */
-    asn: string
-    city: string
-    clientTrustScore: number
+  cacheEverything?: boolean
+  scrapeShield?: boolean
+  apps?: boolean
+  image?: {
     /**
-     * The three-letter airport code of the data center that the request
-     * hit. (e.g. "DFW")
+     * Maximum width in image pixels. The value must be an integer.
      */
-    colo: string
-    continent: string
+    width?: number
     /**
-     * The two-letter country code in the request. This is the same value
-     * as that provided in the CF-IPCountry header. (e.g. "US")
+     * Maximum height in image pixels.
      */
-    country: string
-    httpProtocol: string
-    latitude: number
-    longitude: number
-    postalCode: string
+    height?: number
     /**
-     * e.g. "Texas"
+     * Resizing mode as a string. It affects interpretation of width and height
+     * options:
+     *  - scale-down: Similar to contain, but the image is never enlarged. If
+     *    the image is larger than given width or height, it will be resized.
+     *    Otherwise its original size will be kept.
+     *  - contain: Resizes to maximum size that fits within the given width and
+     *    height. If only a single dimension is given (e.g. only width), the
+     *    image will be shrunk or enlarged to exactly match that dimension.
+     *    Aspect ratio is always preserved.
+     *  - cover: Resizes (shrinks or enlarges) to fill the entire area of width
+     *    and height. If the image has an aspect ratio different from the ratio
+     *    of width and height, it will be cropped to fit.
      */
-    region: string
+    fit?: 'scale-down' | 'contain' | 'cover'
     /**
-     * e.g. "TX"
+     * When cropping with fit: "cover", this defines the side or point that should
+     * be left uncropped. The value is either a string
+     * "left", "right", "top", "bottom" or "center" (the default),
+     * or an object {x, y} containing focal point coordinates in the original
+     * image expressed as fractions ranging from 0.0 (top or left) to 1.0
+     * (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will
+     * crop bottom or left and right sides as necessary, but won’t crop anything
+     * from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to
+     * preserve as much as possible around a point at 20% of the height of the
+     * source image.
      */
-    regionCode: string
+    gravity?: 'left' | 'right' | 'top' | 'bottom' | 'center' | { x: number; y: number }
     /**
-     * e.g. "weight=256;exclusive=1"
+     * Quality setting from 1-100 (useful values are in 60-90 range). Lower values
+     * make images look worse, but load faster. The default is 85. It applies only
+     * to JPEG and WebP images. It doesn’t have any effect on PNG.
      */
-    requestPriority: string
+    quality?: number
     /**
-     * e.g. "America/Chicago"
+     * Output format to generate. It can be:
+     *  - webp: generate images in Google WebP format. Set quality to 100 to get
+     *    the WebP-lossles format.
+     *  - json: instead of generating an image, outputs information about the
+     *    image, in JSON format. The JSON object will contain image size
+     *    (before and after resizing), source image’s MIME type, file size, etc.
      */
-    timezone: string
-    tlsVersion: string
-    tlsCipher: string
-    tlsClientAuth: {
-      certIssuerDNLegacy: string
-      certIssuerDN: string
-      certPresented: '0' | '1'
-      certSubjectDNLegacy: string
-      certSubjectDN: string
-      certNotBefore: string // In format "Dec 22 19:39:00 2018 GMT"
-      certNotAfter: string // In format "Dec 22 19:39:00 2018 GMT"
-      certSerial: string
-      certFingerprintSHA1: string
-      certVerified: string // “SUCCESS”, “FAILED:reason”, “NONE”
-    }
+    format?: 'webp' | 'json'
+  }
+  minify?: {
+    javascript?: boolean
+    css?: boolean
+    html?: boolean
+  }
+  mirage?: boolean
+  /**
+   * Redirects the request to an alternate origin server. You can use this,
+   * for example, to implement load balancing across several origins.
+   * (e.g.us-east.example.com)
+   *
+   * Note - For security reasons, the hostname set in resolveOverride must
+   * be proxied on the same Cloudflare zone of the incoming request.
+   * Otherwise, the setting is ignored. CNAME hosts are allowed, so to
+   * resolve to a host under a different domain or a DNS only domain first
+   * declare a CNAME record within your own zone’s DNS mapping to the
+   * external hostname, set proxy on Cloudflare, then set resolveOverride
+   * to point to that CNAME record.
+   */
+  resolveOverride?: string
+}
+
+interface CfRequestProperties {
+  /**
+   * In addition to the properties on the standard Request object,
+   * the cf object contains extra information about the request provided
+   * by Cloudflare's edge.
+   *
+   * Note: Currently, settings in the cf object cannot be accessed in the
+   * playground.
+   */
+  /**
+   *  (e.g. 395747)
+   */
+  asn: string
+  city: string
+  clientTrustScore: number
+  /**
+   * The three-letter airport code of the data center that the request
+   * hit. (e.g. "DFW")
+   */
+  colo: string
+  continent: string
+  /**
+   * The two-letter country code in the request. This is the same value
+   * as that provided in the CF-IPCountry header. (e.g. "US")
+   */
+  country: string
+  httpProtocol: string
+  latitude: number
+  longitude: number
+  postalCode: string
+  /**
+   * e.g. "Texas"
+   */
+  region: string
+  /**
+   * e.g. "TX"
+   */
+  regionCode: string
+  /**
+   * e.g. "weight=256;exclusive=1"
+   */
+  requestPriority: string
+  /**
+   * e.g. "America/Chicago"
+   */
+  timezone: string
+  tlsVersion: string
+  tlsCipher: string
+  tlsClientAuth: {
+    certIssuerDNLegacy: string
+    certIssuerDN: string
+    certPresented: '0' | '1'
+    certSubjectDNLegacy: string
+    certSubjectDN: string
+    certNotBefore: string // In format "Dec 22 19:39:00 2018 GMT"
+    certNotAfter: string // In format "Dec 22 19:39:00 2018 GMT"
+    certSerial: string
+    certFingerprintSHA1: string
+    certVerified: string // “SUCCESS”, “FAILED:reason”, “NONE”
   }
 }
 
+interface RequestInit {
+  cf?: CfRequestInit|CfRequestProperties
+}
+
+declare function addEventListener(
+  type: 'fetch',
+  handler: (event: FetchEvent) => void,
+): void
+
+interface Request {
+  cf: CfRequestProperties
+}
+
 interface ContentOptions {
   /**
    * Controls the way the HTMLRewriter treats inserted content.
