OXYGENHUB
# e833eb0a9e7f oxygenhub-android / app / src / main / java / io / oxygenhub / android / api / HubClient.kt
15.5 KiB · last changed Project boards on the phone: every board you can see, columns to swipe, cards that open and move 10 days ago source blame history raw
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
     * The proposals the caller should act on, across repositories (the hub's
46
     * dashboard); with [landable], also those it can land now (#20, oxygenhub#311).
47
     */
48
    suspend fun userProposals(landable: Boolean = false): UserProposals
49
50
    /** A repository's proposals: open (with drafts), landed, closed or all. */
51
    suspend fun proposals(owner: String, name: String, state: ProposalState = ProposalState.Open): List<Proposal>
52
53
    suspend fun proposal(owner: String, name: String, number: Long): Proposal
54
55
    /** The checks on a proposal's projected state. */
56
    suspend fun checks(owner: String, name: String, number: Long): List<Check>
57
58
    /**
59
     * Land it (`repo:write`); the proposal as landed. The hub refuses with 409
60
     * and its reason when it may not land, and 403 when the token lacks the scope.
61
     */
62
    suspend fun land(owner: String, name: String, number: Long): Proposal
63
64
    /** Land it by itself when its checks pass, or not (`repo:write`); the proposal after. */
65
    suspend fun setAutoLand(owner: String, name: String, number: Long, on: Boolean): Proposal
66
67
    /** A one-time token registering this phone as a runner for the account's repositories (`repo:write`). */
68
    suspend fun runnerToken(): RunnerToken
69
70
    suspend fun issue(owner: String, name: String, number: Long): Issue
71
72
    /** [owner]'s project boards the caller can see. */
73
    suspend fun projects(owner: String): List<Project>
74
75
    suspend fun board(owner: String, number: Long): Board
76
77
    /** Move a card to the column named [column]. */
78
    suspend fun moveCard(owner: String, number: Long, card: Long, column: String)
79
80
    suspend fun issueComments(owner: String, name: String, number: Long): List<Comment>
81
82
    suspend fun comment(owner: String, name: String, number: Long, body: String): Comment
83
84
    /** Close (with why: `completed` or `not_planned`) or reopen. */
85
    suspend fun setIssueState(owner: String, name: String, number: Long, open: Boolean, reason: String = "completed"): Issue
86
87
    suspend fun createIssue(owner: String, name: String, title: String, body: String): Issue
88
89
    /** The repository's labels, to choose from. */
90
    suspend fun labels(owner: String, name: String): List<Label>
91
92
    /** The issue's whole set of labels (triage). */
93
    suspend fun setIssueLabels(owner: String, name: String, number: Long, labels: List<String>): Issue
94
95
    /** One repository (`GET /repos/{owner}/{name}`): its default bookmark, for the code browser. */
96
    suspend fun repository(owner: String, name: String): Repository
97
98
    /** A directory of the tree at [ref] (a bookmark, tag or change), [path] "" for the top. */
99
    suspend fun tree(owner: String, name: String, ref: String, path: String = ""): List<TreeEntry>
100
101
    /** A file's bytes at [ref], as text. */
102
    suspend fun file(owner: String, name: String, ref: String, path: String): String
103
104
    /** [ref]'s history, newest first; only changes to [path] when given. */
105
    suspend fun history(owner: String, name: String, ref: String, path: String? = null, offset: Int = 0, limit: Int = 50): History
106
107
    suspend fun change(owner: String, name: String, hash: String): ChangeDetail
108
109
    /** The repository's bookmarks and tags, to browse at. */
110
    suspend fun refs(owner: String, name: String): Pair<List<String>, List<String>>
111
112
    /** An account's picture (`/avatar/{name}`, public); null when the hub has none this app can draw. */
113
    suspend fun avatar(name: String): Avatar?
114
}
115
116
/**
117
 * The hub's JSON API over OkHttp. [onUnauthorized] runs when the hub
118
 * refuses the token (revoked on the web, or 90 days unused), so the app
119
 * can drop the session and ask for a new sign-in.
120
 */
121
class HubClient(
122
    hub: String,
123
    private val token: String,
124
    private val http: OkHttpClient,
125
    private val onUnauthorized: () -> Unit = {},
126
) : HubApi {
127
    private val base: HttpUrl = "${hub.trimEnd('/')}/api/v1/".toHttpUrl()
128
    private val root: HttpUrl = "${hub.trimEnd('/')}/".toHttpUrl()
129
130
    override suspend fun user(): User = get("user", User.serializer())
131
132
    override suspend fun repositories(): List<Repository> = get("repos", ListSerializer(Repository.serializer()))
133
134
    override suspend fun issues(owner: String, name: String, state: IssueState): List<Issue> =
135
        get(url("repos", owner, name, "issues") { addQueryParameter("state", state.query) }, ListSerializer(Issue.serializer()))
136
137
    override suspend fun inbox(limit: Int): Inbox =
138
        get(url("notifications") { addQueryParameter("limit", limit.coerceIn(1, 200).toString()) }, Inbox.serializer())
139
140
    override suspend fun runnerToken(): RunnerToken = send("POST", url("user", "runner-token"), RunnerToken.serializer())
141
142
    override suspend fun projects(owner: String): List<Project> = get(url("projects", owner), ListSerializer(Project.serializer()))
143
144
    override suspend fun board(owner: String, number: Long): Board = get(url("projects", owner, number.toString()), Board.serializer())
145
146
    override suspend fun moveCard(owner: String, number: Long, card: Long, column: String) {
147
        val json = buildJsonObject { put("column", column) }
148
        call(request(url("projects", owner, number.toString(), "cards", card.toString())).method("PATCH", json.toString().toRequestBody(JsonMedia)).build(), true)
149
    }
150
151
    override suspend fun issue(owner: String, name: String, number: Long): Issue =
152
        get(url("repos", owner, name, "issues", number.toString()), Issue.serializer())
153
154
    override suspend fun issueComments(owner: String, name: String, number: Long): List<Comment> =
155
        get(url("repos", owner, name, "issues", number.toString(), "comments"), ListSerializer(Comment.serializer()))
156
157
    override suspend fun comment(owner: String, name: String, number: Long, body: String): Comment =
158
        sendJson("POST", url("repos", owner, name, "issues", number.toString(), "comments"), buildJsonObject { put("body", body) }, Comment.serializer())
159
160
    override suspend fun setIssueState(owner: String, name: String, number: Long, open: Boolean, reason: String): Issue =
161
        sendJson(
162
            "POST",
163
            url("repos", owner, name, "issues", number.toString()),
164
            buildJsonObject {
165
                put("state", if (open) "open" else "closed")
166
                if (!open) put("reason", reason)
167
            },
168
            Issue.serializer(),
169
        )
170
171
    override suspend fun createIssue(owner: String, name: String, title: String, body: String): Issue =
172
        sendJson("POST", url("repos", owner, name, "issues"), buildJsonObject {
173
            put("title", title)
174
            put("body", body)
175
        }, Issue.serializer())
176
177
    override suspend fun labels(owner: String, name: String): List<Label> =
178
        get(url("repos", owner, name, "labels"), ListSerializer(Label.serializer()))
179
180
    override suspend fun setIssueLabels(owner: String, name: String, number: Long, labels: List<String>): Issue =
181
        sendJson("PATCH", url("repos", owner, name, "issues", number.toString()), buildJsonObject {
182
            put("labels", JsonArray(labels.map { JsonPrimitive(it) }))
183
        }, Issue.serializer())
184
185
    override suspend fun repository(owner: String, name: String): Repository = get(url("repos", owner, name), Repository.serializer())
186
187
    private fun parts(path: String): Array<String> = path.split('/').filter { it.isNotEmpty() }.toTypedArray()
188
189
    override suspend fun tree(owner: String, name: String, ref: String, path: String): List<TreeEntry> =
190
        get(url("repos", owner, name, "tree", ref, *parts(path)), ListSerializer(TreeEntry.serializer()))
191
192
    override suspend fun file(owner: String, name: String, ref: String, path: String): String =
193
        call(request(url("repos", owner, name, "file", ref, *parts(path))).get().build(), notifyUnauthorized = true)
194
195
    override suspend fun history(owner: String, name: String, ref: String, path: String?, offset: Int, limit: Int): History =
196
        get(
197
            url("repos", owner, name, "history", ref) {
198
                path?.let { addQueryParameter("path", it) }
199
                addQueryParameter("offset", offset.toString())
200
                addQueryParameter("limit", limit.toString())
201
            },
202
            History.serializer(),
203
        )
204
205
    override suspend fun change(owner: String, name: String, hash: String): ChangeDetail =
206
        get(url("repos", owner, name, "changes", hash), ChangeDetail.serializer())
207
208
    override suspend fun refs(owner: String, name: String): Pair<List<String>, List<String>> {
209
        val bookmarks = get(url("repos", owner, name, "bookmarks"), ListSerializer(NamedRef.serializer())).map { it.name }
210
        val tags = get(url("repos", owner, name, "tags"), ListSerializer(NamedRef.serializer())).map { it.name }
211
        return bookmarks to tags
212
    }
213
214
    override suspend fun userProposals(landable: Boolean): UserProposals =
215
        get(url("user", "proposals") { if (landable) addQueryParameter("landable", "true") }, UserProposals.serializer())
216
217
    override suspend fun proposals(owner: String, name: String, state: ProposalState): List<Proposal> =
218
        get(url("repos", owner, name, "proposals") { addQueryParameter("state", state.query) }, ListSerializer(Proposal.serializer()))
219
220
    override suspend fun proposal(owner: String, name: String, number: Long): Proposal =
221
        get(url("repos", owner, name, "proposals", number.toString()), Proposal.serializer())
222
223
    override suspend fun checks(owner: String, name: String, number: Long): List<Check> =
224
        get(url("repos", owner, name, "proposals", number.toString(), "checks"), ListSerializer(Check.serializer()))
225
226
    override suspend fun land(owner: String, name: String, number: Long): Proposal =
227
        send("POST", url("repos", owner, name, "proposals", number.toString(), "land"), Proposal.serializer())
228
229
    override suspend fun setAutoLand(owner: String, name: String, number: Long, on: Boolean): Proposal =
230
        send(if (on) "POST" else "DELETE", url("repos", owner, name, "proposals", number.toString(), "auto-land"), Proposal.serializer())
231
232
    override suspend fun markRead(id: Long) {
233
        send("POST", url("notifications", id.toString(), "read"))
234
    }
235
236
    override suspend fun markAllRead() {
237
        send("POST", url("notifications", "read"))
238
    }
239
240
    override suspend fun revokeToken() {
241
        send("DELETE", url("user", "token"), notifyUnauthorized = false)
242
    }
243
244
    override suspend fun avatar(name: String): Avatar? {
245
        val url = root.newBuilder().addPathSegment("avatar").addPathSegment(name).build()
246
        // A public picture: no token goes with it.
247
        val response = try {
248
            http.newCall(Request.Builder().url(url).get().build()).await()
249
        } catch (e: IOException) {
250
            throw HubException.Network(e)
251
        }
252
        response.use { r ->
253
            if (r.code == 404) return null
254
            val bytes = try {
255
                r.body?.bytes() ?: ByteArray(0)
256
            } catch (e: IOException) {
257
                throw HubException.Network(e)
258
            }
259
            if (!r.isSuccessful) throw HubException.Http(r.code, errorDetail(bytes.decodeToString()))
260
            return Avatar.parse(r.header("Content-Type"), bytes)
261
        }
262
    }
263
264
    // The bearer token is never part of a string anything prints.
265
    override fun toString(): String = "HubClient(${base})"
266
267
    private fun url(vararg segments: String, query: HttpUrl.Builder.() -> Unit = {}): HttpUrl {
268
        val b = base.newBuilder()
269
        // Each segment is encoded on its own: an owner or name never adds a path level.
270
        segments.forEach { b.addPathSegment(it) }
271
        b.query()
272
        return b.build()
273
    }
274
275
    private suspend fun <T> get(path: String, serializer: KSerializer<T>): T = get(url(*path.split('/').toTypedArray()), serializer)
276
277
    private suspend fun <T> get(url: HttpUrl, serializer: KSerializer<T>): T {
278
        val body = call(request(url).get().build(), notifyUnauthorized = true)
279
        return try {
280
            HubJson.decodeFromString(serializer, body)
281
        } catch (e: IllegalArgumentException) {
282
            // kotlinx.serialization's errors are IllegalArgumentExceptions.
283
            throw HubException.Unreadable("GET ${url.encodedPath}", e)
284
        }
285
    }
286
287
    private suspend fun send(method: String, url: HttpUrl, notifyUnauthorized: Boolean = true): String {
288
        val body = if (method == "DELETE") null else "{}".toRequestBody(JsonMedia)
289
        return call(request(url).method(method, body).build(), notifyUnauthorized)
290
    }
291
292
    private suspend fun <T> send(method: String, url: HttpUrl, serializer: KSerializer<T>): T {
293
        val body = send(method, url)
294
        return try {
295
            HubJson.decodeFromString(serializer, body)
296
        } catch (e: IllegalArgumentException) {
297
            throw HubException.Unreadable("$method ${url.encodedPath}", e)
298
        }
299
    }
300
301
    /** [json] as the body; the answer read with [serializer]. */
302
    private suspend fun <T> sendJson(method: String, url: HttpUrl, json: JsonObject, serializer: KSerializer<T>): T {
303
        val body = call(request(url).method(method, json.toString().toRequestBody(JsonMedia)).build(), notifyUnauthorized = true)
304
        return try {
305
            HubJson.decodeFromString(serializer, body)
306
        } catch (e: IllegalArgumentException) {
307
            throw HubException.Unreadable("$method ${url.encodedPath}", e)
308
        }
309
    }
310
311
    private fun request(url: HttpUrl): Request.Builder = Request.Builder()
312
        .url(url)
313
        .header("Accept", "application/json")
314
        .header("Authorization", "Bearer $token")
315
316
    private suspend fun call(request: Request, notifyUnauthorized: Boolean): String {
317
        val response = try {
318
            http.newCall(request).await()
319
        } catch (e: IOException) {
320
            throw HubException.Network(e)
321
        }
322
        response.use { r ->
323
            val text = try {
324
                r.body?.string().orEmpty()
325
            } catch (e: IOException) {
326
                throw HubException.Network(e)
327
            }
328
            if (!r.isSuccessful) {
329
                if (r.code == 401 && notifyUnauthorized) onUnauthorized()
330
                throw HubException.Http(r.code, errorDetail(text))
331
            }
332
            return text
333
        }
334
    }
335
}