gwi

README

This project delivers various functions to be used in your server, with that you can customize all pages and paths.

Usage

The simplest way of using this project is the following example:

package main

import (
	"net/http"

	"blmayer.dev/gwi"
)

func main() {
	// init user vault
	v, err := NewFileVault("users.json", "--salt--")
	// handle error
	
	// gwi config struct
	c := gwi.Config{
		Root: "path/to/git/folder",
		PagesRoot: "path/to/html-templates",
		...
	}

	g, _ := gwi.NewFromConfig(c, v)
	// handle error

	err := http.ListenAndServe(":8080", g.Handle())
	// handle err
}

Examples

Users

To get a list of your users is simple:

<ul>
	{{range users}}
	<li>{{.}}</li>
	{{end}}
</ul>

File tree

To get the file tree for the current reference:

<table>
    <tr>
        <th>Mode</th>
        <th>Size</th>
        <th>Name</th>
    </tr>
    {{range tree .Ref}}
    <tr>
        <td>{{.Mode}}</td>
        <td>{{.Size}}</td>
	<td>{{.Name}}</td>
    </tr>
    {{end}}
</table>

Will print a nice list of your project files.

Commits

Using the functions commits and commit you're able to see a list of commits and check details of each one:

<table>
    <tr>
        <th>Time</th>
        <th>Author</th>
        <th>Message</th>
    </tr>
    {{range commits .Ref}}
    <tr>
        <td>{{.Author.When.String}}</td>
        <td>{{.Author.Name}}</td>
	<td>{{.Message}}</td>
    </tr>
    {{end}}
</table>

To get the list, and the following show a commit's details:

{{with commit .Ref}}

<p><b>Commited at:</b> {{.Committer.When.String}}</p>
<p><b>Author:</b> {{.Committer.Name}} ({{.Committer.Email}})</p>
<p><b>Message:</b></p>
<p>{{.Message}}</p>
{{end}}

Documentation

Overview

gwi stands for Git Web Interface, so it lets you customize the appearance of your git repositories using templates. gwi is intended to be run on servers where your bare git repositories are located, so it can detect and render them correctly.

gwi works in a simple way: it is a web server, and your request's path points which user and repo are selected, i.e.:

GET root/user/repo/action/args

selects the repository named repo from the user named user. Those are just hierarchical abstractions. Then the next folder in the path defines the template it will run, in this case the action, so gwi will execute a template named action.html with the selected repo information available. Lastly, everything that comes after action is part of args, and it is passed to templates under the Args field.

Template functions

This package provides functions that you can call in your templates, letting you query the data you want in an efficient way. Currently we export the following functions:

• usage
• users
• repos
• head
• thread
• mails
• desc
• branches
• tags
• log
• commits
• commit
• tree
• files
• file
• markdown

Which can be called on templates using the standard template syntax.

To see complete details about them see FuncMapTempl.

Handlers

gwi comes with 2 handlers: Main and List, which are meant to be used in different situations. See their respective docs for their use.

The default branch for git is main.

Examples

The most simple way of using this is initializing and using the handle function:

package main

import (
	"net/http"

	"blmayer.dev/gwi"
)

func main() {
	// init user vault
	v, err := NewFileVault("users.json", "--salt--")
	// handle error

	// gwi config struct
	c := gwi.Config{
		Root: "path/to/git/folder",
		PagesRoot: "path/to/html-templates",
		...
	}

	g, _ := gwi.NewFromConfig(c, v)
	// handle error

	err := http.ListenAndServe(":8080", g.Handle())
	// handle err
}

Another good example is [main_test.go].

Using templates provided:

Repo has {{commits .Ref}} commits.

Will print the number of commits on the repo.

Index

• Variables
• type Config
• type File
• type FileVault
  • func NewFileVault(path, salt string) (FileVault, error)
  • func (f FileVault) GetUser(login string) User
  • func (f FileVault) Mix(data string) string
  • func (f FileVault) Validate(login, pass string) bool
• type Gwi
  • func NewFromConfig(config Config, vault Vault) (Gwi, error)
  • func (g *Gwi) GitCGIHandler(w http.ResponseWriter, r *http.Request)
  • func (g *Gwi) Handle() http.Handler
  • func (g *Gwi) ListHandler(w http.ResponseWriter, r *http.Request)
  • func (g *Gwi) MainHandler(w http.ResponseWriter, r *http.Request)
• type Info
• type Usage
• type User
• type Vault

Variables

var FuncMapTempl = map[string]any{

	"usage":    diskUsage,
	"users":    func() []string { return nil },
	"repos":    func(user string) []string { return nil },
	"head":     func() *plumbing.Reference { return nil },
	"thread":   func(section string) []any { return nil },
	"mails":    func(thread string) []any { return nil },
	"desc":     func(ref plumbing.Hash) string { return "" },
	"branches": func(ref plumbing.Hash) []*plumbing.Reference { return nil },
	"tags":     func() []*plumbing.Reference { return nil },
	"log":      func(ref plumbing.Hash) []*object.Commit { return nil },
	"commits":  func(ref plumbing.Hash) int { return -1 },
	"commit":   func(ref plumbing.Hash) *object.Commit { return nil },
	"tree":     func(ref plumbing.Hash) []File { return nil },
	"files":    func(ref plumbing.Hash) int { return -1 },
	"file":     func(ref plumbing.Hash, name string) string { return "" },
	"markdown": mdown,
}

FuncMapTempl gives the signatures for all functions available on templates.

Types

type Config

type Config struct {
	Domain      string
	MailAddress string
	PagesRoot   string
	Root        string
	CGIRoot     string
	CGIPrefix   string
	LogLevel    logger.Level
	Functions   map[string]func(p ...any) any
}

Config is used to configure the gwi application, things like Root, PagesRoot and CGIRoot are the central part that make gwi work. Domain, MailAddress and Functions are mostly used to enhance the information displayed on templates.

type File

type File struct {
	*object.File
	Size int64
}

type FileVault

type FileVault struct {
	Users map[string]User
	// contains filtered or unexported fields
}

func NewFileVault

func NewFileVault(path, salt string) (FileVault, error)

func (FileVault) GetUser

func (f FileVault) GetUser(login string) User

func (FileVault) Mix

func (f FileVault) Mix(data string) string

func (FileVault) Validate

func (f FileVault) Validate(login, pass string) bool

type Gwi

type Gwi struct {
	// contains filtered or unexported fields
}

func NewFromConfig

func NewFromConfig(config Config, vault Vault) (Gwi, error)

func (*Gwi) GitCGIHandler

func (g *Gwi) GitCGIHandler(w http.ResponseWriter, r *http.Request)

GitCGIHandler is the interface with git CGI that handles git operations like pull and push. To use this handler use the correct config options.

func (*Gwi) Handle

func (g *Gwi) Handle() http.Handler

Handle returns all handlers defined here, it should be used to handle requests, as this provides the list and main handlers in the correct path.

func (*Gwi) ListHandler

func (g *Gwi) ListHandler(w http.ResponseWriter, r *http.Request)

ListHandler is used for listing users, or repos for a user given in the URL path, this handler is usefull for creating listings of projects, as this is very light on reads, and can be executed more often. It populates the template data with just User and Repo fields, along with 2 functions: users and repos.

func (*Gwi) MainHandler

func (g *Gwi) MainHandler(w http.ResponseWriter, r *http.Request)

MainHandler is the handler used to display information about a repository. It contains all functions defined it FuncMapTempl with the correct user and repo selected; and provides the complete Info struct as data to the template. This handler is used to display data like commits, files, branches and tags about a given repo.

type Info

type Info struct {
	User    string
	Repo    string
	Ref     plumbing.Hash
	RefName string
	Args    string
}

Info is the structure that is passed as data to templates being executed. The values are filled with the selected repo and user given on the URL.

type Usage

type Usage struct {
	Total int
	Free  int
	Used  int
}

type User

type User interface {
	Email() string
	Login() string
	Pass() string
}

User interface represents what a user should provide at a minimum. This interface is available on templates and is also used internaly.

type Vault

type Vault interface {
	GetUser(login string) User
	Validate(login, pass string) bool
}

Vault is used to authenticate write calls to git repositories, the Vault implementation FileVault is a simple example that uses salt and hashes to store and validate users. In real applications you should use a better approache and implement your own Vault interface.