tupi

README

Tupi - A simple http server
============================

.. raw:: html

    <img src="https://raw.githubusercontent.com/jucacrispim/tupi/master/docs/source/_static/logo.svg" height="100px">

Tupi is a very simple http server. Its main purpose is to provide an easy
way to serve files from, and upload file to, a directory.


Build & install
---------------

Tupi is written in go so you need the go compiler installed. With that installed
clone the code:

.. code-block:: sh

   $ git clone https://github.com/jucacrispim/tupi


And install the program with:

.. code-block:: sh

   $ cd tupi
   $ make install


.. code-block:: note

   For all make targets use ``make help``


Usage
-----

Tupi was created to serve and upload files to a directory. So first lets create
a directory with files

.. code-block:: sh

   $ mkdir myfiles
   $ echo "My first file" > myfiles/file.txt


Serving files
+++++++++++++

You can start the server using the command ``tupi``

.. code-block:: sh

   $ tupi -root myfiles

This is going to serve the files in the ``myfiles`` directory and the server
will listen in the port 8080

Use the option ``-h`` for all the options for tupi.

.. code-block:: sh

   $ tupi -h

With the server running we can fetch files from the directory.

.. code-block:: sh

   $ curl http://localhost:8080/file.txt
   My first file

You can also list the contents of a directory:

.. code-block:: sh

   $ curl http://localhost:8080/
   <pre>
   <a href="file.txt">file.txt</a>
   </pre>

You can also, instead of listing the contents of a directory, return the
index.html file in it. To do so use the option ``default-to-index``.

.. code-block:: sh

   $ tupi -default-to-index


Uploading files
+++++++++++++++

To upload files is required an authenticated request using basic http auth.
Tupi reads the user auth information from a htpasswd file. To create a
htpasswd file use:

.. code-block:: sh

   $ htpasswd -c -B /my/htpasswd myusername

And start tupi with the ``-htpasswd`` flag:

.. code-block:: sh

   $ tupi -root myfiles -htpasswd /my/htpasswd


.. warning::

   Your htpasswd file MUST NOT be within the root directory being served
   by tupi

Now you can upload files sending a POST request to the "/u/" path in the server.
The request must have the ``multipart/form-data`` Content-Type header and the
file must be in a input named ``file``.

.. code-block:: sh

   $ curl --user test:123 -F 'file=@/home/juca/powerreplica.jpg' http://localhost:8080/u/
   powerreplica.jpg

   $ curl http://localhost:8080/
   <pre>
   <a href="file.txt">file.txt</a>
   <a href="powerreplica.jpg">powerreplica.jpg</a>
   </pre>


Extracting files
++++++++++++++++

Tupi is capable of extracting ``.tar.gz`` files. To extract files you send a
POST request to the "/e/" path in the server. This request must also have the
``multipart/form-data`` Content-Type header and the file must be in a
input named ``file``.

.. code-block:: sh

   $ curl --user test:123 -F 'file=@/home/juca/test.tar.gz' http://localhost:8080/e/
   bla/
   bla/two.txt
   bla/ble/
   bla/ble/four.txt
   bla/ble/bad.txt
   bla/ble/three.txt
   bla/one.txt

   $ curl http://localhost:8080/
   <pre>
   <a href="bla/">bla/</a>
   <a href="file.txt">file.txt</a>
   <a href="powerreplica.jpg">powerreplica.jpg</a>
   </pre>



Using https
+++++++++++

To use https you need to start tupi with ``-certfile`` and ``-keyfile``
flags.

.. code-block:: sh

  $ tupi -root myfiles -certfile /my/file.pem -keyfile /my/file.key


Config file
++++++++++++

You can use a config file instead of command line options. Check the
documentation `here <https://tupi.poraodojuca.dev/index.html#config-file>`_.


Virtual domains
+++++++++++++++

Tupi also supports the use of virutal domains. Check the virtual domains
documantation `here <https://tupi.poraodojuca.dev/#virtual-domains>`_.

Plugins
+++++++

Tupi can be exteded by plugins. Check the `documentation <https://tupi.poraodojuca.dev/plugins.html>`_
on how to write plugins for tupi


Full documentation
++++++++++++++++++

Check the full documentation `here <https://tupi.poraodojuca.dev>`_.

Documentation

Index

• Constants
• func AcquireLock(key string)
• func Debugf(format string, v ...interface{})
• func Errorf(format string, v ...interface{})
• func GetLogLevel() logLevel
• func Infof(format string, v ...interface{})
• func InitPlugin(fpath string, domain string, conf *map[string]any) (*plugin.Plugin, error)
• func IsLocked(key string) bool
• func LoadAuthPlugin(fpath string, domain string, conf *map[string]any) error
• func LoadServePlugin(fpath string, domain string, conf *map[string]any) error
• func ReleaseLock(key string)
• func SetLogLevel(level logLevel)
• func SetLogLevelStr(levelstr string) error
• func Tracef(format string, v ...interface{})
• func Warningf(format string, v ...interface{})
• type AuthFn
  • func GetAuthPlugin(fpath string) (AuthFn, error)
• type Config
  • func GetConfig() (Config, error)
  • func GetConfigFromFile(fpath string) (Config, error)
  • func (c *Config) HasSSL() bool
  • func (c *Config) Validate() error
• type DomainConfig
  • func GetConfigFromCommandLine() DomainConfig
  • func (c *DomainConfig) HasCert() bool
  • func (c *DomainConfig) HasKey() bool
  • func (c *DomainConfig) Validate() error
• type ServeFn
  • func GetServePlugin(fpath string) (ServeFn, error)
• type TupiServer
  • func SetupServer(conf Config) TupiServer
  • func (s *TupiServer) LoadPlugins()
  • func (s *TupiServer) Run()

Constants

const (
	LevelTrace logLevel = iota
	LevelDebug
	LevelInfo
	LevelWarning
	LevelError
)

const INVALID_PREFIX_MSG = "Invalid prefix"

const UPLOAD_CONTENT_TYPE = "multipart/form-data"

Functions

func AcquireLock

func AcquireLock(key string)

AcquireLock locks a resource based in a key When you are done you must release the lock with ReleaseLock()

func Debugf

func Debugf(format string, v ...interface{})

func Errorf

func Errorf(format string, v ...interface{})

func GetLogLevel

func GetLogLevel() logLevel

func Infof

func Infof(format string, v ...interface{})

func InitPlugin

func InitPlugin(fpath string, domain string, conf *map[string]any) (*plugin.Plugin, error)

InitPlugin tries to run the “Init“ function of a plugin. As it is optinal, if not found returns without error. The “Init“ function get a domain and a config map for the domain as parameters. The plugin “Init“ function signature is as follows:

func(string, map[string]any) error

InitPlugin is intended to be run as part of the server start process.

func IsLocked

func IsLocked(key string) bool

IsLocked return a bool informing if a given resource is locked

func LoadAuthPlugin

func LoadAuthPlugin(fpath string, domain string, conf *map[string]any) error

LoadAuthPlugin loads a authentication plugin looking for an “Authenticate“ function. The “Authenticate“ function gets a referece to http.Request, a domain and a config map for the domain as parameters. The signature of the “Authenticate“ function is as follows:

func(*http.Request, string, map[string]any)

LoadAuthPlugin is intended to be run as part of the server start process.

func LoadServePlugin

func LoadServePlugin(fpath string, domain string, conf *map[string]any) error

LoadServePlugin loads a authentication plugin looking for an “Serve“ function. The “Serve“ function gets a referece to http.Request, a domain and a config map for the domain as parameters. The signature of the “Serve“ function is as follows:

func(*http.Request, string, map[string]any)

LoadServePlugin is intended to be run as part of the server start process.

func ReleaseLock

func ReleaseLock(key string)

ReleaseLock releases the lock for a given resource identified by a key.

func SetLogLevel

func SetLogLevel(level logLevel)

func SetLogLevelStr

func SetLogLevelStr(levelstr string) error

func Tracef

func Tracef(format string, v ...interface{})

func Warningf

func Warningf(format string, v ...interface{})

Types

type AuthFn

type AuthFn func(*http.Request, string, *map[string]any) (bool, int)

func GetAuthPlugin

func GetAuthPlugin(fpath string) (AuthFn, error)

Returns an already loaded “Autenticate“ function of an auth plugin.

type Config

type Config struct {
	Domains map[string]DomainConfig
}

func GetConfig

func GetConfig() (Config, error)

GetConfig returns the config struct for the server by reading the confs passed in the command line and optionally in a config file. Config file values have precedence over command line values

func GetConfigFromFile

func GetConfigFromFile(fpath string) (Config, error)

func (*Config) HasSSL

func (c *Config) HasSSL() bool

func (*Config) Validate

func (c *Config) Validate() error

type DomainConfig

type DomainConfig struct {
	Host             string
	Port             int
	AlternativePort  int
	RootDir          string
	Timeout          int
	HtpasswdFile     string
	UploadPath       string
	ExtractPath      string
	MaxUploadSize    int64
	CertFilePath     string
	KeyFilePath      string
	DefaultToIndex   bool
	ConfigFile       string
	AuthPlugin       string
	AuthPluginConf   map[string]interface{}
	ServePlugin      string
	ServePluginConf  map[string]interface{}
	LogLevel         string
	PreventOverwrite bool
	AuthMethods      []string
	// contains filtered or unexported fields
}

func GetConfigFromCommandLine

func GetConfigFromCommandLine() DomainConfig

func (*DomainConfig) HasCert

func (c *DomainConfig) HasCert() bool

func (*DomainConfig) HasKey

func (c *DomainConfig) HasKey() bool

func (*DomainConfig) Validate

func (c *DomainConfig) Validate() error

type ServeFn

type ServeFn func(http.ResponseWriter, *http.Request, *map[string]any)

func GetServePlugin

func GetServePlugin(fpath string) (ServeFn, error)

Returns an already loaded "Serve" function of a serve plugin

type TupiServer

type TupiServer struct {
	Conf Config
	// We have one server for each port we listen
	Servers []*http.Server
}

func SetupServer

func SetupServer(conf Config) TupiServer

SetupServer creates a new instance of the tupi http server. You can start it using “TupiServer.Run“

func (*TupiServer) LoadPlugins

func (s *TupiServer) LoadPlugins()

func (*TupiServer) Run

func (s *TupiServer) Run()