Overbryd/0-README.md

## 0-README.md

      
        

          Raw
        
        
          
            
          
          
            
              0-README.md
            
          
        
      
    
  
    Cloudflare fragment rendering/caching
This worker script will evaluate your origin response, and replace html comments marked as fragment:key with a respective prefetch defined in a X-Fragments response header.
Usage
Your origin must include the X-Fragments header, specifying the a comma separated list of prefetch requests to make for that response.
< HTTP/1.1 200 OK
< Content-Type: text/html
< Content-Length: 3825
< X-Fragments: header http://localhost:8080/header.html, footer http://localhost:8080/footer.html

Or multiple X-Fragments header work too:
< HTTP/1.1 200 OK
< Content-Type: text/html
< Content-Length: 3825
< X-Fragments: header https://yoursite.com/header.html
< X-Fragments: footer https://yoursite.com/footer.html

All prefetches happen asynchronously in parallel.
Then in your response body, you can have specific html comments that will be replaced by the prefetched responses.
<!DOCTYPE HTML>
<html>
  <head>
    <!-- fragment:header -->
    <title>Cloudflare Fragments</title>
  </head>
  <body>
    Some of your body content.
    <!-- fragment:footer
      <p>This would be the fallback content if
         'footer' does not fetch in time,
         is unspecified
         or does not respond successfully</p>
    -->
  </body>
</html>

  

  

## worker.js
/* Define regular expressions at top to have them precompiled.
 */
const htmlContentType = new RegExp('text\/html', 'i')
const fragmentStart = new RegExp('<!-- fragment:(\\w+)( -->)?')
const commentEnd = new RegExp('-->')

addEventListener('fetch', event => {
  event.respondWith(main(event.request))
})

/* The main entry function
*/
async function main(request) {
  const response = await fetch(request)
  const fragments = prefetchFragments(response.headers)

  return transformResponse(response, fragments)
}

/* Build a dictionary of promises that we can evaluate later.
 * These fetch or timeout.
 *
 * The overall timeout is shared by each promise. The cumulative amount of time, that
 * all fetch-requests can spend is 10 seconds.
 *
 * Each fetch request defined in the headers gets a fair share.
 * We let the promises race and later fail gracefully when the fetch does not return in time.
 *
 * This is an important circuit-breaker mechanism, to not fail the main request.
 */
function prefetchFragments(headers) {
  const header = headers.get('X-Fragments')
  if (header === null) return {}

  const fragments = {}
  const values = header.split(',')
  const safeTimeout = 10000 / values.length

  values.forEach((entry) => {
    const [key, url] = entry.trim().split(' ')
    const request = new Request(url)
    const timeout = new Promise((resolve, reject) => {
      const wait = setTimeout(() => {
        clearTimeout(wait)
        reject()
      }, safeTimeout)
    })

    fragments[key] = Promise.race([
      fetch(request),
      timeout
    ])
  })

  return fragments
}

/*
 * Here we decide whether we are going to stream & parse the response body,
 * or just return the response as is, since the request is not eligble for fragments.
 *
 * Only Content-Type: text/html responses with one or more fragments are going to be evaluated.
 */
function transformResponse(response, fragments) {
  const contentType = response.headers.get('Content-Type')

  if (
    contentType
    && htmlContentType.test(contentType)
    && Object.keys(fragments).length > 0
  ) {
    const { readable, writable } = new TransformStream()
    transformBody(response.body, writable, fragments)
    return new Response(readable, response)
  } else {
    return response
  }
}

/*
 * This function transforms the origin response body.
 *
 * It assumes the response to be utf-8 encoded
 */
async function transformBody(body, writable, fragments) {
  const encoding = new TextDecoder('utf-8')
  const reader = body.getReader()
  const writer = writable.getWriter()

  // initialise the parser state
  let state = {writer: writer, fragments: fragments}
  let fun = parse
  let lastLine = ""

  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    const buffer = encoding.decode(value, {stream: !done})
    const lines = (lastLine + buffer).split("\n")

    /* This loop is basically a parse-tree keeping state between each line.
     *
     * But most important, is to not include the last line.
     * The response chunks, might be cut-off just in the middle of a line, and thus not representing
     * a full line that can be reasoned about.
     *
     * Therefore we keep the last line, and concatenate it with the next lines.
     */
    let i = 0;
    const length = lines.length - 1;
    for (; i < length; i++) {
      const line = lines[i]
      const resp = await fun(state, line)
      let [nextFun, newState] = resp
      fun = nextFun
      state = newState
    }
    lastLine = lines[length] || ""

  }

  endParse(state)

  await writer.close()
}

/*
 * This is the main parser function.
 * The state machine goes like this:
 *
 * parse
 *       -> ON fragmentMatch with fallback
 *        > parseFragmentFallback
 *
 *       -> ON fragmentMatch without fallback
 *        > parse
 *
 * parseFragmentFallback
 *                       -> ON closing comment
 *                        > parse
 */
async function parse(state, line) {
  const fragmentMatch = line.match(fragmentStart)

  if (fragmentMatch) {
    const [match, key, fragmentEnd] = fragmentMatch
    const fragmentPromise = state.fragments[key]

    if (fragmentEnd && fragmentPromise) {
      await writeFragment(fragmentPromise, state.writer, line + "\n")
      return [parse, state]
    } else if (fragmentPromise) {
      state.fragmentPromise = state.fragments[key]
      state.fallbackBuffer = ""

      write(state.writer, line.replace(fragmentStart, ""))
      return [parseFragmentFallback, state]
    }
  }

  write(state.writer, line + "\n")
  return [parse, state]
}

/*
 * This is a sub-state, that is looking for a closing comment --> to terminate the fallback.
 * It will keep buffering the response to build the fallback buffer.
 *
 * When it finds a `-->` on a line, it will attempt to write the fragment.
 */
async function parseFragmentFallback(state, line) {
  if (commentEnd.test(line)) {
    await writeFragment(state.fragmentPromise, state.writer, state.fallbackBuffer)
    state.fragmentPromise = null
    state.fallbackBuffer = null

    write(state.writer, line.replace(commentEnd, "\n"))
    return [parse, state]
  } else {
    state.fallbackBuffer = state.fallbackBuffer + line + "\n"
    return [parseFragmentFallback, state]
  }
}

/*
 * This is called after traversing all lines.
 * If we have accumulated fallback buffer until here,
 * we might want to dump the response, because someone forgot to add an closing '-->' comment tag.
 */
async function endParse(state) {
  if (state.fallbackBuffer !== null) {
    write(state.writer, state.fallbackBuffer)
  }
}

/*
 * This function handles a fragment.
 * In order for a fragment to render, it must fetch in time and respond with a success state.
 *
 * The function will attempt to resolve the promise and pipe any successful response directly
 * to the main response. Blocking until the fragment response is consumed.
 *
 * If the fragment does not respond in time (a timeout happened), we attempt to render a fallback.
 *
 * If the fragment response is not succesful, we attempt to render a fallback.
 */
async function writeFragment(fragmentPromise, writer, fallbackResponse) {
  try {
    const fragmentResponse = await fragmentPromise

    if (fragmentResponse.ok) {
      await pipe(fragmentResponse.body.getReader(), writer)
    } else {
      write(writer, fallbackResponse)
    }

  } catch(e) {
    write(writer, fallbackResponse)
  }
}

/*
 * Helper function to pipe one stream into the other.
 */
async function pipe(reader, writer) {
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    await writer.write(value)
  }
}

/*
 * Helper function to write an utf-8 string to a stream.
 */
async function write(writer, str) {
  const bytes = new TextEncoder('utf-8').encode(str)
  await writer.write(bytes)
}
	/* Define regular expressions at top to have them precompiled.
	*/
	const htmlContentType = new RegExp('text\/html', 'i')
	const fragmentStart = new RegExp('<!-- fragment:(\\w+)( -->)?')
	const commentEnd = new RegExp('-->')

	addEventListener('fetch', event => {
	event.respondWith(main(event.request))
	})

	/* The main entry function
	*/
	async function main(request) {
	const response = await fetch(request)
	const fragments = prefetchFragments(response.headers)

	return transformResponse(response, fragments)
	}

	/* Build a dictionary of promises that we can evaluate later.
	* These fetch or timeout.
	*
	* The overall timeout is shared by each promise. The cumulative amount of time, that
	* all fetch-requests can spend is 10 seconds.
	*
	* Each fetch request defined in the headers gets a fair share.
	* We let the promises race and later fail gracefully when the fetch does not return in time.
	*
	* This is an important circuit-breaker mechanism, to not fail the main request.
	*/
	function prefetchFragments(headers) {
	const header = headers.get('X-Fragments')
	if (header === null) return {}

	const fragments = {}
	const values = header.split(',')
	const safeTimeout = 10000 / values.length

	values.forEach((entry) => {
	const [key, url] = entry.trim().split(' ')
	const request = new Request(url)
	const timeout = new Promise((resolve, reject) => {
	const wait = setTimeout(() => {
	clearTimeout(wait)
	reject()
	}, safeTimeout)
	})

	fragments[key] = Promise.race([
	fetch(request),
	timeout
	])
	})

	return fragments
	}

	/*
	* Here we decide whether we are going to stream & parse the response body,
	* or just return the response as is, since the request is not eligble for fragments.
	*
	* Only Content-Type: text/html responses with one or more fragments are going to be evaluated.
	*/
	function transformResponse(response, fragments) {
	const contentType = response.headers.get('Content-Type')

	if (
	contentType
	&& htmlContentType.test(contentType)
	&& Object.keys(fragments).length > 0
	) {
	const { readable, writable } = new TransformStream()
	transformBody(response.body, writable, fragments)
	return new Response(readable, response)
	} else {
	return response
	}
	}

	/*
	* This function transforms the origin response body.
	*
	* It assumes the response to be utf-8 encoded
	*/
	async function transformBody(body, writable, fragments) {
	const encoding = new TextDecoder('utf-8')
	const reader = body.getReader()
	const writer = writable.getWriter()

	// initialise the parser state
	let state = {writer: writer, fragments: fragments}
	let fun = parse
	let lastLine = ""

	while (true) {
	const { done, value } = await reader.read()
	if (done) break
	const buffer = encoding.decode(value, {stream: !done})
	const lines = (lastLine + buffer).split("\n")

	/* This loop is basically a parse-tree keeping state between each line.
	*
	* But most important, is to not include the last line.
	* The response chunks, might be cut-off just in the middle of a line, and thus not representing
	* a full line that can be reasoned about.
	*
	* Therefore we keep the last line, and concatenate it with the next lines.
	*/
	let i = 0;
	const length = lines.length - 1;
	for (; i < length; i++) {
	const line = lines[i]
	const resp = await fun(state, line)
	let [nextFun, newState] = resp
	fun = nextFun
	state = newState
	}
	lastLine = lines[length] \|\| ""

	}

	endParse(state)

	await writer.close()
	}

	/*
	* This is the main parser function.
	* The state machine goes like this:
	*
	* parse
	* -> ON fragmentMatch with fallback
	* > parseFragmentFallback
	*
	* -> ON fragmentMatch without fallback
	* > parse
	*
	* parseFragmentFallback
	* -> ON closing comment
	* > parse
	*/
	async function parse(state, line) {
	const fragmentMatch = line.match(fragmentStart)

	if (fragmentMatch) {
	const [match, key, fragmentEnd] = fragmentMatch
	const fragmentPromise = state.fragments[key]

	if (fragmentEnd && fragmentPromise) {
	await writeFragment(fragmentPromise, state.writer, line + "\n")
	return [parse, state]
	} else if (fragmentPromise) {
	state.fragmentPromise = state.fragments[key]
	state.fallbackBuffer = ""

	write(state.writer, line.replace(fragmentStart, ""))
	return [parseFragmentFallback, state]
	}
	}

	write(state.writer, line + "\n")
	return [parse, state]
	}

	/*
	* This is a sub-state, that is looking for a closing comment --> to terminate the fallback.
	* It will keep buffering the response to build the fallback buffer.
	*
	* When it finds a `-->` on a line, it will attempt to write the fragment.
	*/
	async function parseFragmentFallback(state, line) {
	if (commentEnd.test(line)) {
	await writeFragment(state.fragmentPromise, state.writer, state.fallbackBuffer)
	state.fragmentPromise = null
	state.fallbackBuffer = null

	write(state.writer, line.replace(commentEnd, "\n"))
	return [parse, state]
	} else {
	state.fallbackBuffer = state.fallbackBuffer + line + "\n"
	return [parseFragmentFallback, state]
	}
	}

	/*
	* This is called after traversing all lines.
	* If we have accumulated fallback buffer until here,
	* we might want to dump the response, because someone forgot to add an closing '-->' comment tag.
	*/
	async function endParse(state) {
	if (state.fallbackBuffer !== null) {
	write(state.writer, state.fallbackBuffer)
	}
	}

	/*
	* This function handles a fragment.
	* In order for a fragment to render, it must fetch in time and respond with a success state.
	*
	* The function will attempt to resolve the promise and pipe any successful response directly
	* to the main response. Blocking until the fragment response is consumed.
	*
	* If the fragment does not respond in time (a timeout happened), we attempt to render a fallback.
	*
	* If the fragment response is not succesful, we attempt to render a fallback.
	*/
	async function writeFragment(fragmentPromise, writer, fallbackResponse) {
	try {
	const fragmentResponse = await fragmentPromise

	if (fragmentResponse.ok) {
	await pipe(fragmentResponse.body.getReader(), writer)
	} else {
	write(writer, fallbackResponse)
	}

	} catch(e) {
	write(writer, fallbackResponse)
	}
	}

	/*
	* Helper function to pipe one stream into the other.
	*/
	async function pipe(reader, writer) {
	while (true) {
	const { done, value } = await reader.read()
	if (done) break
	await writer.write(value)
	}
	}

	/*
	* Helper function to write an utf-8 string to a stream.
	*/
	async function write(writer, str) {
	const bytes = new TextEncoder('utf-8').encode(str)
	await writer.write(bytes)
	}