🔌 extend the server api for enhanced binder connections (#681)

* ⚙️ server can now accept custom provider specs for binder connection url building
* 🔌 repoproviderspecs as default

package.json

@@ -17,6 +17,7 @@
     "demo": "turbo run demo",
     "docs": "turbo run docs",
     "test": "turbo run test",
+    "test:core:watch": "turbo run test:watch --filter=thebe-core",
     "test:e2e": "turbo run test:e2e",
     "lint": "turbo run lint",
     "lint:format": "turbo run lint:format",
@@ -52,7 +53,7 @@
   },
   "homepage": "https://thebe.readthedocs.io/en/latest",
   "devDependencies": {
-    "happy-dom": "^10.10.4",
+    "happy-dom": "^10.11.2",
     "turbo": "^1.4.2",
     "vitest": "^0.34.2"
   },

packages/core/src/config.ts

@@ -24,8 +24,8 @@ export class Config {
   private _serverSettings: Required<Omit<ServerSettings, 'wsUrl'>> & { wsUrl?: string };
   private _events: ThebeEvents;
 
-  constructor(opts: CoreOptions = {}, events?: ThebeEvents) {
-    this._events = events ?? new ThebeEvents();
+  constructor(opts: CoreOptions = {}, extraConfig?: { events?: ThebeEvents }) {
+    this._events = extraConfig?.events ?? new ThebeEvents();
 
     this._options = {
       mathjaxUrl:

packages/core/src/options.ts

@@ -8,14 +8,13 @@ import type {
   SavedSessionOptions,
   MathjaxOptions,
 } from './types';
-import { RepoProvider } from './types';
 
 export function makeBinderOptions(opts: BinderOptions) {
   return {
     repo: 'executablebooks/thebe-binder-base',
     ref: 'HEAD',
     binderUrl: 'https://mybinder.org',
-    repoProvider: RepoProvider.github,
+    repoProvider: 'github',
     ...opts,
   };
 }
@@ -58,14 +57,14 @@ export function makeConfiguration(
   options: CoreOptions & { [k: string]: any },
   events?: ThebeEvents,
 ) {
-  return new Config(options, events);
+  return new Config(options, { events });
 }
 
 export function ensureCoreOptions(
   options: CoreOptions & { [k: string]: any },
   events?: ThebeEvents,
 ): Required<CoreOptions> {
-  const config = new Config(options, events);
+  const config = new Config(options, { events });
 
   return {
     ...config.base,

packages/core/src/server.ts

@@ -1,5 +1,6 @@
 import type {
   KernelOptions,
+  RepoProviderSpec,
   RestAPIContentsResponse,
   ServerRestAPI,
   ServerRuntime,
@@ -11,8 +12,8 @@ import type { ServiceManager } from '@jupyterlab/services';
 import type { LiteServerConfig } from 'thebe-lite';
 import type { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import type { StatusEvent } from './events';
-import { RepoProvider } from './types';
-import { makeGitHubUrl, makeGitLabUrl, makeGitUrl } from './url';
+import { WellKnownRepoProvider } from './types';
+import { WELL_KNOWN_REPO_PROVIDERS, makeBinderUrl } from './url';
 import { getExistingServer, makeStorageKey, saveServerInfo } from './sessions';
 import {
   KernelManager,
@@ -37,6 +38,7 @@ class ThebeServer implements ServerRuntime, ServerRestAPI {
   readonly ready: Promise<ThebeServer>;
   sessionManager?: SessionManager;
   serviceManager?: ServiceManager; // jlite only
+  repoProviders?: RepoProviderSpec[];
   private resolveReadyFn?: (value: ThebeServer | PromiseLike<ThebeServer>) => void;
   private _isDisposed: boolean;
   private events: EventEmitter;
@@ -243,25 +245,8 @@ class ThebeServer implements ServerRuntime, ServerRestAPI {
     });
   }
 
-  _makeBinderUrl() {
-    let url: string;
-    switch (this.config.binder.repoProvider) {
-      case RepoProvider.git:
-        url = makeGitUrl(this.config.binder);
-        break;
-      case RepoProvider.gitlab:
-        url = makeGitLabUrl(this.config.binder);
-        break;
-      case RepoProvider.github:
-      default:
-        url = makeGitHubUrl(this.config.binder);
-        break;
-    }
-    return url;
-  }
-
   async checkForSavedBinderSession() {
-    const url = this._makeBinderUrl();
+    const url = makeBinderUrl(this.config.binder, this.repoProviders ?? WELL_KNOWN_REPO_PROVIDERS);
     return getExistingServer(this.config.savedSessions, url);
   }
 
@@ -273,14 +258,17 @@ class ThebeServer implements ServerRuntime, ServerRestAPI {
    * @param opts
    * @returns
    */
-  async connectToServerViaBinder(): Promise<void> {
+  async connectToServerViaBinder(customProviders?: RepoProviderSpec[]): Promise<void> {
     // request new server
     this.events.triggerStatus({
       status: ServerStatusEvent.launching,
       message: `Connecting to binderhub at ${this.config.binder.binderUrl}`,
     });
 
-    const url = this._makeBinderUrl();
+    // TODO binder connection setup probably better as a a factory independent of the server
+    this.repoProviders = [...WELL_KNOWN_REPO_PROVIDERS, ...(customProviders ?? [])];
+
+    const url = makeBinderUrl(this.config.binder, this.repoProviders);
 
     this.events.triggerStatus({
       status: ServerStatusEvent.launching,

packages/core/src/types.ts

@@ -39,13 +39,13 @@ export interface CoreOptions {
   serverSettings?: ServerSettings;
 }
 
-export enum RepoProvider {
-  'git' = 'git',
-  'github' = 'github',
-  'gitlab' = 'gitlab',
-  'gist' = 'gist',
+export interface RepoProviderSpec {
+  name: string;
+  makeUrl: (opts: BinderOptions) => string;
 }
 
+export type WellKnownRepoProvider = 'git' | 'github' | 'gitlab' | 'gist';
+
 export type MathjaxOptions = Pick<CoreOptions, 'mathjaxConfig' | 'mathjaxUrl'>;
 
 export interface SavedSessionOptions {
@@ -58,7 +58,7 @@ export interface BinderOptions {
   repo?: string;
   ref?: string;
   binderUrl?: string;
-  repoProvider?: RepoProvider;
+  repoProvider?: WellKnownRepoProvider | string;
 }
 
 export interface ServerSettings {

packages/core/src/url.ts

@@ -1,9 +1,5 @@
-import type { BinderOptions } from './types';
-import { RepoProvider } from './types';
-
-function throwOnBadProvider(actual: RepoProvider, expected: RepoProvider) {
-  if (actual !== expected) throw Error(`Bad Provider, expected ${expected} got ${actual}`);
-}
+import type { BinderOptions, RepoProviderSpec } from './types';
+import { WellKnownRepoProvider } from './types';
 
 /**
  * Make a binder url for git providers
@@ -15,11 +11,11 @@ function throwOnBadProvider(actual: RepoProvider, expected: RepoProvider) {
  * @param opts BinderOptions
  * @returns a binder compatible url
  */
-export function makeGitUrl(opts: Required<BinderOptions>): string {
-  throwOnBadProvider(opts.repoProvider, RepoProvider.git);
+function makeGitUrl(opts: BinderOptions): string {
+  if (!opts.repo) throw Error('repo is required for git provider');
   const { repo, binderUrl, ref } = opts;
   const encodedRepo = encodeURIComponent(repo.replace(/(^\/)|(\/?$)/g, ''));
-  return `${binderUrl.replace(/(\/?$)/g, '')}/build/git/${encodedRepo}/${ref}`;
+  return `${binderUrl?.replace(/(\/?$)/g, '')}/build/git/${encodedRepo}/${ref ?? 'HEAD'}`;
 }
 
 /**
@@ -33,13 +29,13 @@ export function makeGitUrl(opts: Required<BinderOptions>): string {
  * @param opts BinderOptions
  * @returns  a binder compatible url
  */
-export function makeGitLabUrl(opts: Required<BinderOptions>): string {
-  throwOnBadProvider(opts.repoProvider, RepoProvider.gitlab);
-  const binderUrl = opts.binderUrl.replace(/(\/?$)/g, '');
+function makeGitLabUrl(opts: BinderOptions): string {
+  if (!opts.repo) throw Error('repo is required for gitlab provider');
+  const binderUrl = opts.binderUrl?.replace(/(\/?$)/g, '');
   const repo = encodeURIComponent(
-    opts.repo.replace(/^(https?:\/\/)?gitlab.com\//, '').replace(/(^\/)|(\/?$)/g, ''),
+    (opts.repo ?? '').replace(/^(https?:\/\/)?gitlab.com\//, '').replace(/(^\/)|(\/?$)/g, ''),
   );
-  return `${binderUrl}/build/gl/${repo}/${opts.ref}`;
+  return `${binderUrl}/build/gl/${repo}/${opts.ref ?? 'HEAD'}`;
 }
 
 /**
@@ -53,16 +49,55 @@ export function makeGitLabUrl(opts: Required<BinderOptions>): string {
  * @param opts BinderOptions
  * @returns  a binder compatible url
  */
-export function makeGitHubUrl(opts: Required<BinderOptions>): string {
-  throwOnBadProvider(opts.repoProvider, RepoProvider.github);
+function makeGitHubUrl(opts: BinderOptions): string {
+  if (!opts.repo) throw Error('repo is required for github provider');
   const repo = opts.repo.replace(/^(https?:\/\/)?github.com\//, '').replace(/(^\/)|(\/?$)/g, '');
-  const binderUrl = opts.binderUrl.replace(/(\/?$)/g, '');
-  return `${binderUrl}/build/gh/${repo}/${opts.ref}`;
+  const binderUrl = opts.binderUrl?.replace(/(\/?$)/g, '');
+  return `${binderUrl}/build/gh/${repo}/${opts.ref ?? 'HEAD'}`;
 }
 
-export function makeGistUrl(opts: Required<BinderOptions>): string {
-  throwOnBadProvider(opts.repoProvider, RepoProvider.gist);
+function makeGistUrl(opts: BinderOptions): string {
+  if (!opts.repo) throw Error('repo is required for gist provider');
   const repo = opts.repo.replace(/^(https?:\/\/)?github.com\//, '').replace(/(^\/)|(\/?$)/g, '');
-  const binderUrl = opts.binderUrl.replace(/(\/?$)/g, '');
-  return `${binderUrl}/build/gist/${repo}/${opts.ref}`;
+  const binderUrl = opts.binderUrl?.replace(/(\/?$)/g, '');
+  return `${binderUrl}/build/gist/${repo}/${opts.ref ?? 'HEAD'}`;
+}
+
+export const GITHUB_SPEC: RepoProviderSpec = {
+  name: 'github',
+  makeUrl: makeGitHubUrl,
+};
+
+export const GITLAB_SPEC: RepoProviderSpec = {
+  name: 'gitlab',
+  makeUrl: makeGitLabUrl,
+};
+
+export const GIT_SPEC: RepoProviderSpec = {
+  name: 'git',
+  makeUrl: makeGitUrl,
+};
+
+export const GIST_SPEC: RepoProviderSpec = {
+  name: 'gist',
+  makeUrl: makeGistUrl,
+};
+
+export const WELL_KNOWN_REPO_PROVIDERS = [GITHUB_SPEC, GITLAB_SPEC, GIT_SPEC, GIST_SPEC];
+
+/**
+ * Make a binder url for both well known or custom providers
+ *
+ * Custom providers are supported by passing in an array of CustomRepoProviderSpecs.
+ *
+ */
+export function makeBinderUrl(opts: BinderOptions, repoProviders: RepoProviderSpec[]): string {
+  const providerMap: Record<string, RepoProviderSpec> =
+    repoProviders.reduce((obj, spec) => ({ ...obj, [spec.name]: spec }), {}) ?? {};
+
+  const provider = opts.repoProvider ?? 'github';
+  if (!Object.keys(providerMap).includes(provider))
+    throw Error(`Unknown provider ${opts.repoProvider}`);
+
+  return providerMap[provider].makeUrl(opts);
 }

packages/core/tests/config.spec.ts

@@ -19,7 +19,7 @@ describe('config', () => {
         repo: 'executablebooks/thebe-binder-base',
         ref: 'HEAD',
         binderUrl: 'https://mybinder.org',
-        repoProvider: RepoProvider.github,
+        repoProvider: 'github',
       });
     });
     test('kernels', () => {

packages/core/tests/options.spec.ts

@@ -1,6 +1,5 @@
 import { describe, test, expect } from 'vitest';
 
-import { RepoProvider } from '../src/types';
 import {
   makeBinderOptions,
   makeKernelOptions,
@@ -15,7 +14,7 @@ describe('options', () => {
         repo: 'executablebooks/thebe-binder-base',
         ref: 'HEAD',
         binderUrl: 'https://mybinder.org',
-        repoProvider: RepoProvider.github,
+        repoProvider: 'github',
       });
     });
     test('override all', () => {
@@ -24,13 +23,13 @@ describe('options', () => {
           repo: 'abc',
           ref: 'x',
           binderUrl: 'anystring',
-          repoProvider: RepoProvider.git,
+          repoProvider: 'git',
         }),
       ).toEqual({
         repo: 'abc',
         ref: 'x',
         binderUrl: 'anystring',
-        repoProvider: RepoProvider.git,
+        repoProvider: 'git',
       });
     });
   });