doc: added documentation to all functions

dev
Jef Roosens 2022-05-07 22:06:17 +02:00
parent 5b016df85d
commit 5f7d7c4780
Signed by untrusted user: Jef Roosens
GPG Key ID: B75D4F293C7052DB
7 changed files with 32 additions and 9 deletions

View File

@ -11,6 +11,7 @@ pub:
api_key string api_key string
} }
// new creates a new Client instance.
pub fn new(address string, api_key string) Client { pub fn new(address string, api_key string) Client {
return Client{ return Client{
address: address address: address
@ -18,6 +19,8 @@ pub fn new(address string, api_key string) Client {
} }
} }
// send_request_raw sends an HTTP request, returning the http.Response object.
// It encodes the params so that they're safe to pass as HTTP query parameters.
fn (c &Client) send_request_raw(method Method, url string, params map[string]string, body string) ?http.Response { fn (c &Client) send_request_raw(method Method, url string, params map[string]string, body string) ?http.Response {
mut full_url := '$c.address$url' mut full_url := '$c.address$url'
@ -47,9 +50,8 @@ fn (c &Client) send_request<T>(method Method, url string, params map[string]stri
return c.send_request_with_body<T>(method, url, params, '') return c.send_request_with_body<T>(method, url, params, '')
} }
// send_request_with_body<T> is a convenience method for sending requests to // send_request_with_body<T> calls send_request_raw_response & parses its
// the repos API. It mostly does string manipulation to create a query string // output as a Response<T> object.
// containing the provided params.
fn (c &Client) send_request_with_body<T>(method Method, url string, params map[string]string, body string) ?Response<T> { fn (c &Client) send_request_with_body<T>(method Method, url string, params map[string]string, body string) ?Response<T> {
res_text := c.send_request_raw_response(method, url, params, body) ? res_text := c.send_request_raw_response(method, url, params, body) ?
data := json.decode(Response<T>, res_text) ? data := json.decode(Response<T>, res_text) ?
@ -57,6 +59,7 @@ fn (c &Client) send_request_with_body<T>(method Method, url string, params map[s
return data return data
} }
// send_request_raw_response returns the raw text response for an HTTP request.
fn (c &Client) send_request_raw_response(method Method, url string, params map[string]string, body string) ?string { fn (c &Client) send_request_raw_response(method Method, url string, params map[string]string, body string) ?string {
res := c.send_request_raw(method, url, params, body) ? res := c.send_request_raw(method, url, params, body) ?

View File

@ -4,21 +4,21 @@ import db { GitRepo }
import net.http { Method } import net.http { Method }
import response { Response } import response { Response }
// get_repos returns the current list of repos. // get_git_repos returns the current list of repos.
pub fn (c &Client) get_git_repos() ?[]GitRepo { pub fn (c &Client) get_git_repos() ?[]GitRepo {
data := c.send_request<[]GitRepo>(Method.get, '/api/repos', {}) ? data := c.send_request<[]GitRepo>(Method.get, '/api/repos', {}) ?
return data.data return data.data
} }
// get_repo returns the repo for a specific ID. // get_git_repo returns the repo for a specific ID.
pub fn (c &Client) get_git_repo(id int) ?GitRepo { pub fn (c &Client) get_git_repo(id int) ?GitRepo {
data := c.send_request<GitRepo>(Method.get, '/api/repos/$id', {}) ? data := c.send_request<GitRepo>(Method.get, '/api/repos/$id', {}) ?
return data.data return data.data
} }
// add_repo adds a new repo to the server. // add_git_repo adds a new repo to the server.
pub fn (c &Client) add_git_repo(url string, branch string, repo string, arch []string) ?Response<string> { pub fn (c &Client) add_git_repo(url string, branch string, repo string, arch []string) ?Response<string> {
mut params := { mut params := {
'url': url 'url': url
@ -35,14 +35,14 @@ pub fn (c &Client) add_git_repo(url string, branch string, repo string, arch []s
return data return data
} }
// remove_repo removes the repo with the given ID from the server. // remove_git_repo removes the repo with the given ID from the server.
pub fn (c &Client) remove_git_repo(id int) ?Response<string> { pub fn (c &Client) remove_git_repo(id int) ?Response<string> {
data := c.send_request<string>(Method.delete, '/api/repos/$id', {}) ? data := c.send_request<string>(Method.delete, '/api/repos/$id', {}) ?
return data return data
} }
// patch_repo sends a PATCH request to the given repo with the params as // patch_git_repo sends a PATCH request to the given repo with the params as
// payload. // payload.
pub fn (c &Client) patch_git_repo(id int, params map[string]string) ?Response<string> { pub fn (c &Client) patch_git_repo(id int, params map[string]string) ?Response<string> {
data := c.send_request<string>(Method.patch, '/api/repos/$id', params) ? data := c.send_request<string>(Method.patch, '/api/repos/$id', params) ?

View File

@ -5,12 +5,14 @@ import net.http { Method }
import response { Response } import response { Response }
import time import time
// get_build_logs returns all build logs.
pub fn (c &Client) get_build_logs() ?Response<[]BuildLog> { pub fn (c &Client) get_build_logs() ?Response<[]BuildLog> {
data := c.send_request<[]BuildLog>(Method.get, '/api/logs', {}) ? data := c.send_request<[]BuildLog>(Method.get, '/api/logs', {}) ?
return data return data
} }
// get_build_logs_for_repo returns all build logs for a given repo.
pub fn (c &Client) get_build_logs_for_repo(repo_id int) ?Response<[]BuildLog> { pub fn (c &Client) get_build_logs_for_repo(repo_id int) ?Response<[]BuildLog> {
params := { params := {
'repo': repo_id.str() 'repo': repo_id.str()
@ -21,18 +23,21 @@ pub fn (c &Client) get_build_logs_for_repo(repo_id int) ?Response<[]BuildLog> {
return data return data
} }
// get_build_log returns a specific build log.
pub fn (c &Client) get_build_log(id int) ?Response<BuildLog> { pub fn (c &Client) get_build_log(id int) ?Response<BuildLog> {
data := c.send_request<BuildLog>(Method.get, '/api/logs/$id', {}) ? data := c.send_request<BuildLog>(Method.get, '/api/logs/$id', {}) ?
return data return data
} }
// get_build_log_content returns the contents of the build log file.
pub fn (c &Client) get_build_log_content(id int) ?string { pub fn (c &Client) get_build_log_content(id int) ?string {
data := c.send_request_raw_response(Method.get, '/api/logs/$id/content', {}, '') ? data := c.send_request_raw_response(Method.get, '/api/logs/$id/content', {}, '') ?
return data return data
} }
// add_build_log adds a new build log to the server.
pub fn (c &Client) add_build_log(repo_id int, start_time time.Time, end_time time.Time, arch string, exit_code int, content string) ?Response<string> { pub fn (c &Client) add_build_log(repo_id int, start_time time.Time, end_time time.Time, arch string, exit_code int, content string) ?Response<string> {
params := { params := {
'repo': repo_id.str() 'repo': repo_id.str()

View File

@ -10,6 +10,7 @@ struct Config {
api_key string [required] api_key string [required]
} }
// cmd returns the cli module that handles the build repos API.
pub fn cmd() cli.Command { pub fn cmd() cli.Command {
return cli.Command{ return cli.Command{
name: 'logs' name: 'logs'
@ -64,12 +65,14 @@ pub fn cmd() cli.Command {
} }
} }
// print_log_list prints a list of logs.
fn print_log_list(logs []db.BuildLog) { fn print_log_list(logs []db.BuildLog) {
for log in logs { for log in logs {
println('$log.id\t$log.start_time\t$log.exit_code') println('$log.id\t$log.start_time\t$log.exit_code')
} }
} }
// list prints a list of all build logs.
fn list(conf Config) ? { fn list(conf Config) ? {
c := client.new(conf.address, conf.api_key) c := client.new(conf.address, conf.api_key)
logs := c.get_build_logs() ?.data logs := c.get_build_logs() ?.data
@ -77,6 +80,7 @@ fn list(conf Config) ? {
print_log_list(logs) print_log_list(logs)
} }
// list prints a list of all build logs for a given repo.
fn list_for_repo(conf Config, repo_id int) ? { fn list_for_repo(conf Config, repo_id int) ? {
c := client.new(conf.address, conf.api_key) c := client.new(conf.address, conf.api_key)
logs := c.get_build_logs_for_repo(repo_id) ?.data logs := c.get_build_logs_for_repo(repo_id) ?.data
@ -84,6 +88,7 @@ fn list_for_repo(conf Config, repo_id int) ? {
print_log_list(logs) print_log_list(logs)
} }
// info print the detailed info for a given build log.
fn info(conf Config, id int) ? { fn info(conf Config, id int) ? {
c := client.new(conf.address, conf.api_key) c := client.new(conf.address, conf.api_key)
log := c.get_build_log(id) ?.data log := c.get_build_log(id) ?.data
@ -91,6 +96,8 @@ fn info(conf Config, id int) ? {
print(log) print(log)
} }
// content outputs the contents of the log file for a given build log to
// stdout.
fn content(conf Config, id int) ? { fn content(conf Config, id int) ? {
c := client.new(conf.address, conf.api_key) c := client.new(conf.address, conf.api_key)
content := c.get_build_log_content(id) ? content := c.get_build_log_content(id) ?

View File

@ -153,6 +153,8 @@ pub fn (db &VieterDb) update_git_repo_archs(repo_id int, archs []GitRepoArch) {
} }
} }
// git_repo_exists is a utility function that checks whether a repo with the
// given id exists.
pub fn (db &VieterDb) git_repo_exists(repo_id int) bool { pub fn (db &VieterDb) git_repo_exists(repo_id int) bool {
db.get_git_repo(repo_id) or { return false } db.get_git_repo(repo_id) or { return false }

View File

@ -12,6 +12,7 @@ pub:
exit_code int [nonull] exit_code int [nonull]
} }
// str returns a string representation.
pub fn (bl &BuildLog) str() string { pub fn (bl &BuildLog) str() string {
mut parts := [ mut parts := [
'id: $bl.id', 'id: $bl.id',

View File

@ -9,6 +9,8 @@ import time
import os import os
import util import util
// get_logs returns all build logs in the database. A 'repo' query param can
// optionally be added to limit the list of build logs to that repository.
['/api/logs'; get] ['/api/logs'; get]
fn (mut app App) get_logs() web.Result { fn (mut app App) get_logs() web.Result {
if !app.is_authorized() { if !app.is_authorized() {
@ -24,6 +26,7 @@ fn (mut app App) get_logs() web.Result {
return app.json(http.Status.ok, new_data_response(logs)) return app.json(http.Status.ok, new_data_response(logs))
} }
// get_single_log returns the build log with the given id.
['/api/logs/:id'; get] ['/api/logs/:id'; get]
fn (mut app App) get_single_log(id int) web.Result { fn (mut app App) get_single_log(id int) web.Result {
if !app.is_authorized() { if !app.is_authorized() {
@ -35,8 +38,9 @@ fn (mut app App) get_single_log(id int) web.Result {
return app.json(http.Status.ok, new_data_response(log)) return app.json(http.Status.ok, new_data_response(log))
} }
// get_log_content returns the actual build log file for the given id.
['/api/logs/:id/content'; get] ['/api/logs/:id/content'; get]
fn (mut app App) get_log_contents(id int) web.Result { fn (mut app App) get_log_content(id int) web.Result {
if !app.is_authorized() { if !app.is_authorized() {
return app.json(http.Status.unauthorized, new_response('Unauthorized.')) return app.json(http.Status.unauthorized, new_response('Unauthorized.'))
} }
@ -58,6 +62,7 @@ fn parse_query_time(query string) ?time.Time {
return t return t
} }
// post_log adds a new log to the database.
['/api/logs'; post] ['/api/logs'; post]
fn (mut app App) post_log() web.Result { fn (mut app App) post_log() web.Result {
if !app.is_authorized() { if !app.is_authorized() {