docs: Responsible for spinning up and spinning down execution.
imports:
  commons: commons.yml
  problemV2: ./v2/problem.yml
types:
  SubmissionId:
    type: uuid
  ShareId:
    type: string
  SubmissionRequest:
    union:
      initializeProblemRequest: InitializeProblemRequest
      initializeWorkspaceRequest: {}
      submitV2: SubmitRequestV2
      workspaceSubmit: WorkspaceSubmitRequest
      stop: StopRequest
  InitializeProblemRequest:
    properties:
      problemId: commons.ProblemId
      problemVersion: optional<integer>
  SubmitRequestV2:
    properties:
      submissionId: SubmissionId
      language: commons.Language
      submissionFiles: list<SubmissionFileInfo>
      problemId: commons.ProblemId
      problemVersion: optional<integer>
      userId: optional<string>
  WorkspaceSubmitRequest:
    properties:
      submissionId: SubmissionId
      language: commons.Language
      submissionFiles: list<SubmissionFileInfo>
      userId: optional<string>
  SubmissionFileInfo:
    properties:
      directory: string
      filename: string
      contents: string
  SubmissionTypeEnum:
    enum:
      - TEST
    docs: Keep in sync with SubmissionType.
  StopRequest:
    properties:
      submissionId: SubmissionId
  SubmissionResponse:
    union:
      serverInitialized: {}
      problemInitialized: commons.ProblemId
      workspaceInitialized: {}
      serverErrored: ExceptionInfo
      codeExecutionUpdate: CodeExecutionUpdate
      terminated: TerminatedResponse
  CodeExecutionUpdate:
    union:
      buildingExecutor:
        type: BuildingExecutorResponse
        docs: Statuses if an executor for the session isn't ready (Before
          RunningResponse).
      running:
        type: RunningResponse
        docs: Sent once a test submission is executing.
      errored:
        type: ErroredResponse
        docs: Sent if a submission cannot be run (i.e. Compile Error).
      stopped:
        type: StoppedResponse
        docs: Sent if a submission is stopped.
      graded:
        type: GradedResponse
        docs: Graded testcases without trace information.
      gradedV2:
        type: GradedResponseV2
        docs: Graded submission for v2 problems.
      workspaceRan:
        type: WorkspaceRanResponse
        docs: Workspace run without trace information.
      recording:
        type: RecordingResponseNotification
        docs: Gives progress about what is being recorded.
      recorded:
        type: RecordedResponseNotification
        docs: Graded testcases with trace information.
      invalidRequest:
        type: InvalidRequestResponse
        docs: Sent if an invalid request is sent for a submission.
      finished:
        type: FinishedResponse
        docs: Sent once a submission is graded and fully recorded.
  BuildingExecutorResponse:
    properties:
      submissionId: SubmissionId
      status: ExecutionSessionStatus
  RunningResponse:
    properties:
      submissionId: SubmissionId
      state: RunningSubmissionState
  RunningSubmissionState:
    enum:
      - QUEUEING_SUBMISSION
      - KILLING_HISTORICAL_SUBMISSIONS
      - WRITING_SUBMISSION_TO_FILE
      - COMPILING_SUBMISSION
      - RUNNING_SUBMISSION
  ErroredResponse:
    properties:
      submissionId: SubmissionId
      errorInfo: ErrorInfo
  ErrorInfo:
    union:
      compileError: CompileError
      runtimeError:
        type: RuntimeError
        docs: |
          If the submission cannot be executed and throws a runtime error before getting to any of the testcases.
      internalError:
        type: InternalError
        docs: |
          If the trace backend encounters an unexpected error.
  CompileError:
    properties:
      message: string
  RuntimeError:
    properties:
      message: string
  InternalError:
    properties:
      exceptionInfo: ExceptionInfo
  StoppedResponse:
    properties:
      submissionId: SubmissionId
  WorkspaceRanResponse:
    properties:
      submissionId: SubmissionId
      runDetails: WorkspaceRunDetails
  WorkspaceRunDetails:
    properties:
      exceptionV2: optional<ExceptionV2>
      exception: optional<ExceptionInfo>
      stdout: string
  GradedResponse:
    properties:
      submissionId: SubmissionId
      testCases: map<string, TestCaseResultWithStdout>
  GradedResponseV2:
    properties:
      submissionId: SubmissionId
      testCases: map<problemV2.TestCaseId, TestCaseGrade>
  TestCaseGrade:
    union:
      hidden: TestCaseHiddenGrade
      nonHidden: TestCaseNonHiddenGrade
  TestCaseHiddenGrade:
    properties:
      passed: boolean
  TestCaseNonHiddenGrade:
    properties:
      passed: boolean
      actualResult: optional<commons.VariableValue>
      exception: optional<ExceptionV2>
      stdout: string
  RecordedResponseNotification:
    properties:
      submissionId: SubmissionId
      traceResponsesSize: integer
      testCaseId: optional<string>
  RecordingResponseNotification:
    properties:
      submissionId: SubmissionId
      testCaseId: optional<string>
      lineNumber: integer
      lightweightStackInfo: LightweightStackframeInformation
      tracedFile: optional<TracedFile>
  LightweightStackframeInformation:
    properties:
      numStackFrames: integer
      topStackFrameMethodName: string
  TestCaseResultWithStdout:
    properties:
      result: TestCaseResult
      stdout: string
  TestCaseResult:
    properties:
      expectedResult: commons.VariableValue
      actualResult: ActualResult
      passed: boolean
  ActualResult:
    union:
      value: commons.VariableValue
      exception: ExceptionInfo
      exceptionV2: ExceptionV2
  ExceptionV2:
    union:
      generic: ExceptionInfo
      timeout: {}
  ExceptionInfo:
    properties:
      exceptionType: string
      exceptionMessage: string
      exceptionStacktrace: string
  InvalidRequestResponse:
    properties:
      request: SubmissionRequest
      cause: InvalidRequestCause
  InvalidRequestCause:
    union:
      submissionIdNotFound:
        type: SubmissionIdNotFound
        docs: The submission request references a submission id that doesn't exist.
      customTestCasesUnsupported:
        type: CustomTestCasesUnsupported
      unexpectedLanguage:
        type: UnexpectedLanguageError
        docs: The submission request was routed to an incorrect language executor.
  ExistingSubmissionExecuting:
    properties:
      submissionId: SubmissionId
  SubmissionIdNotFound:
    properties:
      missingSubmissionId: SubmissionId
  CustomTestCasesUnsupported:
    properties:
      problemId: commons.ProblemId
      submissionId: SubmissionId
  UnexpectedLanguageError:
    properties:
      expectedLanguage: commons.Language
      actualLanguage: commons.Language
  TerminatedResponse:
    properties: {}
  FinishedResponse:
    properties:
      submissionId: SubmissionId

  StdoutResponse:
    properties:
      submissionId: SubmissionId
      stdout: string
  StderrResponse:
    properties:
      submissionId: SubmissionId
      stderr: string
  TraceResponse:
    properties:
      submissionId: SubmissionId
      lineNumber: integer
      returnValue: optional<commons.DebugVariableValue>
      expressionLocation: optional<ExpressionLocation>
      stack: StackInformation
      stdout: optional<string>

  TraceResponseV2:
    properties:
      submissionId: SubmissionId
      lineNumber: integer
      file: TracedFile
      returnValue: optional<commons.DebugVariableValue>
      expressionLocation: optional<ExpressionLocation>
      stack: StackInformation
      stdout: optional<string>
  TracedFile:
    properties:
      filename: string
      directory: string

  ExpressionLocation:
    properties:
      start: integer
      offset: integer
  StackInformation:
    properties:
      numStackFrames: integer
      topStackFrame: optional<StackFrame>
  StackFrame:
    properties:
      methodName: string
      lineNumber: integer
      scopes: list<Scope>
  Scope:
    properties:
      variables: map<string, commons.DebugVariableValue>
  ExecutionSessionResponse:
    properties:
      sessionId: string
      executionSessionUrl: optional<string>
      language: commons.Language
      status: ExecutionSessionStatus
  ExecutionSessionStatus:
    enum:
      - CREATING_CONTAINER #Requesting resources
      - PROVISIONING_CONTAINER #Downloading image
      - PENDING_CONTAINER #Setting up container
      - RUNNING_CONTAINER #Container running
      - LIVE_CONTAINER #Container can be pinged
      - FAILED_TO_LAUNCH #Container failed to launch

  SubmissionStatusV2:
    union:
      test: TestSubmissionStatusV2
      workspace: WorkspaceSubmissionStatusV2
  TestSubmissionStatusV2:
    properties:
      updates: list<TestSubmissionUpdate>
      problemId: commons.ProblemId
      problemVersion: integer
      problemInfo: problemV2.ProblemInfoV2
  WorkspaceSubmissionStatusV2:
    properties:
      updates: list<WorkspaceSubmissionUpdate>
  TestSubmissionUpdate:
    properties:
      updateTime: datetime
      updateInfo: TestSubmissionUpdateInfo
  TestSubmissionUpdateInfo:
    union:
      running: RunningSubmissionState
      stopped: {}
      errored: ErrorInfo
      gradedTestCase: GradedTestCaseUpdate
      recordedTestCase: RecordedTestCaseUpdate
      finished: {}
  WorkspaceSubmissionUpdate:
    properties:
      updateTime: datetime
      updateInfo: WorkspaceSubmissionUpdateInfo
  WorkspaceSubmissionUpdateInfo:
    union:
      running: RunningSubmissionState
      ran: WorkspaceRunDetails
      stopped: {}
      traced: {}
      tracedV2: WorkspaceTracedUpdate
      errored: ErrorInfo
      finished: {}
  GradedTestCaseUpdate:
    properties:
      testCaseId: problemV2.TestCaseId
      grade: TestCaseGrade
  RecordedTestCaseUpdate:
    properties:
      testCaseId: problemV2.TestCaseId
      traceResponsesSize: integer
  WorkspaceTracedUpdate:
    properties:
      traceResponsesSize: integer

  SubmissionTypeState:
    union:
      test: TestSubmissionState
      workspace: WorkspaceSubmissionState
  WorkspaceSubmissionState:
    properties:
      status: WorkspaceSubmissionStatus
  WorkspaceSubmissionStatus:
    union:
      stopped: {}
      errored: ErrorInfo
      running: RunningSubmissionState
      ran: WorkspaceRunDetails
      traced: WorkspaceRunDetails
  TestSubmissionState:
    properties:
      problemId: commons.ProblemId
      defaultTestCases: list<commons.TestCase>
      customTestCases: list<commons.TestCase>
      status: TestSubmissionStatus
  TestSubmissionStatus:
    union:
      stopped: {}
      errored: ErrorInfo
      running: RunningSubmissionState
      testCaseIdToState: map<string, SubmissionStatusForTestCase>
  SubmissionStatusForTestCase:
    union:
      graded: TestCaseResultWithStdout
      gradedV2: TestCaseGrade
      traced: TracedTestCase
  TracedTestCase:
    properties:
      result: TestCaseResultWithStdout
      traceResponsesSize: integer
  TraceResponsesPage:
    properties:
      offset:
        type: optional<integer>
        docs: |
          If present, use this to load subseqent pages.
          The offset is the id of the next trace response to load.
      traceResponses: list<TraceResponse>
  TraceResponsesPageV2:
    properties:
      offset:
        type: optional<integer>
        docs: |
          If present, use this to load subseqent pages.
          The offset is the id of the next trace response to load.
      traceResponses: list<TraceResponseV2>
  GetTraceResponsesPageRequest:
    properties:
      offset:
        type: optional<integer>
  WorkspaceStarterFilesResponse:
    properties:
      files: map<commons.Language, WorkspaceFiles>
  WorkspaceStarterFilesResponseV2:
    properties:
      filesByLanguage: map<commons.Language, problemV2.Files>
  WorkspaceFiles:
    properties:
      mainFile: commons.FileInfo
      readOnlyFiles: list<commons.FileInfo>

  ExecutionSessionState:
    properties:
      lastTimeContacted: optional<string>
      sessionId:
        type: string
        docs: >
          The auto-generated session id. Formatted as a uuid.
      isWarmInstance: boolean
      awsTaskId: optional<string>
      language: commons.Language
      status: ExecutionSessionStatus

  GetExecutionSessionStateResponse:
    properties:
      states: map<string, ExecutionSessionState>
      numWarmingInstances: optional<integer>
      warmingSessionIds: list<string>

  GetSubmissionStateResponse:
    properties:
      timeSubmitted: optional<datetime>
      submission: string
      language: commons.Language
      submissionTypeState: SubmissionTypeState

service:
  base-path: /sessions
  auth: false
  endpoints:
    createExecutionSession:
      docs: Returns sessionId and execution server URL for session. Spins up server.
      method: POST
      path: /create-session/{language}
      path-parameters:
        language: commons.Language
      response: ExecutionSessionResponse

    getExecutionSession:
      docs: Returns execution server URL for session. Returns empty if session isn't
        registered.
      method: GET
      path: /{sessionId}
      path-parameters:
        sessionId: string
      response: optional<ExecutionSessionResponse>

    stopExecutionSession:
      docs: Stops execution session. #TODO: only an admin should be able to trigger this
      method: DELETE
      path: /stop/{sessionId}
      path-parameters:
        sessionId: string

    getExecutionSessionsState:
      method: GET
      path: /execution-sessions-state
      response: GetExecutionSessionStateResponse