Describe the backend API in one contract and generate code from it

オープン
#9,485 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
リファクタリング
明瞭さ
おおむね明確
活発さ
活発
技術スタック
angular, openapi, scala, typescript

調査の方向性

Read #9395 for the shared resource operations, then inspect config-service and its 9 endpoints as the proposed pilot. Compare its existing service declarations and callers with the contract and generated interfaces/client described in the issue. Done means config-service is served through generated interfaces, called through the generated client, and CI fails when generated files are stale.

索引モデルが issue の本文から書いたものです。

説明

Task Summary

No file describes the backend's API. Each of its more than 230 endpoints is declared by hand in a Scala resource class, and again wherever it is called: in the Angular frontend, where 42 files call the backend through HttpClient with paths and types written by hand, and in the agent service's clients under agent-service/src/api/. #5918 showed how these copies drift apart without any build failing. The unification in #9395 makes this pressing, because it gives every kind the same operations, and because the agent service and an MCP server (#9457, #8663) need those operations described well enough for a model to call them.

This task adds an api/ folder with one contract for the backend API, and generates the code on both sides of it. The contract states the three primitives of #9395 once, as templates, so a kind states only what is specific to it. For example, these lines would be all of environments, and show how datasets add an operation of their own:

model EnvironmentSpec {
  packages: Record<string>;
}
model Environment is Resource<EnvironmentSpec>;

@route("/environments")
interface Environments extends ResourceOperations<Environment>, AccessOperations {}

@route("/datasets")
interface Datasets extends ResourceOperations<Dataset>, VersionOperations<Dataset>, AccessOperations {
  @put @route("/{rid}/files/{path}")
  @extension("x-permission", "write")
  uploadFile(@path rid: Rid, @path path: string, @body file: bytes): void | Error;
}

Environments would keep the operations they have, under the same paths as every other kind, and gain the two they lack today: reading one environment, and sharing. uploadFile shows how a kind adds an operation of its own and states the access level it needs, as mengw15 asked in #9395.

Before
flowchart LR
  subgraph hand["The same endpoint, declared three times by hand"]
    f["Angular service<br/>path, request and response types"]
    a["Agent service client<br/>path, request and response types"]
    s["Scala resource class<br/>path, parameters, types"]
  end
  f -- "HTTP" --> s
  a -- "HTTP" --> s
After
flowchart LR
  c["api/<br/>the contract"]
  o["OpenAPI document"]
  si["Server interfaces"]
  impl["Service code<br/>implements them"]
  tc["TypeScript client"]
  fe["Frontend"]
  ag["Agent service"]
  pm["Permission map"]
  chk["The access check"]
  td["Tool definitions"]
  mcp["Served by the agent<br/>and the MCP server, #9457"]
  c --> o
  o --> si --> impl
  o --> tc
  tc --> fe
  tc --> ag
  o --> pm --> chk
  o --> td --> mcp
Scope
  1. The contract and its conventions. Templates for resource, version and sharing operations; one error shape; one way to page a list; and on every operation an id, a summary and described parameters, which also become the names and descriptions of tools.
  2. The generators. The OpenAPI document, server interfaces for the Dropwizard 4 services, one TypeScript client for the frontend and the agent service, the permission map that the access check reads, and tool definitions for the operations the contract marks as tools.
  3. A drift check. CI fails when a generated file is stale, or when an implementation no longer matches the contract.
  4. A pilot. One existing service moves to the contract end to end before any resource endpoint does. config-service, with 9 endpoints, is small enough.

This task does not add the resource endpoints, which come with the reads (#9489) and writes (#9490) of each kind, and it does not serve tools over MCP, which is #9457.

Discussion Points
  1. The contract language. TypeSpec (MIT) compiles to OpenAPI and has templates, which is what lets a kind be a few lines; my Texera 2.0 prototype, built outside main, described 15 kinds this way in 25 files. The alternatives are OpenAPI written by hand, which has no templates, or OpenAPI generated from the JAX-RS annotations, which keeps Scala as the source but makes the TypeScript side wait for the Scala build.
  2. Generated code, committed or built. Committed code shows up in review and builds without the generators. Code generated in the build cannot go stale.
  3. The Dashboard Service. It runs on Dropwizard 1.3 until #5423 lands, so it cannot implement interfaces generated for Dropwizard 4 yet.

Done when the pilot is served from generated interfaces and called through the generated client, and CI fails on a stale generated file.

Task Type
  • Refactor / Cleanup
  • DevOps / Deployment / CI
  • Testing / QA
  • Documentation
  • Performance
  • Other
主要言語
Scala
スター
333
フォーク
202
平均マージ
3日 11時間
マージ済み PR(30日)
185

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

apache/texera のほかの issue

apache/texera の issue をすべて見る

似ている issue

Scala の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。