feat(sdk): support per-method parameter overrides in spec generation (#12904)

* feat(sdk): support per-method parameter overrides in spec generation

A Method's parameters list previously only applied to additional methods;
the primary method's spec always mirrored the route params. Honor it for
the primary method too: entries override route params by name, and a new
Parameter hide flag drops a param from the spec while the route keeps
accepting it at runtime — for routes shared across scopes where a param
is only meaningful on some of them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(functions): report positive buildDuration when jobs callbacks arrive out of order

The jobs worker stamps buildStartedAt on the first log callback, but the
jobs-service delivers callbacks out of order: when exit/complete land
before any log line, finalize fell back to 'now' and second-resolution
subtraction reported buildDuration 0 for a finished build. This flaked
FunctionsCustomServerTest::testGetDeployment (assertGreaterThan(0, ...))
on this PR's CI and previously on main (65056998da re-triggered CI for
the same failure).

Compute the duration with sub-second precision and round up so any
finished build reports at least 1 second, matching the executor Builds
worker's ceil semantics, and fall back to the deployment's creation time
when buildStartedAt was never stamped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sdk): honor null default overrides and parameter hiding in GraphQL

Parameter's constructor defaulted `default` to null, so an explicit
`default: null` override was indistinguishable from no override and got
filtered out — the spec kept the route default. Use an Undefined sentinel
so explicit null clears a route default while unset still means inherit.

The GraphQL mapper treated a method's parameters purely as a whitelist,
so a hide-only list inverted intent: the hidden param became the only
one exposed. Hidden params are now always excluded, listed params keep
their whitelist role with optional/validator/description overrides
applied, and a list with no visible entries falls back to the route
params minus the hidden ones — matching the OpenAPI semantics without
breaking the bulk-method whitelists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(sdk): apply optional overrides to spec params via unset sentinel

optional defaulted to false, so an unset flag was indistinguishable from
an explicit optional: false and the OpenAPI merge skipped it entirely —
while GraphQL applied it, letting the same method emit a required GraphQL
argument but an optional OpenAPI field. Reuse the Undefined sentinel so
only an explicitly set flag overrides the route in both formats.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jake BarnbyandClaude Fable 5 authored and GitHub committed 2026-07-17 23:15:39 +12:00
1 parent dc3cf93c2e
commit b664671af9
9 files changed
+348 -27

No files matched your search

+22 -15
View File
@@ -108,6 +108,16 @@ class Mapper
}
}
$hidden = [];
$overrides = [];
foreach ($method->getParameters() as $sdkParameter) {
if ($sdkParameter->getHide()) {
$hidden[$sdkParameter->getName()] = true;
continue;
}
$overrides[$sdkParameter->getName()] = $sdkParameter;
}
foreach ($models as $model) {
$type = Mapper::model(\ucfirst($model->getType()));
$description = $route->getDesc();
@@ -115,36 +125,33 @@ class Mapper
$list = false;
foreach ($route->getParams() as $name => $parameter) {
$sdkParameters = $method->getParameters();
if (isset($hidden[$name])) {
continue;
}
if (!empty($sdkParameters)) {
$sdkMethodParameters = [];
foreach ($sdkParameters as $sdkParameter) {
$sdkMethodParameters[$sdkParameter->getName()] = $sdkParameter;
}
$override = $overrides[$name] ?? null;
if (!\array_key_exists($name, $sdkMethodParameters)) {
continue;
}
$optional = $sdkMethodParameters[$name]->getOptional();
} else {
$optional = $parameter['optional'];
if (!empty($overrides) && $override === null) {
continue;
}
if ($name === 'queries') {
$list = true;
}
$optional = $override !== null && $override->hasOptional()
? $override->getOptional()
: $parameter['optional'];
$parameterType = Mapper::param(
$utopia,
$parameter['validator'],
$override?->getValidator() ?? $parameter['validator'],
!$optional,
$parameter['injections']
);
$params[$name] = [
'type' => $parameterType,
'description' => $parameter['description'],
'description' => $override?->getDescription() ?: $parameter['description'],
];
}
@@ -299,14 +299,13 @@ class Jobs extends Action
$function = $dbForProject->getDocument('functions', $deployment->getAttribute('resourceId'));
$logs = $deployment->getAttribute('buildLogs', '');
$startedAt = \strtotime($deployment->getAttribute('buildStartedAt', '') ?: 'now') ?: \time();
$trailer = $success
? "\033[90m[" . \date('H:i:s') . "] \033[90m[\033[0mappwrite\033[90m]\033[32m Deployment finished. \033[0m\n"
: "\n" . ($message !== '' ? $message : 'Build failed.') . "\n";
$update = [
'status' => $success ? 'ready' : 'failed',
'buildEndedAt' => DateTime::now(),
'buildDuration' => \max(0, \time() - $startedAt),
'buildDuration' => $this->duration($deployment),
'buildLogs' => $this->truncate($logs . $trailer),
];
if ($success) {
@@ -352,6 +351,29 @@ class Jobs extends Action
return $deployment;
}
/**
* Elapsed build seconds, rounded up so any finished build reports at least
* 1 (mirrors the executor Builds worker). Callbacks arrive out of order, so
* buildStartedAt (stamped by the first log callback) can be missing when a
* terminal callback finalizes first — fall back to the deployment's
* creation time rather than reporting 0.
*/
private function duration(Document $deployment): int
{
$startedAt = $deployment->getAttribute('buildStartedAt', '') ?: $deployment->getCreatedAt();
if (empty($startedAt)) {
return 0;
}
try {
$started = (float) (new \DateTimeImmutable($startedAt))->format('U.u');
} catch (\Exception) {
return 0;
}
return (int) \ceil(\max(0.0, \microtime(true) - $started));
}
/**
* Post a VCS commit status for a VCS deployment (no-op for non-VCS builds
* or silent mode). Best-effort — a failed status update never fails the build.
+29 -6
View File
@@ -9,16 +9,18 @@ class Parameter
/**
* @param string $name
* @param string $description
* @param mixed|null $default
* @param mixed $default Explicit null overrides a route default with null; leave unset for no override
* @param Validator|callable|null $validator
* @param bool $optional
* @param bool|Undefined $optional Leave unset for no override
* @param bool $hide Omit this parameter from the generated specification while keeping it accepted at runtime
*/
public function __construct(
protected string $name,
protected string $description = '',
protected mixed $default = null,
protected mixed $default = Undefined::Value,
protected mixed $validator = null,
protected bool $optional = false,
protected bool|Undefined $optional = Undefined::Value,
protected bool $hide = false,
) {
}
@@ -46,7 +48,12 @@ class Parameter
public function getDefault(): mixed
{
return $this->default;
return $this->default === Undefined::Value ? null : $this->default;
}
public function hasDefault(): bool
{
return $this->default !== Undefined::Value;
}
public function setDefault(mixed $default): static
@@ -68,7 +75,12 @@ class Parameter
public function getOptional(): bool
{
return $this->optional;
return $this->optional === Undefined::Value ? false : $this->optional;
}
public function hasOptional(): bool
{
return $this->optional !== Undefined::Value;
}
public function setOptional(bool $optional): static
@@ -76,4 +88,15 @@ class Parameter
$this->optional = $optional;
return $this;
}
public function getHide(): bool
{
return $this->hide;
}
public function setHide(bool $hide): static
{
$this->hide = $hide;
return $this;
}
}
+44
View File
@@ -2,6 +2,7 @@
namespace Appwrite\SDK\Specification;
use Appwrite\SDK\Method;
use Appwrite\Utopia\Response\Model;
use Utopia\DI\Container;
use Utopia\Http\Route;
@@ -196,6 +197,49 @@ abstract class Format
return $resources;
}
/**
* Parameters emitted for a method: the route params merged with SDK-only
* additions. A method may declare an explicit `parameters` list to
* override route params by name — set fields replace the route's, and
* `hide: true` drops the param from the spec while the route keeps
* accepting it at runtime.
*
* @return array<string, array<string, mixed>>
*/
protected function getMethodParameters(Route $route, Method $method): array
{
$parameters = \array_merge($route->getParams(), $method->getAdditionalParameters());
foreach ($method->getParameters() as $parameter) {
$name = $parameter->getName();
if ($parameter->getHide()) {
unset($parameters[$name]);
continue;
}
$overrides = \array_filter([
'description' => $parameter->getDescription() ?: null,
'validator' => $parameter->getValidator(),
], fn (mixed $value) => $value !== null);
if ($parameter->hasDefault()) {
$overrides['default'] = $parameter->getDefault();
}
if ($parameter->hasOptional()) {
$overrides['optional'] = $parameter->getOptional();
}
$parameters[$name] = \array_merge(
$parameters[$name] ?? ['optional' => $parameter->getOptional(), 'injections' => []],
$overrides,
);
}
return $parameters;
}
protected function getValidator(array $param): mixed
{
return \is_callable($param['validator'])
@@ -421,10 +421,7 @@ class OpenAPI3 extends Format
$parameterNodes = [];
$parameters = \array_merge(
$route->getParams(),
$sdk->getAdditionalParameters(),
);
$parameters = $this->getMethodParameters($route, $sdk);
foreach ($parameters as $name => $param) { // Set params
if (($param['deprecated'] ?? false) === true) {
+8
View File
@@ -0,0 +1,8 @@
<?php
namespace Appwrite\SDK;
enum Undefined
{
case Value;
}
+66
View File
@@ -0,0 +1,66 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Functions;
use Appwrite\Platform\Modules\Functions\Workers\Jobs;
use PHPUnit\Framework\TestCase;
use ReflectionMethod;
use Utopia\Database\Document;
final class JobsTest extends TestCase
{
private Jobs $jobs;
public function setUp(): void
{
$this->jobs = new Jobs();
}
public function testDurationRoundsSubSecondBuildUpToOneSecond(): void
{
$deployment = new Document([
'buildStartedAt' => (new \DateTimeImmutable('-500 milliseconds'))->format('Y-m-d H:i:s.v'),
]);
$this->assertSame(1, $this->callJobs('duration', $deployment));
}
public function testDurationFallsBackToCreationTimeWhenStartMissing(): void
{
$deployment = new Document([
'$createdAt' => (new \DateTimeImmutable('-4500 milliseconds'))->format('Y-m-d H:i:s.v'),
]);
$this->assertSame(5, $this->callJobs('duration', $deployment));
}
public function testDurationIsZeroWithoutAnyTimestamp(): void
{
$this->assertSame(0, $this->callJobs('duration', new Document([])));
}
public function testDurationClampsFutureStartToZero(): void
{
$deployment = new Document([
'buildStartedAt' => (new \DateTimeImmutable('+10 seconds'))->format('Y-m-d H:i:s.v'),
]);
$this->assertSame(0, $this->callJobs('duration', $deployment));
}
public function testDurationIsZeroForUnparseableStart(): void
{
$deployment = new Document([
'buildStartedAt' => 'not-a-date',
]);
$this->assertSame(0, $this->callJobs('duration', $deployment));
}
private function callJobs(string $method, mixed ...$arguments): mixed
{
return (new ReflectionMethod($this->jobs, $method))->invoke($this->jobs, ...$arguments);
}
}
+80
View File
@@ -5,10 +5,18 @@ declare(strict_types=1);
namespace Tests\Unit\GraphQL;
use Appwrite\GraphQL\Types\Mapper;
use Appwrite\SDK\Method;
use Appwrite\SDK\Parameter;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\Utopia\Response;
use GraphQL\Type\Definition\NamedType;
use PHPUnit\Framework\TestCase;
use Swoole\Http\Response as SwooleResponse;
use Utopia\DI\Container;
use Utopia\Http\Adapter\FPM\Server;
use Utopia\Http\Http;
use Utopia\Http\Route;
use Utopia\Validator\Text;
final class BuilderTest extends TestCase
{
@@ -30,4 +38,76 @@ final class BuilderTest extends TestCase
$this->assertInstanceOf(NamedType::class, $type);
$this->assertSame('Table', $type->name());
}
public function testRouteOmitsHiddenParameters(): void
{
Method::$processed = [];
Method::$errors = [];
$method = new Method(
namespace: 'test',
group: null,
name: 'createGraphQLHiddenTest',
description: 'Create test.',
auth: [],
responses: [
new SDKResponse(code: 201, model: Response::MODEL_ANY),
],
parameters: [
new Parameter('engine', hide: true),
],
);
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->param('name', '', new Text(128), 'Name.')
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$fields = \iterator_to_array($this->mapRoute($route, $method));
$this->assertCount(1, $fields);
$this->assertArrayHasKey('name', $fields[0]['args']);
$this->assertArrayNotHasKey('engine', $fields[0]['args']);
}
public function testRouteParameterWhitelistStillApplies(): void
{
Method::$processed = [];
Method::$errors = [];
$method = new Method(
namespace: 'test',
group: null,
name: 'createGraphQLWhitelistTest',
description: 'Create test.',
auth: [],
responses: [
new SDKResponse(code: 201, model: Response::MODEL_ANY),
],
parameters: [
new Parameter('name', optional: false),
],
);
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->param('name', '', new Text(128), 'Name.')
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$fields = \iterator_to_array($this->mapRoute($route, $method));
$this->assertCount(1, $fields);
$this->assertSame(['name'], \array_keys($fields[0]['args']));
}
private function mapRoute(Route $route, Method $method): iterable
{
return Mapper::route(
new Http(new Server(new Container()), 'UTC'),
$route,
$method,
'POST',
static fn () => 1,
);
}
}
@@ -4,6 +4,7 @@ namespace Tests\Unit\SDK\Specification;
use Appwrite\SDK\ContentType;
use Appwrite\SDK\Method;
use Appwrite\SDK\Parameter;
use Appwrite\SDK\Response as SDKResponse;
use Appwrite\SDK\Specification\Format;
use Appwrite\SDK\Specification\Format\OpenAPI3;
@@ -135,6 +136,79 @@ final class FormatTest extends TestCase
);
}
public function testMethodParameterOverridesFilterAndReplaceRouteParams(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->label('sdk', new Method(
namespace: 'test',
group: null,
name: 'createTestWithOverrides',
description: 'Create test.',
auth: [],
responses: [],
parameters: [
new Parameter('engine', hide: true),
new Parameter('name', description: 'Overridden description.'),
],
))
->param('name', '', new Text(128), 'Original description.')
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$properties = $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['properties'];
$this->assertArrayNotHasKey('engine', $properties);
$this->assertSame('Overridden description.', $properties['name']['description']);
$this->assertSame(['name'], $spec['paths']['/tests']['post']['requestBody']['content']['application/json']['schema']['required']);
}
public function testMethodParameterNullDefaultOverridesRouteDefault(): void
{
Method::$processed = [];
Method::$errors = [];
$method = new Method(
namespace: 'test',
group: null,
name: 'createTestWithNullDefault',
description: 'Create test.',
auth: [],
responses: [],
parameters: [
new Parameter('engine', default: null),
new Parameter('name', description: 'Overridden description.', optional: false),
],
);
$route = (new Route('POST', '/v1/tests'))
->desc('Create test')
->param('name', 'default-name', new Text(128), 'Original description.', true)
->param('engine', 'mysql', new Text(16), 'Engine.', true);
$format = new class (new Container(), [], [], [], [], 0, 'console') extends OpenAPI3 {
/**
* @return array<string, array<string, mixed>>
*/
public function methodParameters(Route $route, Method $method): array
{
return $this->getMethodParameters($route, $method);
}
};
$parameters = $format->methodParameters($route, $method);
$this->assertNull($parameters['engine']['default']);
$this->assertTrue($parameters['engine']['optional']);
$this->assertSame('default-name', $parameters['name']['default']);
$this->assertSame('Overridden description.', $parameters['name']['description']);
$this->assertFalse($parameters['name']['optional']);
}
public function testDeleteRouteOptionalParamsAreQueryParams(): void
{
Method::$processed = [];