aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorChocobozzz <me@florianbigard.com>2020-04-10 15:07:54 +0200
committerChocobozzz <me@florianbigard.com>2020-04-10 15:23:25 +0200
commit5e2b2e2775421cd98286d6e2f75cf38aae7a212c (patch)
treed92e32824d83cecbe5e90206738f393b47e55754
parent9afa0901f11c321e071c42ba3c814a3af4843c55 (diff)
downloadPeerTube-5e2b2e2775421cd98286d6e2f75cf38aae7a212c.tar.gz
PeerTube-5e2b2e2775421cd98286d6e2f75cf38aae7a212c.tar.zst
PeerTube-5e2b2e2775421cd98286d6e2f75cf38aae7a212c.zip
Add ability for plugins to add custom routes
-rw-r--r--server/controllers/plugins.ts41
-rw-r--r--server/lib/plugins/plugin-manager.ts51
-rw-r--r--server/lib/plugins/register-helpers-store.ts235
-rw-r--r--server/lib/plugins/register-helpers.ts180
-rw-r--r--server/middlewares/validators/plugins.ts48
-rw-r--r--server/tests/fixtures/peertube-plugin-test-five/main.js21
-rw-r--r--server/tests/fixtures/peertube-plugin-test-five/package.json20
-rw-r--r--server/tests/plugins/index.ts1
-rw-r--r--server/tests/plugins/plugin-router.ts91
-rw-r--r--server/typings/plugins/register-server-option.model.ts7
-rw-r--r--support/doc/plugins/guide.md19
11 files changed, 482 insertions, 232 deletions
diff --git a/server/controllers/plugins.ts b/server/controllers/plugins.ts
index 1caee9a29..1fc49b646 100644
--- a/server/controllers/plugins.ts
+++ b/server/controllers/plugins.ts
@@ -2,7 +2,7 @@ import * as express from 'express'
2import { PLUGIN_GLOBAL_CSS_PATH } from '../initializers/constants' 2import { PLUGIN_GLOBAL_CSS_PATH } from '../initializers/constants'
3import { join } from 'path' 3import { join } from 'path'
4import { PluginManager, RegisteredPlugin } from '../lib/plugins/plugin-manager' 4import { PluginManager, RegisteredPlugin } from '../lib/plugins/plugin-manager'
5import { servePluginStaticDirectoryValidator } from '../middlewares/validators/plugins' 5import { getPluginValidator, pluginStaticDirectoryValidator } from '../middlewares/validators/plugins'
6import { serveThemeCSSValidator } from '../middlewares/validators/themes' 6import { serveThemeCSSValidator } from '../middlewares/validators/themes'
7import { PluginType } from '../../shared/models/plugins/plugin.type' 7import { PluginType } from '../../shared/models/plugins/plugin.type'
8import { isTestInstance } from '../helpers/core-utils' 8import { isTestInstance } from '../helpers/core-utils'
@@ -24,22 +24,36 @@ pluginsRouter.get('/plugins/translations/:locale.json',
24) 24)
25 25
26pluginsRouter.get('/plugins/:pluginName/:pluginVersion/static/:staticEndpoint(*)', 26pluginsRouter.get('/plugins/:pluginName/:pluginVersion/static/:staticEndpoint(*)',
27 servePluginStaticDirectoryValidator(PluginType.PLUGIN), 27 getPluginValidator(PluginType.PLUGIN),
28 pluginStaticDirectoryValidator,
28 servePluginStaticDirectory 29 servePluginStaticDirectory
29) 30)
30 31
31pluginsRouter.get('/plugins/:pluginName/:pluginVersion/client-scripts/:staticEndpoint(*)', 32pluginsRouter.get('/plugins/:pluginName/:pluginVersion/client-scripts/:staticEndpoint(*)',
32 servePluginStaticDirectoryValidator(PluginType.PLUGIN), 33 getPluginValidator(PluginType.PLUGIN),
34 pluginStaticDirectoryValidator,
33 servePluginClientScripts 35 servePluginClientScripts
34) 36)
35 37
38pluginsRouter.use('/plugins/:pluginName/router',
39 getPluginValidator(PluginType.PLUGIN, false),
40 servePluginCustomRoutes
41)
42
43pluginsRouter.use('/plugins/:pluginName/:pluginVersion/router',
44 getPluginValidator(PluginType.PLUGIN),
45 servePluginCustomRoutes
46)
47
36pluginsRouter.get('/themes/:pluginName/:pluginVersion/static/:staticEndpoint(*)', 48pluginsRouter.get('/themes/:pluginName/:pluginVersion/static/:staticEndpoint(*)',
37 servePluginStaticDirectoryValidator(PluginType.THEME), 49 getPluginValidator(PluginType.THEME),
50 pluginStaticDirectoryValidator,
38 servePluginStaticDirectory 51 servePluginStaticDirectory
39) 52)
40 53
41pluginsRouter.get('/themes/:pluginName/:pluginVersion/client-scripts/:staticEndpoint(*)', 54pluginsRouter.get('/themes/:pluginName/:pluginVersion/client-scripts/:staticEndpoint(*)',
42 servePluginStaticDirectoryValidator(PluginType.THEME), 55 getPluginValidator(PluginType.THEME),
56 pluginStaticDirectoryValidator,
43 servePluginClientScripts 57 servePluginClientScripts
44) 58)
45 59
@@ -85,22 +99,27 @@ function servePluginStaticDirectory (req: express.Request, res: express.Response
85 const [ directory, ...file ] = staticEndpoint.split('/') 99 const [ directory, ...file ] = staticEndpoint.split('/')
86 100
87 const staticPath = plugin.staticDirs[directory] 101 const staticPath = plugin.staticDirs[directory]
88 if (!staticPath) { 102 if (!staticPath) return res.sendStatus(404)
89 return res.sendStatus(404)
90 }
91 103
92 const filepath = file.join('/') 104 const filepath = file.join('/')
93 return res.sendFile(join(plugin.path, staticPath, filepath), sendFileOptions) 105 return res.sendFile(join(plugin.path, staticPath, filepath), sendFileOptions)
94} 106}
95 107
108function servePluginCustomRoutes (req: express.Request, res: express.Response, next: express.NextFunction) {
109 const plugin: RegisteredPlugin = res.locals.registeredPlugin
110 const router = PluginManager.Instance.getRouter(plugin.npmName)
111
112 if (!router) return res.sendStatus(404)
113
114 return router(req, res, next)
115}
116
96function servePluginClientScripts (req: express.Request, res: express.Response) { 117function servePluginClientScripts (req: express.Request, res: express.Response) {
97 const plugin: RegisteredPlugin = res.locals.registeredPlugin 118 const plugin: RegisteredPlugin = res.locals.registeredPlugin
98 const staticEndpoint = req.params.staticEndpoint 119 const staticEndpoint = req.params.staticEndpoint
99 120
100 const file = plugin.clientScripts[staticEndpoint] 121 const file = plugin.clientScripts[staticEndpoint]
101 if (!file) { 122 if (!file) return res.sendStatus(404)
102 return res.sendStatus(404)
103 }
104 123
105 return res.sendFile(join(plugin.path, staticEndpoint), sendFileOptions) 124 return res.sendFile(join(plugin.path, staticEndpoint), sendFileOptions)
106} 125}
diff --git a/server/lib/plugins/plugin-manager.ts b/server/lib/plugins/plugin-manager.ts
index 44530d203..37fb07716 100644
--- a/server/lib/plugins/plugin-manager.ts
+++ b/server/lib/plugins/plugin-manager.ts
@@ -13,15 +13,14 @@ import { PLUGIN_GLOBAL_CSS_PATH } from '../../initializers/constants'
13import { PluginType } from '../../../shared/models/plugins/plugin.type' 13import { PluginType } from '../../../shared/models/plugins/plugin.type'
14import { installNpmPlugin, installNpmPluginFromDisk, removeNpmPlugin } from './yarn' 14import { installNpmPlugin, installNpmPluginFromDisk, removeNpmPlugin } from './yarn'
15import { outputFile, readJSON } from 'fs-extra' 15import { outputFile, readJSON } from 'fs-extra'
16import { ServerHook, ServerHookName, serverHookObject } from '../../../shared/models/plugins/server-hook.model' 16import { ServerHook, ServerHookName } from '../../../shared/models/plugins/server-hook.model'
17import { getHookType, internalRunHook } from '../../../shared/core-utils/plugins/hooks' 17import { getHookType, internalRunHook } from '../../../shared/core-utils/plugins/hooks'
18import { RegisterServerOptions } from '../../typings/plugins/register-server-option.model' 18import { RegisterServerOptions } from '../../typings/plugins/register-server-option.model'
19import { PluginLibrary } from '../../typings/plugins' 19import { PluginLibrary } from '../../typings/plugins'
20import { ClientHtml } from '../client-html' 20import { ClientHtml } from '../client-html'
21import { RegisterServerHookOptions } from '../../../shared/models/plugins/register-server-hook.model'
22import { RegisterServerSettingOptions } from '../../../shared/models/plugins/register-server-setting.model'
23import { PluginTranslation } from '../../../shared/models/plugins/plugin-translation.model' 21import { PluginTranslation } from '../../../shared/models/plugins/plugin-translation.model'
24import { buildRegisterHelpers, reinitVideoConstants } from './register-helpers' 22import { RegisterHelpersStore } from './register-helpers-store'
23import { RegisterServerHookOptions } from '@shared/models/plugins/register-server-hook.model'
25 24
26export interface RegisteredPlugin { 25export interface RegisteredPlugin {
27 npmName: string 26 npmName: string
@@ -59,10 +58,11 @@ export class PluginManager implements ServerHook {
59 private static instance: PluginManager 58 private static instance: PluginManager
60 59
61 private registeredPlugins: { [name: string]: RegisteredPlugin } = {} 60 private registeredPlugins: { [name: string]: RegisteredPlugin } = {}
62 private settings: { [name: string]: RegisterServerSettingOptions[] } = {}
63 private hooks: { [name: string]: HookInformationValue[] } = {} 61 private hooks: { [name: string]: HookInformationValue[] } = {}
64 private translations: PluginLocalesTranslations = {} 62 private translations: PluginLocalesTranslations = {}
65 63
64 private registerHelpersStore: { [npmName: string]: RegisterHelpersStore } = {}
65
66 private constructor () { 66 private constructor () {
67 } 67 }
68 68
@@ -103,7 +103,17 @@ export class PluginManager implements ServerHook {
103 } 103 }
104 104
105 getRegisteredSettings (npmName: string) { 105 getRegisteredSettings (npmName: string) {
106 return this.settings[npmName] || [] 106 const store = this.registerHelpersStore[npmName]
107 if (store) return store.getSettings()
108
109 return []
110 }
111
112 getRouter (npmName: string) {
113 const store = this.registerHelpersStore[npmName]
114 if (!store) return null
115
116 return store.getRouter()
107 } 117 }
108 118
109 getTranslations (locale: string) { 119 getTranslations (locale: string) {
@@ -164,7 +174,6 @@ export class PluginManager implements ServerHook {
164 } 174 }
165 175
166 delete this.registeredPlugins[plugin.npmName] 176 delete this.registeredPlugins[plugin.npmName]
167 delete this.settings[plugin.npmName]
168 177
169 this.deleteTranslations(plugin.npmName) 178 this.deleteTranslations(plugin.npmName)
170 179
@@ -176,7 +185,10 @@ export class PluginManager implements ServerHook {
176 this.hooks[key] = this.hooks[key].filter(h => h.npmName !== npmName) 185 this.hooks[key] = this.hooks[key].filter(h => h.npmName !== npmName)
177 } 186 }
178 187
179 reinitVideoConstants(plugin.npmName) 188 const store = this.registerHelpersStore[plugin.npmName]
189 store.reinitVideoConstants(plugin.npmName)
190
191 delete this.registerHelpersStore[plugin.npmName]
180 192
181 logger.info('Regenerating registered plugin CSS to global file.') 193 logger.info('Regenerating registered plugin CSS to global file.')
182 await this.regeneratePluginGlobalCSS() 194 await this.regeneratePluginGlobalCSS()
@@ -429,34 +441,21 @@ export class PluginManager implements ServerHook {
429 // ###################### Generate register helpers ###################### 441 // ###################### Generate register helpers ######################
430 442
431 private getRegisterHelpers (npmName: string, plugin: PluginModel): RegisterServerOptions { 443 private getRegisterHelpers (npmName: string, plugin: PluginModel): RegisterServerOptions {
432 const registerHook = (options: RegisterServerHookOptions) => { 444 const onHookAdded = (options: RegisterServerHookOptions) => {
433 if (serverHookObject[options.target] !== true) {
434 logger.warn('Unknown hook %s of plugin %s. Skipping.', options.target, npmName)
435 return
436 }
437
438 if (!this.hooks[options.target]) this.hooks[options.target] = [] 445 if (!this.hooks[options.target]) this.hooks[options.target] = []
439 446
440 this.hooks[options.target].push({ 447 this.hooks[options.target].push({
441 npmName, 448 npmName: npmName,
442 pluginName: plugin.name, 449 pluginName: plugin.name,
443 handler: options.handler, 450 handler: options.handler,
444 priority: options.priority || 0 451 priority: options.priority || 0
445 }) 452 })
446 } 453 }
447 454
448 const registerSetting = (options: RegisterServerSettingOptions) => { 455 const registerHelpersStore = new RegisterHelpersStore(npmName, plugin, onHookAdded.bind(this))
449 if (!this.settings[npmName]) this.settings[npmName] = [] 456 this.registerHelpersStore[npmName] = registerHelpersStore
450
451 this.settings[npmName].push(options)
452 }
453
454 const registerHelpers = buildRegisterHelpers(npmName, plugin)
455 457
456 return Object.assign(registerHelpers, { 458 return registerHelpersStore.buildRegisterHelpers()
457 registerHook,
458 registerSetting
459 })
460 } 459 }
461 460
462 private sanitizeAndCheckPackageJSONOrThrow (packageJSON: PluginPackageJson, pluginType: PluginType) { 461 private sanitizeAndCheckPackageJSONOrThrow (packageJSON: PluginPackageJson, pluginType: PluginType) {
diff --git a/server/lib/plugins/register-helpers-store.ts b/server/lib/plugins/register-helpers-store.ts
new file mode 100644
index 000000000..c76c0161a
--- /dev/null
+++ b/server/lib/plugins/register-helpers-store.ts
@@ -0,0 +1,235 @@
1import { PluginSettingsManager } from '@shared/models/plugins/plugin-settings-manager.model'
2import { PluginModel } from '@server/models/server/plugin'
3import { PluginStorageManager } from '@shared/models/plugins/plugin-storage-manager.model'
4import { PluginVideoLanguageManager } from '@shared/models/plugins/plugin-video-language-manager.model'
5import { VIDEO_CATEGORIES, VIDEO_LANGUAGES, VIDEO_LICENCES } from '@server/initializers/constants'
6import { PluginVideoLicenceManager } from '@shared/models/plugins/plugin-video-licence-manager.model'
7import { PluginVideoCategoryManager } from '@shared/models/plugins/plugin-video-category-manager.model'
8import { RegisterServerOptions } from '@server/typings/plugins'
9import { buildPluginHelpers } from './plugin-helpers'
10import { logger } from '@server/helpers/logger'
11import { RegisterServerHookOptions } from '@shared/models/plugins/register-server-hook.model'
12import { serverHookObject } from '@shared/models/plugins/server-hook.model'
13import { RegisterServerSettingOptions } from '@shared/models/plugins/register-server-setting.model'
14import * as express from 'express'
15
16type AlterableVideoConstant = 'language' | 'licence' | 'category'
17type VideoConstant = { [key in number | string]: string }
18
19type UpdatedVideoConstant = {
20 [name in AlterableVideoConstant]: {
21 added: { key: number | string, label: string }[]
22 deleted: { key: number | string, label: string }[]
23 }
24}
25
26export class RegisterHelpersStore {
27 private readonly updatedVideoConstants: UpdatedVideoConstant = {
28 language: { added: [], deleted: [] },
29 licence: { added: [], deleted: [] },
30 category: { added: [], deleted: [] }
31 }
32
33 private readonly settings: RegisterServerSettingOptions[] = []
34
35 private readonly router: express.Router
36
37 constructor (
38 private readonly npmName: string,
39 private readonly plugin: PluginModel,
40 private readonly onHookAdded: (options: RegisterServerHookOptions) => void
41 ) {
42 this.router = express.Router()
43 }
44
45 buildRegisterHelpers (): RegisterServerOptions {
46 const registerHook = this.buildRegisterHook()
47 const registerSetting = this.buildRegisterSetting()
48
49 const getRouter = this.buildGetRouter()
50
51 const settingsManager = this.buildSettingsManager()
52 const storageManager = this.buildStorageManager()
53
54 const videoLanguageManager = this.buildVideoLanguageManager()
55
56 const videoLicenceManager = this.buildVideoLicenceManager()
57 const videoCategoryManager = this.buildVideoCategoryManager()
58
59 const peertubeHelpers = buildPluginHelpers(this.npmName)
60
61 return {
62 registerHook,
63 registerSetting,
64
65 getRouter,
66
67 settingsManager,
68 storageManager,
69
70 videoLanguageManager,
71 videoCategoryManager,
72 videoLicenceManager,
73
74 peertubeHelpers
75 }
76 }
77
78 reinitVideoConstants (npmName: string) {
79 const hash = {
80 language: VIDEO_LANGUAGES,
81 licence: VIDEO_LICENCES,
82 category: VIDEO_CATEGORIES
83 }
84 const types: AlterableVideoConstant[] = [ 'language', 'licence', 'category' ]
85
86 for (const type of types) {
87 const updatedConstants = this.updatedVideoConstants[type][npmName]
88 if (!updatedConstants) continue
89
90 for (const added of updatedConstants.added) {
91 delete hash[type][added.key]
92 }
93
94 for (const deleted of updatedConstants.deleted) {
95 hash[type][deleted.key] = deleted.label
96 }
97
98 delete this.updatedVideoConstants[type][npmName]
99 }
100 }
101
102 getSettings () {
103 return this.settings
104 }
105
106 getRouter () {
107 return this.router
108 }
109
110 private buildGetRouter () {
111 return () => this.router
112 }
113
114 private buildRegisterSetting () {
115 return (options: RegisterServerSettingOptions) => {
116 this.settings.push(options)
117 }
118 }
119
120 private buildRegisterHook () {
121 return (options: RegisterServerHookOptions) => {
122 if (serverHookObject[options.target] !== true) {
123 logger.warn('Unknown hook %s of plugin %s. Skipping.', options.target, this.npmName)
124 return
125 }
126
127 return this.onHookAdded(options)
128 }
129 }
130
131 private buildSettingsManager (): PluginSettingsManager {
132 return {
133 getSetting: (name: string) => PluginModel.getSetting(this.plugin.name, this.plugin.type, name),
134
135 setSetting: (name: string, value: string) => PluginModel.setSetting(this.plugin.name, this.plugin.type, name, value)
136 }
137 }
138
139 private buildStorageManager (): PluginStorageManager {
140 return {
141 getData: (key: string) => PluginModel.getData(this.plugin.name, this.plugin.type, key),
142
143 storeData: (key: string, data: any) => PluginModel.storeData(this.plugin.name, this.plugin.type, key, data)
144 }
145 }
146
147 private buildVideoLanguageManager (): PluginVideoLanguageManager {
148 return {
149 addLanguage: (key: string, label: string) => {
150 return this.addConstant({ npmName: this.npmName, type: 'language', obj: VIDEO_LANGUAGES, key, label })
151 },
152
153 deleteLanguage: (key: string) => {
154 return this.deleteConstant({ npmName: this.npmName, type: 'language', obj: VIDEO_LANGUAGES, key })
155 }
156 }
157 }
158
159 private buildVideoCategoryManager (): PluginVideoCategoryManager {
160 return {
161 addCategory: (key: number, label: string) => {
162 return this.addConstant({ npmName: this.npmName, type: 'category', obj: VIDEO_CATEGORIES, key, label })
163 },
164
165 deleteCategory: (key: number) => {
166 return this.deleteConstant({ npmName: this.npmName, type: 'category', obj: VIDEO_CATEGORIES, key })
167 }
168 }
169 }
170
171 private buildVideoLicenceManager (): PluginVideoLicenceManager {
172 return {
173 addLicence: (key: number, label: string) => {
174 return this.addConstant({ npmName: this.npmName, type: 'licence', obj: VIDEO_LICENCES, key, label })
175 },
176
177 deleteLicence: (key: number) => {
178 return this.deleteConstant({ npmName: this.npmName, type: 'licence', obj: VIDEO_LICENCES, key })
179 }
180 }
181 }
182
183 private addConstant<T extends string | number> (parameters: {
184 npmName: string
185 type: AlterableVideoConstant
186 obj: VideoConstant
187 key: T
188 label: string
189 }) {
190 const { npmName, type, obj, key, label } = parameters
191
192 if (obj[key]) {
193 logger.warn('Cannot add %s %s by plugin %s: key already exists.', type, npmName, key)
194 return false
195 }
196
197 if (!this.updatedVideoConstants[type][npmName]) {
198 this.updatedVideoConstants[type][npmName] = {
199 added: [],
200 deleted: []
201 }
202 }
203
204 this.updatedVideoConstants[type][npmName].added.push({ key, label })
205 obj[key] = label
206
207 return true
208 }
209
210 private deleteConstant<T extends string | number> (parameters: {
211 npmName: string
212 type: AlterableVideoConstant
213 obj: VideoConstant
214 key: T
215 }) {
216 const { npmName, type, obj, key } = parameters
217
218 if (!obj[key]) {
219 logger.warn('Cannot delete %s %s by plugin %s: key does not exist.', type, npmName, key)
220 return false
221 }
222
223 if (!this.updatedVideoConstants[type][npmName]) {
224 this.updatedVideoConstants[type][npmName] = {
225 added: [],
226 deleted: []
227 }
228 }
229
230 this.updatedVideoConstants[type][npmName].deleted.push({ key, label: obj[key] })
231 delete obj[key]
232
233 return true
234 }
235}
diff --git a/server/lib/plugins/register-helpers.ts b/server/lib/plugins/register-helpers.ts
deleted file mode 100644
index 4c0935a05..000000000
--- a/server/lib/plugins/register-helpers.ts
+++ /dev/null
@@ -1,180 +0,0 @@
1import { PluginSettingsManager } from '@shared/models/plugins/plugin-settings-manager.model'
2import { PluginModel } from '@server/models/server/plugin'
3import { PluginStorageManager } from '@shared/models/plugins/plugin-storage-manager.model'
4import { PluginVideoLanguageManager } from '@shared/models/plugins/plugin-video-language-manager.model'
5import { VIDEO_CATEGORIES, VIDEO_LANGUAGES, VIDEO_LICENCES } from '@server/initializers/constants'
6import { PluginVideoLicenceManager } from '@shared/models/plugins/plugin-video-licence-manager.model'
7import { PluginVideoCategoryManager } from '@shared/models/plugins/plugin-video-category-manager.model'
8import { RegisterServerOptions } from '@server/typings/plugins'
9import { buildPluginHelpers } from './plugin-helpers'
10import { logger } from '@server/helpers/logger'
11
12type AlterableVideoConstant = 'language' | 'licence' | 'category'
13type VideoConstant = { [key in number | string]: string }
14type UpdatedVideoConstant = {
15 [name in AlterableVideoConstant]: {
16 [npmName: string]: {
17 added: { key: number | string, label: string }[]
18 deleted: { key: number | string, label: string }[]
19 }
20 }
21}
22
23const updatedVideoConstants: UpdatedVideoConstant = {
24 language: {},
25 licence: {},
26 category: {}
27}
28
29function buildRegisterHelpers (npmName: string, plugin: PluginModel): Omit<RegisterServerOptions, 'registerHook' | 'registerSetting'> {
30 const settingsManager = buildSettingsManager(plugin)
31 const storageManager = buildStorageManager(plugin)
32
33 const videoLanguageManager = buildVideoLanguageManager(npmName)
34
35 const videoCategoryManager = buildVideoCategoryManager(npmName)
36 const videoLicenceManager = buildVideoLicenceManager(npmName)
37
38 const peertubeHelpers = buildPluginHelpers(npmName)
39
40 return {
41 settingsManager,
42 storageManager,
43 videoLanguageManager,
44 videoCategoryManager,
45 videoLicenceManager,
46 peertubeHelpers
47 }
48}
49
50function reinitVideoConstants (npmName: string) {
51 const hash = {
52 language: VIDEO_LANGUAGES,
53 licence: VIDEO_LICENCES,
54 category: VIDEO_CATEGORIES
55 }
56 const types: AlterableVideoConstant[] = [ 'language', 'licence', 'category' ]
57
58 for (const type of types) {
59 const updatedConstants = updatedVideoConstants[type][npmName]
60 if (!updatedConstants) continue
61
62 for (const added of updatedConstants.added) {
63 delete hash[type][added.key]
64 }
65
66 for (const deleted of updatedConstants.deleted) {
67 hash[type][deleted.key] = deleted.label
68 }
69
70 delete updatedVideoConstants[type][npmName]
71 }
72}
73
74export {
75 buildRegisterHelpers,
76 reinitVideoConstants
77}
78
79// ---------------------------------------------------------------------------
80
81function buildSettingsManager (plugin: PluginModel): PluginSettingsManager {
82 return {
83 getSetting: (name: string) => PluginModel.getSetting(plugin.name, plugin.type, name),
84
85 setSetting: (name: string, value: string) => PluginModel.setSetting(plugin.name, plugin.type, name, value)
86 }
87}
88
89function buildStorageManager (plugin: PluginModel): PluginStorageManager {
90 return {
91 getData: (key: string) => PluginModel.getData(plugin.name, plugin.type, key),
92
93 storeData: (key: string, data: any) => PluginModel.storeData(plugin.name, plugin.type, key, data)
94 }
95}
96
97function buildVideoLanguageManager (npmName: string): PluginVideoLanguageManager {
98 return {
99 addLanguage: (key: string, label: string) => addConstant({ npmName, type: 'language', obj: VIDEO_LANGUAGES, key, label }),
100
101 deleteLanguage: (key: string) => deleteConstant({ npmName, type: 'language', obj: VIDEO_LANGUAGES, key })
102 }
103}
104
105function buildVideoCategoryManager (npmName: string): PluginVideoCategoryManager {
106 return {
107 addCategory: (key: number, label: string) => {
108 return addConstant({ npmName, type: 'category', obj: VIDEO_CATEGORIES, key, label })
109 },
110
111 deleteCategory: (key: number) => {
112 return deleteConstant({ npmName, type: 'category', obj: VIDEO_CATEGORIES, key })
113 }
114 }
115}
116
117function buildVideoLicenceManager (npmName: string): PluginVideoLicenceManager {
118 return {
119 addLicence: (key: number, label: string) => {
120 return addConstant({ npmName, type: 'licence', obj: VIDEO_LICENCES, key, label })
121 },
122
123 deleteLicence: (key: number) => {
124 return deleteConstant({ npmName, type: 'licence', obj: VIDEO_LICENCES, key })
125 }
126 }
127}
128
129function addConstant<T extends string | number> (parameters: {
130 npmName: string
131 type: AlterableVideoConstant
132 obj: VideoConstant
133 key: T
134 label: string
135}) {
136 const { npmName, type, obj, key, label } = parameters
137
138 if (obj[key]) {
139 logger.warn('Cannot add %s %s by plugin %s: key already exists.', type, npmName, key)
140 return false
141 }
142
143 if (!updatedVideoConstants[type][npmName]) {
144 updatedVideoConstants[type][npmName] = {
145 added: [],
146 deleted: []
147 }
148 }
149
150 updatedVideoConstants[type][npmName].added.push({ key, label })
151 obj[key] = label
152
153 return true
154}
155
156function deleteConstant<T extends string | number> (parameters: {
157 npmName: string
158 type: AlterableVideoConstant
159 obj: VideoConstant
160 key: T
161}) {
162 const { npmName, type, obj, key } = parameters
163
164 if (!obj[key]) {
165 logger.warn('Cannot delete %s %s by plugin %s: key does not exist.', type, npmName, key)
166 return false
167 }
168
169 if (!updatedVideoConstants[type][npmName]) {
170 updatedVideoConstants[type][npmName] = {
171 added: [],
172 deleted: []
173 }
174 }
175
176 updatedVideoConstants[type][npmName].deleted.push({ key, label: obj[key] })
177 delete obj[key]
178
179 return true
180}
diff --git a/server/middlewares/validators/plugins.ts b/server/middlewares/validators/plugins.ts
index 910d03c29..65765f473 100644
--- a/server/middlewares/validators/plugins.ts
+++ b/server/middlewares/validators/plugins.ts
@@ -1,5 +1,5 @@
1import * as express from 'express' 1import * as express from 'express'
2import { body, param, query } from 'express-validator' 2import { body, param, query, ValidationChain } from 'express-validator'
3import { logger } from '../../helpers/logger' 3import { logger } from '../../helpers/logger'
4import { areValidationErrors } from './utils' 4import { areValidationErrors } from './utils'
5import { isNpmPluginNameValid, isPluginNameValid, isPluginTypeValid, isPluginVersionValid } from '../../helpers/custom-validators/plugins' 5import { isNpmPluginNameValid, isPluginNameValid, isPluginTypeValid, isPluginVersionValid } from '../../helpers/custom-validators/plugins'
@@ -10,24 +10,43 @@ import { InstallOrUpdatePlugin } from '../../../shared/models/plugins/install-pl
10import { PluginType } from '../../../shared/models/plugins/plugin.type' 10import { PluginType } from '../../../shared/models/plugins/plugin.type'
11import { CONFIG } from '../../initializers/config' 11import { CONFIG } from '../../initializers/config'
12 12
13const servePluginStaticDirectoryValidator = (pluginType: PluginType) => [ 13const getPluginValidator = (pluginType: PluginType, withVersion = true) => {
14 param('pluginName').custom(isPluginNameValid).withMessage('Should have a valid plugin name'), 14 const validators: (ValidationChain | express.Handler)[] = [
15 param('pluginVersion').custom(isPluginVersionValid).withMessage('Should have a valid plugin version'), 15 param('pluginName').custom(isPluginNameValid).withMessage('Should have a valid plugin name')
16 param('staticEndpoint').custom(isSafePath).withMessage('Should have a valid static endpoint'), 16 ]
17 17
18 (req: express.Request, res: express.Response, next: express.NextFunction) => { 18 if (withVersion) {
19 logger.debug('Checking servePluginStaticDirectory parameters', { parameters: req.params }) 19 validators.push(
20 param('pluginVersion').custom(isPluginVersionValid).withMessage('Should have a valid plugin version')
21 )
22 }
20 23
21 if (areValidationErrors(req, res)) return 24 return validators.concat([
25 (req: express.Request, res: express.Response, next: express.NextFunction) => {
26 logger.debug('Checking getPluginValidator parameters', { parameters: req.params })
27
28 if (areValidationErrors(req, res)) return
29
30 const npmName = PluginModel.buildNpmName(req.params.pluginName, pluginType)
31 const plugin = PluginManager.Instance.getRegisteredPluginOrTheme(npmName)
32
33 if (!plugin) return res.sendStatus(404)
34 if (withVersion && plugin.version !== req.params.pluginVersion) return res.sendStatus(404)
22 35
23 const npmName = PluginModel.buildNpmName(req.params.pluginName, pluginType) 36 res.locals.registeredPlugin = plugin
24 const plugin = PluginManager.Instance.getRegisteredPluginOrTheme(npmName)
25 37
26 if (!plugin || plugin.version !== req.params.pluginVersion) { 38 return next()
27 return res.sendStatus(404)
28 } 39 }
40 ])
41}
42
43const pluginStaticDirectoryValidator = [
44 param('staticEndpoint').custom(isSafePath).withMessage('Should have a valid static endpoint'),
29 45
30 res.locals.registeredPlugin = plugin 46 (req: express.Request, res: express.Response, next: express.NextFunction) => {
47 logger.debug('Checking pluginStaticDirectoryValidator parameters', { parameters: req.params })
48
49 if (areValidationErrors(req, res)) return
31 50
32 return next() 51 return next()
33 } 52 }
@@ -149,7 +168,8 @@ const listAvailablePluginsValidator = [
149// --------------------------------------------------------------------------- 168// ---------------------------------------------------------------------------
150 169
151export { 170export {
152 servePluginStaticDirectoryValidator, 171 pluginStaticDirectoryValidator,
172 getPluginValidator,
153 updatePluginSettingsValidator, 173 updatePluginSettingsValidator,
154 uninstallPluginValidator, 174 uninstallPluginValidator,
155 listAvailablePluginsValidator, 175 listAvailablePluginsValidator,
diff --git a/server/tests/fixtures/peertube-plugin-test-five/main.js b/server/tests/fixtures/peertube-plugin-test-five/main.js
new file mode 100644
index 000000000..c1435b928
--- /dev/null
+++ b/server/tests/fixtures/peertube-plugin-test-five/main.js
@@ -0,0 +1,21 @@
1async function register ({
2 getRouter
3}) {
4 const router = getRouter()
5 router.get('/ping', (req, res) => res.json({ message: 'pong' }))
6
7 router.post('/form/post/mirror', (req, res) => {
8 res.json(req.body)
9 })
10}
11
12async function unregister () {
13 return
14}
15
16module.exports = {
17 register,
18 unregister
19}
20
21// ###########################################################################
diff --git a/server/tests/fixtures/peertube-plugin-test-five/package.json b/server/tests/fixtures/peertube-plugin-test-five/package.json
new file mode 100644
index 000000000..1f5d65d9d
--- /dev/null
+++ b/server/tests/fixtures/peertube-plugin-test-five/package.json
@@ -0,0 +1,20 @@
1{
2 "name": "peertube-plugin-test-five",
3 "version": "0.0.1",
4 "description": "Plugin test 5",
5 "engine": {
6 "peertube": ">=1.3.0"
7 },
8 "keywords": [
9 "peertube",
10 "plugin"
11 ],
12 "homepage": "https://github.com/Chocobozzz/PeerTube",
13 "author": "Chocobozzz",
14 "bugs": "https://github.com/Chocobozzz/PeerTube/issues",
15 "library": "./main.js",
16 "staticDirs": {},
17 "css": [],
18 "clientScripts": [],
19 "translations": {}
20}
diff --git a/server/tests/plugins/index.ts b/server/tests/plugins/index.ts
index 9c9499a79..1414e7e58 100644
--- a/server/tests/plugins/index.ts
+++ b/server/tests/plugins/index.ts
@@ -3,3 +3,4 @@ import './filter-hooks'
3import './translations' 3import './translations'
4import './video-constants' 4import './video-constants'
5import './plugin-helpers' 5import './plugin-helpers'
6import './plugin-router'
diff --git a/server/tests/plugins/plugin-router.ts b/server/tests/plugins/plugin-router.ts
new file mode 100644
index 000000000..cf4130f4b
--- /dev/null
+++ b/server/tests/plugins/plugin-router.ts
@@ -0,0 +1,91 @@
1/* eslint-disable @typescript-eslint/no-unused-expressions,@typescript-eslint/require-await */
2
3import 'mocha'
4import { cleanupTests, flushAndRunServer, ServerInfo } from '../../../shared/extra-utils/server/servers'
5import {
6 getPluginTestPath,
7 installPlugin,
8 makeGetRequest,
9 makePostBodyRequest,
10 setAccessTokensToServers, uninstallPlugin
11} from '../../../shared/extra-utils'
12import { expect } from 'chai'
13
14describe('Test plugin helpers', function () {
15 let server: ServerInfo
16 const basePaths = [
17 '/plugins/test-five/router/',
18 '/plugins/test-five/0.0.1/router/'
19 ]
20
21 before(async function () {
22 this.timeout(30000)
23
24 server = await flushAndRunServer(1)
25 await setAccessTokensToServers([ server ])
26
27 await installPlugin({
28 url: server.url,
29 accessToken: server.accessToken,
30 path: getPluginTestPath('-five')
31 })
32 })
33
34 it('Should answer "pong"', async function () {
35 for (const path of basePaths) {
36 const res = await makeGetRequest({
37 url: server.url,
38 path: path + 'ping',
39 statusCodeExpected: 200
40 })
41
42 expect(res.body.message).to.equal('pong')
43 }
44 })
45
46 it('Should mirror post body', async function () {
47 const body = {
48 hello: 'world',
49 riri: 'fifi',
50 loulou: 'picsou'
51 }
52
53 for (const path of basePaths) {
54 const res = await makePostBodyRequest({
55 url: server.url,
56 path: path + 'form/post/mirror',
57 fields: body,
58 statusCodeExpected: 200
59 })
60
61 expect(res.body).to.deep.equal(body)
62 }
63 })
64
65 it('Should remove the plugin and remove the routes', async function () {
66 await uninstallPlugin({
67 url: server.url,
68 accessToken: server.accessToken,
69 npmName: 'peertube-plugin-test-five'
70 })
71
72 for (const path of basePaths) {
73 await makeGetRequest({
74 url: server.url,
75 path: path + 'ping',
76 statusCodeExpected: 404
77 })
78
79 await makePostBodyRequest({
80 url: server.url,
81 path: path + 'ping',
82 fields: {},
83 statusCodeExpected: 404
84 })
85 }
86 })
87
88 after(async function () {
89 await cleanupTests([ server ])
90 })
91})
diff --git a/server/typings/plugins/register-server-option.model.ts b/server/typings/plugins/register-server-option.model.ts
index fda9afb11..3d6217d1b 100644
--- a/server/typings/plugins/register-server-option.model.ts
+++ b/server/typings/plugins/register-server-option.model.ts
@@ -6,6 +6,7 @@ import { PluginVideoCategoryManager } from '../../../shared/models/plugins/plugi
6import { PluginVideoLanguageManager } from '../../../shared/models/plugins/plugin-video-language-manager.model' 6import { PluginVideoLanguageManager } from '../../../shared/models/plugins/plugin-video-language-manager.model'
7import { PluginVideoLicenceManager } from '../../../shared/models/plugins/plugin-video-licence-manager.model' 7import { PluginVideoLicenceManager } from '../../../shared/models/plugins/plugin-video-licence-manager.model'
8import { Logger } from 'winston' 8import { Logger } from 'winston'
9import { Router } from 'express'
9 10
10export type PeerTubeHelpers = { 11export type PeerTubeHelpers = {
11 logger: Logger 12 logger: Logger
@@ -32,5 +33,11 @@ export type RegisterServerOptions = {
32 videoLanguageManager: PluginVideoLanguageManager 33 videoLanguageManager: PluginVideoLanguageManager
33 videoLicenceManager: PluginVideoLicenceManager 34 videoLicenceManager: PluginVideoLicenceManager
34 35
36 // Get plugin router to create custom routes
37 // Base routes of this router are
38 // * /plugins/:pluginName/:pluginVersion/router/...
39 // * /plugins/:pluginName/router/...
40 getRouter(): Router
41
35 peertubeHelpers: PeerTubeHelpers 42 peertubeHelpers: PeerTubeHelpers
36} 43}
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 8e720e94b..bdc9d2ad8 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -12,6 +12,7 @@
12 - [Settings](#settings) 12 - [Settings](#settings)
13 - [Storage](#storage) 13 - [Storage](#storage)
14 - [Update video constants](#update-video-constants) 14 - [Update video constants](#update-video-constants)
15 - [Add custom routes](#add-custom-routes)
15 - [Client helpers (themes & plugins)](#client-helpers-themes--plugins) 16 - [Client helpers (themes & plugins)](#client-helpers-themes--plugins)
16 - [Plugin static route](#plugin-static-route) 17 - [Plugin static route](#plugin-static-route)
17 - [Translate](#translate) 18 - [Translate](#translate)
@@ -71,7 +72,9 @@ async function register ({
71 storageManager, 72 storageManager,
72 videoCategoryManager, 73 videoCategoryManager,
73 videoLicenceManager, 74 videoLicenceManager,
74 videoLanguageManager 75 videoLanguageManager,
76 peertubeHelpers,
77 getRouter
75}) { 78}) {
76 registerHook({ 79 registerHook({
77 target: 'action:application.listening', 80 target: 'action:application.listening',
@@ -178,6 +181,20 @@ videoLicenceManager.addLicence(42, 'Best licence')
178videoLicenceManager.deleteLicence(7) // Public domain 181videoLicenceManager.deleteLicence(7) // Public domain
179``` 182```
180 183
184#### Add custom routes
185
186You can create custom routes using an [express Router](https://expressjs.com/en/4x/api.html#router) for your plugin:
187
188```js
189const router = getRouter()
190router.get('/ping', (req, res) => res.json({ message: 'pong' }))
191```
192
193The `ping` route can be accessed using:
194 * `/plugins/:pluginName/:pluginVersion/router/ping`
195 * Or `/plugins/:pluginName/router/ping`
196
197
181### Client helpers (themes & plugins) 198### Client helpers (themes & plugins)
182 199
183### Plugin static route 200### Plugin static route