support/doc/development/server.md

   1 # Server code
   2
   3 ## Add a new feature walkthrough
   4
   5 Here's a list of all the parts of the server to update if you want to add a new feature (new API REST endpoints for example) to the PeerTube server.
   6 Some of these may be optional (for example your new endpoint may not need to send notifications) but this guide tries to be exhaustive.
   7
   8  * Configuration:
   9    - Add you new configuration key in `config/default.yaml` and `config/production.yaml`
  10    - If you configuration needs to be different in dev or tests environments, also update `config/dev.yaml` and `config/test.yaml`
  11    - Load your configuration in `server/initializers/config.ts`
  12    - Check new configuration keys are set in `server/initializers/checker-before-init.ts`
  13    - You can also ensure configuration consistency in `server/initializers/checker-after-init.ts`
  14    - If you want your configuration to be available in the client:
  15      + Add your field in `shared/models/server/server-config.model.ts`
  16      + Update `server/lib/server-config-manager.ts` to include your new configuration
  17    - If you want your configuration to be updatable by the web admin in the client:
  18      + Add your field in `shared/models/server/custom-config.model.ts`
  19      + Add the configuration to the config object in the `server/controllers/api/config.ts` controller
  20  * Controllers:
  21    - Create the controller file and fill it with your REST API routes
  22    - Import and use your controller in the parent controller
  23  * Middlewares:
  24    - Create your validator middleware in `server/middlewares/validators` that will be used by your controllers
  25    - Add your new middleware file `server/middlewares/validators/index.ts` so it's easier to import
  26    - Create the entry in `server/types/express.d.ts` to attach the database model loaded by your middleware to the express response
  27  * Validators:
  28    - Create your validators that will be used by your middlewares in `server/helpers/custom-validators`
  29  * Typescript models:
  30    - Create the API models (request parameters or response) in `shared/models`
  31    - Add your models in `index.ts` of current directory to facilitate the imports
  32  * Sequelize model (BDD):
  33    - If you need to create a new table:
  34      + Create the Sequelize model in `server/models/`:
  35        * Create the `@Column`
  36        * Add some indexes if you need
  37        * Create static methods to load a specific from the database `loadBy...`
  38        * Create static methods to load a list of models from the database `listBy...`
  39        * Create the instance method `toFormattedJSON` that creates the JSON to send to the REST API from the model
  40      + Add your new Sequelize model to `server/initializers/database.ts`
  41      + Create a new file in `server/types` to define multiple versions of your Sequelize model depending on database associations
  42      + Add this new file to `server/types/*/index.ts` to facilitate the imports
  43      + Create database migrations:
  44        * Create the migration file in `server/initializers/migrations` using raw SQL (copy the same SQL query as at PeerTube startup)
  45        * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts`
  46    - If updating database schema (adding/removing/renaming a column):
  47      + Update the sequelize models in `server/models/`
  48      + Add migrations:
  49        * Create the migration file in `initializers/migrations` using Sequelize Query Interface (`.addColumn`, `.dropTable`, `.changeColumn`)
  50        * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts`
  51  * Notifications:
  52    - Create the new notification model in `shared/models/users/user-notification.model.ts`
  53    - Create the notification logic in `server/lib/notifier/shared`:
  54      + Email subject has a common prefix (defined by the admin in PeerTube configuration)
  55    - Add your notification to `server/lib/notifier/notifier.ts`
  56    - Create the email template in `server/lib/emails`:
  57      + A text version is automatically generated from the HTML
  58      + The template usually extends `../common/grettings` that already says "Hi" and "Cheers". You just have to write the title and the content blocks that will be inserted in the appropriate places in the HTML template
  59    - If you need to associate a new table with `userNotification`:
  60      + Associate the new table in `UserNotificationModel` (don't forget the index)
  61      + Add the object property in the API model definition (`shared/models/users/user-notification.model.ts`)
  62      + Add the object in `UserNotificationModel.toFormattedJSON`
  63      + Handle this new notification type in client (`UserNotificationsComponent`)
  64      + Handle the new object property in client model (`UserNotification`)
  65  * Tests:
  66    - Create your command class in `shared/server-commands/` that will wrap HTTP requests to your new endpoint
  67    - Add your command file in `index.ts` of current directory
  68    - Instantiate your command class in `shared/server-commands/server/server.ts`
  69    - Create your test file in `server/tests/api/check-params` to test middleware validators/authentification/user rights (offensive tests)
  70    - Add it to `server/tests/api/check-params/index.ts`
  71    - Create your test file in `server/tests/api` to test your new endpoints
  72    - Add it to `index.ts` of current directory
  73    - Add your notification test in `server/tests/api/notifications`
  74  * Update REST API documentation in `support/doc/api/openapi.yaml`