docs: added comment string to each function

main
Jef Roosens 2022-04-30 20:22:03 +02:00
parent fb65efdfbe
commit f9f440500e
Signed by untrusted user: Jef Roosens
GPG Key ID: B75D4F293C7052DB
12 changed files with 49 additions and 1 deletions

View File

@ -10,6 +10,11 @@ const container_build_dir = '/build'
const build_image_repo = 'vieter-build'
// create_build_image creates a builder image given some base image which can
// then be used to build & package Arch images. It mostly just updates the
// system, install some necessary packages & creates a non-root user to run
// makepkg with. The base image should be some Linux distribution that uses
// Pacman as its package manager.
pub fn create_build_image(base_image string) ?string {
commands := [
// Update repos & install required packages
@ -67,6 +72,9 @@ pub fn create_build_image(base_image string) ?string {
return image.id
}
// build_repo builds, packages & publishes a given Arch package based on the
// provided GitRepo. The base image ID should be of an image previously created
// by create_build_image.
pub fn build_repo(address string, api_key string, base_image_id string, repo &git.GitRepo) ? {
build_arch := os.uname().machine
@ -113,6 +121,7 @@ pub fn build_repo(address string, api_key string, base_image_id string, repo &gi
docker.remove_container(id) ?
}
// build builds every Git repo in the server's list.
fn build(conf Config) ? {
build_arch := os.uname().machine

View File

@ -16,6 +16,7 @@ pub:
timestamp time.Time
}
// Overloaded operator for comparing ScheduledBuild objects
fn (r1 ScheduledBuild) < (r2 ScheduledBuild) bool {
return r1.timestamp < r2.timestamp
}
@ -147,6 +148,8 @@ fn (mut d Daemon) schedule_build(repo_id string, repo git.GitRepo) ? {
})
}
// renew_repos requests the newest list of Git repos from the server & replaces
// the old one.
fn (mut d Daemon) renew_repos() ? {
d.linfo('Renewing repos...')
mut new_repos := git.get_repos(d.address, d.api_key) ?
@ -189,6 +192,7 @@ fn (mut d Daemon) renew_queue() ? {
}
}
// rebuild_base_image recreates the builder image.
fn (mut d Daemon) rebuild_base_image() ? {
d.linfo('Rebuilding builder image....')
@ -196,6 +200,8 @@ fn (mut d Daemon) rebuild_base_image() ? {
d.image_build_timestamp = time.now().add_seconds(60 * d.image_rebuild_frequency)
}
// clean_old_base_images tries to remove any old but still present builder
// images.
fn (mut d Daemon) clean_old_base_images() {
mut i := 0

View File

@ -65,6 +65,7 @@ pub fn (ce &CronExpression) next(ref time.Time) ?time.Time {
if minute_index == ce.minutes.len && hour_index < ce.hours.len {
hour_index += 1
}
if hour_index == ce.hours.len && day_index < ce.days.len {
day_index += 1
}
@ -197,6 +198,8 @@ fn parse_range(s string, min int, max int, mut bitv []bool) ? {
}
}
// bitv_to_ints converts a bit vector into an array containing the
// corresponding values.
fn bitv_to_ints(bitv []bool, min int) []int {
mut out := []int{}
@ -209,6 +212,8 @@ fn bitv_to_ints(bitv []bool, min int) []int {
return out
}
// parse_part parses a given part of a cron expression & returns the
// corresponding array of ints.
fn parse_part(s string, min int, max int) ?[]int {
mut bitv := []bool{len: max - min + 1, init: false}

View File

@ -9,6 +9,8 @@ const socket = '/var/run/docker.sock'
const buf_len = 1024
// send writes a request to the Docker socket, waits for a response & returns
// it.
fn send(req &string) ?http.Response {
// Open a connection to the socket
mut s := unix.connect_stream(docker.socket) or {
@ -72,12 +74,14 @@ fn send(req &string) ?http.Response {
return http.parse_response(res.bytestr())
}
// request_with_body sends a request to the Docker socket with the given body.
fn request_with_body(method string, url urllib.URL, content_type string, body string) ?http.Response {
req := '$method $url.request_uri() HTTP/1.1\nHost: localhost\nContent-Type: $content_type\nContent-Length: $body.len\n\n$body\n\n'
return send(req)
}
// request sends a request to the Docker socket with an empty body.
fn request(method string, url urllib.URL) ?http.Response {
req := '$method $url.request_uri() HTTP/1.1\nHost: localhost\n\n'

View File

@ -96,6 +96,8 @@ pub fn cmd() cli.Command {
}
}
// get_repo_id_by_prefix tries to find the repo with the given prefix in its
// ID. If multiple or none are found, an error is raised.
fn get_repo_id_by_prefix(conf Config, id_prefix string) ?string {
repos := get_repos(conf.address, conf.api_key) ?
@ -118,6 +120,7 @@ fn get_repo_id_by_prefix(conf Config, id_prefix string) ?string {
return res[0]
}
// list prints out a list of all repositories.
fn list(conf Config) ? {
repos := get_repos(conf.address, conf.api_key) ?
@ -126,12 +129,14 @@ fn list(conf Config) ? {
}
}
// add adds a new repository to the server's list.
fn add(conf Config, url string, branch string, repo string, arch []string) ? {
res := add_repo(conf.address, conf.api_key, url, branch, repo, arch) ?
println(res.message)
}
// remove removes a repository from the server's list.
fn remove(conf Config, id_prefix string) ? {
id := get_repo_id_by_prefix(conf, id_prefix) ?
res := remove_repo(conf.address, conf.api_key, id) ?
@ -139,6 +144,7 @@ fn remove(conf Config, id_prefix string) ? {
println(res.message)
}
// patch patches a given repository with the provided params.
fn patch(conf Config, id_prefix string, params map[string]string) ? {
id := get_repo_id_by_prefix(conf, id_prefix) ?
res := patch_repo(conf.address, conf.api_key, id, params) ?

View File

@ -4,6 +4,9 @@ import json
import response { Response }
import net.http
// send_request<T> is a convenience method for sending requests to the repos
// API. It mostly does string manipulation to create a query string containing
// the provided params.
fn send_request<T>(method http.Method, address string, url string, api_key string, params map[string]string) ?Response<T> {
mut full_url := '$address$url'

View File

@ -175,6 +175,7 @@ pub fn read_pkg_archive(pkg_path string) ?Pkg {
}
}
// format_entry returns a string properly formatted to be added to a desc file.
fn format_entry(key string, value string) string {
return '\n%$key%\n$value\n'
}

View File

@ -2,6 +2,8 @@ module repo
import os
// archive_add_entry writes a file to an archive, given its path & inner path
// inside the archive.
fn archive_add_entry(archive &C.archive, entry &C.archive_entry, file_path &string, inner_path &string) {
st := C.stat{}
@ -29,7 +31,7 @@ fn archive_add_entry(archive &C.archive, entry &C.archive_entry, file_path &stri
}
}
// Re-generate the repo archive files
// sync regenerates the repository archive files.
fn (r &RepoGroupManager) sync(repo string, arch string) ? {
subrepo_path := os.join_path(r.repos_dir, repo, arch)

View File

@ -2,6 +2,7 @@ module server
import net.http
// is_authorized checks whether the provided API key is correct.
fn (mut app App) is_authorized() bool {
x_header := app.req.header.get_custom('X-Api-Key', http.HeaderQueryConfig{ exact: true }) or {
return false

View File

@ -8,6 +8,7 @@ import response { new_data_response, new_response }
const repos_file = 'repos.json'
// get_repos returns the current list of repos.
['/api/repos'; get]
fn (mut app App) get_repos() web.Result {
if !app.is_authorized() {
@ -25,6 +26,7 @@ fn (mut app App) get_repos() web.Result {
return app.json(http.Status.ok, new_data_response(repos))
}
// get_single_repo returns the information for a single repo.
['/api/repos/:id'; get]
fn (mut app App) get_single_repo(id string) web.Result {
if !app.is_authorized() {
@ -48,6 +50,7 @@ fn (mut app App) get_single_repo(id string) web.Result {
return app.json(http.Status.ok, new_data_response(repo))
}
// post_repo creates a new repo from the provided query string.
['/api/repos'; post]
fn (mut app App) post_repo() web.Result {
if !app.is_authorized() {
@ -86,6 +89,7 @@ fn (mut app App) post_repo() web.Result {
return app.json(http.Status.ok, new_response('Repo added successfully.'))
}
// delete_repo removes a given repo from the server's list.
['/api/repos/:id'; delete]
fn (mut app App) delete_repo(id string) web.Result {
if !app.is_authorized() {
@ -113,6 +117,7 @@ fn (mut app App) delete_repo(id string) web.Result {
return app.json(http.Status.ok, new_response('Repo removed successfully.'))
}
// patch_repo updates a repo's data with the given query params.
['/api/repos/:id'; patch]
fn (mut app App) patch_repo(id string) web.Result {
if !app.is_authorized() {

View File

@ -16,6 +16,9 @@ pub fn (mut app App) healthcheck() web.Result {
return app.json(http.Status.ok, new_response('Healthy.'))
}
// get_repo_file handles all Pacman-related routes. It returns both the
// repository's archives, but also package archives or the contents of a
// package's desc file.
['/:repo/:arch/:filename'; get; head]
fn (mut app App) get_repo_file(repo string, arch string, filename string) web.Result {
mut full_path := ''
@ -54,6 +57,7 @@ fn (mut app App) get_repo_file(repo string, arch string, filename string) web.Re
return app.file(full_path)
}
// put_package handles publishing a package to a repository.
['/:repo/publish'; post]
fn (mut app App) put_package(repo string) web.Result {
if !app.is_authorized() {

View File

@ -47,6 +47,7 @@ fn parse_attrs(name string, attrs []string) ?([]http.Method, string) {
return methods, path.to_lower()
}
// Extracts query parameters from a URL.
fn parse_query_from_url(url urllib.URL) map[string]string {
mut query := map[string]string{}
for v in url.query().data {
@ -55,6 +56,7 @@ fn parse_query_from_url(url urllib.URL) map[string]string {
return query
}
// Extract form data from an HTTP request.
fn parse_form_from_request(request http.Request) ?(map[string]string, map[string][]http.FileData) {
mut form := map[string]string{}
mut files := map[string][]http.FileData{}