ext/curl: expand CURLOPT_SEEKFUNCTION test coverage

Add curl_seekfunction_error.phpt covering the callback error paths — a
non-int return (TypeError), an out-of-range return (ValueError), a
throwing callback, the null reset, and a non-callable scalar — none of
which were previously exercised. Add curl_seekfunction_gc.phpt, which
builds a seek-closure/handle reference cycle so cycle collection
(curl_get_gc) is verified to reclaim it. Strengthen curl_seekfunction.phpt
to assert the callback argument contract (handle, offset, origin).

Also rename the awkward $offset_ parameter to $position and tidy the
curl_seek default-return comment and the copy test description.

Author: GrahamCampbell

ext/curl/interface.c

@@ -839,10 +839,7 @@ static size_t curl_read(char *data, size_t size, size_t nmemb, void *ctx)
 static int curl_seek(void *clientp, curl_off_t offset, int origin)
 {
 	php_curl *ch = (php_curl *)clientp;
-	/* Default to CANTSEEK so libcurl can fall back (or fail the rewind
-	   cleanly) when no callback is set or the callback misbehaves, rather
-	   than resending the body from the wrong offset. */
-	int rval = CURL_SEEKFUNC_CANTSEEK;
+	int rval = CURL_SEEKFUNC_CANTSEEK; /* safe default if unset or the callback misbehaves */
 
 #if PHP_CURL_DEBUG
 	fprintf(stderr, "curl_seek() called\n");

ext/curl/tests/curl_copy_handle_seek.phpt

@@ -1,5 +1,5 @@
 --TEST--
-Test curl_copy_handle() preserves CURLOPT_SEEKFUNCTION
+Test curl_copy_handle() with CURLOPT_SEEKFUNCTION
 --EXTENSIONS--
 curl
 --FILE--
@@ -21,12 +21,12 @@ curl_setopt($ch, CURLOPT_READFUNCTION, function ($ch, $fd, int $length) use ($bo
     $offset += strlen($chunk);
     return $chunk;
 });
-curl_setopt($ch, CURLOPT_SEEKFUNCTION, function ($ch, int $offset_, int $origin) use (&$offset, &$seekCalls) {
+curl_setopt($ch, CURLOPT_SEEKFUNCTION, function ($ch, int $position, int $origin) use (&$offset, &$seekCalls) {
     if ($origin !== SEEK_SET) {
         return CURL_SEEKFUNC_CANTSEEK;
     }
     $seekCalls++;
-    $offset = $offset_;
+    $offset = $position;
     return CURL_SEEKFUNC_OK;
 });
 

ext/curl/tests/curl_seekfunction.phpt

@@ -10,6 +10,7 @@ $host = curl_cli_server_start();
 $body = 'Hello cURL seek!';
 $offset = 0;
 $seekCalls = 0;
+$argsChecked = false;
 
 $ch = curl_init("{$host}/get.inc?test=redirect");
 curl_setopt($ch, CURLOPT_UPLOAD, true);
@@ -21,12 +22,18 @@ curl_setopt($ch, CURLOPT_READFUNCTION, function ($ch, $fd, int $length) use ($bo
     $offset += strlen($chunk);
     return $chunk;
 });
-curl_setopt($ch, CURLOPT_SEEKFUNCTION, function ($ch, int $offset_, int $origin) use (&$offset, &$seekCalls) {
+curl_setopt($ch, CURLOPT_SEEKFUNCTION, function ($ch, int $position, int $origin) use (&$offset, &$seekCalls, &$argsChecked) {
+    if (!$argsChecked) {
+        $argsChecked = true;
+        var_dump($ch instanceof CurlHandle);
+        var_dump($position === 0);
+        var_dump($origin === SEEK_SET);
+    }
     if ($origin !== SEEK_SET) {
         return CURL_SEEKFUNC_CANTSEEK;
     }
     $seekCalls++;
-    $offset = $offset_;
+    $offset = $position;
     return CURL_SEEKFUNC_OK;
 });
 
@@ -39,3 +46,6 @@ var_dump(str_contains($response, $body));
 --EXPECT--
 bool(true)
 bool(true)
+bool(true)
+bool(true)
+bool(true)

ext/curl/tests/curl_seekfunction_error.phpt

@@ -0,0 +1,77 @@
+--TEST--
+CURLOPT_SEEKFUNCTION callback error handling and option validation
+--EXTENSIONS--
+curl
+--FILE--
+<?php
+include 'server.inc';
+$host = curl_cli_server_start();
+
+// Drive a 307-redirect upload so libcurl invokes the seek callback to rewind
+// the body; $seek is the callback under test.
+function run_upload(string $host, callable $seek): void
+{
+    $offset = 0;
+    $body = 'Hello cURL seek!';
+    $ch = curl_init("{$host}/get.inc?test=redirect");
+    curl_setopt($ch, CURLOPT_UPLOAD, true);
+    curl_setopt($ch, CURLOPT_INFILESIZE, strlen($body));
+    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
+    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
+    curl_setopt($ch, CURLOPT_READFUNCTION, function ($ch, $fd, int $length) use ($body, &$offset) {
+        $chunk = substr($body, $offset, $length);
+        $offset += strlen($chunk);
+        return $chunk;
+    });
+    curl_setopt($ch, CURLOPT_SEEKFUNCTION, $seek);
+    curl_exec($ch);
+}
+
+echo "Returning a non-int:\n";
+try {
+    run_upload($host, fn($ch, $offset, $origin) => 'not an int');
+} catch (\TypeError $e) {
+    echo $e->getMessage(), "\n";
+}
+
+echo "\nReturning an out-of-range int:\n";
+try {
+    run_upload($host, fn($ch, $offset, $origin) => 42);
+} catch (\ValueError $e) {
+    echo $e->getMessage(), "\n";
+}
+
+echo "\nThrowing from the callback:\n";
+try {
+    run_upload($host, function ($ch, $offset, $origin) {
+        throw new \RuntimeException('boom from seek');
+    });
+} catch (\RuntimeException $e) {
+    echo $e->getMessage(), "\n";
+}
+
+echo "\nSetting the callback to null:\n";
+var_dump(curl_setopt(curl_init(), CURLOPT_SEEKFUNCTION, null));
+
+echo "\nSetting a non-callable scalar:\n";
+try {
+    curl_setopt(curl_init(), CURLOPT_SEEKFUNCTION, 42);
+} catch (\TypeError $e) {
+    echo $e->getMessage(), "\n";
+}
+?>
+--EXPECT--
+Returning a non-int:
+The CURLOPT_SEEKFUNCTION callback must return one of CURL_SEEKFUNC_OK, CURL_SEEKFUNC_FAIL or CURL_SEEKFUNC_CANTSEEK
+
+Returning an out-of-range int:
+The CURLOPT_SEEKFUNCTION callback must return one of CURL_SEEKFUNC_OK, CURL_SEEKFUNC_FAIL or CURL_SEEKFUNC_CANTSEEK
+
+Throwing from the callback:
+boom from seek
+
+Setting the callback to null:
+bool(true)
+
+Setting a non-callable scalar:
+curl_setopt(): Argument #3 ($value) must be a valid callback for option CURLOPT_SEEKFUNCTION, no array or string given

ext/curl/tests/curl_seekfunction_gc.phpt

@@ -0,0 +1,19 @@
+--TEST--
+CURLOPT_SEEKFUNCTION callback participates in cycle collection (curl_get_gc)
+--EXTENSIONS--
+curl
+--FILE--
+<?php
+// A seek callback that captures its own handle forms a reference cycle
+// (handle -> seek fcc -> closure -> handle). The cycle collector can only
+// reclaim it if curl_get_gc() exposes the seek fcc.
+$ch = curl_init();
+curl_setopt($ch, CURLOPT_SEEKFUNCTION, function ($handle, $offset, $origin) use ($ch) {
+    return CURL_SEEKFUNC_OK;
+});
+unset($ch);
+
+var_dump(gc_collect_cycles() > 0);
+?>
+--EXPECT--
+bool(true)