0
# Server Execution
1

2
Core server execution functions that provide the main entry points for running Hypercorn servers. These functions handle server startup, worker management, and shutdown processes for both programmatic and command-line usage.
3

4
## Capabilities
5

6
### Main Server Runner
7

8
Primary function for executing the Hypercorn server with a given configuration, supporting multiple worker classes and handling server lifecycle.
9

10
```python { .api }
11
def run(config: Config) -> int:
12
    """
13
    Main entry point to run Hypercorn server.
14
    
15
    Starts the Hypercorn server with the provided configuration,
16
    supporting both single-worker and multi-worker modes.
17
    Handles worker lifecycle, signal handling, and graceful shutdown.
18
    
19
    Args:
20
        config: Config object containing all server settings
21
        
22
    Returns:
23
        Exit code (0 for success, non-zero for errors)
24
        
25
    Supported worker classes:
26
        - 'asyncio': Standard asyncio event loop
27
        - 'uvloop': High-performance uvloop event loop  
28
        - 'trio': Trio async framework
29
    """
30
```
31

32
### Command Line Interface
33

34
CLI entry point that parses command-line arguments and runs the server, providing access to all configuration options through command-line flags.
35

36
```python { .api }
37
def main(sys_args: list[str] | None = None) -> int:
38
    """
39
    CLI entry point with argument parsing.
40
    
41
    Parses command-line arguments to create configuration and
42
    runs the Hypercorn server. Provides access to all Config
43
    options through command-line flags and positional arguments.
44
    
45
    Args:
46
        sys_args: Optional list of command-line arguments.
47
                 If None, uses sys.argv
48
                 
49
    Returns:
50
        Exit code (0 for success, non-zero for errors)
51
        
52
    Command-line usage:
53
        hypercorn [OPTIONS] APPLICATION_PATH
54
        
55
    Common options:
56
        --bind, -b: Binding address (can be used multiple times)
57
        --workers, -w: Number of worker processes  
58
        --worker-class, -k: Worker class (asyncio, uvloop, trio)
59
        --certfile: SSL certificate file
60
        --keyfile: SSL private key file
61
        --reload: Enable auto-reload on file changes
62
        --access-logfile: Access log file path
63
        --error-logfile: Error log file path
64
        --log-level: Logging level
65
        --pid: PID file path
66
        --daemon: Run as daemon process
67
    """
68
```
69

70
## Usage Examples
71

72
### Programmatic Server Execution
73

74
```python
75
from hypercorn.config import Config
76
from hypercorn.run import run
77

78
# Create and configure server
79
config = Config()
80
config.bind = ["0.0.0.0:8000"] 
81
config.workers = 4
82
config.worker_class = "asyncio"
83

84
# Run the server
85
exit_code = run(config)
86
print(f"Server exited with code: {exit_code}")
87
```
88

89
### Command Line Usage
90

91
```bash
92
# Basic usage
93
hypercorn app:application
94

95
# Specify binding and workers
96
hypercorn --bind 0.0.0.0:8000 --workers 4 app:application
97

98
# HTTPS with SSL certificates
99
hypercorn --certfile cert.pem --keyfile key.pem --bind 0.0.0.0:443 app:application
100

101
# Development mode with auto-reload
102
hypercorn --reload --bind 127.0.0.1:8000 app:application
103

104
# Production settings
105
hypercorn \
106
  --bind 0.0.0.0:8000 \
107
  --workers 8 \
108
  --worker-class uvloop \
109
  --access-logfile access.log \
110
  --error-logfile error.log \
111
  --pid hypercorn.pid \
112
  app:application
113
```
114

115
### Integration with Process Managers
116

117
```bash
118
# Using with systemd
119
[Unit]
120
Description=Hypercorn ASGI Server
121
After=network.target
122

123
[Service]
124
Type=exec
125
ExecStart=/usr/local/bin/hypercorn --bind 0.0.0.0:8000 --workers 4 app:application
126
Restart=always
127
User=www-data
128
Group=www-data
129

130
[Install]
131
WantedBy=multi-user.target
132
```
133

134
### Signal Handling
135

136
The server responds to standard UNIX signals:
137

138
- **SIGTERM**: Graceful shutdown
139
- **SIGINT**: Graceful shutdown (Ctrl+C)
140
- **SIGUSR1**: Restart workers (master process continues)
141
- **SIGCHLD**: Handle child process termination
142

143
### Worker Management
144

145
In multi-worker mode:
146

147
- Master process manages worker lifecycle
148
- Workers are automatically restarted if they crash
149
- Graceful worker replacement during configuration reloads
150
- Load balancing across workers using SO_REUSEPORT (when available)