feat: configurable per-module sandbox stack size (#394)

The sandbox execution stack was fixed at WASM_STACK_SIZE (512 KB). The
module already carried a stack_size field and module_init already honored
a non-zero value (falling back to WASM_STACK_SIZE), but the size was
hardcoded to 0, so it was always the default.

Expose it as an optional "stack-size" route config field (bytes). It is
parsed into route_config, passed through module_alloc/module_init, rounded
up to a page, and flows into per-sandbox allocation via the existing
wasm_stack_alloc(module->stack_size). Omitting it (or 0) keeps the
WASM_STACK_SIZE default, so existing specs are unaffected.

Granularity is per-module (keyed by the .so path) because the stack pool
is sized per-module; a true per-route size for a shared module would break
the pool. The first route to create a module sets its stack size; a later
route requesting a different size for an already-created module is warned
and the existing size is kept. Preprocess modules use the default.

Verified: builds; applied size tracks the config exactly (1 MB -> 1048576,
16 KB -> 16384), omitting the field yields the 524288 default, and an
unmodified spec still serves resize requests byte-identically (10/10).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bushidocodes

runtime/include/module.h

@@ -42,7 +42,7 @@ struct module {
  *******************************/
 
 void           module_free(struct module *module);
-struct module *module_alloc(char *path, enum module_type type);
+struct module *module_alloc(char *path, enum module_type type, uint32_t stack_size);
 
 /*************************
  * Public Static Inlines *

runtime/include/route_config.h

@@ -21,6 +21,7 @@ enum route_config_member
 	route_config_member_model_beta1,
 	route_config_member_model_beta2,
 	route_config_member_http_resp_content_type,
+	route_config_member_stack_size,
 	route_config_member_len
 };
 
@@ -36,6 +37,7 @@ struct route_config {
 	uint32_t model_beta1;
 	uint32_t model_beta2;
 	char    *http_resp_content_type;
+	uint32_t stack_size; /* in bytes; 0 means use the runtime default (WASM_STACK_SIZE) */
 };
 
 static inline void
@@ -57,6 +59,7 @@ route_config_print(struct route_config *config)
 	printf("[Route] Admissions Percentile: %hhu\n", config->admissions_percentile);
 	printf("[Route] Relative Deadline (us): %u\n", config->relative_deadline_us);
 	printf("[Route] HTTP Response Content Type: %s\n", config->http_resp_content_type);
+	printf("[Route] Stack Size (bytes, 0=default): %u\n", config->stack_size);
 #ifdef EXECUTION_HISTOGRAM
 	printf("[Route] Path of Preprocessing Module: %s\n", config->path_preprocess);
 	printf("[Route] Model Bias: %u\n", config->model_bias);

runtime/include/route_config_parse.h

@@ -9,7 +9,7 @@
 static const char *route_config_json_keys[route_config_member_len] =
   {"route",           "path",        "admissions-percentile", "relative-deadline-us",
    "path_preprocess", "model-bias",  "model-scale",           "model-num-of-param",
-   "model-beta1",     "model-beta2", "http-resp-content-type"};
+   "model-beta1",     "model-beta2", "http-resp-content-type", "stack-size"};
 
 static inline int
 route_config_set_key_once(bool *did_set, enum route_config_member member)
@@ -132,6 +132,14 @@ route_config_parse(struct route_config *config, const char *json_buf, jsmntok_t
 
 			config->http_resp_content_type = strndup(json_buf + tokens[i].start,
 			                                         tokens[i].end - tokens[i].start);
+		} else if (strcmp(key, route_config_json_keys[route_config_member_stack_size]) == 0) {
+			if (!has_valid_type(tokens[i], key, JSMN_PRIMITIVE, json_buf)) return -1;
+			if (route_config_set_key_once(did_set, route_config_member_stack_size) == -1) return -1;
+
+			int rc = parse_uint32_t(tokens[i], json_buf,
+			                        route_config_json_keys[route_config_member_stack_size],
+			                        &config->stack_size);
+			if (rc < 0) return -1;
 		} else {
 			fprintf(stderr, "%s is not a valid key\n", key);
 			return -1;

runtime/include/tenant_functions.h

@@ -103,12 +103,22 @@ tenant_alloc(struct tenant_config *config)
 		struct module *module = module_database_find_by_path(&tenant->module_db, config->routes[i].path);
 		if (module == NULL) {
 			/* Ownership of path moves here */
-			module = module_alloc(config->routes[i].path, APP_MODULE);
+			module = module_alloc(config->routes[i].path, APP_MODULE, config->routes[i].stack_size);
 			if (module != NULL) {
 				module_database_add(&tenant->module_db, module);
 				config->routes[i].path = NULL;
 			}
 		} else {
+			/* The module (keyed by path) already exists, so its stack size is fixed. The stack pool is
+			 * sized per-module, so a route cannot request a different stack size for a shared module. */
+			if (config->routes[i].stack_size != 0
+			    && round_up_to_page(config->routes[i].stack_size) != module->stack_size) {
+				fprintf(stderr,
+				        "Warning: route %s requested stack-size %u for %s, but that module already "
+				        "exists with stack size %u; keeping the existing size.\n",
+				        config->routes[i].route, config->routes[i].stack_size, config->routes[i].path,
+				        module->stack_size);
+			}
 			free(config->routes[i].path);
 			config->routes[i].path = NULL;
 		}
@@ -123,7 +133,8 @@ tenant_alloc(struct tenant_config *config)
 			                                                 config->routes[i].path_preprocess);
 			if (module_proprocess == NULL) {
 				/* Ownership of path moves here */
-				module_proprocess = module_alloc(config->routes[i].path_preprocess, PREPROCESS_MODULE);
+				module_proprocess = module_alloc(config->routes[i].path_preprocess, PREPROCESS_MODULE,
+				                                 0 /* preprocess modules use the default stack size */);
 				if (module_proprocess != NULL) {
 					module_database_add(&tenant->module_db, module_proprocess);
 					config->routes[i].path_preprocess = NULL;

runtime/src/module.c

@@ -29,14 +29,12 @@
  * @returns 0 on success, -1 on error
  */
 static inline int
-module_init(struct module *module, char *path)
+module_init(struct module *module, char *path, uint32_t stack_size)
 {
 	assert(module != NULL);
 	assert(path != NULL);
 	assert(strlen(path) > 0);
 
-	uint32_t stack_size = 0;
-
 	int rc = 0;
 
 	atomic_init(&module->reference_count, 0);
@@ -49,6 +47,7 @@ module_init(struct module *module, char *path)
 
 	module->path = path;
 
+	/* A stack_size of 0 means the config did not specify one, so fall back to the runtime default. */
 	module->stack_size = ((uint32_t)(round_up_to_page(stack_size == 0 ? WASM_STACK_SIZE : stack_size)));
 
 	module_alloc_table(module);
@@ -107,7 +106,7 @@ module_free(struct module *module)
  */
 
 struct module *
-module_alloc(char *path, enum module_type type)
+module_alloc(char *path, enum module_type type, uint32_t stack_size)
 {
 	size_t alignment     = (size_t)CACHE_PAD;
 	size_t size_to_alloc = (size_t)round_to_cache_pad(sizeof(struct module));
@@ -123,7 +122,7 @@ module_alloc(char *path, enum module_type type)
 	memset(module, 0, size_to_alloc);
 	module->type = type;
 
-	int rc = module_init(module, path);
+	int rc = module_init(module, path, stack_size);
 	if (rc < 0) goto init_err;
 
 done: