README
¶
Houston is an Express-like Gemini server, written in Go. Primarily because I want to. Not because it's necessary. There are plenty other Gemini servers that have all important functionality covered, and several are written in Go themselves. I just want to make my own.
That said, this aims to be lightweight and easy to use. This was initially developed to suite my own purposes, for my own capsules, as I wanted a server that I understood. Not somebody else's.
Basic Usage Example
Easiest way to learn, for me, is by reading an example. Here you go:
package main
import (
"fmt"
"git.sr.ht/~seanld/houston"
)
func main() {
mainRouter := houston.BlankRouter()
// Route a URL path to a static file directory, like:
// gemini://localhost/ -> ./sandbox/index.gmi
// gemini://localhost/hello -> ./sandbox/hello.gmi
mainRouter.AddSandbox("/", "sandbox")
// Run a function when gemini://localhost/interact is visited.
mainRouter.AddRoute("/interact", func(ctx houston.Context) {
// Send input response to client, and then run a function
// with the entered input value.
ctx.InputAndDo("Enter name", func(s string, c houston.Context) {
ctx.SendStringf("text/gemini", "Hello, %s, you are #%d.", s, 1)
})
})
// Provide a router, certificate file, and private key file.
newServer := houston.NewServer(mainRouter, "cert/main.crt", "cert/my.key")
fmt.Println("Starting server...")
newServer.Start("localhost")
}
More Info
Router structs are used by Server structs to provide functionality for handling
request-to-response. Routers can have Route and Sandbox instances. They can be
added to a router by doing Router.AddRoute(url, func (net.Conn) {}) or
Router.AddSandbox(url, sandboxDirPath).
Route instances connect a URL path to a function that is executed when it's visited.
Sandbox instances connect a URL path to a local directory that holds static files.
For example, if you connect /hello to local dir /hello-static, and /hello-static
has a file named index.gmi in it, and someone visits /hello, it will attempt
to load the file /hello-static/index.gmi. Or any other file specified from that dir.
Context instances provide the URL of a connection, the actual net.Conn of the
connection, some methods for conveniently sending responses, and other features.
Documentation
¶
Index ¶
- func CleanURLPath(targetUrl string) string
- func GetMimetypeFromPath(targetPath string) string
- func GetSharedPath(path1 string, path2 string) string
- func HandleConnection(s *Server, c net.Conn)
- func URLToSandboxPath(targetUrl string, sandbox Sandbox) (string, error)
- type Context
- func (ctx *Context) BadRequest(info string)
- func (ctx *Context) CGIError(info string)
- func (ctx *Context) CertNotAuthorized(info string)
- func (ctx *Context) CertNotValid(info string)
- func (ctx *Context) ClientCertRequired(info string)
- func (c *Context) GetQuery() string
- func (ctx *Context) Gone(info string)
- func (ctx *Context) Input(prompt string)
- func (ctx *Context) InputAndDo(prompt string, handler InputHandler)
- func (ctx *Context) NotFound(info string)
- func (ctx *Context) PermFailure(info string)
- func (ctx *Context) ProxyError(info string)
- func (ctx *Context) ProxyRequestRefused(info string)
- func (ctx *Context) RedirectPerm(url string)
- func (ctx *Context) RedirectTemp(url string)
- func (ctx *Context) SendBytes(mimeType string, content []byte)
- func (ctx *Context) SendFile(mimeType string, path string) error
- func (ctx *Context) SendString(mimeType string, str string)
- func (ctx *Context) SendStringf(mimeType string, str string, values ...interface{})
- func (ctx *Context) SensitiveInput(prompt string)
- func (ctx *Context) ServerUnavailable(info string)
- func (ctx *Context) SlowDown(waitSeconds int)
- func (ctx *Context) Success(mimeType string)
- func (ctx *Context) TempFail(info string)
- type InputHandler
- type Route
- type RouteHandler
- type Router
- type RouterOpts
- type Sandbox
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanURLPath ¶ added in v0.1.1
func GetMimetypeFromPath ¶
func GetSharedPath ¶
Get the common part of two paths.
func HandleConnection ¶
Types ¶
type Context ¶
func (*Context) BadRequest ¶
func (*Context) CertNotAuthorized ¶
func (*Context) CertNotValid ¶
func (*Context) ClientCertRequired ¶
func (*Context) InputAndDo ¶
func (ctx *Context) InputAndDo(prompt string, handler InputHandler)
func (*Context) PermFailure ¶
func (*Context) ProxyError ¶
func (*Context) ProxyRequestRefused ¶
func (*Context) RedirectPerm ¶
func (*Context) RedirectTemp ¶
func (*Context) SendString ¶
func (*Context) SendStringf ¶
func (*Context) SensitiveInput ¶
func (*Context) ServerUnavailable ¶
type InputHandler ¶
type Route ¶
type Route struct {
Path string
Handler RouteHandler
}
type RouteHandler ¶
type RouteHandler func(Context)
type Router ¶
type Router struct {
Routes []Route
Sandboxes []Sandbox
ErrorHandler RouteHandler
}
func BlankRouter ¶
func BlankRouter() Router
func NewRouter ¶
func NewRouter(config RouterOpts) Router
func (*Router) AddRoute ¶
func (r *Router) AddRoute(targetPath string, handler RouteHandler)
func (*Router) AddSandbox ¶
func (*Router) GetRouteHandler ¶
func (r *Router) GetRouteHandler(targetPath string) RouteHandler
Get the handler for a given route. If no route matches a handler, then return the default error handler.
type RouterOpts ¶
type RouterOpts struct {
ErrorHandler RouteHandler
}
Source Files