PeerTube/support/doc/development/server.md

Server code

Database model typing

Sequelize models contain optional fields corresponding to table joins. For example, VideoModel has a VideoChannel?: VideoChannelModel field. It can be filled if the SQL query joined with the videoChannel table or empty if not. It can be difficult in TypeScript to understand if a function argument expects associations to be filled or not. To improve clarity and reduce bugs, PeerTube defines multiple versions of a database model depending on its associations in server/types/models/. These models start with M and by default do not include any association. MVideo for example corresponds to VideoModel without any association, where VideoChannel attribute doesn't exist. On the other hand, MVideoWithChannel is a MVideo that has a VideoChannel field. This way, a function that accepts video: MVideoWithChannel argument expects a video with channel populated. Main PeerTube code should never use ...Model (VideoModel) database type, but always M... instead (MVideo, MVideoChannel etc).

Add a new feature walkthrough

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. Some of these may be optional (for example your new endpoint may not need to send notifications) but this guide tries to be exhaustive.

• Configuration:
  • Add you new configuration key in config/default.yaml and config/production.yaml
  • If you configuration needs to be different in dev or tests environments, also update config/dev.yaml and config/test.yaml
  • Load your configuration in server/initializers/config.ts
  • Check new configuration keys are set in server/initializers/checker-before-init.ts
  • You can also ensure configuration consistency in server/initializers/checker-after-init.ts
  • If you want your configuration to be available in the client:
    • Add your field in shared/models/server/server-config.model.ts
    • Update server/lib/server-config-manager.ts to include your new configuration
  • If you want your configuration to be updatable by the web admin in the client:
    • Add your field in shared/models/server/custom-config.model.ts
    • Add the configuration to the config object in the server/controllers/api/config.ts controller
• Controllers:
  • Create the controller file and fill it with your REST API routes
  • Import and use your controller in the parent controller
• Middlewares:
  • Create your validator middleware in server/middlewares/validators that will be used by your controllers
  • Add your new middleware file server/middlewares/validators/index.ts so it's easier to import
  • Create the entry in server/types/express.d.ts to attach the database model loaded by your middleware to the express response
• Validators:
  • Create your validators that will be used by your middlewares in server/helpers/custom-validators
• Typescript models:
  • Create the API models (request parameters or response) in shared/models
  • Add your models in index.ts of current directory to facilitate the imports
• Sequelize model (BDD):
  • If you need to create a new table:
    • Create the Sequelize model in server/models/:
      • Create the @Column
      • Add some indexes if you need
      • Create static methods to load a specific from the database loadBy...
      • Create static methods to load a list of models from the database listBy...
      • Create the instance method toFormattedJSON that creates the JSON to send to the REST API from the model
    • Add your new Sequelize model to server/initializers/database.ts
    • Create a new file in server/types to define multiple versions of your Sequelize model depending on database associations
    • Add this new file to server/types/*/index.ts to facilitate the imports
    • Create database migrations:
      • Create the migration file in server/initializers/migrations using raw SQL (copy the same SQL query as at PeerTube startup)
      • Update LAST_MIGRATION_VERSION in server/initializers/constants.ts
  • If updating database schema (adding/removing/renaming a column):
    • Update the sequelize models in server/models/
    • Add migrations:
      • Create the migration file in initializers/migrations using Sequelize Query Interface (.addColumn, .dropTable, .changeColumn)
      • Update LAST_MIGRATION_VERSION in server/initializers/constants.ts
• Notifications:
  • Create the new notification model in shared/models/users/user-notification.model.ts
  • Create the notification logic in server/lib/notifier/shared:
    • Email subject has a common prefix (defined by the admin in PeerTube configuration)
  • Add your notification to server/lib/notifier/notifier.ts
  • Create the email template in server/lib/emails:
    • A text version is automatically generated from the HTML
    • 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
  • If you need to associate a new table with userNotification:
    • Associate the new table in UserNotificationModel (don't forget the index)
    • Add the object property in the API model definition (shared/models/users/user-notification.model.ts)
    • Add the object in UserNotificationModel.toFormattedJSON
    • Handle this new notification type in client (UserNotificationsComponent)
    • Handle the new object property in client model (UserNotification)
• Tests:
  • Create your command class in shared/server-commands/ that will wrap HTTP requests to your new endpoint
  • Add your command file in index.ts of current directory
  • Instantiate your command class in shared/server-commands/server/server.ts
  • Create your test file in server/tests/api/check-params to test middleware validators/authentification/user rights (offensive tests)
  • Add it to server/tests/api/check-params/index.ts
  • Create your test file in server/tests/api to test your new endpoints
  • Add it to index.ts of current directory
  • Add your notification test in server/tests/api/notifications
• Update REST API documentation in support/doc/api/openapi.yaml