mirror of
https://github.com/appwrite/appwrite.git
synced 2026-11-18 20:36:03 +00:00
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:
1 parent
dc3cf93c2e
commit
b664671af9
9 files changed
+348
-27
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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) {
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
<?php
|
||||
|
||||
namespace Appwrite\SDK;
|
||||
|
||||
enum Undefined
|
||||
{
|
||||
case Value;
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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 = [];
|
||||
|
||||
Reference in new issue
Block a user