ttserver

ttserver

ttserver is a simple TCP server aiming to handle simple text protocols.

SYNOPSIS

ttserver -config <path> [-help]

OPTIONS

-config <path>

The path of the configuration file.

-help

Display the help message.

DESCRIPTION

ttserver is a simple TCP server allowing to:

• serve content over custom connection handlers:
  • finger and gopher protocols' handlers included
  • a basic page renderer supporting:
    • Go templates
    • caching
    • fetching remotes contents
• define generic routes with regex
• fetch remote contents (json, html, feeds) and display them in pages
• run cron tasks to create/update pages
• server content over TLS with the support of the ACME protocol (Let's Encrypt)
• gather stats about the server on a Prometheus compatible endpoint, /metrics
• handle PROXY protocol

CONFIGURATION

The configuration file is a JSON formatted file.

Logging (log)

The log object is used to configure the logging system:

Example:

  "log": {
    "level": "trace",
    "format": "text",
    "to": "stderr"
  },

Prometheus (prometheus)

The prometheus object is used to configure the Prometheus endpoint:

Example:

  "prometheus": {
    "address": "127.0.0.1:9777",
    "endpoint": "/metrics",
    "summaryMaxAge": 86400,
    "chanSize": 1024
  },

Authentication (prometheus.auth)

The prometheus.auth.basic object is used to configure the Prometheus authentication access to the endpoint with Basic Auth:

Example:

  "prometheus": {
    ...
    "auth": {
      "basic": {
        "username": "username",
        "password": "password"
      }
    },
  },

Space (space)

The space object is used to configure a space (in other words: what will be seved and how):

Example:

  "space": {
    "cache": {
        ...
    },
    "listener": {
        ...
    },
    "handler": {
        ...
    },
    "basedir": "examples/gopher",
    "routes": {
        ...
    }

Cache (space.cache)

The space.cache object is used to configure the cache.

The cache is only relevant if you use a handler with page renderer functions that use it.

The space.cache.memory object is used to configure the in-memory cache store.

Listener (space.listener)

The space.listener object is used to configure the listener.

Example:

  "space": {
    ...
    "listener": {
      "address": "127.0.0.1:7070",
      "domains": ["gopher-test.t18s.fr"]
    }
  }

The space.listener.tls.acme object is used to configure the ACME client.

Currently, only the DNS challenge is supported with a small subset of providers.

To configure a provider, the credentials need to be provided using environment variables:

• Gandi: GANDI_API_TOKEN
• Cloudflare: CLOUDFLARE_API_TOKEN
• Hetzner: HETZNER_API_TOKEN
• DigitalOcean: DO_API_TOKEN

Example:

  "space": {
    ...
    "listener": {
      ...
      "tls": {
        "acme": {
          "dnsprovider": "gandi",
          "email": "xxxx@xxxx",
          "ca": "https://acme-staging-v02.api.letsencrypt.org/directory",
          "testca": "https://acme-staging-v02.api.letsencrypt.org/directory",
          "storage": {
            "file": {
              "path": ".certmagic"
            }
          }
        }
      }
    }
  }

####### ACME storage (space.listener.tls.acme.storage)

The space.listener.tls.acme.storage object is used to configure the ACME storage.

####### ACME file storage (space.listener.tls.acme.storage.file)

The space.listener.tls.acme.storage.file object is used to configure the ACME file storage.

Handler (space.handler)

The space.handler object is used to configure the handler.

Example:

  "space": {
    ...
    "handler": {
      "name": "finger",
    }
  }

The space.handler object used by the Finger handler allows custom parameters.

The Finger protocol don't have know how to identify the requested domain (like the Host header in HTTP). But the address could be used in a template

So here is the decision tree for the domain: response_domain > SNI domain (if enabled) > space.listener.domains[0] > space.listener.address (address part)

And for the port: response_rt > space.listener.address (port part)

Example:

  "space": {
    ...
    "handler": {
      "name": "finger",
      "parameters": {
        "response_domain": "finger-test.t18s.fr",
        "response_port": "7979"
      }
    }
  }

The space.handler object used by the Gopher handler allows custom parameters.

The Gopher protocol don't have know how to identify the requested domain (like the Host header in HTTP). But :

• the response needs to contain the address and port of the server
• the address could be used in a template

So here is the decision tree for the domain: response_domain > SNI domain (if enabled) > space.listener.domains[0] > space.listener.address (address part)

And for the port: response_rt > space.listener.address (port part)

Example:

  "space": {
    ...
    "handler": {
      "name": "gopher",
      "parameters": {
        "response_domain": "gopher-test.t18s.fr",
        "response_port": "7070"
      }
    }
  }

Routes (space.routes)

The space.routes object is used to configure a map<name, route object> of routes.

The name can be:

• a name of a page pointing to an existing template file (without the .tpl extension)
• a name of a page where the template file is defined in the route object
• a regex that can matches multiples name:
  • the template file is defined in the route object
  • the regex capturing groups can be used to point to a template file

The space.route.<name> object is used to configure a route.

A route can render the content of a template or a file. By default, the name of the route is used to find a template and then a file.

A route can be automatically executed by a cron process that will fake a connection.

Example:

  "space": {
    ...
    "routes": {
      "~^blog/(\\d{4})/(\\d{2})$": {
        "template": "blog/$1-$2.tpl"
      },
    }
  }

The space.route.<name>.fetch object is used to configure a map<name, fetch object> of fetches.

The space.route.<name>.fetch.<name> object is used to configure a fetch.

A fetch allows to get content from external JSON or Feed (atom, rss) pages and inject them into a page.

Example:

  "space": {
    ...
    "routes": {
      "aggregator/unix": {
        "template": "aggregator.tpl",
        "fetch": {
          "1_slashdot": {
            "type": "feed",
            "uri": "http://rss.slashdot.org/Slashdot/slashdotMain"
          },
          "2_undeadly": {
            "type": "feed",
            "uri": "https://undeadly.org/cgi?action=rss&items=15"
          },
          "3_undeadly_errata": {
            "type": "feed",
            "uri": "https://undeadly.org/errata/errata.rss"
          }
        },
        "cron": "0 30 */5 * * *"
      },
    }
  }

EXAMPLES

See examples for some configurations.

TODO

Common:

• make the linters happy
• tests
• use lib viper to handle confs

Listener:

• allow to listen on multiple addresses
• add IPv6 support

TLS:

• allow to customize TLS ciphers
• add more certs' handlers

ACME:

• handle more dns providers
• add more challenges
• better handling of the dns providers (don't import them all?)

LICENSE

See LICENSE.md