1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
;;; forgejo-api.el --- HTTP layer for Forgejo API -*- lexical-binding: t; -*-
;; Copyright (C) 2026 Thanos Apollo
;; Author: Thanos Apollo <public@thanosapollo.org>
;; Keywords: extensions
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Async HTTP layer for the Forgejo REST API (v1).
;;
;; All network requests go through `forgejo-api--request'. Public
;; wrappers (`forgejo-api-get', `forgejo-api-post', etc.) accept a
;; host URL, endpoint, optional parameters, and a callback that
;; receives the parsed JSON response.
;;; Code:
(require 'url)
(require 'json)
(require 'cl-lib)
(declare-function forgejo-token "forgejo.el" (host-url))
(defvar forgejo--api-default-limit)
;;; URL building
(defun forgejo-api--url (host endpoint &optional params)
"Build a full API URL for HOST and ENDPOINT with optional query PARAMS.
HOST is the base URL (e.g. \"https://codeberg.org\").
ENDPOINT should not have a leading slash.
PARAMS is an alist of (KEY . VALUE) pairs for the query string."
(let ((base (format "%s/api/v1/%s" host endpoint)))
(if params
(concat base "?"
(mapconcat (lambda (pair)
(format "%s=%s"
(url-hexify-string (car pair))
(url-hexify-string
(format "%s" (cdr pair)))))
params "&"))
base)))
;;; Response parsing
(defun forgejo-api--parse-headers (buffer)
"Parse pagination headers from HTTP response BUFFER.
Returns a plist with :total-count and :link."
(with-current-buffer buffer
(save-excursion
(goto-char (point-min))
(let (total-count link)
(while (re-search-forward "^\\([^:]+\\): \\(.+\\)\r?$" nil t)
(let ((name (downcase (match-string 1)))
(value (match-string 2)))
(cond
((string= name "x-total-count")
(setq total-count (string-to-number value)))
((string= name "link")
(setq link value)))))
(list :total-count total-count :link link)))))
(defun forgejo-api--parse-response (buffer)
"Parse the JSON body from HTTP response BUFFER.
Returns the parsed JSON as alists/lists, or nil for empty bodies."
(with-current-buffer buffer
(goto-char (point-min))
(re-search-forward "\r?\n\r?\n" nil t)
(unless (= (point) (point-max))
(json-parse-buffer :object-type 'alist :array-type 'list))))
(defun forgejo-api--response-status (buffer)
"Return the HTTP status code from response BUFFER."
(with-current-buffer buffer
(goto-char (point-min))
(when (re-search-forward "^HTTP/[0-9.]+ \\([0-9]+\\)" nil t)
(string-to-number (match-string 1)))))
;;; Core request
(defun forgejo-api--request (host method endpoint &optional params
json-body callback)
"Make an async HTTP request to the Forgejo API.
HOST is the instance base URL (e.g. \"https://codeberg.org\").
METHOD is the HTTP method string (\"GET\", \"POST\", etc.).
ENDPOINT is the API path (without /api/v1/ prefix).
PARAMS is an alist of query parameters.
JSON-BODY, when non-nil, is an alist to encode as the request body.
CALLBACK is called with two arguments: (RESPONSE-DATA HEADERS-PLIST).
RESPONSE-DATA is the parsed JSON.
HEADERS-PLIST contains :total-count and :link."
(let ((url-request-method method)
(url-request-extra-headers
`(("Authorization" . ,(encode-coding-string
(concat "token " (forgejo-token host))
'ascii))
("Accept" . "application/json")
,@(when json-body
'(("Content-Type" . "application/json")))))
(url-request-data
(when json-body
(encode-coding-string (json-encode json-body) 'utf-8)))
(url (forgejo-api--url host endpoint params)))
(url-retrieve
url
(lambda (status)
(unwind-protect
(let ((http-status (forgejo-api--response-status (current-buffer))))
(cond
((and http-status (>= http-status 400))
(let* ((err-data (condition-case nil
(forgejo-api--parse-response (current-buffer))
(json-parse-error nil)))
(err-msg (when (listp err-data)
(alist-get 'message err-data))))
(message "Forgejo API HTTP %d: %s %s%s"
http-status method endpoint
(if err-msg (concat " - " err-msg) ""))))
((plist-get status :error)
(message "Forgejo API error: %S" (plist-get status :error)))
(t
(when callback
(let ((headers (forgejo-api--parse-headers (current-buffer)))
(data (forgejo-api--parse-response (current-buffer))))
(funcall callback data headers))))))
(kill-buffer (current-buffer))))
nil t)))
;;; Public wrappers
(defun forgejo-api-get (host endpoint &optional params callback)
"GET ENDPOINT on HOST with query PARAMS, call CALLBACK with (data headers)."
(forgejo-api--request host "GET" endpoint params nil callback))
(defun forgejo-api-get-all (host endpoint &optional params callback)
"GET all pages from ENDPOINT on HOST, call CALLBACK with (all-data headers).
Fetches pages sequentially until all results are collected.
PARAMS should include a \"limit\" entry. The \"page\" param is
managed automatically."
(let ((limit (or (cdr (assoc "limit" params)) "30"))
(accum nil)
(page 1))
(cl-labels
((fetch-page ()
(let ((page-params (cons (cons "page" (number-to-string page))
params)))
(forgejo-api-get
host endpoint page-params
(lambda (data headers)
(setq accum (append accum data))
(let ((total (plist-get headers :total-count)))
(if (and total
(< (length accum) total)
(>= (length data) (string-to-number limit)))
(progn
(setq page (1+ page))
(fetch-page))
(when callback
(funcall callback accum headers)))))))))
(fetch-page))))
(defun forgejo-api-get-paged (host endpoint params page-callback
&optional done-callback)
"GET all pages from ENDPOINT on HOST, calling PAGE-CALLBACK after each.
PAGE-CALLBACK receives (PAGE-DATA HEADERS PAGE-NUMBER).
DONE-CALLBACK receives (ALL-DATA HEADERS) when all pages are fetched."
(let ((limit (or (cdr (assoc "limit" params)) "50"))
(accum nil)
(page 1))
(cl-labels
((fetch-page ()
(let ((page-params (cons (cons "page" (number-to-string page))
params)))
(forgejo-api-get
host endpoint page-params
(lambda (data headers)
(setq accum (append accum data))
(when page-callback
(funcall page-callback data headers page))
(let ((total (plist-get headers :total-count)))
(if (and total
(< (length accum) total)
(>= (length data) (string-to-number limit)))
(progn
(setq page (1+ page))
(fetch-page))
(when done-callback
(funcall done-callback accum headers)))))))))
(fetch-page))))
(defun forgejo-api-post (host endpoint &optional params json-body callback)
"POST to ENDPOINT on HOST with PARAMS and JSON-BODY, call CALLBACK."
(forgejo-api--request host "POST" endpoint params json-body callback))
(defun forgejo-api-patch (host endpoint &optional json-body callback)
"PATCH ENDPOINT on HOST with JSON-BODY, call CALLBACK."
(forgejo-api--request host "PATCH" endpoint nil json-body callback))
(defun forgejo-api-put (host endpoint &optional json-body callback)
"PUT ENDPOINT on HOST with JSON-BODY, call CALLBACK."
(forgejo-api--request host "PUT" endpoint nil json-body callback))
(defun forgejo-api-delete (host endpoint &optional json-body callback)
"DELETE ENDPOINT on HOST with optional JSON-BODY, call CALLBACK."
(forgejo-api--request host "DELETE" endpoint nil json-body callback))
;;; Instance settings
(defun forgejo-api-get-settings (host &optional callback)
"Fetch API settings from HOST.
Caches `default_paging_num' in `forgejo--api-default-limit'.
Calls CALLBACK with the settings alist when done."
(forgejo-api-get
host "settings/api" nil
(lambda (data _headers)
(setq forgejo--api-default-limit
(alist-get 'default_paging_num data))
(when callback
(funcall callback data)))))
(defun forgejo-api-default-limit ()
"Return the cached default page limit, or 50 as fallback."
(or forgejo--api-default-limit 50))
(provide 'forgejo-api)
;;; forgejo-api.el ends here
|
