diff --git a/docs/dev-plugins.md b/docs/dev-plugins.md index 4304c6127..5d980fa35 100644 --- a/docs/dev-plugins.md +++ b/docs/dev-plugins.md @@ -3,29 +3,44 @@ id: dev-plugins title: "Developing Plugins" --- -There are many ways to extend `verdaccio`, currently we support `authentication plugins`, `middleware plugins` (since `v2.7.0`) and `storage plugins` since (`v3.x`). +There are many ways to extend `verdaccio`, the kind of plugins supported are: + +* Authentication plugins +* Middleware plugins (since `v2.7.0`) +* Storage plugins since (`v3.x`) + +> We recommend developing plugins using our [flow type definitions](https://github.com/verdaccio/flow-types). ## Authentication Plugin -This section will describe how it looks like a Verdaccio plugin in a ES5 way. Basically we have to return an object with a single method called `authenticate` that will recieve 3 arguments (`user, password, callback`). Once the authentication has been executed there is 2 options to give a response to `verdaccio`. +Basically we have to return an object with a single method called `authenticate` that will recieve 3 arguments (`user, password, callback`). ### API -```js -function authenticate (user, password, callback) { - ...more stuff +```flow +interface IPluginAuth extends IPlugin { + login_url?: string; + authenticate(user: string, password: string, cb: Callback): void; + adduser(user: string, password: string, cb: Callback): void; + allow_access(user: RemoteUser, pkg: $Subtype, cb: Callback): void; + allow_publish(user: RemoteUser, pkg: $Subtype, cb: Callback): void; } ``` +> Only `adduser`, `allow_access` and `allow_publish` are optional, verdaccio provide a fallback in all those cases. -##### OnError +#### Callback + +Once the authentication has been executed there is 2 options to give a response to `verdaccio`. + +###### OnError Either something bad happened or auth was unsuccessful. -``` +```flow callback(null, false) ``` -##### OnSuccess +###### OnSuccess The auth was successful. @@ -69,7 +84,7 @@ Auth.prototype.authenticate = function (user, password, callback) { module.exports = Auth; ``` -And the setup +And the configuration will looks like: ```yaml auth: @@ -81,7 +96,17 @@ Where `htpasswd` is the sufix of the plugin name. eg: `verdaccio-htpasswd` and t ## Middleware Plugin Middleware plugins have the capability to modify the API layer, either adding new endpoints or intercepting requests. - + +```flow +interface verdaccio$IPluginMiddleware extends verdaccio$IPlugin { + register_middlewares(app: any, auth: IBasicAuth, storage: IStorageManager): void; +} +``` + +### register_middlewares + +The method provide full access to the authentification and storage via `auth` and `storage`. `app` is the express application that allows you to add new endpoints. + > A pretty good example of middleware plugin is the [sinopia-github-oauth](https://github.com/soundtrackyourbrand/sinopia-github-oauth) and [verdaccio-audit](https://github.com/verdaccio/verdaccio-audit). @@ -99,28 +124,32 @@ To register a middleware we need an object with a single method called `register ## Storage Plugin -Verdaccio by default uses a file system storage plugin [local-storage](https://github.com/verdaccio/local-storage) but, since `verdaccio@3.x` you can plug in a custom storage. +Verdaccio by default uses a file system storage plugin [local-storage](https://github.com/verdaccio/local-storage), but, since `verdaccio@3.x` you can plug in a custom storage replacing the default behaviour. ### API -The storage API is a bit more complex, you will need to create a class that return a `ILocalData` implementation. Please see details bellow. +The storage API is a bit more complex, you will need to create a class that return a `IPluginStorage` implementation. Please see details bellow. -```js - -class LocalDatabase{ - constructor(config: Config, logger: Logger): ILocalData; +```flow +class LocalDatabase{ + constructor(config: $Subtype, logger: verdaccio$Logger): ILocalData; } -declare interface verdaccio$ILocalData { +interface IPluginStorage { + logger: verdaccio$Logger; + config: $Subtype; add(name: string, callback: verdaccio$Callback): void; remove(name: string, callback: verdaccio$Callback): void; get(callback: verdaccio$Callback): void; getSecret(): Promise; setSecret(secret: string): Promise; getPackageStorage(packageInfo: string): verdaccio$IPackageStorage; + search(onPackage: verdaccio$Callback, onEnd: verdaccio$Callback, validateName: Function): void; } -declare interface verdaccio$ILocalPackageManager { +interface IPackageStorageManager { + path: string; + logger: verdaccio$Logger; writeTarball(name: string): verdaccio$IUploadTarball; readTarball(name: string): verdaccio$IReadTarball; readPackage(fileName: string, callback: verdaccio$Callback): void; @@ -135,14 +164,17 @@ declare interface verdaccio$ILocalPackageManager { savePackage(fileName: string, json: verdaccio$Package, callback: verdaccio$Callback): void; } -interface IUploadTarball extends stream$PassThrough { +class verdaccio$IUploadTarball extends stream$PassThrough { + abort: Function; + done: Function; + _transform: Function; abort(): void; done(): void; } -interface IReadTarball extends stream$PassThrough { +class verdaccio$IReadTarball extends stream$PassThrough { + abort: Function; abort(): void; - done(): void; } ``` diff --git a/docs/install.md b/docs/install.md index 8a195fb15..cc6d3411c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -41,8 +41,6 @@ warn --- config file - /home/.config/verdaccio/config.yaml warn --- http address - http://localhost:4873/ - verdaccio/3.0.1 ``` -![](https://cdn-images-1.medium.com/max/720/1*jDHnZ7_68u5s1lFK2cygnA.gif) - For more information about the CLI, please [read the cli section](cli.md). ## Docker Image diff --git a/docs/plugins.md b/docs/plugins.md index de6ee800a..3ee8ae90b 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -3,9 +3,9 @@ id: plugins title: "Plugins" --- -Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding +Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding endpoints or using a custom storage. - + > If you are interested to develop your own plugin, read the [development](dev-plugins.md) section. ## Usage @@ -26,8 +26,8 @@ $> npm install --global sinopia-memory Open the `config.yaml` file and update the `auth` section as follows: The default configuration looks like this, due we use a build-in `htpasswd` plugin by default that you can disable just commenting out the following lines. - - + + ### Auth Plugin Configuration ```yaml @@ -71,6 +71,8 @@ middlewares: enabled: true ``` +> You might follow the [audit middle plugin](https://github.com/verdaccio/verdaccio-audit) as base example. + ### Store Plugin Configuration This is an example how to set up a storage plugin. All storage plugins must be defined in the **store** namespace. @@ -139,5 +141,5 @@ modern verdaccio API and using the prefix as *verdaccio-xx-name*. ## Caveats -> Not all these plugins are been tested continuously, some of them might not work at all. +> Not all these plugins are been tested continuously, some of them might not work at all. Please if you found any issue feel free to notify the owner of each plugin. diff --git a/docs/web.md b/docs/web.md index 90b7712bf..9334547e4 100644 --- a/docs/web.md +++ b/docs/web.md @@ -1,9 +1,9 @@ --- id: webui -title: "Web User Interface" +title: "Web User Interface2" --- -

+

Verdaccio has a web user interface to display only the private packges and can be customisable.