armor/doc.go

   1 /*
   2 Package armor implements a data encoding scheme that satisfies the
   3 requirements of the AMP (Accelerated Mobile Pages) subset of HTML, and
   4 survives modification by an AMP cache. For the requirements of AMP HTML,
   5 see https://amp.dev/documentation/guides-and-tutorials/learn/spec/amphtml/.
   6 For modifications that may be made by an AMP cache, see
   7 https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-cache-modifications.md.
   8
   9 The encoding is based on ones created by Ivan Markin. See codec/amp/ in
  10 https://github.com/nogoegst/amper and discussion at
  11 https://bugs.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/25985.
  12
  13 The encoding algorithm works as follows. Base64-encode the input. Prepend the
  14 input with the byte '0'; this is a protocol version indicator that the decoder
  15 can use to determine how to interpret the bytes that follow. Split the base64
  16 into fixed-size chunks separated by whitespace. Take up to 1024 chunks at a
  17 time, and wrap them in a pre element. Then, situate the markup so far within the
  18 body of the AMP HTML boilerplate. The decoding algorithm is to scan the HTML for
  19 pre elements, split their text contents on whitespace and concatenate, then
  20 base64 decode. The base64 encoding uses the standard alphabet, with normal "="
  21 padding (https://tools.ietf.org/html/rfc4648#section-4).
  22
  23 The reason for splitting the base64 into chunks is that AMP caches reportedly
  24 truncate long strings that are not broken by whitespace:
  25 https://bugs.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake/25985#note_2592348.
  26 The characters that may separate the chunks are the ASCII whitespace characters
  27 (https://infra.spec.whatwg.org/#ascii-whitespace) "\x09", "\x0a", "\x0c",
  28 "\x0d", and "\x20". The reason for separating the chunks into pre elements is to
  29 limit the amount of text a decoder may have to buffer while parsing the HTML.
  30 Each pre element may contain at most 64 KB of text. pre elements may not be
  31 nested.
  32
  33 Example
  34
  35 The following is the result of encoding the string
  36 "This was encoded with AMP armor.":
  37
  38         <!doctype html>
  39         <html amp>
  40         <head>
  41         <meta charset="utf-8">
  42         <script async src="https://cdn.ampproject.org/v0.js"></script>
  43         <link rel="canonical" href="#">
  44         <meta name="viewport" content="width=device-width">
  45         <style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>
  46         </head>
  47         <body>
  48         <pre>
  49         0VGhpcyB3YXMgZW5jb2RlZCB3aXRoIEF
  50         NUCBhcm1vci4=
  51         </pre>
  52         </body>
  53         </html>
  54 */
  55 package armor