Merge pull request #1 from cdr/plugin-api-b398

Add plugin API stub

Author: nhooyr

src/node/plugin.d.ts

@@ -0,0 +1,108 @@
+/**
+ * This file describes the code-server plugin API for adding new applications.
+ *
+ * This API is not stable and subject to change as we refine it.
+ */
+
+/**
+ * Overlay
+ *
+ * The homepage of code-server will launch into VS Code. However, there will be an overlay
+ * button that when clicked, will show all available applications with their names,
+ * icons and provider plugins. When one clicks on an app's icon, they will be directed
+ * to <code-server-root>/<plugin-name>/<app-name> to access the application.
+ *
+ * At some point we will adjust this API and the overlay to also easily allow installing
+ * new plugins and applications.
+ */
+
+/**
+ * Plugins
+ *
+ * Plugins are just node modules.
+ *
+ * code-server will use $CS_PLUGIN_PATH to find plugins. Each subdirectory in
+ * $CS_PLUGIN_PATH with a package.json where the engine is code-server is a plugin.
+ *
+ * e.g. CS_PLUGIN_PATH=/tmp/nhooyr:/tmp/ash will cause code-server to search
+ * /tmp/nhooyr and then /tmp/ash for plugins.
+ *
+ * After the search is complete, plugins will be required in first found order and
+ * inited via the API described below.
+ *
+ * There will also be a /api/applications endpoint to allow programmatic access to all
+ * available applications. It could be used to create a custom application dashboard for
+ * example.
+ */
+import { Logger } from "@coder/logger"
+
+/**
+ * Your plugin module must implement this interface.
+ *
+ * The plugin's name, description and version are fetched from its module's package.json
+ *
+ * All routes registered by a plugin will be automatically under
+ * <code-server-root>/<plugin-name>
+ *
+ * If two plugins are found with the exact same name, then code-server will
+ * use the last one found and emit a warning.
+ */
+export interface Plugin {
+  /**
+   *
+   * This is called when /api/applications is hit or the code-server overlay
+   * needs to refresh the list of applications and so code-server is collecting
+   * each plugin's list of applications.
+   *
+   * Ensure this is as fast as possible.
+   */
+  applications(): Application[] | Promise<Application[]>
+
+  /**
+   * init passes the API interface to the plugin so that it may register its routes.
+   */
+  init(api: API): void
+}
+
+/**
+ * Application represents a user accessible application.
+ *
+ * When the user clicks on the icon, they will be redirected to
+ * <code-server-root>/<plugin-name>/<app-name>
+ * where the application should be accessible.
+ *
+ * If the app's name is the same as the plugin's name then
+ * <code-server-root>/<plugin-name> will be used instead.
+ */
+export interface Application {
+  readonly name: string
+
+  /**
+   * The path at which the icon for this application can be accessed.
+   * <code-server-root>/<plugin-name>/<app-name>/<icon-path>
+   */
+  readonly iconPath: string
+
+  /**
+   * Used to indicate the version of the application.
+   */
+  readonly version: string
+}
+
+/**
+ * API is passed to plugins so that they may register their routes.
+ */
+export interface API {
+  /**
+   * All plugin logs should be logged via this logger.
+   */
+  readonly log: Logger
+
+  /**
+   * ....
+   *
+   * API idential to express to register routes under the plugin's subpath.
+   * plugins can use proxy middlewhere to send their requests to their own
+   * server if they cannot or do not want to use node/express.
+   */
+}