api: refactor, add user endpoints

Author: ChlodAlejandro

src/Deputy.ts

@@ -3,7 +3,7 @@ import DeputyStorage from './DeputyStorage';
 import DeputyCommunications from './DeputyCommunications';
 import DeputySession from './session/DeputySession';
 import DeputyCasePage from './wiki/DeputyCasePage';
-import DeputyDispatch from './api/DeputyDispatch';
+import Dispatch from './api/Dispatch';
 import ContributionSurveyRow from './models/ContributionSurveyRow';
 import performHacks from './wiki/util/performHacks';
 import DeputyCase from './wiki/DeputyCase';
@@ -40,7 +40,7 @@ class Deputy {
 	 * @private
 	 */
 	static instance: Deputy;
-	readonly DeputyDispatch = DeputyDispatch;
+	readonly DeputyDispatch = Dispatch;
 	readonly DeputyStorage = DeputyStorage;
 	readonly DeputySession = DeputySession;
 	readonly DeputyCommunications = DeputyCommunications;
@@ -71,7 +71,7 @@ class Deputy {
 
 	// Components
 
-	dispatch: DeputyDispatch;
+	dispatch: Dispatch;
 	storage: DeputyStorage;
 	comms: DeputyCommunications;
 	session: DeputySession;
@@ -150,7 +150,7 @@ class Deputy {
 		this.storage = new DeputyStorage();
 		await this.storage.init();
 		// Initialize the Deputy API interface
-		this.dispatch = new DeputyDispatch();
+		this.dispatch = Dispatch.i;
 		// Initialize communications
 		this.comms = new DeputyCommunications();
 		this.comms.init();

src/api/DeputyDispatch.ts

@@ -0,0 +1,60 @@
+import { ExpandedRevisionData } from './ExpandedRevisionData';
+import Requester from '../util/Requester';
+import { deputyVersion } from '../DeputyVersion';
+
+/**
+ * API communication class
+ */
+export default class Dispatch {
+
+	/**
+	 * Singleton instance.
+	 */
+	static readonly i = new Dispatch();
+
+	/**
+	 * Token used for authentication on the server side. Allows access to deleted
+	 * revisions if the user has proper rights.
+	 */
+	static token?: string;
+
+	/**
+	 * Creates a Deputy API instance.
+	 */
+	private constructor() { /* ignored for now */ }
+
+	/**
+	 * Logs the user out of the API.
+	 */
+	async logout() {
+		// TODO: Make logout API request
+		await window.deputy.storage.setKV( 'api-token', null );
+	}
+
+	/**
+	 * Logs in the user. Optional: only used for getting data on deleted revisions.
+	 */
+	async login() {
+		Dispatch.token = await window.deputy.storage.getKV( 'api-token' );
+		// TODO: If token, set token
+		// TODO: If no token, start OAuth flow and make login API request
+		throw new Error( 'Unimplemented method.' );
+	}
+
+	/**
+	 * Returns a fully-formed HTTP URL from a given endpoint. This uses the wiki's
+	 * set Dispatch endpoint and a given target (such as `/v1/revisions`) to get
+	 * the full URL.
+	 *
+	 * @param endpoint The endpoint to get
+	 */
+	async getEndpoint( endpoint: string ): Promise<URL> {
+		return new URL(
+			endpoint.replace( /^\/+/, '' ),
+			( await window.deputy.getWikiConfig() ).core.dispatchRoot.get()
+				.href
+				.replace( /\/+$/, '' )
+		);
+	}
+
+}

src/api/Dispatch.ts

@@ -0,0 +1,146 @@
+import { deputyVersion } from '../DeputyVersion';
+
+interface DeputyDispatchTaskOptions {
+	/**
+	 * The rate in milliseconds at which new progress requests are made.
+	 *
+	 *  @default 500
+	 */
+	refreshRate?: number;
+}
+
+/**
+ *
+ */
+export class DeputyDispatchTask<T> extends EventTarget implements DeputyDispatchTaskOptions {
+
+	id: string;
+	progress = 0;
+	finished = false;
+	baseEndpoint: URL;
+	promise: Promise<T>;
+
+	refreshRate: number;
+
+	/**
+	 * @return The endpoint for retrieving this task's progress
+	 */
+	get progressEndpoint(): URL {
+		const u = new URL( this.id + '/progress', this.baseEndpoint );
+		u.search = '';
+		return u;
+	}
+
+	/**
+	 * @return The endpoint for retrieving this task's result
+	 */
+	get resultEndpoint(): URL {
+		const u = new URL( this.id, this.baseEndpoint );
+		u.search = '';
+		return u;
+	}
+
+	/**
+	 *
+	 * @param endpoint
+	 * @param id
+	 * @param options
+	 */
+	constructor( endpoint: URL, id: string, options: DeputyDispatchTaskOptions ) {
+		super();
+		this.baseEndpoint = new URL( endpoint );
+		if ( !this.baseEndpoint.pathname.endsWith( '/' ) ) {
+			this.baseEndpoint.pathname += '/';
+		}
+		this.id = id;
+
+		this.refreshRate = options.refreshRate ?? 500;
+
+		// Execute last.
+		this.promise = this.waitUntilDone();
+	}
+
+	/**
+	 * Get the progress of this task.
+	 *
+	 * @return A tuple containing the progress and the `finished` boolean.
+	 */
+	async fetchProgress(): Promise<[number, boolean]> {
+		return fetch( this.progressEndpoint )
+			.then( r => r.json() )
+			.then( d => [ d.progress, d.finished ] );
+	}
+
+	/**
+	 * Get the result of this task.
+	 *
+	 * @return The result of the task.
+	 */
+	async fetchResult(): Promise<T> {
+		return fetch( this.resultEndpoint )
+			.then( r => r.json() );
+	}
+
+	/**
+	 * Wait until this task has finished running.
+	 */
+	async waitUntilDone(): Promise<T> {
+		while ( !this.finished ) {
+			const [ progress, finished ] = await this.fetchProgress();
+			if ( progress !== this.progress ) {
+				this.progress = progress;
+				this.dispatchEvent( new CustomEvent( 'progress', { detail: progress } ) );
+			}
+			if ( finished !== this.finished ) {
+				this.finished = finished;
+				this.dispatchEvent( new CustomEvent( 'finished' ) );
+			}
+			await new Promise( r => setTimeout( r, this.refreshRate ) );
+		}
+
+		return this.fetchResult();
+	}
+
+}
+
+/**
+ * Utility class for making Deputy Dispatch asynchronous requests.
+ *
+ * An asynchronous request is a special type of request made to the endpoint. It
+ * starts with a POST on the target endpoint with the relevant data, which returns
+ * a special ID. This ID can then be used to periodically poll the server for task
+ * status, and eventually be used to get the data back from the server.
+ */
+export default class DispatchAsync {
+
+	/**
+	 *
+	 * @param endpoint
+	 * @param options
+	 * @param taskOptions
+	 */
+	static async makeRequest<T>(
+		endpoint: URL,
+		options: Record<string, any>,
+		taskOptions: DeputyDispatchTaskOptions = {}
+	): Promise<DeputyDispatchTask<T>> {
+		const taskInfo = await fetch( endpoint, {
+			body: JSON.stringify( options ),
+			headers: {
+				'Content-Type': 'application/json',
+				'Api-User-Agent': `Deputy/${deputyVersion} (${window.location.hostname})`
+			},
+			redirect: 'follow'
+		} )
+			.then( r => {
+				if ( r.status !== 202 ) {
+					throw new Error( `DeputyDispatchAsync: Unexpected status code ${r.status}` );
+				}
+				return r;
+			} )
+			.then( r => r.json() );
+
+		return new DeputyDispatchTask( endpoint, taskInfo.id, taskOptions );
+	}
+
+}

src/api/DispatchAsync.ts

@@ -0,0 +1,55 @@
+import { ExpandedRevisionData } from './ExpandedRevisionData';
+import Requester from '../util/Requester';
+import Dispatch from './Dispatch';
+import { deputyVersion } from '../DeputyVersion';
+
+/**
+ *
+ */
+export default class DispatchRevisions {
+
+	/**
+	 * Singleton instance
+	 */
+	static readonly i = new DispatchRevisions();
+	/**
+	 *
+	 */
+	private constructor() { /* ignored */ }
+
+	/**
+	 * Gets expanded revision data from the API. This returns a response similar to the
+	 * `revisions` object provided by action=query, but also includes additional information
+	 * relevant (such as the parsed (HTML) comment, diff size, etc.)
+	 *
+	 * @param revisions The revisions to get the data for
+	 * @return An object of expanded revision data mapped by revision IDs
+	 */
+	async get(
+		revisions: number[]
+	): Promise<Record<number, ExpandedRevisionData>> {
+		return Requester.fetch(
+			await Dispatch.i.getEndpoint(
+				`v1/revisions/${mw.config.get( 'wgWikiID' )}`
+			),
+			{
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/x-www-form-urlencoded',
+					'Api-User-Agent': `Deputy/${deputyVersion} (${window.location.hostname})`
+				},
+				body: 'revisions=' + revisions.join( '|' )
+			}
+		)
+			.then( ( r ) => r.json() )
+			.then( ( j ) => {
+				if ( j.error ) {
+					throw new Error( j.error.info );
+				}
+
+				return j;
+			} )
+			.then( ( j ) => j.revisions );
+	}
+
+}