From aa862cd4ddefb8ff392e6f898676f9b8ca10f841 Mon Sep 17 00:00:00 2001
From: Marcus Deglos <marcus@deglos.com>
Date: Sat, 3 Mar 2012 05:19:52 +0000
Subject: [PATCH] Documented the architectural philosophy and design decisions.

---
 esi.module                         | 33 +++++++++++++++++++++++++++++-
 modules/esi_block/esi_block.module | 10 +++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/esi.module b/esi.module
index 4ac869a..e016623 100644
--- a/esi.module
+++ b/esi.module
@@ -3,8 +3,39 @@
  * @file
  *   Adds support for ESI (Edge-Side-Include) integration, allowing components\
  *   to be delivered by ESI, with support for per-component cache times.
+ *
+ * Architectural philosophy:
+ * - The ESI module provides a base API, but does not serve ESIs by itself.
+ * - Each ESI component (a block, a panel pane, etc) will require different
+ *   approaches for:
+ *   a) removing the original content from the page delivery.
+ *   b) replacing the content with an ESI tag.
+ *   c) dictating the level of context required to rebuild the original
+ *      component when delivering an ESI fragment.
+ *   d) constructing an ESI URL which contains all the required context
+ *      information.
+ *   Therefore, each ESI component will typically be a module by itself.
+ *   Separating components into individual modules will also help performance:
+ *   for example, sites which don't use panels will not be required to load
+ *   hooks and handlers for ESI-panels integration.
+ * - Each ESI component will have a menu path in the format:
+ *   /esi/{$esi_component_name}/any/context/information/required
+ * - ESI fragments will be delivered using a minimalist delivery method -
+ *   drupal_deliver_html_page() is not required or used; it is replaced by
+ *   esi_deliver_esi_component().
+ * - ESI's primary use-case is integration with Varnish, so the module is
+ *   optimised and primarily tested against Varnish (Varnish versions 2.x and
+ *   3.x).
+ * - Some components - for example, blocks - may vary according to user-roles.
+ *   Caching those fragments separately could unnecessarily increase the size
+ *   of cache needed, because the user's session cookie doesn't provide role
+ *   information to a proxy.  ESI provides a role cookie (and has an API to
+ *   provide any arbitrary context cookie) to allow proxies more-granular
+ *   control over fragment-cacheing. This will almost-certainly require custom
+ *   configuration of the proxy (the example VCLs demonstrate this for Varnish)
+ *   and some proxies may not have this capability, so will typically have a
+ *   lower cache-hit rate and may require a larger cache size to compensate.
  */
-
 // Default TTL for all components served by ESI is 5 minutes.
 define('ESI_DEFAULT_TTL', 300);
 
diff --git a/modules/esi_block/esi_block.module b/modules/esi_block/esi_block.module
index 5fe9f98..834ecdd 100644
--- a/modules/esi_block/esi_block.module
+++ b/modules/esi_block/esi_block.module
@@ -2,6 +2,16 @@
 /**
  * @file
  * ESI handler for blocks.
+ *
+ * Architectural philosophy:
+ * - Remove the existing block as early as possible, to avoid building the
+ *   contents of the block, only to throw them away.  This happens with
+ *   hook_block_list_alter().
+ * - Use the block's existing cache settings (DRUPAL_CACHE_PER_PAGE, etc) to
+ *   govern how the ESI URL is constructed, and the cache headers provided when
+ *   the ESI fragment is delivered.
+ * - Provide *no* theme furniture around the ESI tag. Ensure that the relevant
+ *   theme furniture is invoked to be delivered with the ESI fragment.
  */
 
 /**