Merge pull request #118 from keyqcloud/feature/190-p1-pagination-guardrails

feat(190): pagination guardrails — max page size + unbounded-list backstop (P1)

Author: kennethphough

src/Core/Api.php

@@ -175,6 +175,15 @@ class Api
 		'STRICT_TYPING' => true,
 		'AUTH_STRATEGY_DISPATCHER' => 'off',
 		'KYTE_ACTIVITY_LOG_MAX_FIELD_BYTES' => 16384,
+		// Pagination guardrails (KYTE-#190). KYTE_MAX_PAGE_SIZE clamps a
+		// client-supplied X-Kyte-Page-Size (industry norm ~100). When a list
+		// request carries no page index it would otherwise return every row;
+		// KYTE_MAX_UNBOUNDED_ROWS is a generous backstop so it can't pull a
+		// whole large table (measure the truncation log, then tighten toward
+		// paginate-by-default). Controller-layer only — internal Model::retrieve
+		// stays unbounded. Both overridable per install in config.php.
+		'KYTE_MAX_PAGE_SIZE' => 100,
+		'KYTE_MAX_UNBOUNDED_ROWS' => 10000,
 	];
 
 	/**
@@ -369,6 +378,27 @@ public static function addKyteAttributes(&$modeldef) {
 		];
 	}
 
+	/**
+	 * Clamp a requested page size to a sane range (KYTE-#190 pagination
+	 * guardrail): capped at $max, and falling back to $default for a
+	 * non-positive value. Pure/static for unit testing.
+	 *
+	 * @param mixed $requested Raw client-supplied page size
+	 * @param int   $max       Hard maximum (KYTE_MAX_PAGE_SIZE)
+	 * @param int   $default   Fallback when the request is non-positive
+	 * @return int
+	 */
+	public static function clampPageSize($requested, $max, $default) {
+		$requested = intval($requested);
+		if ($requested < 1) {
+			return intval($default);
+		}
+		if ($requested > $max) {
+			return intval($max);
+		}
+		return $requested;
+	}
+
 	/**
      * Sets database credentials to the default database.
      */
@@ -1040,8 +1070,15 @@ private function validateRequest()
 			}
 		}
 
-		// set page size
-		$this->page_size = isset($_SERVER['HTTP_X_KYTE_PAGE_SIZE']) ? intval($_SERVER['HTTP_X_KYTE_PAGE_SIZE']) : PAGE_SIZE;
+		// set page size — pagination guardrail (KYTE-#190): clamp a client-
+		// supplied X-Kyte-Page-Size to KYTE_MAX_PAGE_SIZE (falling back to the
+		// default for a non-positive value) so no request can demand an
+		// oversized page.
+		$this->page_size = self::clampPageSize(
+			isset($_SERVER['HTTP_X_KYTE_PAGE_SIZE']) ? $_SERVER['HTTP_X_KYTE_PAGE_SIZE'] : 0,
+			KYTE_MAX_PAGE_SIZE,
+			PAGE_SIZE
+		);
 		// get page num from header
 		$this->page_num = isset($_SERVER['HTTP_X_KYTE_PAGE_IDX']) ? intval($_SERVER['HTTP_X_KYTE_PAGE_IDX']) : 0;
 

src/Mvc/Controller/ModelController.php

@@ -798,13 +798,39 @@ public function get($field, $value)
             if ($projection !== null) {
                 $objs->select($projection);
             }
-            $objs->retrieve($field, $value, $isLike, $conditions, $all, $order);
+
+            // Pagination guardrail (KYTE-#190): an unbounded HTTP list (no page
+            // index) is capped by a backstop so a client can't pull an entire
+            // large table. Paginated requests (page_num >= 1) manage their own
+            // LIMIT. A caller can opt out of the cap with X-Kyte-All: true (the
+            // truncation log below still records unbounded reads). Internal
+            // Model::retrieve calls don't pass through here, so they stay
+            // unbounded-capable.
+            $backstop = 0;
+            $optOutUnbounded = isset($_SERVER['HTTP_X_KYTE_ALL']) && $_SERVER['HTTP_X_KYTE_ALL'] === 'true';
+            if (!$this->api->page_num && !$optOutUnbounded) {
+                $backstop = KYTE_MAX_UNBOUNDED_ROWS;
+            }
+            $objs->retrieve($field, $value, $isLike, $conditions, $all, $order, $backstop);
 
             // get total count
             $this->api->total_count = $objs->total;
             $this->api->total_filtered = $objs->total_filtered;
             $this->api->page_total = ceil($this->api->total_filtered / $this->api->page_size);
 
+            // Log when the backstop actually truncated an unbounded list, so the
+            // real blast radius can be measured before the ceiling is tightened
+            // toward paginate-by-default.
+            if ($backstop > 0 && $objs->total_filtered > $backstop) {
+                error_log(sprintf(
+                    "KYTE-#190 pagination backstop: '%s' unbounded list capped to %d of %d rows (uri=%s)",
+                    $this->model['name'],
+                    $backstop,
+                    $objs->total_filtered,
+                    isset($_SERVER['REQUEST_URI']) ? $_SERVER['REQUEST_URI'] : ''
+                ));
+            }
+
             if ($this->failOnNull && count($objs->objects) < 1) {
                 throw new \Exception($this->exceptionMessages['get']['failOnNull']);
             }

tests/ApiTest.php

@@ -6,6 +6,20 @@
 class APiTest extends TestCase
 {
 
+    public function testClampPageSize() {
+        // within range -> unchanged
+        $this->assertSame(25, \Kyte\Core\Api::clampPageSize(25, 100, 50));
+        // over max -> clamped to max
+        $this->assertSame(100, \Kyte\Core\Api::clampPageSize(1000000, 100, 50));
+        $this->assertSame(100, \Kyte\Core\Api::clampPageSize(101, 100, 50));
+        // exactly max -> unchanged
+        $this->assertSame(100, \Kyte\Core\Api::clampPageSize(100, 100, 50));
+        // non-positive / non-numeric -> default
+        $this->assertSame(50, \Kyte\Core\Api::clampPageSize(0, 100, 50));
+        $this->assertSame(50, \Kyte\Core\Api::clampPageSize(-5, 100, 50));
+        $this->assertSame(50, \Kyte\Core\Api::clampPageSize('abc', 100, 50));
+    }
+
     public function testInitApiSuccess() {
         $api = new \Kyte\Core\Api();
 

tests/ModelTest.php

@@ -289,6 +289,13 @@ public function testCreateTable() {
         $this->assertTrue($model->retrieve('category', 'Test', false, null, true));
         $this->assertEquals(3, $model->count());
 
+        // test retrieve with a row limit (KYTE-#190 pagination-backstop
+        // mechanism): a $limit caps the returned rows even for an unbounded,
+        // non-paginated retrieve. Three rows match; limit 1 returns one.
+        $model = new \Kyte\Core\Model(TestTable);
+        $this->assertTrue($model->retrieve('category', 'Test', false, null, true, null, 1));
+        $this->assertEquals(1, $model->count());
+
         // test retrieve order by
         $model = new \Kyte\Core\Model(TestTable);
         $this->assertTrue($model->retrieve('category', 'Test', false, null, true, ['field' => 'category', 'direction' => 'asc']));