Documentation
¶
Overview ¶
Package tlsle provides Let's Encrypt TLS certificate provider using HTTP-01 ACME challenges. Wraps autocert for automatic certificate management with renewal and caching support.
Example:
provider, _ := tlsle.New(
tlsle.WithDomains("example.com"),
tlsle.WithEmail("admin@example.com"),
)
defer provider.Close()
go provider.StartHTTPServer(":80", nil)
tlsConfig, _ := provider.TLSConfig()
Index ¶
- Variables
- type LetsEncrypt
- func (le *LetsEncrypt) Close(ctx context.Context) error
- func (le *LetsEncrypt) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
- func (le *LetsEncrypt) HTTPHandler(fallback http.Handler) http.Handler
- func (le *LetsEncrypt) StartHTTPServer(addr string, fallback http.Handler) error
- func (le *LetsEncrypt) StartHTTPServerWithContext(ctx context.Context, addr string, fallback http.Handler) error
- func (le *LetsEncrypt) TLSConfig() (*tls.Config, error)
- func (le *LetsEncrypt) Type() tlsproviders.ProviderType
- type Option
- func WithCacheDir[T interface{ ... }](v T) Option
- func WithClient(v *acme.Client) Option
- func WithDomains(v ...string) Option
- func WithEmail[T interface{ ... }](v T) Option
- func WithHttpShutdownTimeout(v time.Duration) Option
- func WithLogger(v *slog.Logger) Option
- func WithRenewBefore(v time.Duration) Option
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilHTTPServerContext is returned when a nil context is provided to StartHTTPServerWithContext. ErrNilHTTPServerContext = errors.New("acme http server: context cannot be nil") // ErrHTTPServerStarted is returned when attempting to start an already running HTTP server. ErrHTTPServerStarted = errors.New("acme http server: already started") )
var ( // ErrNoDomains is returned when no domains are configured. ErrNoDomains = errors.New("no domains configured") // ErrNoEmail is returned when no email is configured. ErrNoEmail = errors.New("no email configured") )
Functions ¶
This section is empty.
Types ¶
type LetsEncrypt ¶
type LetsEncrypt struct {
// contains filtered or unexported fields
}
LetsEncrypt provides automatic TLS certificate management using the ACME protocol and Let's Encrypt certificate authority. Use New to create a new instance.
func New ¶
func New(opt ...Option) (*LetsEncrypt, error)
New creates a new Let's Encrypt TLS certificate provider. The provider uses HTTP-01 challenges which require port 80 to be accessible.
Example:
provider, err := tlsle.New(
tlsle.WithDomains("example.com"),
tlsle.WithEmail("admin@example.com"),
tlsle.WithCacheDir("./certs"),
)
func (*LetsEncrypt) Close ¶
func (le *LetsEncrypt) Close(ctx context.Context) error
Close stops the HTTP server gracefully using the provided context. The context controls the graceful shutdown timeout. Returns context.DeadlineExceeded if shutdown doesn't complete within the context timeout.
Example:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() provider.Close(ctx)
func (*LetsEncrypt) GetCertificate ¶
func (le *LetsEncrypt) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate retrieves or requests a certificate for the given domain. This method implements the tls.Config.GetCertificate callback.
Example:
config := &tls.Config{GetCertificate: provider.GetCertificate}
func (*LetsEncrypt) HTTPHandler ¶
func (le *LetsEncrypt) HTTPHandler(fallback http.Handler) http.Handler
HTTPHandler returns an HTTP handler that responds to ACME HTTP-01 challenges. Non-ACME requests are forwarded to the fallback handler.
Example:
mux := http.NewServeMux()
http.ListenAndServe(":80", provider.HTTPHandler(mux))
func (*LetsEncrypt) StartHTTPServer ¶
func (le *LetsEncrypt) StartHTTPServer(addr string, fallback http.Handler) error
StartHTTPServer starts the ACME HTTP server for handling HTTP-01 challenges. The server must be accessible on port 80 from the internet for challenge validation. The fallback handler receives non-ACME requests.
Example:
go provider.StartHTTPServer(":80", nil)
Example with HTTP to HTTPS redirect:
redirect := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
http.Redirect(w, r, "https://"+r.Host+r.URL.Path, http.StatusMovedPermanently)
})
go provider.StartHTTPServer(":80", redirect)
func (*LetsEncrypt) StartHTTPServerWithContext ¶
func (le *LetsEncrypt) StartHTTPServerWithContext(ctx context.Context, addr string, fallback http.Handler) error
StartHTTPServerWithContext starts the ACME HTTP server with context support. The context enables graceful shutdown and cancellation.
Example:
ctx, cancel := context.WithCancel(context.Background()) defer cancel() go provider.StartHTTPServerWithContext(ctx, ":80", nil)
func (*LetsEncrypt) TLSConfig ¶
func (le *LetsEncrypt) TLSConfig() (*tls.Config, error)
TLSConfig returns a TLS configuration with automatic certificate management. The configuration uses secure defaults and handles certificate renewal automatically.
Example:
tlsConfig, err := provider.TLSConfig()
if err != nil {
log.Fatal(err)
}
server := &http.Server{
Addr: ":443",
TLSConfig: tlsConfig,
Handler: handler,
}
server.ListenAndServeTLS("", "")
func (*LetsEncrypt) Type ¶
func (le *LetsEncrypt) Type() tlsproviders.ProviderType
Type returns the provider type identifier. Always returns ProviderTypeLetsEncrypt.
Example:
fmt.Println(provider.Type()) // "letsencrypt"
type Option ¶
type Option func(o *options) error
Option is a functional option for configuring options.
func WithCacheDir ¶
WithCacheDir sets the cacheDir option.
func WithHttpShutdownTimeout ¶
WithHttpShutdownTimeout sets the httpShutdownTimeout option.
func WithRenewBefore ¶
WithRenewBefore sets the renewBefore option.
Source Files