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 CertPoolForTesting
func CertPoolForTesting(pemFiles ...string) (*x509.CertPool, error)
CertPoolForTesting returns a new x509.CertPool containing the certs in the specified pem files. It is intended for testing purposes only.
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 NewSelfSignedCert
func NewSelfSignedCert(certFile, keyFile string, options ...SelfSignedOption) error
NewSelfSignedCert creates a self signed certificate. Default values for the supported options are:
- an rsa 4096 bit private key will be generated and used.
- "localhost" and "127.0.0.1" are used for the DNS and IP addresses included in the certificate.
- certificates are valid from time.Now() and for 5 days.
- the organization is 'cloudeng llc'.
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.
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
Func SelfSignedCertCommand
func SelfSignedCertCommand(name string) *subcmd.Command
SelfSignedCertCommand returns a subcmd.Command that provides the ability to generate a self signed certificate and private key file.
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, storeOpts ...interface{}) (*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. Any supplied storeOpts are passed to TLSConfigUsingCertStore.
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, typ, name, testingCA string, storeOpts ...interface{}) (*tls.Config, error)
TLSConfigUsingCertStore returns a tls.Config configured with the certificate obtained from a certificate store.
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(certStore CertStore, opts ...CertServingCacheOption) *CertServingCache
NewCertServingCache returns a new instance of CertServingCache that uses the supplied CertStore.
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
Delete(ctx context.Context, name string) error
}
CertStore represents a store for TLS certificates.
Functions
func NewCertStore(ctx context.Context, typ, name string, storeOpts ...interface{}) (CertStore, error)
Type CertStoreFactory
type CertStoreFactory interface {
Type() string
Describe() string
New(ctx context.Context, name string, opts ...interface{}) (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 HTTPServerFlags
type HTTPServerFlags struct {
Address string `subcmd:"https,:8080,address to run https web server on"`
TLSCertFlags
AcmeRedirectTarget string `subcmd:"acme-redirect-target,,host implementing acme client that this http server will redirect acme challenges to"`
TestingCAPem string `subcmd:"acme-testing-ca,,'pem file containing a CA to be trusted for testing purposes only, for example, when using letsencrypt\\'s staging service'"`
}
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 SelfSignedOption
type SelfSignedOption func(ssc *selfSignedCertOptions)
SelfSignedOption represents an option to NewSelfSignedCert.
Functions
func CertAllIPAddresses() SelfSignedOption
CertIPAddresses specifies that all local IPs be used in the generated certificate.
func CertDNSHosts(hosts ...string) SelfSignedOption
CertDNSHosts specifies the set of dns host names to use in the generated certificate.
func CertIPAddresses(ips ...string) SelfSignedOption
CertIPAddresses specifies the set of ip addresses to use in the generated certificate.
func CertOrganizations(orgs ...string) SelfSignedOption
CertOrganizations specifies that the organization to be used in the generated certificate.
func CertPrivateKey(key crypto.PrivateKey) SelfSignedOption
CertPrivateKey specifies the private key to use for the certificate.
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.
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 ¶
- func CertPoolForTesting(pemFiles ...string) (*x509.CertPool, error)
- func NewHTTPServer(addr string, handler http.Handler) (net.Listener, *http.Server, error)
- func NewSelfSignedCert(certFile, keyFile string, options ...SelfSignedOption) error
- func NewTLSServer(addr string, handler http.Handler, cfg *tls.Config) (net.Listener, *http.Server, error)
- func RedirectPort80(ctx context.Context, httpsAddr string, acmeRedirectHost string) error
- func RedirectToHTTPSHandlerFunc(tlsPort string, acmeRedirectHost *url.URL) http.HandlerFunc
- func RegisterCertStoreFactory(cache CertStoreFactory)
- func RegisteredCertStores() []string
- func SafePath(path string) error
- func SelfSignedCertCommand(name string) *subcmd.Command
- func ServeTLSWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error
- func ServeWithShutdown(ctx context.Context, ln net.Listener, srv *http.Server, grace time.Duration) error
- func TLSConfigFromFlags(ctx context.Context, cl HTTPServerFlags, storeOpts ...interface{}) (*tls.Config, error)
- func TLSConfigUsingCertFiles(certFile, keyFile string) (*tls.Config, error)
- func TLSConfigUsingCertStore(ctx context.Context, typ, name, testingCA string, storeOpts ...interface{}) (*tls.Config, error)
- type CertServingCache
- type CertServingCacheOption
- type CertStore
- type CertStoreFactory
- type HTTPServerFlags
- type SelfSignedOption
- type TLSCertFlags
- type TLSCertStoreFlags
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CertPoolForTesting ¶
CertPoolForTesting returns a new x509.CertPool containing the certs in the specified pem files. It is intended for testing purposes only.
func NewHTTPServer ¶
NewHTTPServer returns a new *http.Server and a listener whose address defaults to ":http".
func NewSelfSignedCert ¶
func NewSelfSignedCert(certFile, keyFile string, options ...SelfSignedOption) error
NewSelfSignedCert creates a self signed certificate. Default values for the supported options are:
- an rsa 4096 bit private key will be generated and used.
- "localhost" and "127.0.0.1" are used for the DNS and IP addresses included in the certificate.
- certificates are valid from time.Now() and for 5 days.
- the organization is 'cloudeng llc'.
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 ¶
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.
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 SelfSignedCertCommand ¶
SelfSignedCertCommand returns a subcmd.Command that provides the ability to generate a self signed certificate and private key file.
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, storeOpts ...interface{}) (*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. Any supplied storeOpts are passed to TLSConfigUsingCertStore.
func TLSConfigUsingCertFiles ¶
TLSConfigUsingCertFiles returns a tls.Config configured with the certificate read from the supplied files.
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(certStore CertStore, opts ...CertServingCacheOption) *CertServingCache
NewCertServingCache returns a new instance of CertServingCache that uses the supplied CertStore.
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
Delete(ctx context.Context, name string) error
}
CertStore represents a store for TLS certificates.
type CertStoreFactory ¶
type CertStoreFactory interface {
Type() string
Describe() string
New(ctx context.Context, name string, opts ...interface{}) (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 HTTPServerFlags ¶
type HTTPServerFlags struct {
Address string `subcmd:"https,:8080,address to run https web server on"`
TLSCertFlags
AcmeRedirectTarget string `subcmd:"acme-redirect-target,,host implementing acme client that this http server will redirect acme challenges to"`
TestingCAPem string `` /* 149-byte string literal not displayed */
}
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 SelfSignedOption ¶
type SelfSignedOption func(ssc *selfSignedCertOptions)
SelfSignedOption represents an option to NewSelfSignedCert.
func CertAllIPAddresses ¶
func CertAllIPAddresses() SelfSignedOption
CertIPAddresses specifies that all local IPs be used in the generated certificate.
func CertDNSHosts ¶
func CertDNSHosts(hosts ...string) SelfSignedOption
CertDNSHosts specifies the set of dns host names to use in the generated certificate.
func CertIPAddresses ¶
func CertIPAddresses(ips ...string) SelfSignedOption
CertIPAddresses specifies the set of ip addresses to use in the generated certificate.
func CertOrganizations ¶
func CertOrganizations(orgs ...string) SelfSignedOption
CertOrganizations specifies that the organization to be used in the generated certificate.
func CertPrivateKey ¶
func CertPrivateKey(key crypto.PrivateKey) SelfSignedOption
CertPrivateKey specifies the private key to use for the certificate.
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
Directories