webapp

package module
v0.0.0-...-e1b65c3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2025 License: Apache-2.0 Imports: 18 Imported by: 3

README

Package cloudeng.io/webapp

import cloudeng.io/webapp

Package webapp and its sub-packages provide support for building webapps. This includes utility routines for managing http.Server instances, generating self-signed TLS certificates etc. The sub-packages provide support for managing the assets to be served, various forms of authentication and common toolchains such as webpack. For production purposes assets are built into the server's binary, but for development they are built into the binary but can be overridden from a local filesystem or from a running development server that manages those assets (eg. a webpack dev server instance). This provides the flexibility for both simple deployment of production servers and iterative development within the same application.

An example/template can be found in cmd/webapp.

Functions

Func NewHTTPServer
func NewHTTPServer(addr string, handler http.Handler) (net.Listener, *http.Server, error)

NewHTTPServer returns a new *http.Server and a listener whose address defaults to ":http".

Func NewTLSServer
func NewTLSServer(addr string, handler http.Handler, cfg *tls.Config) (net.Listener, *http.Server, error)

NewTLSServer returns a new *http.Server and a listener whose address defaults to ":https".

Func RedirectPort80
func RedirectPort80(ctx context.Context, httpsAddr string, acmeRedirectHost string) error

RedirectPort80 starts an http.Server that will redirect port 80 to the specified supplied https port. If acmeRedirect is specified then acme HTTP-01 challenges will be redirected to that URL. The server will run in the background until the supplied context is canceled.

Func RedirectToHTTPSHandlerFunc
func RedirectToHTTPSHandlerFunc(tlsPort string, acmeRedirectHost *url.URL) http.HandlerFunc

RedirectToHTTPSHandlerFunc is a http.HandlerFunc that will redirect to the specified port but using https as the scheme. Install it on port 80 to redirect all http requests to https on tlsPort. tlsPort defaults to 443. If acmeRedirect is specified then acme HTTP-01 challenges will be redirected to that URL.

Func RegisterCertStoreFactory
func RegisterCertStoreFactory(cache CertStoreFactory)

RegisterCertStoreFactory makes the supplied CertStoreFactory available for use via the TLSCertStoreFlags command line flags.

Func RegisteredCertStores
func RegisteredCertStores() []string

RegisteredCertStores returns the list of currently registered certificate stores.

Func SafePath
func SafePath(path string) error

SafePath checks if the given path is safe for use as a filename screening for control characters, windows device names, relative paths, paths (eg. a/b is not allowed) etc.

Func ServeTLSWithShutdown
func ServeTLSWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error

ServeTLSWithShutdown is like ServeWithShutdown except for a TLS server. Note that any TLS options must be configured prior to calling this function via the TLSConfig field in http.Server.

Func ServeWithShutdown
func ServeWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error

ServeWithShutdown runs srv.ListenAndServe in background and then waits for the context to be canceled. It will then attempt to shutdown the web server within the specified grace period.

Func TLSConfigFromFlags
func TLSConfigFromFlags(ctx context.Context, cl HTTPServerFlags, getStoreOpts func() (opts []any, err error), cacheOpts ...CertServingCacheOption) (*tls.Config, error)

TLSConfigFromFlags creates a tls.Config based on the supplied flags, which may require obtaining certificates directly from pem files or from a possibly remote certificate store using TLSConfigUsingCertStore. If a cert store is specified then the getStoreOpts function may be used to obtain additional options for the store. A cache is then created to from that store using the supplied cacheOpts.

Func TLSConfigUsingCertFiles
func TLSConfigUsingCertFiles(certFile, keyFile string) (*tls.Config, error)

TLSConfigUsingCertFiles returns a tls.Config configured with the certificate read from the supplied files.

Func TLSConfigUsingCertStore
func TLSConfigUsingCertStore(ctx context.Context, store CertStore, cacheOpts ...CertServingCacheOption) (*tls.Config, error)

TLSConfigUsingCertStore returns a tls.Config configured with the certificate obtained from the specified certificate store accessed via a CertServingCache created with the supplied options.

Types

Type CertServingCache
type CertServingCache struct {
	// contains filtered or unexported fields
}

CertServingCache implements an in-memory cache of TLS/SSL certificates loaded from a backing store. Validation of the certificates is performed on loading rather than every use. It provides a GetCertificate method that can be used by tls.Config. A TTL (default of 6 hours) is used so that the in-memory cache will reload certificates from the store on a periodic basis (with some jitter) to allow for certificates to be refreshed.

Functions
func NewCertServingCache(ctx context.Context, certStore CertStore, opts ...CertServingCacheOption) *CertServingCache

NewCertServingCache returns a new instance of CertServingCache that uses the supplied CertStore. The supplied context is cached and used by the GetCertificate method, this allows for credentials etc to be passed to the CertStore.Get method called by GetCertificate via the context.

Methods
func (m *CertServingCache) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate can be assigned to tls.Config.GetCertificate.

Type CertServingCacheOption
type CertServingCacheOption func(*CertServingCache)

CertServingCacheOption represents options to NewCertServingCache.

Functions
func CertCacheNowFunc(fn func() time.Time) CertServingCacheOption

CertCacheNowFunc sets the function used to obtain the current time. This is generally only required for testing purposes.

func CertCacheRootCAs(rootCAs *x509.CertPool) CertServingCacheOption

CertCacheRootCAs sets the rootCAs to be used when verifying the validity of the certificate loaded from the back store.

func CertCacheTTL(ttl time.Duration) CertServingCacheOption

CertCacheTTL sets the in-memory TTL beyond which cache entries are refreshed. This is generally only required for testing purposes.

Type CertStore
type CertStore interface {
	Get(ctx context.Context, name string) ([]byte, error)
	Put(ctx context.Context, name string, data []byte) error
}

CertStore represents a store for TLS certificates.

Functions
func NewCertStore(ctx context.Context, typ, name string, storeOpts ...any) (CertStore, error)
Type CertStoreFactory
type CertStoreFactory interface {
	Type() string
	Describe() string
	New(ctx context.Context, name string, opts ...any) (CertStore, error)
}

CertStoreFactory is the interface that must be implemented to register a new CertStore type with this package so that it may accessed via the TLSCertStoreFlags command line flags.

Type HTTPAcmeFlags
type HTTPAcmeFlags struct {
	AcmeRedirectTarget string `subcmd:"acme-redirect-target,,host implementing acme client that this http server will redirect acme challenges to"`
}

HTTPAcmeFlags defines flags for running an http server that will handle acme challenges, currently it allows for redirecting them to a server that implements the acme client protocol.

Type HTTPServerFlags
type HTTPServerFlags struct {
	Address string `subcmd:"https,:8080,address to run https web server on"`
	TLSCertFlags
}

HTTPServerFlags defines commonly used flags for running an http server. TLS certificates may be retrieved either from a local cert and key file as specified by tls-cert and tls-key; this is generally used for testing or when the domain certificates are available only as files. The altnerative, preferred for production, source for TLS certificates is from a cache as specified by tls-cert-cache-type and tls-cert-cache-name. The cache may be on local disk, or preferably in some shared service such as Amazon's Secrets Service.

Type TLSCertFlags
type TLSCertFlags struct {
	TLSCertStoreFlags
	CertificateFile string `subcmd:"tls-cert,,ssl certificate file"`
	KeyFile         string `subcmd:"tls-key,,ssl private key file"`
}

TLSCertFlags defines commonly used flags for obtaining TLS/SSL certificates. Certificates may be obtained in one of two ways: from a cache of certificates, or from local files.

Type TLSCertStoreFlags
type TLSCertStoreFlags struct {
	CertStoreType  string `subcmd:"tls-cert-store-type,,'the type of the certificate store to use for retrieving tls certificates, use --tls-list-stores to see the currently available types'"`
	CertStore      string `subcmd:"tls-cert-store,,'name/address of the certificate cache to use for retrieving tls certificates, the interpreation of this depends on the tls-cert-store-type flag'"`
	ListStoreTypes bool   `subcmd:"tls-list-stores,,list the available types of tls certificate store"`
}

TLSCertStoreFlags defines commonly used flags for specifying a TLS/SSL certificate store. This is generally used in conjunction with TLSConfigFromFlags for apps that simply want to use stored certificates. Apps that manage/obtain/renew certificates may use them directly.

Examples

ExampleServeWithShutdown

Documentation

Overview

Package webapp and its sub-packages provide support for building webapps. This includes utility routines for managing http.Server instances, generating self-signed TLS certificates etc. The sub-packages provide support for managing the assets to be served, various forms of authentication and common toolchains such as webpack. For production purposes assets are built into the server's binary, but for development they are built into the binary but can be overridden from a local filesystem or from a running development server that manages those assets (eg. a webpack dev server instance). This provides the flexibility for both simple deployment of production servers and iterative development within the same application.

An example/template can be found in cmd/webapp.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewHTTPServer 

func NewHTTPServer(addr string, handler http.Handler) (net.Listener, *http.Server, error)

NewHTTPServer returns a new *http.Server and a listener whose address defaults to ":http".

func NewTLSServer 

func NewTLSServer(addr string, handler http.Handler, cfg *tls.Config) (net.Listener, *http.Server, error)

NewTLSServer returns a new *http.Server and a listener whose address defaults to ":https".

func RedirectPort80 

func RedirectPort80(ctx context.Context, httpsAddr string, acmeRedirectHost string) error

RedirectPort80 starts an http.Server that will redirect port 80 to the specified supplied https port. If acmeRedirect is specified then acme HTTP-01 challenges will be redirected to that URL. The server will run in the background until the supplied context is canceled.

func RedirectToHTTPSHandlerFunc 

func RedirectToHTTPSHandlerFunc(tlsPort string, acmeRedirectHost *url.URL) http.HandlerFunc

RedirectToHTTPSHandlerFunc is a http.HandlerFunc that will redirect to the specified port but using https as the scheme. Install it on port 80 to redirect all http requests to https on tlsPort. tlsPort defaults to 443. If acmeRedirect is specified then acme HTTP-01 challenges will be redirected to that URL.

func RegisterCertStoreFactory 

func RegisterCertStoreFactory(cache CertStoreFactory)

RegisterCertStoreFactory makes the supplied CertStoreFactory available for use via the TLSCertStoreFlags command line flags.

func RegisteredCertStores 

func RegisteredCertStores() []string

RegisteredCertStores returns the list of currently registered certificate stores.

func SafePath 

func SafePath(path string) error

SafePath checks if the given path is safe for use as a filename screening for control characters, windows device names, relative paths, paths (eg. a/b is not allowed) etc.

func ServeTLSWithShutdown 

func ServeTLSWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error

ServeTLSWithShutdown is like ServeWithShutdown except for a TLS server. Note that any TLS options must be configured prior to calling this function via the TLSConfig field in http.Server.

func ServeWithShutdown 

func ServeWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error

ServeWithShutdown runs srv.ListenAndServe in background and then waits for the context to be canceled. It will then attempt to shutdown the web server within the specified grace period.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"time"

	"cloudeng.io/webapp"
)

func main() {
	handler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		fmt.Fprintln(w, "Hello, World!")
	})

	ln, srv, err := webapp.NewHTTPServer("127.0.0.1:0", handler)
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
	defer cancel()

	host, port, _ := net.SplitHostPort(ln.Addr().String())
	if port != "0" {
		fmt.Printf("server listening on: %s:<some-port>\n", host)
	}

	if err := webapp.ServeWithShutdown(ctx, ln, srv, 5*time.Second); err != nil {
		log.Printf("server shutdown error: %v", err)
	}
	fmt.Println("server shutdown complete")
}

Output:

server listening on: 127.0.0.1:<some-port>
server shutdown complete

func TLSConfigFromFlags 

func TLSConfigFromFlags(ctx context.Context, cl HTTPServerFlags, getStoreOpts func() (opts []any, err error), cacheOpts ...CertServingCacheOption) (*tls.Config, error)

TLSConfigFromFlags creates a tls.Config based on the supplied flags, which may require obtaining certificates directly from pem files or from a possibly remote certificate store using TLSConfigUsingCertStore. If a cert store is specified then the getStoreOpts function may be used to obtain additional options for the store. A cache is then created to from that store using the supplied cacheOpts.

func TLSConfigUsingCertFiles 

func TLSConfigUsingCertFiles(certFile, keyFile string) (*tls.Config, error)

TLSConfigUsingCertFiles returns a tls.Config configured with the certificate read from the supplied files.

func TLSConfigUsingCertStore 

func TLSConfigUsingCertStore(ctx context.Context, store CertStore, cacheOpts ...CertServingCacheOption) (*tls.Config, error)

TLSConfigUsingCertStore returns a tls.Config configured with the certificate obtained from the specified certificate store accessed via a CertServingCache created with the supplied options.

Types

type CertServingCache 

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

CertServingCache implements an in-memory cache of TLS/SSL certificates loaded from a backing store. Validation of the certificates is performed on loading rather than every use. It provides a GetCertificate method that can be used by tls.Config. A TTL (default of 6 hours) is used so that the in-memory cache will reload certificates from the store on a periodic basis (with some jitter) to allow for certificates to be refreshed.

func NewCertServingCache 

func NewCertServingCache(ctx context.Context, certStore CertStore, opts ...CertServingCacheOption) *CertServingCache

NewCertServingCache returns a new instance of CertServingCache that uses the supplied CertStore. The supplied context is cached and used by the GetCertificate method, this allows for credentials etc to be passed to the CertStore.Get method called by GetCertificate via the context.

func (*CertServingCache) GetCertificate 

func (m *CertServingCache) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate can be assigned to tls.Config.GetCertificate.

type CertServingCacheOption 

type CertServingCacheOption func(*CertServingCache)

CertServingCacheOption represents options to NewCertServingCache.

func CertCacheNowFunc 

func CertCacheNowFunc(fn func() time.Time) CertServingCacheOption

CertCacheNowFunc sets the function used to obtain the current time. This is generally only required for testing purposes.

func CertCacheRootCAs 

func CertCacheRootCAs(rootCAs *x509.CertPool) CertServingCacheOption

CertCacheRootCAs sets the rootCAs to be used when verifying the validity of the certificate loaded from the back store.

func CertCacheTTL 

func CertCacheTTL(ttl time.Duration) CertServingCacheOption

CertCacheTTL sets the in-memory TTL beyond which cache entries are refreshed. This is generally only required for testing purposes.

type CertStore 

type CertStore interface {
	Get(ctx context.Context, name string) ([]byte, error)
	Put(ctx context.Context, name string, data []byte) error
}

CertStore represents a store for TLS certificates.

func NewCertStore 

func NewCertStore(ctx context.Context, typ, name string, storeOpts ...any) (CertStore, error)

type CertStoreFactory 

type CertStoreFactory interface {
	Type() string
	Describe() string
	New(ctx context.Context, name string, opts ...any) (CertStore, error)
}

CertStoreFactory is the interface that must be implemented to register a new CertStore type with this package so that it may accessed via the TLSCertStoreFlags command line flags.

type HTTPAcmeFlags 

type HTTPAcmeFlags struct {
	AcmeRedirectTarget string `subcmd:"acme-redirect-target,,host implementing acme client that this http server will redirect acme challenges to"`
}

HTTPAcmeFlags defines flags for running an http server that will handle acme challenges, currently it allows for redirecting them to a server that implements the acme client protocol.

type HTTPServerFlags 

type HTTPServerFlags struct {
	Address string `subcmd:"https,:8080,address to run https web server on"`
	TLSCertFlags
}

HTTPServerFlags defines commonly used flags for running an http server. TLS certificates may be retrieved either from a local cert and key file as specified by tls-cert and tls-key; this is generally used for testing or when the domain certificates are available only as files. The altnerative, preferred for production, source for TLS certificates is from a cache as specified by tls-cert-cache-type and tls-cert-cache-name. The cache may be on local disk, or preferably in some shared service such as Amazon's Secrets Service.

type TLSCertFlags 

type TLSCertFlags struct {
	TLSCertStoreFlags
	CertificateFile string `subcmd:"tls-cert,,ssl certificate file"`
	KeyFile         string `subcmd:"tls-key,,ssl private key file"`
}

TLSCertFlags defines commonly used flags for obtaining TLS/SSL certificates. Certificates may be obtained in one of two ways: from a cache of certificates, or from local files.

type TLSCertStoreFlags 

type TLSCertStoreFlags struct {
	CertStoreType  string `` /* 164-byte string literal not displayed */
	CertStore      string `` /* 170-byte string literal not displayed */
	ListStoreTypes bool   `subcmd:"tls-list-stores,,list the available types of tls certificate store"`
}

TLSCertStoreFlags defines commonly used flags for specifying a TLS/SSL certificate store. This is generally used in conjunction with TLSConfigFromFlags for apps that simply want to use stored certificates. Apps that manage/obtain/renew certificates may use them directly.

Source Files

View all Source files

Directories

Path Synopsis
cmd
acme module
webapp module
Package devtest provides utilities for the development and testing of web applications, including TLS certificate generation and management.
 Package devtest provides utilities for the development and testing of web applications, including TLS certificate generation and management.
chromedputil
Package chromedputil provides utility functions for working with the Chrome DevTools Protocol via github.com/chromedp.
 Package chromedputil provides utility functions for working with the Chrome DevTools Protocol via github.com/chromedp.
Package jsonapi provides utilities for working with json REST APIs.
 Package jsonapi provides utilities for working with json REST APIs.
webauth
acme
Package acme provides support for working with acme/letsencrypt providers.
 Package acme provides support for working with acme/letsencrypt providers.
jwtutil
Package jwtutil provides support for creating and verifying JSON Web Tokens (JWTs) managed by the github.com/golang-jwt/jwt/v5 package.
 Package jwtutil provides support for creating and verifying JSON Web Tokens (JWTs) managed by the github.com/golang-jwt/jwt/v5 package.
webauthn/passkeys
Package passkeys provides support for creating and authenticating WebAuthn passkeys.
 Package passkeys provides support for creating and authenticating WebAuthn passkeys.
auth0 module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.