bird

README

Bird

Bird is an alternative web protocol. It is used to share Seed documents which can contain links. Seed is a simple markup language. The birdspace is entirely plaintext, no binary at all (as God intended).

This repository specifically is a Go library for using Bird protocol and the Seed markup language. It is the refence implementation of both. It also provides eagle which is a mix between curl and cat for documents in the birdspace. It also also provides the library and binary owl which allows you to easily host a Bird protocol file server.

Quickstart

Bird protocol

Bird is a request-response networking protocol for the birdspace. It is incredibly simple and has no error handling whatsoever. It is transported on TCP.

A request is simply sending a Bird protocol-relative URL without a trailing slash followed by a newline character to a Bird server. A response is simply a valid Seed document in reply to the request.

Seed document

Seed is a simple markup language for documents, similar to Markdown. It is completely plaintext and it is line based. It does not support embedding, only linking. Every line has to end in just a newline character, not CRLF.

Other Documentation

• Bird Specification :)
• Bird Library
• Seed Specification
• Seed Library

License

This project is licensed under the MIT license.

Documentation

Overview

Package bird provides Bird protocol client and server implementations.

Index

• Constants
• Variables
• func Fetch(rawurl string) (sr *seed.Reader, close func() (err error), err error)
• func Serve(address string, h Handler) (err error)
• type Handler
• type HandlerFunc
  • func (hf HandlerFunc) ServeBird(u *url.URL, sw *seed.Writer)

Constants

const (
	// DefaultPort is the default Bird port for TCP.
	DefaultPort uint16 = 6668
)

Variables

var (
	// ErrNoHostURL indicates that the URL given was missing the host.
	ErrNoHostURL = errors.New("URL should have host")
	// ErrProtocolRelativeURL indicates that the URL given was not relative to
	// the bird:// scheme.
	ErrProtocolRelativeURL = errors.New("URL should be protocol relative and have no scheme")
	// ErrTrailingSlashURL indicates that the URL given had a trailing slash,
	// which is not allowed in the Bird protocol.
	ErrTrailingSlashURL = errors.New("URL should not have trailing slash")
)

Functions

func Fetch

func Fetch(rawurl string) (sr *seed.Reader, close func() (err error), err error)

Fetch fetches the requested Seed document using Bird.

rawurl is a Bird URL that is protocol-relative and without a trailing slash. bird://hello/world/ is simply //hello/world.

sr is the Seed document reader, close is a function that closes the underlying connection and err is any error in creating a connection to the Bird server.

func Serve

func Serve(address string, h Handler) (err error)

Serve starts a Bird server using h to handle requests. It opens a new goroutine to handle each request. It automatically closes the connection after h returns. Any invalid requests are immediately skipped.

Types

type Handler

type Handler interface {
	ServeBird(u *url.URL, sw *seed.Writer)
}

Handler responds to a Bird request.

ServeBird writes a Seed document to sw in response to the request URL u.

type HandlerFunc

type HandlerFunc func(u *url.URL, sw *seed.Writer)

HandlerFunc is a Handler that allows you to use a function to handle Bird requests.

f := func(u *url.URL, sw *seed.Writer) {
	sw.Text("Hello, world!")
}
h := bird.HandlerFunc(f)
bird.Serve(..., h)

f is type converted to a HandlerFunc here and is used as a Handler.

func (HandlerFunc) ServeBird

func (hf HandlerFunc) ServeBird(u *url.URL, sw *seed.Writer)

ServeBird calls the handler function.