advanced build (1/2): a small refactor of index generating procedure; generation strategies

1 files changed, 64 insertions, 6 deletions

diff --git a/inc/config.php b/inc/config.php
index 82fdc882..91804429 100644
--- a/inc/config.php
+++ b/inc/config.php
@@ -1203,16 +1203,74 @@
 	// Try not to build pages when we shouldn't have to.
 	$config['try_smarter'] = true;
 
-	// EXPERIMENTAL: Defer static HTML building to a moment, when a given file is actually accessed.
-	// Warning: This option won't run out of the box. You need to tell your webserver, that a file
-	// for serving 403 and 404 pages is /smart_build.php. Also, you need to turn off indexes.
+/*
+ * ====================
+ *  Advanced build
+ * ====================
+ */
+
+	// Strategies for file generation. Also known as an "advanced build". If you don't have performance
+	// issues, you can safely ignore that part, because it's hard to configure and won't even work on
+	// your free webhosting.
+	//
+	// A strategy is a function, that given the PHP environment and ($fun, $array) variable pair, returns
+	// an $action array or false.
+	//
+	// $fun - a controller function name, see inc/controller.php. This is named after functions, so that
+	//        we can generate the files in daemon.
+	//
+	// $array - arguments to be passed
+	//
+	// $action - action to be taken. It's an array, and the first element of it is one of the following:
+	//   * "immediate" - generate the page immediately
+	//   * "defer" - defer page generation to a moment a worker daemon gets to build it (serving a stale
+	//               page in the meantime). The remaining arguments are daemon-specific. Daemon isn't
+	//               implemented yet :DDDD inb4 while(true) { generate(Queue::Get()) }; (which is probably it).
+	//   * "build_on_load" - defer page generation to a moment, when the user actually accesses the page.
+	//                       This is a smart_build behaviour. You shouldn't use this one too much, if you
+	//                       use it for active boards, the server may choke due to a possible race condition.
+	//                       See my blog post: https://engine.vichan.net/blog/res/2.html
+	//
+	// So, let's assume we want to build a thread 1324 on board /b/, because a new post appeared there.
+	// We try the first strategy, giving it arguments: 'sb_thread', array('b', 1324). The strategy will
+	// now return a value $action, denoting an action to do. If $action is false, we try another strategy.
+	//
+	// As I said, configuration isn't easy.
+	//
+	// 1. chmod 0777 directories: tmp/locks/ and tmp/queue/.
+	// 2. serve 403 and 404 requests to go thru smart_build.php
+	//    for nginx, this blog post contains config snippets: https://engine.vichan.net/blog/res/2.html
+	// 3. disable indexes in your webserver
+	// 4. launch any number of daemons (eg. twice your number of threads?) using the command:
+	//    $ tools/worker.php
+	//    You don't need to do that step if you are not going to use the "defer" option.
+	// 5. enable smart_build_helper (see below)
+	// 6. edit the strategies (see inc/functions.php for the builtin ones). You can use lambdas. I will test
+	//    various ones and include one that works best for me.
+	$config['generation_strategies'] = array();
+	// Add a sane strategy. It forces to immediately generate a page user is about to land on. Otherwise,
+	// it has no opinion, so it needs a fallback strategy.
+	$config['generation_strategies'][] = 'strategy_sane';
+	// Add an immediate catch-all strategy. This is the default function of imageboards: generate all pages
+	// on post time.
+	$config['generation_strategies'][] = 'strategy_immediate';
+	// NOT RECOMMENDED: Instead of an all-"immediate" strategy, you can use an all-"build_on_load" one (used
+	// to be initialized using $config['smart_build']; ) for all pages instead of those to be build
+	// immediately. A rebuild done in this mode should remove all your static files
+	// $config['generation_strategies'][1] = 'strategy_smart_build';
+
+	// Deprecated. Leave it false. See above.
 	$config['smart_build'] = false;
 
-	// Smart build related: when a file doesn't exist, where should we redirect?
+	// Use smart_build.php for dispatching missing requests. It may be useful without smart_build or advanced
+	// build, for example it will regenerate the missing files.
+	$config['smart_build_helper'] = true;
+
+	// smart_build.php: when a file doesn't exist, where should we redirect?
 	$config['page_404'] = '/404.html';
 
-	// Smart build related: extra entrypoints.
-	$config['smart_build_entrypoints'] = array();
+	// Extra controller entrypoints. Controller is used only by smart_build and advanced build.
+	$config['controller_entrypoints'] = array();
 
 /*
  * ====================