Describe the backend API in one contract and generate code from it
メンテナーはふだん 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
- 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.
- 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.
- A drift check. CI fails when a generated file is stale, or when an implementation no longer matches the contract.
- 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
- 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.
- Generated code, committed or built. Committed code shows up in review and builds without the generators. Code generated in the build cannot go stale.
- 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
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
apache/texera のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
addOperator returns an error but still adds the operator対応中かも @sunny-kavixo が 5 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
apache/texera#9121 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
Failed tool calls are marked as succeeded (isError is always false)対応中かも @oliarmak-web が 14 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
apache/texera#9120 · コメント 8 件 · 担当者 1 名 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
apache/texera#8682 · コメント 5 件 ·
メンテナーはふだん 1 日以内に返信
似ている issue
-
? - Needs Triage bug
難易度 2/5 1〜3時間 初心者へのやさしさ 75/100
NVIDIA/cudf-spark#16937 ·
メンテナーはふだん 1 日以内に返信
-
LFST not-issued-store count truncation can incorrectly clear strictShouldWait対応中かも @weidingliu が今日担当しました。 オープンmodule: memory type: bug/reported
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
OpenXiangShan/XiangShan#6974 · コメント 1 件 · 担当者 1 名 ·
メンテナーはふだん 3 日以内に返信
-
bug indigo
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
PurpleKingdomGames/indigoengine#300 · コメント 1 件 ·
-
JavaReservoirSampleOperator returns the whole input when the dataset size is unknown対応中かも @sasmith-14 が 2 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
apache/wayang#884 · コメント 3 件 ·
メンテナーはふだん 2 日以内に返信
-
AI Generated CI/CD ⚒️ Flaky-tests 🐦 python 🐍
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
valkey-io/valkey-glide#7722 ·
メンテナーはふだん 1 日以内に返信