Describe the backend API in one contract and generate code from it
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 35/100
- Tipo di issue
- Refactoring
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Attiva
- Stack tecnologico
- angular, openapi, scala, typescript
- Ambito
- backend-api-design, build-system, ci-cd, devtools
Direzione di ricerca
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.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
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
- Lingua principale
- Scala
- Stelle
- 333
- Fork
- 202
- Merge medio
- 3g 11h
- PR unite (30g)
- 185
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di apache/texera
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
I maintainer di solito rispondono entro 1 giorno
-
addOperator returns an error but still adds the operatorForse già presa @sunny-kavixo l’ha presa 5 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
apache/texera#9121 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
Failed tool calls are marked as succeeded (isError is always false)Forse già presa @oliarmak-web l’ha presa 14 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 80/100
apache/texera#9120 · 8 commenti · 1 assegnatario ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
apache/texera#8682 · 5 commenti ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di apache/texera
Issue simili
-
? - Needs Triage bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 75/100
NVIDIA/cudf-spark#16937 ·
I maintainer di solito rispondono entro 1 giorno
-
LFST not-issued-store count truncation can incorrectly clear strictShouldWaitForse già presa @weidingliu l’ha presa oggi. Apertamodule: memory type: bug/reported
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
OpenXiangShan/XiangShan#6974 · 1 commento · 1 assegnatario ·
I maintainer di solito rispondono entro 3 giorni
-
bug indigo
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
PurpleKingdomGames/indigoengine#300 · 1 commento ·
-
JavaReservoirSampleOperator returns the whole input when the dataset size is unknownForse già presa @sasmith-14 l’ha presa 2 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
apache/wayang#884 · 3 commenti ·
I maintainer di solito rispondono entro 2 giorni
-
AI Generated CI/CD ⚒️ Flaky-tests 🐦 python 🐍
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
valkey-io/valkey-glide#7722 ·
I maintainer di solito rispondono entro 1 giorno