5.6 KiB
WebDAV Server Implementation
This document describes the WebDAV server implementation for HeroLauncher.
Overview
The WebDAV server provides a way to access and manage files through the WebDAV protocol, which allows for remote file management over HTTP/HTTPS. This implementation uses the Go standard library's WebDAV package from golang.org/x/net/webdav.
The server supports both HTTP and HTTPS connections, basic authentication, and includes comprehensive debug logging for troubleshooting.
Implementation Details
The WebDAV server is implemented in the pkg/webdavserver package. The server can be configured with various options including:
- Host and port to listen on
- Base path for the WebDAV endpoint
- File system path to serve files from
- Read and write timeouts
- Debug mode for verbose logging
- Basic authentication with username/password
- HTTPS support with TLS certificate and key files
Usage
Starting the WebDAV Server
To start the WebDAV server, use the cmd/webdavserver/main.go command:
go run cmd/webdavserver/main.go [options]
Available options:
-host: Host address to bind to (default: "0.0.0.0")-port: Port to listen on (default: 9999)-base-path: Base URL path for WebDAV (default: "/")-fs: File system path to serve (default: system temp directory + "/heroagent")-debug: Enable debug mode with verbose logging (default: false)-auth: Enable basic authentication (default: false)-username: Username for basic authentication (default: "admin")-password: Password for basic authentication (default: "1234")-https: Enable HTTPS (default: false)-cert: Path to TLS certificate file (optional if auto-generation is enabled)-key: Path to TLS key file (optional if auto-generation is enabled)-auto-gen-certs: Auto-generate certificates if they don't exist (default: true)-cert-validity: Validity period in days for auto-generated certificates (default: 365)-cert-org: Organization name for auto-generated certificates (default: "HeroLauncher WebDAV Server")
Connecting to WebDAV from macOS
A bash script is provided to easily connect to the WebDAV server from macOS:
./scripts/open_webdav_osx.sh [options]
Available options:
-h, --host: WebDAV server hostname (default: "localhost")-p, --port: WebDAV server port (default: 9999)-path, --path-prefix: Path prefix for WebDAV URL (default: "")-s, --https: Use HTTPS instead of HTTP (default: false)-u, --username: Username for authentication-pw, --password: Password for authentication--help: Show help message
API
Server Configuration
// Config holds the configuration for the WebDAV server
type Config struct {
Host string
Port int
BasePath string
FileSystem string
ReadTimeout time.Duration
WriteTimeout time.Duration
DebugMode bool
UseAuth bool
Username string
Password string
UseHTTPS bool
CertFile string
KeyFile string
AutoGenerateCerts bool
CertValidityDays int
CertOrganization string
}
// DefaultConfig returns the default configuration
func DefaultConfig() Config
Server Methods
// NewServer creates a new WebDAV server
func NewServer(config Config) (*Server, error)
// Start starts the WebDAV server
func (s *Server) Start() error
// Stop stops the WebDAV server
func (s *Server) Stop() error
Integration with HeroLauncher
The WebDAV server can be integrated with the main HeroLauncher application by adding it to the server initialization in cmd/server/main.go.
Directory Structure
The WebDAV server uses the following directory structure:
<parent-of-fs>/
├── <fs-dir>/ # WebDAV files served to clients (specified by -fs)
└── certificates/ # TLS certificates for HTTPS
Where certificates are stored in a certificates directory next to the filesystem directory specified with the -fs parameter.
Security Considerations
- Basic authentication is supported but disabled by default
- HTTPS is supported but disabled by default
- The server can automatically generate self-signed certificates if needed
- For production use, always enable authentication and HTTPS
- Use strong passwords and properly signed certificates for production
- Be careful about which directories you expose through WebDAV
- Consider implementing IP-based access restrictions for additional security
Debugging
When troubleshooting WebDAV connections, the debug mode can be enabled with the -debug flag. This will provide detailed logging of:
- All incoming requests
- Request headers
- Client information
- Authentication attempts
- WebDAV operations
Debug logs are prefixed with [WebDAV DEBUG] for easy filtering.
Examples
Starting a secure WebDAV server with auto-generated certificates
go run cmd/webdavserver/main.go -auth -username myuser -password mypass -https -fs /path/to/files -debug
Starting a secure WebDAV server with existing certificates
go run cmd/webdavserver/main.go -auth -username myuser -password mypass -https -cert /path/to/cert.pem -key /path/to/key.pem -fs /path/to/files -debug -auto-gen-certs=false
Connecting from macOS with authentication
./scripts/open_webdav_osx.sh -s -u myuser -pw mypass