diff options
author | Chocobozzz <me@florianbigard.com> | 2023-03-16 11:49:40 +0100 |
---|---|---|
committer | Chocobozzz <me@florianbigard.com> | 2023-03-16 14:15:33 +0100 |
commit | 11c834bdba42f124a172b643b292e45f043b3be9 (patch) | |
tree | 447453d92eeab8cc94e4291b7d3bc59c02a8b142 /support/doc/development/server.md | |
parent | dc9c9500bf5f0fd66906576ee3df4f1c49a1871d (diff) | |
download | PeerTube-11c834bdba42f124a172b643b292e45f043b3be9.tar.gz PeerTube-11c834bdba42f124a172b643b292e45f043b3be9.tar.zst PeerTube-11c834bdba42f124a172b643b292e45f043b3be9.zip |
Add server code new feature walkthrough
Diffstat (limited to 'support/doc/development/server.md')
-rw-r--r-- | support/doc/development/server.md | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/support/doc/development/server.md b/support/doc/development/server.md new file mode 100644 index 000000000..4647f2b4f --- /dev/null +++ b/support/doc/development/server.md | |||
@@ -0,0 +1,74 @@ | |||
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` | ||