Types for Rabbit MQ Gradeworker Socket Server

rmq_socket_server_types.ts

export namespace GradeWorker {
  /**
   * Base class for RMQ requests to gradeworker.
   */
  export interface Request {
    how_to_handle_result: HowToHandleResult;
    attachment?: any; // Way to included as arbitrary data in rabbitMQ responses
  }

  /**
   * Part of every request to gradeworker, which asks the gradeworker to do something
   * specific with the result of the request.
   */
  interface HowToHandleResult {
    strategy: HandleResultStrategy;
  }

  /**
   * Tagged union discriminant for HowToHandleResult.
   */
  export enum HandleResultStrategy {
    sendToQueue = "send_to_queue",
    doNothing = "do_nothing",
  }

  /**
   * Variant of HowToHandleResult. Asks the grade worker not to do anything with the result
   * of the request.
   */
  interface HandleResultDoNothing extends HowToHandleResult {
    strategy: HandleResultStrategy.doNothing;
  }

  export const isDoNotHandleResultHandler = (
    handler: HowToHandleResult,
  ): handler is HandleResultSendToQueue => handler.strategy === HandleResultStrategy.doNothing;

  /**
   * Variant of HowToHandleResult. Asks the grade worker to send the result of the request back into RMQ,
   * into a queue of the requestor's choice.
   */
  interface HandleResultSendToQueue extends HowToHandleResult {
    strategy: HandleResultStrategy.sendToQueue;
    queue: string;
  }

  export const isSendToQueueResultHandler = (
    handler: HowToHandleResult,
  ): handler is HandleResultSendToQueue => handler.strategy === HandleResultStrategy.sendToQueue;

  /**
   * Base class for responses to RMQ requests, which may be received by use of HandleResultSendToQueue.
   */
  export interface Result {
    success: boolean;
    attachment?: any;
  }

  /**
   * Base class for responses to RMQ requests which denote that the request errored, in some way that suggests
   * an invalid request, and will not be re-attempted by the gradeworker.
   */
  export interface ResultError extends Result {
    success: false;
    error_msg: string;
    attachment?: any;
  }

  /**
   * Base class for responses to RMQ requests which denote that the request was processed successfully.
   */
  export interface ResultSuccess extends Result {
    success: true;
    attachment?: any;
  }

  /**
   * An executable code snippet, which can be sent over to the grade worker.
   */
  export interface CodeSnippet {
    language: Language;
    code: string;
  }

  /**
   * The set of programming languages supported by the grade worker.
   */
  export enum Language {
    python = "python",
  }

  export type Duration = number; // in milliseconds
  export const DEFAULT_DURATION = 5000; // 5 seconds

  /**
   * A captured line of output text from running code.
   * It may come from the stdout or stderr. (Possibly extensible).
   */
  interface OutputLine {
    stream: StreamType;
    line: string;
  }

  /**
   * See OutputLine.
   */
  export enum StreamType {
    stdout = "stdout",
    stderr = "stderr",
  }

  /**
   * A request to run a code snippet, possibly several times, potentially in
   * several different ways, then record and return the output of each execution.
   */
  export interface RequestTestSnippet<
    TC extends CodeTestCase = CodeTestCaseInputOutput | CodeTestCaseFunctionCall
  > extends Request {
    how_to_handle_result: HandleResultSendToQueue;
    snippet: CodeSnippet;
    exec_cases: TC[];
  }

  /**
   * Successful result variant for the response to RequestExecSnippet.
   */
  export interface ResultSuccessTestSnippet extends ResultSuccess {
    exec_cases: CodeTestCaseOutput[];
  }

  /***
   * Result type for ResultExecSnippet.
   */
  export type ResultTestSnippet = ResultSuccessTestSnippet | ResultError;

  /**
   * A way to run a code snippet, and determine whether it passed some 'test', on a binary
   * pass/fail system.
   */
  interface CodeTestCase {
    variant: CodeTestCaseVariant;
    timeout?: Duration;
    attachment?: any;
  }

  /**
   * Tagged union discriminant for CodeTestCase.
   */
  export enum CodeTestCaseVariant {
    inputOutput = "input_output",
    functionCall = "function_call",
  }

  /**
   * CodeTestCase variant. Run the snippet, feed it some lines of input, and check if it
   * produced some exact correct lines of output.
   */
  interface CodeTestCaseInputOutput extends CodeTestCase {
    variant: CodeTestCaseVariant.inputOutput;
    input_lines: string[];
    output_lines: string[];
  }

  /**
   * CodeTestCase variant. Run a specific named function within the snippet, feed it a
   * sequence of json-deserialized arguments, and compare the output to a json-deserialized
   * correct output.
   */
  interface CodeTestCaseFunctionCall extends CodeTestCase {
    variant: CodeTestCaseVariant.functionCall;
    function_name: string;
    function_input: any[];
    function_output: any;
  }

  /**
   * The recorded output of running a code snippet with a CodeExecCase.
   *
   * May be extended for specific code test case variants.
   */
  interface CodeTestCaseOutput {
    snippet_runtime: Duration;
    snippet_exit_code: number;
    snippet_output: OutputLine[];
    snippet_timed_out: boolean;
    test_passed: boolean;
    attachment?: any;
  }

  /**
   * Extension of CodeTestCaseOutput for the output of a CaseTestCaseFunctionCall.
   */
  interface CodeTestCastOutputFunctionCall extends CodeTestCaseOutput {
    function_output: any;
  }

  /**
   * A request to grade a code snippet.
   */
  export interface RequestGradeSnippet extends Request {
    snippet: CodeSnippet;
    grade_cases: CodeGradeCase[];
  }

  /**
   * The success result of a gradeworker request to grade a snippet.
   */
  export interface ResultSuccessGradeSnippet extends ResultSuccess {
    graded_cases: GradedCodeCase[];
    combined_grade: number;
  }

  /**
   * The RequestGradeSnippet result type.
   */
  export type ResultGradeSnippet = ResultSuccessGradeSnippet | ResultError;

  /**
   * Adds relative points, for grading, to a CodeTestCase.
   */
  interface CodeGradeCase {
    test_case: CodeTestCase;
    grade_relative_points: number;
  }

  /**
   * The result of running and grading a CodeTestCase.
   */
  interface GradedCodeCase {
    snippet_runtime: Duration;
    snippet_exit_code: number;
    snippet_output: OutputLine[];
    snippet_timed_out: boolean;
    grade_passed: boolean;
    grade_relative_points: number;
    attachment?: any;
  }
}