HTTPServer

apiVersion: core/v1
kind: HTTPServer
metadata:
  name: "default"
  namespace: "default"
spec: {}

  1syntax = "proto3";
  2package core.v1;
  3
  4import "buf/validate/validate.proto";
  5import "core/v1/http.proto";
  6import "core/v1/httphandler.proto";
  7import "kernel/network.proto";
  8import "kernel/resource.proto";
  9
 10option go_package = "github.com/aileron-gateway/aileron-gateway/apis/core/v1";
 11
 12// HTTPServer resource definition.
 13// apiVersion="core/v1", kind="HTTPServer".
 14message HTTPServer {
 15    string          APIVersion = 1 [json_name = "apiVersion"];
 16    string          Kind       = 2 [json_name = "kind"];
 17    kernel.Metadata Metadata   = 3 [json_name = "metadata"];
 18    HTTPServerSpec  Spec       = 4 [json_name = "spec"];
 19}
 20
 21// HTTPServerSpec is the specifications for the HTTPServer object.
 22message HTTPServerSpec {
 23    // [OPTIONAL]
 24    // ErrorHandler is the reference to a ErrorHandler object.
 25    // Referred object must implement ErrorHandler interface.
 26    // This error handler will be used for default NotFound handler.
 27    // This field will be ignored if NotFoundHandler is specified
 28    // or a handler for root path "/" is registered.
 29    // Default error handler is used when not set.
 30    kernel.Reference ErrorHandler = 1 [json_name = "errorHandler"];
 31
 32    // [OPTIONAL]
 33    // Addr is the address which the server listen to.
 34    // If not set, default port is used.
 35    // The format must be "host:port", ":port" or "host%zone:port".
 36    // For example, "0.0.0.0:443", "[::1]:443", ":443", "localhost:443", ":https".
 37    // See more address example at https://pkg.go.dev/net#Dial.
 38    // To use unix domain socket such like, "/var/run/gateway.sock" or "@gateway",
 39    // set Network and Address in the ListenConfig of HTTP2Config field.
 40    // Default is [":8080"].
 41    string Addr = 2 [json_name = "addr"];
 42
 43    // [OPTIONAL]
 44    // ShutdownTimeout is the timeout dutation of graceful shutdown of the server in seconds.
 45    // Default is [30].
 46    int32 ShutdownTimeout = 3 [json_name = "shutdownTimeout"];
 47
 48    // [OPTIONAL]
 49    // HTTPConfig is the configuration for HTTP/1.1 and HTTP/2 server.
 50    // HTTP server is enabled if both HTTP2Config and HTTP3Config
 51    // are not configured.
 52    // Default is not set.
 53    HTTPConfig HTTPConfig = 4 [json_name = "httpConfig"];
 54
 55    // [OPTIONAL]
 56    // HTTP2Config is the additional config for HTTP/2 server.
 57    // Default is not set.
 58    HTTP2Config HTTP2Config = 5 [json_name = "http2Config"];
 59
 60    // [OPTIONAL]
 61    // HTTP3Config is the configuration for HTTP3, or Quic server.
 62    // HTTP2 server is enabled if both HTTP2Config and HTTP3Config
 63    // was not configured.
 64    // This configuration only enables quick(udp) server.
 65    // So, it is usually required to enable both HTTP2 (tcp) and HTTP3 (udp) servers
 66    // to access this server directory from browsers.
 67    // Default is not set.
 68    HTTP3Config HTTP3Config = 6 [json_name = "http3Config"];
 69
 70    // [OPTIONAL]
 71    // Middleware is the list of middleware applied for the entire server.
 72    // Default is not set.
 73    repeated kernel.Reference Middleware = 7 [json_name = "middleware"];
 74
 75    // [OPTIONAL]
 76    // VirtualHosts is the list of virtual host specification.
 77    // Use this for configuring the route for this server.
 78    // Default is not set.
 79    repeated VirtualHostSpec VirtualHosts = 8 [json_name = "virtualHosts"];
 80
 81    // [OPTIONAL]
 82    // EnableProfile enables profile endpoint for the server.
 83    // If true, following endpoints are registered to the server.
 84    //   - pprof.Index at "GET /debug/pprof/"
 85    //   - pprof.Cmdline at "GET /debug/pprof/cmdline"
 86    //   - pprof.Profile at "GET /debug/pprof/profile"
 87    //   - pprof.Symbol at "GET /debug/pprof/symbol"
 88    //   - pprof.Trace at "GET /debug/pprof/trace"
 89    // See https://pkg.go.dev/net/http/pprof.
 90    // DO NOT enable this on production environment.
 91    // Default is [false].
 92    bool EnableProfile = 9 [json_name = "enableProfile"];
 93
 94    // [OPTIONAL]
 95    // EnableExpvar enables expvar endpoint for the server.
 96    // The endpoint is "GET /debug/vars".
 97    // See https://pkg.go.dev/expvar.
 98    // DO NOT enable this on production environment.
 99    // Default is [false].
100    bool EnableExpvar = 10 [json_name = "enableExpvar"];
101}
102
103// HTTPConfig is the configuration for a HTTP 1/2 server.
104message HTTPConfig {
105    // EnableGeneralOptionsHandler, if false, passes "OPTIONS *" requests to the Handler,
106    // otherwise responds with 200 OK and Content-Length: 0.
107    // This fileid is used only for http server, not for http3 sever.
108    // Default is [false].
109    bool EnableGeneralOptionsHandler = 1 [json_name = "enableGeneralOptionsHandler"];
110
111    // [OPTIONAL]
112    // ReadTimeout is the maximum duration for reading the entire request, including the body.
113    // A zero or negative value means there will be no timeout.
114    // Because each request body's acceptable deadline or upload rate are not decided per-request
115    // by this ReadTimeout, most users will prefer to use ReadHeaderTimeout.
116    // It is valid to use them both.
117    // This fileid is used only for http server, not for http3 sever.
118    // Default is [30] seconds.
119    int64 ReadTimeout = 2 [json_name = "readTimeout"];
120
121    // [OPTIONAL]
122    // ReadHeaderTimeout is the amount of time allowed to read request headers.
123    // The connection's read deadline is reset after reading the headers.
124    // If ReadHeaderTimeout is zero, the value of ReadTimeout is used.
125    // If both are zero, there is no timeout.
126    // This fileid is used only for http server, not for http3 sever.
127    // Default is [30] seconds.
128    int64 ReadHeaderTimeout = 3 [json_name = "readHeaderTimeout"];
129
130    // [OPTIONAL]
131    // WriteTimeout is the maximum duration before timing out writes of the response.
132    // It is reset whenever a new request's header is read.
133    // Like ReadTimeout, this is not applied per-request basis.
134    // A zero or negative value means there will be no timeout.
135    // This fileid is used only for http server, not for http3 sever.
136    // Default is [30] seconds.
137    int64 WriteTimeout = 4 [json_name = "writeTimeout"];
138
139    // [OPTIONAL]
140    // WriteTimeout is the maximum duration before timing out writes of the response.
141    // It is reset whenever a new request's header is read.
142    // Like ReadTimeout, this is not applied per-request basis.
143    // A zero or negative value means there will be no timeout.
144    // This fileid is used only for http server, not for http3 sever.
145    // Default is [10] seconds.
146    int64 IdleTimeout = 5 [json_name = "idleTimeout"];
147
148    // [OPTIONAL]
149    // MaxHeaderBytes controls the maximum number of bytes the server will read
150    // parsing the request header's keys and values, including the request line.
151    // It does not limit the size of the request body.
152    // Default is [8192].
153    int32 MaxHeaderBytes = 6 [json_name = "maxHeaderBytes"];
154
155    // [OPTIONAL]
156    // DisableKeepAlive disables HTTP keep-alives.
157    // Only very resource-constrained environments or servers in the process of shutting down should disable them.
158    // This fileid is used only for http server, not for http3 sever.
159    // Default is [false].
160    bool DisableKeepAlive = 7 [json_name = "disableKeepAlive"];
161
162    // [OPTIONAL]
163    // ListenConfig is the config for TCP listener.
164    // Default values are used when this field is not used.
165    // TLSConfig in this field will be ignored.
166    // Network must be "tcp"
167    kernel.ListenConfig ListenConfig = 8 [json_name = "listenConfig"];
168
169    // [OPTIONAL]
170    // AltSvc is the Alt-Svc header value.
171    // Alt-Svc header won't be added to response headers if the value is empty
172    // Default is not set, or empty string [""].
173    string AltSvc = 9 [json_name = "altSvc"];
174
175    // [OPTIONAL]
176    // AllowHTTP2 allows HTTP/2 connection with default configuration
177    // using the given TLS configurations if any.
178    // Default is [false].
179    bool AllowHTTP2 = 10 [json_name = "allowHTTP2"];
180}
181
182// HTTP2Config is the configuration for HTTP2 servers.
183// Configuable fields are related to the HTTP2 server
184// found at https://pkg.go.dev/golang.org/x/net/http2#Server
185message HTTP2Config {
186    // [OPTIONAL]
187    // MaxConcurrentStreams optionally specifies the number of
188    // concurrent streams that each client may have open at a
189    // time. This is unrelated to the number of http.Handler goroutines
190    // which may be active globally, which is MaxHandlers.
191    // If zero, MaxConcurrentStreams defaults to at least 100, per
192    // the HTTP/2 spec's recommendations.
193    // Default is zero, [0].
194    uint32 MaxConcurrentStreams = 1 [json_name = "maxConcurrentStreams"];
195
196    // [OPTIONAL]
197    // MaxDecoderHeaderTableSize optionally specifies the http2
198    // SETTINGS_HEADER_TABLE_SIZE to send in the initial settings frame. It
199    // informs the remote endpoint of the maximum size of the header compression
200    // table used to decode header blocks, in octets. If zero, the default value
201    // of 4096 is used.
202    // Default is zero, [0].
203    uint32 MaxDecoderHeaderTableSize = 2 [json_name = "maxDecoderHeaderTableSize"];
204
205    // [OPTIONAL]
206    // MaxEncoderHeaderTableSize optionally specifies an upper limit for the
207    // header compression table used for encoding request headers. Received
208    // SETTINGS_HEADER_TABLE_SIZE settings are capped at this limit. If zero,
209    // the default value of 4096 is used.
210    // Default is zero, [0].
211    uint32 MaxEncoderHeaderTableSize = 3 [json_name = "maxEncoderHeaderTableSize"];
212
213    // [OPTIONAL]
214    // MaxReadFrameSize optionally specifies the largest frame
215    // this server is willing to read. A valid value is between
216    // 16k and 16M, inclusive. If zero or otherwise invalid, a
217    // default value is used.
218    // Default is zero, [0].
219    uint32 MaxReadFrameSize = 4 [json_name = "maxReadFrameSize"];
220
221    // [OPTIONAL]
222    // PermitProhibitedCipherSuites, if true, permits the use of
223    // cipher suites prohibited by the HTTP/2 spec.
224    // Default is [false].
225    bool PermitProhibitedCipherSuites = 5 [json_name = "permitProhibitedCipherSuites"];
226
227    // [OPTIONAL]
228    // IdleTimeout specifies how long until idle clients should be
229    // closed with a GOAWAY frame. PING frames are not considered
230    // activity for the purposes of IdleTimeout.
231    // If zero or negative, there is no timeout.
232    // Default is zero, [0].
233    uint32 IdleTimeout = 6 [json_name = "idleTimeout"];
234
235    // [OPTIONAL]
236    // MaxUploadBufferPerConnection is the size of the initial flow
237    // control window for each connections. The HTTP/2 spec does not
238    // allow this to be smaller than 65535 or larger than 2^32-1.
239    // If the value is outside this range, a default value will be
240    // used instead.
241    // Default is zero, [0].
242    int32 MaxUploadBufferPerConnection = 7 [json_name = "maxUploadBufferPerConnection"];
243
244    // [OPTIONAL]
245    // MaxUploadBufferPerStream is the size of the initial flow control
246    // window for each stream. The HTTP/2 spec does not allow this to
247    // be larger than 2^32-1. If the value is zero or larger than the
248    // maximum, a default value will be used instead.
249    // Default is zero, [0].
250    int32 MaxUploadBufferPerStream = 8 [json_name = "maxUploadBufferPerStream"];
251
252    // [OPTIONAL]
253    // EnableH2C is the flag to set h2c header.
254    // Default is [false].
255    bool EnableH2C = 9 [json_name = "enableH2C"];
256
257    // [OPTIONAL]
258    // AltSvc is the Alt-Svc header value.
259    // Alt-Svc header won't be added to
260    // response headers if the value is empty
261    // Default is not set, or empty string [""].
262    string AltSvc = 10 [json_name = "altSvc"];
263}
264
265// HTTP3Config is the configuration for HTTP3 servers.
266// Configuable fields are related to the HTTP3 server
267// found at https://pkg.go.dev/github.com/quic-go/quic-go/http3#Server
268message HTTP3Config {
269    // [OPTIONAL]
270    // QuicConfig is the configuration for quic protocol of http3 transport layer.
271    // Default values are used when this field is not specified.
272    // HTTP3 server is enabled when this field is set.
273    kernel.QuicConfig QuicConfig = 1 [json_name = "quicConfig"];
274
275    // [OPTIONAL]
276    // TLSConfig is the configuration for TLS connections.
277    // Default values are used when this field is not specified.
278    kernel.TLSConfig TLSConfig = 2 [json_name = "tlsConfig"];
279
280    // [OPTIONAL]
281    // MaxHeaderBytes controls the maximum number of bytes the server will read
282    // parsing the request header's keys and values, including the request line.
283    // It does not limit the size of the request body.
284    // Default is [8192].
285    int32 MaxHeaderBytes = 3 [json_name = "maxHeaderBytes"];
286
287    // [OPTIONAL]
288    // AltSvc is the Alt-Svc header value.
289    // Alt-Svc header won't be added to
290    // response headers if the value is empty
291    // Default is not set, or empty string [""].
292    string AltSvc = 4 [json_name = "altSvc"];
293}
294
295// VirtualHostSpec is the specification of each virtual hosts.
296message VirtualHostSpec {
297    // [OPTIONAL]
298    // Hosts is the list of hostname to accept. Vertual hostnames in other words.
299    // Because the Host headers of requests are used for routing, list all FQDN here including sub domains.
300    // All FQDN must be unique for among the server.
301    // When no hosts are set, handler are registered to the default mux.
302    // Default is not set.
303    repeated string Hosts = 1 [json_name = "hosts", (buf.validate.field).repeated.items.string.pattern = "^[0-9a-zA-Z.-]+$", (buf.validate.field).repeated.unique = true];
304
305    // [OPTIONAL]
306    // Pattern is the path pattern for this hosts.
307    // The specified pattern will be added as a prefix
308    // to the path patterns of all handlers.
309    // This pattern is joined with the registered handler.
310    // Default is not set, or empty string[""].
311    string Pattern = 2 [json_name = "pattern"];
312
313    // [OPTIONAL]
314    // Methods is the list of allowed HTTP methods to ba handled.
315    // This list will be whitelist of HTTP methods if set at least one.
316    // If not set, methods set at each handlers are used.
317    // Default is not set, or allow all.
318    repeated HTTPMethod Methods = 3 [json_name = "methods", (buf.validate.field).repeated.unique = true];
319
320    // [OPTIONAL]
321    // Middleware is the list of middleware applied for all handlers.
322    // Default is not set.
323    repeated kernel.Reference Middleware = 4 [json_name = "middleware"];
324
325    // [OPTIONAL]
326    // Handlers is the list of handler for this host.
327    // This is optional but specify at least 1 handler to serve some apis.
328    // Default is not set.
329    repeated core.v1.HTTPHandlerSpec Handlers = 5 [json_name = "handlers"];
330}