OXYGENHUB

Coverage / app/src/main/java/io/oxygenhub/android/api/HubClient.kt 39.9%

67 of 168 lines run, 32 of 78 functions, 16 of 34 branches · run #1632 on main · run missed

1
package io.oxygenhub.android.api
2
3
import java.io.IOException
4
import kotlinx.serialization.KSerializer
5
import kotlinx.serialization.builtins.ListSerializer
6
import kotlinx.serialization.json.JsonArray
7
import kotlinx.serialization.json.JsonObject
8
import kotlinx.serialization.json.JsonPrimitive
9
import kotlinx.serialization.json.buildJsonObject
10
import kotlinx.serialization.json.put
11
import okhttp3.HttpUrl
12
import okhttp3.HttpUrl.Companion.toHttpUrl
13
import okhttp3.OkHttpClient
14
import okhttp3.Request
15
import okhttp3.RequestBody.Companion.toRequestBody
16
17
/**
18
 * What the app asks of a hub, signed in. The view models see only this, so
19
 * their tests give them a fake. Later screens (oxygenhub-android#3–#5) add
20
 * to it: a repository's tree, history, proposals, runs.
21
 */
22
interface HubApi {
23
    /** The signed-in account (`GET /user`, scope `user:read`). */
24
    suspend fun user(): User
25
26
    /** Every repository the caller can read (`GET /repos`). */
27
    suspend fun repositories(): List<Repository>
28
29
    /** A repository's issues (`GET /repos/{owner}/{name}/issues?state=`). */
30
    suspend fun issues(owner: String, name: String, state: IssueState = IssueState.Open): List<Issue>
31
32
    /** The inbox: the unread count and the newest entries (`GET /notifications`). */
33
    suspend fun inbox(limit: Int = 50): Inbox
34
35
    /** Marks one notification read (`POST /notifications/{id}/read`). */
36
    suspend fun markRead(id: Long)
37
38
    /** Marks the whole inbox read (`POST /notifications/read`). */
39
    suspend fun markAllRead()
40
41
    /** Revokes the token this client signs in with (`DELETE /user/token`). */
42
    suspend fun revokeToken()
43
44
    /**
45
     * This phone takes alerts (#16): its Cloud Messaging [fcmToken] and its
46
     * alert key's [publicKey] (hex), for the token it signed in with
47
     * (`PUT /user/push`). Whether the hub sends alerts at all.
48
     */
49
    suspend fun registerPush(fcmToken: String, publicKey: String): Boolean
50
51
    /**
52
     * The proposals the caller should act on, across repositories (the hub's
53
     * dashboard); with [landable], also those it can land now (#20, oxygenhub#311).
54
     */
55
    suspend fun userProposals(landable: Boolean = false): UserProposals
56
57
    /** Your sky's data, the dashboard backdrop's (#23); a hub before it answers 404. */
58
    suspend fun userSky(): UserSky
59
60
    /** A repository's proposals: open (with drafts), landed, closed or all. */
61
    suspend fun proposals(owner: String, name: String, state: ProposalState = ProposalState.Open): List<Proposal>
62
63
    suspend fun proposal(owner: String, name: String, number: Long): Proposal
64
65
    /** The checks on a proposal's projected state. */
66
    suspend fun checks(owner: String, name: String, number: Long): List<Check>
67
68
    /**
69
     * Land it (`repo:write`); the proposal as landed. The hub refuses with 409
70
     * and its reason when it may not land, and 403 when the token lacks the scope.
71
     */
72
    suspend fun land(owner: String, name: String, number: Long): Proposal
73
74
    /** Land it by itself when its checks pass, or not (`repo:write`); the proposal after. */
75
    suspend fun setAutoLand(owner: String, name: String, number: Long, on: Boolean): Proposal
76
77
    /** A one-time token registering this phone as a runner for the account's repositories (`repo:write`). */
78
    suspend fun runnerToken(): RunnerToken
79
80
    suspend fun issue(owner: String, name: String, number: Long): Issue
81
82
    /** A repository's releases, newest first. */
83
    suspend fun releases(owner: String, name: String): List<Release>
84
85
    /** Issues and proposals matching [query], across the repositories the caller can read. */
86
    suspend fun search(query: String): List<SearchHit>
87
88
    /** A repository's runs, newest first. */
89
    suspend fun runs(owner: String, name: String): List<FlowRun>
90
91
    /** One run, with its jobs. */
92
    suspend fun run(owner: String, name: String, number: Long): FlowRun
93
94
    /** A job's log lines after [after] (0: from the start). */
95
    suspend fun jobLog(owner: String, name: String, number: Long, job: String, after: Long): List<LogLine>
96
97
    suspend fun rerunRun(owner: String, name: String, number: Long)
98
99
    /** Run [job] again in the same run, with the jobs that depend on it. */
100
    suspend fun rerunJob(owner: String, name: String, number: Long, job: String)
101
102
    suspend fun cancelRun(owner: String, name: String, number: Long)
103
104
    /** Approve, or reject, a job that waits for a person (#5, oxygenflow#57); its approval rules decide who may. */
105
    suspend fun decideJob(owner: String, name: String, number: Long, job: String, approve: Boolean)
106
107
    /** Make a run urgent, saying why (#5, oxygenhub#244): a maintainer's, within the owner's cap. */
108
    suspend fun expediteRun(owner: String, name: String, number: Long, reason: String)
109
110
    /** [owner]'s project boards the caller can see. */
111
    suspend fun projects(owner: String): List<Project>
112
113
    suspend fun board(owner: String, number: Long): Board
114
115
    /** Move a card to the column named [column]. */
116
    suspend fun moveCard(owner: String, number: Long, card: Long, column: String)
117
118
    suspend fun issueComments(owner: String, name: String, number: Long): List<Comment>
119
120
    suspend fun comment(owner: String, name: String, number: Long, body: String): Comment
121
122
    /** Close (with why: `completed` or `not_planned`) or reopen. */
123
    suspend fun setIssueState(owner: String, name: String, number: Long, open: Boolean, reason: String = "completed"): Issue
124
125
    suspend fun createIssue(owner: String, name: String, title: String, body: String): Issue
126
127
    /** The repository's labels, to choose from. */
128
    suspend fun labels(owner: String, name: String): List<Label>
129
130
    /** The issue's whole set of labels (triage). */
131
    suspend fun setIssueLabels(owner: String, name: String, number: Long, labels: List<String>): Issue
132
133
    /** The issue's whole set of assignees (triage, #4). */
134
    suspend fun setIssueAssignees(owner: String, name: String, number: Long, assignees: List<String>): Issue
135
136
    /** One repository (`GET /repos/{owner}/{name}`): its default bookmark, for the code browser. */
137
    suspend fun repository(owner: String, name: String): Repository
138
139
    /** A directory of the tree at [ref] (a bookmark, tag or change), [path] "" for the top. */
140
    suspend fun tree(owner: String, name: String, ref: String, path: String = ""): List<TreeEntry>
141
142
    /** A file's bytes at [ref], as text. */
143
    suspend fun file(owner: String, name: String, ref: String, path: String): String
144
145
    /** [ref]'s history, newest first; only changes to [path] when given. */
146
    suspend fun history(owner: String, name: String, ref: String, path: String? = null, offset: Int = 0, limit: Int = 50): History
147
148
    suspend fun change(owner: String, name: String, hash: String): ChangeDetail
149
150
    /** Review a proposal (#4): [verdict] is `approve`, `changes` or `comment`, with [body] said. */
151
    suspend fun review(owner: String, name: String, number: Long, verdict: String, body: String)
152
153
    /** The files a proposal changes, each with its diff, as the proposal page shows them (#4). */
154
    suspend fun proposalDiff(owner: String, name: String, number: Long): List<FileChange>
155
156
    /** The repository's bookmarks and tags, to browse at. */
157
    suspend fun refs(owner: String, name: String): Pair<List<String>, List<String>>
158
159
    /** An account's picture (`/avatar/{name}`, public); null when the hub has none this app can draw. */
160
    suspend fun avatar(name: String): Avatar?
161
162
    /** An account's public profile, and an organisation's (with its members). */
163
    suspend fun account(name: String): User
164
165
    suspend fun organisation(name: String): Organisation
166
}
167
168
/**
169
 * The hub's JSON API over OkHttp. [onUnauthorized] runs when the hub
170
 * refuses the token (revoked on the web, or 90 days unused), so the app
171
 * can drop the session and ask for a new sign-in.
172
 */
173
class HubClient(
174
    hub: String,
175
    private val token: String,
176
    private val http: OkHttpClient,
177
    private val onUnauthorized: () -> Unit = {},
178
) : HubApi {
179
    private val base: HttpUrl = "${hub.trimEnd('/')}/api/v1/".toHttpUrl()
180
    private val root: HttpUrl = "${hub.trimEnd('/')}/".toHttpUrl()
181
182
    override suspend fun user(): User = get("user", User.serializer())
183
184
    override suspend fun repositories(): List<Repository> = get("repos", ListSerializer(Repository.serializer()))
185
186
    override suspend fun issues(owner: String, name: String, state: IssueState): List<Issue> =
187
        get(url("repos", owner, name, "issues") { addQueryParameter("state", state.query) }, ListSerializer(Issue.serializer()))
188
189
    override suspend fun inbox(limit: Int): Inbox =
190
        get(url("notifications") { addQueryParameter("limit", limit.coerceIn(1, 200).toString()) }, Inbox.serializer())
191
192
    override suspend fun runnerToken(): RunnerToken = send("POST", url("user", "runner-token"), RunnerToken.serializer())
193
194
    override suspend fun releases(owner: String, name: String): List<Release> =
195
        get(url("repos", owner, name, "releases"), ListSerializer(Release.serializer()))
196
197
    override suspend fun search(query: String): List<SearchHit> =
198
        get(url("search") { addQueryParameter("q", query) }, ListSerializer(SearchHit.serializer()))
199
200
    override suspend fun runs(owner: String, name: String): List<FlowRun> =
201
        get(url("repos", owner, name, "flow", "runs"), ListSerializer(FlowRun.serializer()))
202
203
    override suspend fun run(owner: String, name: String, number: Long): FlowRun =
204
        get(url("repos", owner, name, "flow", "runs", number.toString()), FlowRun.serializer())
205
206
    override suspend fun jobLog(owner: String, name: String, number: Long, job: String, after: Long): List<LogLine> =
207
        get(
208
            url("repos", owner, name, "flow", "runs", number.toString(), "jobs", job, "log") { addQueryParameter("after", after.toString()) },
209
            ListSerializer(LogLine.serializer()),
210
        )
211
212
    override suspend fun rerunRun(owner: String, name: String, number: Long) {
213
        send("POST", url("repos", owner, name, "flow", "runs", number.toString(), "rerun"))
214
    }
215
216
    override suspend fun rerunJob(owner: String, name: String, number: Long, job: String) {
217
        send("POST", url("repos", owner, name, "flow", "runs", number.toString(), "jobs", job, "rerun"))
218
    }
219
220
    override suspend fun cancelRun(owner: String, name: String, number: Long) {
221
        send("POST", url("repos", owner, name, "flow", "runs", number.toString(), "cancel"))
222
    }
223
224
    override suspend fun decideJob(owner: String, name: String, number: Long, job: String, approve: Boolean) {
225
        send("POST", url("repos", owner, name, "flow", "runs", number.toString(), "jobs", job, if (approve) "approve" else "reject"))
226
    }
227
228
    override suspend fun expediteRun(owner: String, name: String, number: Long, reason: String) {
229
        sendJson("POST", url("repos", owner, name, "flow", "runs", number.toString(), "expedite"), buildJsonObject {
230
            put("reason", reason)
231
        }, Expedited.serializer())
232
    }
233
234
    override suspend fun projects(owner: String): List<Project> = get(url("projects", owner), ListSerializer(Project.serializer()))
235
236
    override suspend fun board(owner: String, number: Long): Board = get(url("projects", owner, number.toString()), Board.serializer())
237
238
    override suspend fun moveCard(owner: String, number: Long, card: Long, column: String) {
239
        val json = buildJsonObject { put("column", column) }
240
        call(request(url("projects", owner, number.toString(), "cards", card.toString())).method("PATCH", json.toString().toRequestBody(JsonMedia)).build(), true)
241
    }
242
243
    override suspend fun issue(owner: String, name: String, number: Long): Issue =
244
        get(url("repos", owner, name, "issues", number.toString()), Issue.serializer())
245
246
    override suspend fun issueComments(owner: String, name: String, number: Long): List<Comment> =
247
        get(url("repos", owner, name, "issues", number.toString(), "comments"), ListSerializer(Comment.serializer()))
248
249
    override suspend fun comment(owner: String, name: String, number: Long, body: String): Comment =
250
        sendJson("POST", url("repos", owner, name, "issues", number.toString(), "comments"), buildJsonObject { put("body", body) }, Comment.serializer())
251
252
    override suspend fun setIssueState(owner: String, name: String, number: Long, open: Boolean, reason: String): Issue =
253
        sendJson(
254
            "POST",
255
            url("repos", owner, name, "issues", number.toString()),
256
            buildJsonObject {
257
                put("state", if (open) "open" else "closed")
258
                if (!open) put("reason", reason)
259
            },
260
            Issue.serializer(),
261
        )
262
263
    override suspend fun createIssue(owner: String, name: String, title: String, body: String): Issue =
264
        sendJson("POST", url("repos", owner, name, "issues"), buildJsonObject {
265
            put("title", title)
266
            put("body", body)
267
        }, Issue.serializer())
268
269
    override suspend fun labels(owner: String, name: String): List<Label> =
270
        get(url("repos", owner, name, "labels"), ListSerializer(Label.serializer()))
271
272
    override suspend fun setIssueAssignees(owner: String, name: String, number: Long, assignees: List<String>): Issue =
273
        sendJson("PATCH", url("repos", owner, name, "issues", number.toString()), buildJsonObject {
274
            put("assignees", JsonArray(assignees.map { JsonPrimitive(it) }))
275
        }, Issue.serializer())
276
277
    override suspend fun setIssueLabels(owner: String, name: String, number: Long, labels: List<String>): Issue =
278
        sendJson("PATCH", url("repos", owner, name, "issues", number.toString()), buildJsonObject {
279
            put("labels", JsonArray(labels.map { JsonPrimitive(it) }))
280
        }, Issue.serializer())
281
282
    override suspend fun account(name: String): User = get(url("users", name), User.serializer())
283
284
    override suspend fun organisation(name: String): Organisation = get(url("orgs", name), Organisation.serializer())
285
286
    override suspend fun repository(owner: String, name: String): Repository = get(url("repos", owner, name), Repository.serializer())
287
288
    private fun parts(path: String): Array<String> = path.split('/').filter { it.isNotEmpty() }.toTypedArray()
289
290
    override suspend fun tree(owner: String, name: String, ref: String, path: String): List<TreeEntry> =
291
        get(url("repos", owner, name, "tree", ref, *parts(path)), ListSerializer(TreeEntry.serializer()))
292
293
    override suspend fun file(owner: String, name: String, ref: String, path: String): String =
294
        call(request(url("repos", owner, name, "file", ref, *parts(path))).get().build(), notifyUnauthorized = true)
295
296
    override suspend fun history(owner: String, name: String, ref: String, path: String?, offset: Int, limit: Int): History =
297
        get(
298
            url("repos", owner, name, "history", ref) {
299
                path?.let { addQueryParameter("path", it) }
300
                addQueryParameter("offset", offset.toString())
301
                addQueryParameter("limit", limit.toString())
302
            },
303
            History.serializer(),
304
        )
305
306
    override suspend fun review(owner: String, name: String, number: Long, verdict: String, body: String) {
307
        sendJson("POST", url("repos", owner, name, "proposals", number.toString(), "reviews"), buildJsonObject {
308
            put("verdict", verdict)
309
            put("body", body)
310
        }, ReviewPosted.serializer())
311
    }
312
313
    override suspend fun proposalDiff(owner: String, name: String, number: Long): List<FileChange> =
314
        get(url("repos", owner, name, "proposals", number.toString(), "diff"), ListSerializer(FileChange.serializer()))
315
316
    override suspend fun change(owner: String, name: String, hash: String): ChangeDetail =
317
        get(url("repos", owner, name, "changes", hash), ChangeDetail.serializer())
318
319
    override suspend fun refs(owner: String, name: String): Pair<List<String>, List<String>> {
320
        val bookmarks = get(url("repos", owner, name, "bookmarks"), ListSerializer(NamedRef.serializer())).map { it.name }
321
        val tags = get(url("repos", owner, name, "tags"), ListSerializer(NamedRef.serializer())).map { it.name }
322
        return bookmarks to tags
323
    }
324
325
    override suspend fun userSky(): UserSky = get(url("user", "sky"), UserSky.serializer())
326
327
    override suspend fun userProposals(landable: Boolean): UserProposals =
328
        get(url("user", "proposals") { if (landable) addQueryParameter("landable", "true") }, UserProposals.serializer())
329
330
    override suspend fun proposals(owner: String, name: String, state: ProposalState): List<Proposal> =
331
        get(url("repos", owner, name, "proposals") { addQueryParameter("state", state.query) }, ListSerializer(Proposal.serializer()))
332
333
    override suspend fun proposal(owner: String, name: String, number: Long): Proposal =
334
        get(url("repos", owner, name, "proposals", number.toString()), Proposal.serializer())
335
336
    override suspend fun checks(owner: String, name: String, number: Long): List<Check> =
337
        get(url("repos", owner, name, "proposals", number.toString(), "checks"), ListSerializer(Check.serializer()))
338
339
    override suspend fun land(owner: String, name: String, number: Long): Proposal =
340
        send("POST", url("repos", owner, name, "proposals", number.toString(), "land"), Proposal.serializer())
341
342
    override suspend fun setAutoLand(owner: String, name: String, number: Long, on: Boolean): Proposal =
343
        send(if (on) "POST" else "DELETE", url("repos", owner, name, "proposals", number.toString(), "auto-land"), Proposal.serializer())
344
345
    override suspend fun markRead(id: Long) {
346
        send("POST", url("notifications", id.toString(), "read"))
347
    }
348
349
    override suspend fun markAllRead() {
350
        send("POST", url("notifications", "read"))
351
    }
352
353
    override suspend fun revokeToken() {
354
        send("DELETE", url("user", "token"), notifyUnauthorized = false)
355
    }
356
357
    override suspend fun registerPush(fcmToken: String, publicKey: String): Boolean =
358
        sendJson("PUT", url("user", "push"), buildJsonObject {
359
            put("fcm_token", fcmToken)
360
            put("public_key", publicKey)
361
        }, PushRegistered.serializer()).alerts
362
363
    override suspend fun avatar(name: String): Avatar? {
364
        val url = root.newBuilder().addPathSegment("avatar").addPathSegment(name).build()
365
        // A public picture: no token goes with it.
366
        val response = try {
367
            http.newCall(Request.Builder().url(url).get().build()).await()
368
        } catch (e: IOException) {
369
            throw HubException.Network(e)
370
        }
371
        response.use { r ->
372
            if (r.code == 404) return null
373
            val bytes = try {
374
                r.body?.bytes() ?: ByteArray(0)
375
            } catch (e: IOException) {
376
                throw HubException.Network(e)
377
            }
378
            if (!r.isSuccessful) throw HubException.Http(r.code, errorDetail(bytes.decodeToString()))
379
            return Avatar.parse(r.header("Content-Type"), bytes)
380
        }
381
    }
382
383
    // The bearer token is never part of a string anything prints.
384
    override fun toString(): String = "HubClient(${base})"
385
386
    private fun url(vararg segments: String, query: HttpUrl.Builder.() -> Unit = {}): HttpUrl {
387
        val b = base.newBuilder()
388
        // Each segment is encoded on its own: an owner or name never adds a path level.
389
        segments.forEach { b.addPathSegment(it) }
390
        b.query()
391
        return b.build()
392
    }
393
394
    private suspend fun <T> get(path: String, serializer: KSerializer<T>): T = get(url(*path.split('/').toTypedArray()), serializer)
395
396
    private suspend fun <T> get(url: HttpUrl, serializer: KSerializer<T>): T {
397
        val body = call(request(url).get().build(), notifyUnauthorized = true)
398
        return try {
399
            HubJson.decodeFromString(serializer, body)
400
        } catch (e: IllegalArgumentException) {
401
            // kotlinx.serialization's errors are IllegalArgumentExceptions.
402
            throw HubException.Unreadable("GET ${url.encodedPath}", e)
403
        }
404
    }
405
406
    private suspend fun send(method: String, url: HttpUrl, notifyUnauthorized: Boolean = true): String {
407
        val body = if (method == "DELETE") null else "{}".toRequestBody(JsonMedia)
408
        return call(request(url).method(method, body).build(), notifyUnauthorized)
409
    }
410
411
    private suspend fun <T> send(method: String, url: HttpUrl, serializer: KSerializer<T>): T {
412
        val body = send(method, url)
413
        return try {
414
            HubJson.decodeFromString(serializer, body)
415
        } catch (e: IllegalArgumentException) {
416
            throw HubException.Unreadable("$method ${url.encodedPath}", e)
417
        }
418
    }
419
420
    /** [json] as the body; the answer read with [serializer]. */
421
    private suspend fun <T> sendJson(method: String, url: HttpUrl, json: JsonObject, serializer: KSerializer<T>): T {
422
        val body = call(request(url).method(method, json.toString().toRequestBody(JsonMedia)).build(), notifyUnauthorized = true)
423
        return try {
424
            HubJson.decodeFromString(serializer, body)
425
        } catch (e: IllegalArgumentException) {
426
            throw HubException.Unreadable("$method ${url.encodedPath}", e)
427
        }
428
    }
429
430
    private fun request(url: HttpUrl): Request.Builder = Request.Builder()
431
        .url(url)
432
        .header("Accept", "application/json")
433
        .header("Authorization", "Bearer $token")
434
435
    private suspend fun call(request: Request, notifyUnauthorized: Boolean): String {
436
        val response = try {
437
            http.newCall(request).await()
438
        } catch (e: IOException) {
439
            throw HubException.Network(e)
440
        }
441
        response.use { r ->
442
            val text = try {
443
                r.body?.string().orEmpty()
444
            } catch (e: IOException) {
445
                throw HubException.Network(e)
446
            }
447
            if (!r.isSuccessful) {
448
                if (r.code == 401 && notifyUnauthorized) onUnauthorized()
449
                throw HubException.Http(r.code, errorDetail(text))
450
            }
451
            return text
452
        }
453
    }
454
}