diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..a0ffdbea4c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,73 @@ +# AGENTS.md + +Appwrite is an end-to-end backend server for web, mobile, native, and backend apps. This guide provides context and instructions for AI coding agents working on the Appwrite codebase. + +## Project Overview + +Appwrite is a self-hosted Backend-as-a-Service (BaaS) platform that provides developers with a set of APIs and tools to build secure, scalable applications. The project uses a hybrid monolithic-microservice architecture built with PHP, running on Swoole for high performance. + +**Key Technologies:** +- **Backend:** PHP 8.3+, Swoole +- **Libraries:** Utopia PHP +- **Database:** MariaDB, Redis +- **Cache:** Redis +- **Queue:** Redis +- **Containers:** Docker + +## Development Commands + +```bash +# Run Appwrite +docker compose up -d --force-recreate --build + +# Run specific test +docker compose exec appwrite test /usr/src/code/tests/e2e/Services/[ServiceName] --filter=[FunctionName] + +# Format code +composer format +``` + +## Code Style Guidelines + +- Follow [PSR-12](https://www.php-fig.org/psr/psr-12/) coding standard +- Use PSR-4 autoloading +- Strict type declarations where applicable +- Comprehensive PHPDoc comments + +### Naming Conventions + +#### `resourceType` Naming Rule + +When a collection has a combination of `resourceType`, `resourceId`, and/or `resourceInternalId`, the value of `resourceType` MUST always be **plural** - for example: `functions`, `sites`, `deployments`. + +Examples: +```php +'resourceType' => 'functions' +'resourceType' => 'sites' +'resourceType' => 'deployments' +``` + +## Security Considerations + +### Critical Security Practices + +- **Never hardcode credentials** - Use environment variables +- **Rate limiting** - Respect abuse prevention mechanisms + +## Dependencies + +Avoid introducing new dependencies other than utopia-php. + +## Pull Request Guidelines +### Before Submitting + +- Run `composer format` +- Update documentation if adding features +- Add/update tests for your changes +- Check that Docker build succeeds +`docs/specs/authentication.drawio.svg` + +## Known Issues and Gotchas + +- **Hot Reload:** Code changes require container restart in some cases +- **Logging:** There is no central place for logs, so when debugging, ensure to check all possibly relevant containers diff --git a/app/controllers/general.php b/app/controllers/general.php index 638df72419..31647eb994 100644 --- a/app/controllers/general.php +++ b/app/controllers/general.php @@ -1034,8 +1034,7 @@ App::init() ->inject('dbForPlatform') ->inject('queueForCertificates') ->inject('platform') - ->inject('authorization') - ->action(function (Request $request, Document $console, Database $dbForPlatform, Certificate $queueForCertificates, array $platform, Authorization $authorization) { + ->action(function (Request $request, Document $console, Database $dbForPlatform, Certificate $queueForCertificates, array $platform) { $hostname = $request->getHostname(); $cache = Config::getParam('hostnames', []); $platformHostnames = $platform['hostnames'] ?? []; @@ -1066,7 +1065,7 @@ App::init() } // 4. Check/create rule (requires DB access) - $authorization->disable(); + Authorization::disable(); try { // TODO: (@Meldiron) Remove after 1.7.x migration $isMd5 = System::getEnv('_APP_RULES_FORMAT') === 'md5'; @@ -1122,7 +1121,7 @@ App::init() } finally { $cache[$domain->get()] = true; Config::setParam('hostnames', $cache); - $authorization->reset(); + Authorization::reset(); } }); diff --git a/app/init/resources.php b/app/init/resources.php index 68ac5c90ca..e013a8c147 100644 --- a/app/init/resources.php +++ b/app/init/resources.php @@ -275,6 +275,7 @@ App::setResource('cors', fn (array $allowedHostnames) => new Cors( 'X-Appwrite-ID', 'X-Appwrite-Timestamp', 'X-Appwrite-Session', + 'X-Appwrite-Platform', // for `$platform` injection and SDK generator // SDK generator 'X-SDK-Version', 'X-SDK-Name', diff --git a/tests/e2e/General/HTTPTest.php b/tests/e2e/General/HTTPTest.php index 6323500136..4012745682 100644 --- a/tests/e2e/General/HTTPTest.php +++ b/tests/e2e/General/HTTPTest.php @@ -31,7 +31,7 @@ class HTTPTest extends Scope $this->assertEquals(204, $response['headers']['status-code']); $this->assertEquals('Appwrite', $response['headers']['server']); $this->assertEquals('GET, POST, PUT, PATCH, DELETE', $response['headers']['access-control-allow-methods']); - $this->assertEquals('Accept, Origin, Cookie, Set-Cookie, Content-Type, Content-Range, X-Appwrite-Project, X-Appwrite-Key, X-Appwrite-Dev-Key, X-Appwrite-Locale, X-Appwrite-Mode, X-Appwrite-JWT, X-Appwrite-Response-Format, X-Appwrite-Timeout, X-Appwrite-ID, X-Appwrite-Timestamp, X-Appwrite-Session, X-SDK-Version, X-SDK-Name, X-SDK-Language, X-SDK-Platform, X-SDK-GraphQL, X-SDK-Profile, Range, Cache-Control, Expires, Pragma, X-Fallback-Cookies, X-Requested-With, X-Forwarded-For, X-Forwarded-User-Agent', $response['headers']['access-control-allow-headers']); + $this->assertEquals('Accept, Origin, Cookie, Set-Cookie, Content-Type, Content-Range, X-Appwrite-Project, X-Appwrite-Key, X-Appwrite-Dev-Key, X-Appwrite-Locale, X-Appwrite-Mode, X-Appwrite-JWT, X-Appwrite-Response-Format, X-Appwrite-Timeout, X-Appwrite-ID, X-Appwrite-Timestamp, X-Appwrite-Session, X-Appwrite-Platform, X-SDK-Version, X-SDK-Name, X-SDK-Language, X-SDK-Platform, X-SDK-GraphQL, X-SDK-Profile, Range, Cache-Control, Expires, Pragma, X-Fallback-Cookies, X-Requested-With, X-Forwarded-For, X-Forwarded-User-Agent', $response['headers']['access-control-allow-headers']); $this->assertEquals('X-Appwrite-Session, X-Fallback-Cookies', $response['headers']['access-control-expose-headers']); $this->assertEquals('http://localhost', $response['headers']['access-control-allow-origin']); $this->assertEquals('true', $response['headers']['access-control-allow-credentials']);