HTTP server

Register name used to load filter: httpout
This filter may be automatically loaded during graph resolution.

The HTTP output filter can act as:

• a simple HTTP server
• an HTTP server sink
• an HTTP server file sink
• an HTTP client sink
• an HTTP server source

The server currently handles GET, HEAD, PUT, POST, DELETE methods, and basic OPTIONS support.
Single or multiple byte ranges are supported for both GET and PUT/POST methods, in all server modes.

• for GET, the resulting body is a single-part body formed by the concatenated byte ranges as requested (no overlap checking).
• for PUT/POST, the received data is pushed to the target file according to the byte ranges specified in the client request.

Warning: the partial PUT request is RFC2616 compliant but not compliant with RFC7230. PATCH method is not yet implemented in GPAC.

When a single read directory is specified, the server root / is the content of this directory.
When multiple read directories are specified, the server root / contains the list of the mount points with their directory names.
When a write directory is specified, the upload resource name identifies a file in this directory (the write directory name is not present in the URL).

A directory rule file (cf gpac -h creds) can be specified in rdirs but NOT in wdir. When rules are used:

• if a directory has a name rule, it will be used in the URL
• otherwise, the directory is directly available under server root /
• read and write access rights are checked

Example

[foodir]  
name=bar

Content RES of this directory is exposed as http://SERVER/bar/RES.

To authenticate services handled by bindings, use a non-existing directory and a name describing the authentication.
Example

[NonExistingDir]  
name=service_root

Requests in the form http://SERVER/service_root/* will be authenticated by this rule.

Listing can be enabled on server using dlist.
When disabled, a GET on a directory will fail.
When enabled, a GET on a directory will return a simple HTML listing of the content inspired from Apache.

Custom headers can be specified using hdrs, they apply to all requests. For more advanced control on requests, use a javascript binding (see js and howtos).

Text files are compressed using gzip or deflate if the client accepts these encodings, unless zmax is set to 0.

Simple HTTP server

In this mode, the filter does not need any input connection and exposes all files in the directories given by rdirs.
PUT and POST methods are only supported if a write directory is specified by wdir option.
Example

gpac httpout:rdirs=outcoming

This sets up a read-only server.

Example

gpac httpout:wdir=incoming

This sets up a write-only server.

Example

gpac httpout:rdirs=outcoming:wdir=incoming:port=8080

This sets up a read-write server running on port 8080.

HTTP server sink

In this mode, the filter will forward input PIDs to connected clients, trashing the data if no client is connected unless hold is specified.
The filter does not use any read directory in this mode.
This mode is mostly useful to setup live HTTP streaming of media sessions such as MP3, MPEG-2 TS or other multiplexed representations:

gpac -i MP3_SOURCE -o http://localhost/live.mp3 --hold

In this example, the server waits for client requests on /live.mp3 and will then push each input packet to all connected clients.
If the source is not real-time, you can inject a reframer filter performing realtime regulation.
Example

gpac -i MP3_SOURCE reframer:rt=on -o http://localhost/live.mp3

In this example, the server will push each input packet to all connected clients, or trash the packet if no connected clients.

In this mode, ICECast meta-data can be inserted using ice. The default inserted values are ice-audio-info, icy-br, icy-pub (set to 1) and icy-name if input ServiceName property is set.
The server will also look for any property called ice-* on the input PID and inject them.
Example

gpac -i source.mp3:#ice-Genre=CoolRock -o http://IP/live.mp3 --ice

This will inject the header ice-Genre: CoolRock in the response.
Once one complete input file is sent, it is no longer available for download unless reopen is set and input PID is not over.

This mode should not be used with multiple files muxers such as DASH or HLS.

HTTP server file sink

In this mode, the filter will write input PIDs to files in the first read directory specified, acting as a file output sink.
The filter uses a read directory in this mode, which must be writable.
Upon client GET request, the server will check if the requested URL matches the name of a file currently being written by the server.

• If so, the server will:

  • send the content using HTTP chunk transfer mode, starting with what is already written on disk
  • push remaining data to the client as soon as received while writing it to disk, until source file is done

• If not so, the server will simply send the file from the disk as a regular HTTP session, without chunk transfer.

This mode is typically used for origin server in HAS sessions where clients may request files while they are being produced (low latency DASH).
Example

gpac -i SOURCE reframer:rt=on -o http://localhost:8080/live.mpd --rdirs=temp --dmode=dynamic --cdur=0.1

In this example, a real-time dynamic DASH session with chunks of 100ms is created, writing files to temp. A client connecting to the live edge will receive segments as they are produced using HTTP chunk transfer.

The server can store incoming files to memory mode by setting the read directory to gmem.
In this mode, max_cache_segs is always at least 1.

If max_cache_segs value N is not 0, each incoming PID will store at most:

• MIN(N, time-shift depth) files if stored in memory
• -N files if stored locally and N is negative
• MAX(N, time-shift depth) files if stored locally and N is positive
• unlimited otherwise (files stored locally, N is positive and no time-shift info)

HTTP client sink

In this mode, the filter will upload input PIDs data to remote server using PUT (or POST if post is set).
This mode must be explicitly activated using hmode.
The filter uses no read or write directories in this mode.
Example

gpac -i SOURCE -o http://targethost:8080/live.mpd:gpac:hmode=push

In this example, the filter will send PUT methods to the server running on port 8080 at targethost location (IP address or name).

HTTP server source

In this mode, the server acts as a source rather than a sink. It declares incoming PUT or POST methods as output PIDs
This mode must be explicitly activated using hmode.
The filter uses no read or write directories in this mode, and uploaded data is NOT stored by the server.
Example

gpac httpout:hmode=source vout aout

In this example, the filter will try to play uploaded files through video and audio output.

HTTPS server

The server can run over TLS (https) for all the server modes. TLS is enabled by specifying cert and pkey options.
Both certificate and key must be in PEM format.
The server currently only operates in either HTTPS or HTTP mode and cannot run both modes at the same time. You will need to use two httpout filters for this, one operating in HTTPS and one operating in HTTP.

Multiple destinations on single server

When running in server mode, multiple HTTP outputs with same URL/port may be used:

• the first loaded HTTP output filter with same URL/port will be reused
• all httpout options of subsequent httpout filters, except dst will be ignored, other options will be inherited as usual

Example

gpac -i dash.mpd dashin:forward=file:FID=D1 dashin:forward=segb:FID=D2 -o http://localhost:80/live.mpd:SID=D1:rdirs=dash -o http://localhost:80/live_rw.mpd:SID=D2:sigfrag

This will:

• load the HTTP server and forward (through D1) the dash session to this server using live.mpd as manifest name
• reuse the HTTP server and regenerate the manifest (through D2 and sigfrag option), using live_rw.mpd as manifest name

Options

dst (cstr): location of destination resource

port (uintl, default: 0): server port

ifce (str): default network interface to use

rdirs (strl): list of directories to expose for read

wdir (str): directory to expose for write

cert (str): certificate file in PEM format to use for TLS mode

pkey (str): private key file in PEM format to use for TLS mode

block_size (uint, default: 10000): block size used to read and write TCP socket

user_agent (str, default: $GUA): user agent string, by default solved from GPAC preferences

close (bool, default: false): close HTTP connection after each request

maxc (uint, default: 100): maximum number of connections, 0 is unlimited

maxp (uint, default: 6): maximum number of connections for one peer (0 is unlimited)

cache_control (str): specify the Cache-Control string to add (none disable cache control and ETag)

hold (bool, default: false): hold packets until one client connects

hmode (enum, default: default): filter operation mode, ignored if wdir is set

• default: run in server mode
• push: run in client mode using PUT or POST
• source: use server as source filter on incoming PUT/POST

timeout (uint, default: 30): timeout in seconds for persistent connections (0 disable timeout)

ext (cstr): set extension for graph resolution, regardless of file extension

mime (cstr): set mime type for graph resolution

quit (bool, default: false): exit server once all input PIDs are done and client disconnects (for test purposes)

post (bool, default: false): use POST instead of PUT for uploading files

dlist (bool, default: false): enable HTML listing for GET requests on directories

sutc (bool, default: false): insert server UTC in response headers as Server-UTC: VAL_IN_MS

cors (enum, default: auto): insert CORS header allowing all domains

• off: disable CORS
• on: enable CORS
• auto: enable CORS when Origin is found in request

reqlog (str): provide short log of the requests indicated in this option (comma separated list, * for all) regardless of HTTP log settings. Value REC logs file writing start/end. If prefix - is set, do not log request end

ice (bool, default: false): insert ICE meta-data in response headers in sink mode

max_client_errors (uint, default: 20): force disconnection after specified number of consecutive errors from HTTTP 1.1 client (ignored in H/2 or when close is set)

max_cache_segs (sint, default: 5): maximum number of segments cached per HAS quality (see filter help)

reopen (bool, default: false): in server mode with no read dir, accept requests on files already over but with input pid not in end of stream

max_async_buf (uint, default: 100000): maximum async buffer size in bytes when sharing output over multiple connection without file IO

blockio (bool, default: false): use blocking IO in push or source mode or in server mode with no read dir

ka (bool, default: true): keep input alive if failure in push mode

hdrs (strl): additional HTTP headers to inject, even values are names, odd values are values

js (str): javascript logic for server

zmax (uint, default: 50000): maximum uncompressed size allowed for gzip or deflate compression for text files (only enabled if client indicates it), 0 will disable compression

cte (bool, default: true): use chunked transfer-encoding mode when possible

maxs (uint, default: 50M): maximum upload size allowed in bytes

norange (bool, default: false): disable byte range support in GET (reply 200 on partial requests)