-
Notifications
You must be signed in to change notification settings - Fork 0
stream
accepts all nodejs methods and the following:
stream doc will serve a document from the render folder
- this method will use cache if available
- this method will use compression if available
- this method will stream respond headers
- this method will send default headers from
config.render.headers
- this method will use etag settings from
config.render.etag
- this method will use cache settings from
config.render.cache
- this method will use gzip/brotli/deflate settings from
config.compression
/**
* stream.doc(path, contentType, callback)
* @param {string} path // file path relative to render dir
* @param {string} contentType // file content-type
* @param {function} callback ~ optional
**/
router.get('/', function(stream, headers, flags){
// send response headers and render static document from the render dir
stream.doc('index.html', 'text/html; charset=utf-8');
});
stream render will serve a rendered document from the render folder. refer to template engines.
- this method will use cache if available
- this method will use compression if available
- this method will stream respond headers
- this method will send default headers from
config.render.headers
- this method will use etag settings from
config.render.etag
- this method will use cache settings from
config.render.cache
- this method will use gzip/brotli/deflate settings from
config.compression
/**
* stream.render(path, obj, callback)
* @param {string} path // file path relative to render dir
* @param {object} obj // data for rendered file
* @param {function} callback ~ optional
**/
router.get('/', function(stream, headers, flags){
// basic ~ default: uses template literals in html documents
stream.render('index.html', {title: 'basic'})
// nunjucks ~ requires manual installation of nunjucks
stream.render('index.njk', {title: 'nunjucks'})
// pug ~ requires manual installation of pug
stream.render('index.pug', {title: 'pug'})
});
stream pushStatic will push a file or files from the static folder before requested.
- this method can be chained to push multiple files
- this method will use cache if available
- this method will use compression if available
- this method will send default headers from
config.static.headers
- this method will use etag settings from
config.static.etag
- this method will use cache settings from
config.static.cache
- this method will use gzip/brotli/deflate settings from
config.compression
-
config.verbose
will log the push state of a file - this method is asynchronous so the
stream
object is immediately returned - any errors are handled by sicarii in the same manner as the static file server
/**
* stream.pushStatic(path, ctype) // single file
* @param {string} path // file path relative to static dir as it would be requested as
* @param {string} ctype // file content type as it would be requested as
*
* stream.pushStatic(obj) // multiple files
* @param {object} obj // obj.path: file path, obj.ctype: content-type
**/
router.get('/', function(stream, headers, flags){
/* push files to the browser before the browser requests them */
// push a file before it has been requested
stream
.pushStatic('/css/main.css', 'text/css')
.status(200)
.doc('index.html', 'text/html')
// or push multiple files before they have been requested
stream
.pushStatic([{
path: '/css/main.css', // file path
ctype: 'text/css' // file content type
},{
path: '/favicon.ico',
ctype: 'image/x-icon'
}])
.status(200)
.render('index.html', {test: 'push'}, function(err){
if(err){return console.error(err)}
})
});
stream.download will initiate a file download upon browser navigation.
- stream.download uses
config.static
settings - this method will use cache if available
- this method will use compression if available
- this method will stream respond headers
- this method will send default headers from
config.static.headers
- this method will use etag settings from
config.static.etag
- this method will use cache settings from
config.static.cache
- this method will use gzip/brotli/deflate settings from
config.compression
- this method will Content-Disposition 'attachment; filename="the files name"' to the headers;
/**
* stream.download(path, contentType, callback)
* @param {string} path // file path relative to static dir
* @param {string} contentType // file content-type
* @param {function} callback ~ optional
**/
router.get('/downloadpath', function(stream, headers, flags){
// main.mjs will download when /downloadpath is navigated to in the browser
stream.download('modules/main.mjs', 'application/javascript');
});
stream.upload will upload a file to your uploads dir if enabled at config.uploads.enable
-
config.uploads.gzip
will enable/disable gzip compression for uploads -
config.uploads.brotli
will enable/disable brotli compression for uploads -
config.uploads.deflate
will enable/disable deflate compression for uploads -
config.uploads.path
is your upload path relative to cwd() -
config.uploads.recursive
will enable recursive dir creation withinconfig.uploads.path
, -
config.uploads.mimetypes
should list all accepted upload mimetypes in the same format asconfig.mimetypes
-
config.uploads.max_filename
max filename length -
config.uploads.max_filesize
max content length
simple upload example:
/**
* stream.upload(settings, callback)
* @param {object} settings // upload settings
* @param {function} callback ~ function(err,res) | optional
**/
router.post('/upload', function(stream, headers, flags){
let ctype = headers.get('content-type');
if(ctype !== 'application/json'){
// do something
}
try {
let body = JSON.stringify(stream.body.json);
let upload_data = {
path: '/test/index.json', // path relative to uploads dir
ctype: ctype, // content type
data: body, // data as string
brotli: true, //override default brotli setting config.uploads.brotli ~ optional
gzip: false //override default gzip setting config.uploads.gzip ~ optional
//deflate: false //override default deflate setting config.uploads.deflate ~ optional
}
stream.upload(upload_data, function(err,res){
if(err){
// do something
return;
}
stream.json({upload: 'success'})
})
} catch (err) {
// do something
}
});
stream.json() performs the following actions:
- add content-type 'application/json' to the headers;
- stream the headers object.
- send stringified json
/**
* stream.json(obj, contentType, callback)
* @param {array/object} obj // data to be stringified
* @param {function} callback ~ optional
**/
router.get('/', function(stream, headers, flags){
stream.json({send: 'json'})
});
stream.redirect() performs the following actions:
- add location destination to the headers;
- stream the headers object.
- send redirect
/**
* stream.redirect(path)
* @param {string} path // redirect anywhere path
**/
router.get('/', function(stream, headers, flags){
//redirect to url
stream.redirect('/test')
});
stream.ip returns the client ip address
- enable config.proxy to return ['x-forwarded-for'] ip
router.get('/', function(stream, headers, flags){
console.log(stream.ip)
// xxx.xxx.x.x.x
});
stream.headers will return an object containing all current and default outbound headers;
this is not to be mistaken with the received headers
object;
router.get('/', function(stream, headers, flags){
//log default received headers to console
console.log(headers.all())
//log default outbound headers to console
console.log(stream.headers)
// add outbound header
stream.addHeader('Content-Type', 'text/plain');
stream.respond(stream.headers);
stream.end('headers sent')
})
stream.addHeader(key,val) will add a header to stream.headers
/**
* stream.addHeader(key, val)
* @param {string} key // header type
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound header
stream.addHeader('Content-Type','text/plain');
//stream.headers['Content-Type'] = 'text/plain';
stream.respond(stream.headers);
stream.end('headers sent')
})
stream.addHeaders(obj) will assign an object of headers to stream.headers
/**
* stream.addHeaders(key, val)
* @param {object} obj // headers object
**/
router.get('/', function(stream, headers, flags){
// add outbound header
stream.addHeaders({
'content-type':'text/plain',
'content-encoding': 'gzip'
});
stream.respond(stream.headers);
stream.end('headers sent')
})
stream.cors() will add the included cors options to stream.headers
- this method will override any default cors headers in
config.render.headers
||config.static.headers
- this method will fallback to
config.cors
if no object is provided
/**
* stream.cors(obj)
* @param {object} obj // optional | cors entries || fallback to config.cors
**/
router.get('/', function(stream, headers, flags){
// add all outbound cors headers
stream.cors({
origin: '', // string | Access-Control-Allow-Origin
methods: '', // string | Access-Control-Allow-Methods
allow_headers: '', // string | Access-Control-Allow-Headers
expose_headers: '',// string | Access-Control-Expose-Headers
credentials: true, // boolean | Access-Control-Allow-Credentials
maxage: 9999 // number | Access-Control-Max-Age
});
// or only some
stream.cors({
origin: '',
methods: '',
allow_headers: ''
});
// or use config.cors
stream.cors();
stream.respond(stream.headers)
stream.end('text')
})
stream.ctype(val) will add the Content-Type header to stream.headers
/**
* stream.ctype(val)
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound Content-Type header
stream.ctype('text/plain');
stream.respond(stream.headers)
stream.end('text')
})
stream.lang(val) will add the Content-Language header to stream.headers
/**
* stream.lang(val)
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound Content-Language header
stream.lang('en-US');
stream.respond(stream.headers)
stream.end('text')
})
stream.tk(val) will add the TK header to stream.headers
/**
* stream.tk(val)
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
/*
Tk: ! (under construction)
Tk: ? (dynamic)
Tk: G (gateway or multiple parties)
Tk: N (not tracking)
Tk: T (tracking)
Tk: C (tracking with consent)
Tk: P (potential consent)
Tk: D (disregarding DNT)
Tk: U (updated)
*/
// add outbound TK header
stream.tk('N');
stream.respond(stream.headers)
stream.end('text')
})
stream.csp(val) will add the Content-Security-Policy header to stream.headers
- stream.csp will load the csp from
config.csp
; - this method enables you to store and use multiple pre-defined content security policies
/**
* stream.csp(val)
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound Content-Security-Policy header from `config.csp.default`
stream.csp('default');
stream.respond(stream.headers)
stream.end('text')
})
stream.feature(val) will add the Feature-Policy header to stream.headers
- stream.feature will load the Feature-Policy from
config.feature_policy
; - this method enables you to store and use multiple pre-defined feature policies
/**
* stream.feature(val)
* @param {string} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound Feature-Policy header from `config.feature_policy.default`
stream.feature('default');
stream.respond(stream.headers)
stream.end('text')
})
stream.status(val) will set the :status header to stream.headers
/**
* stream.status(val)
* @param {number} val // header value
**/
router.get('/', function(stream, headers, flags){
// add outbound :status header
stream.status(200).ctype('text/plain').respond(stream.headers);
stream.end('text')
})
stream.query is part of body parser
. if enabled, it will parse the given query to json.
refer to body parses section.
-
config.stream.method_query
controls the accepted router methods. -
config.stream.content_types
controls the accepted content types.
router.get('/test', function(stream, headers, flags){
let query = stream.query;
console.log(query)
});
stream.qs is similar to stream.query
but returns the unparsed querystring.
This method is intended for use with custom or complex querystrings;
-
config.stream.querystring
enable/disable - the returned querystring is decoded with decodeURIComponent()
router.get('/test', function(stream, headers, flags){
let customquery = stream.qs;
console.log(customquery)
});
stream.body.text is the default body parse format
- returns
string
router.post('/', function(stream, headers, flags){
let body = stream.body.text;
console.log(body)
});
stream.body.buffer is part of body parser
.
- returns
buffer
router.post('/', function(stream, headers, flags){
let buff = stream.body.buffer;
console.log(buff)
});
stream.body.buffer is part of body parser
.
refer to body parses section.
- returns
json
for supported content-types
router.post('/', function(stream, headers, flags){
let obj = stream.body.json;
console.log(obj)
});
this method is a part of cookie parser refer to cookie parser
stream.cookie will enable you to easily access all cookies in headers
- this method automatically deserializes all cookies.
- this method requires
config.cookie_parser.enabled
to be enabled - this method can be enabled/disabled at
config.cookie_parser.auto_parse
router.get('/', function(stream, headers, flags){
// return cookies object ~ config.cookie_parser.auto_parse
console.log(stream.cookies)
})
this method is a part of cookie parser refer to cookie parser
stream.cookie(name,val,obj) will enable you to easily add cookies to the stream.response
- this method automatically adds the created cookie to
stream.headers
- this method can be enabled/disabled at
config.cookie_parser.enabled
- this method can create a separate signed cookie for tamper detection
-
config.cookie_parser.sig.secret
is used to hmac the cookie -
config.cookie_parser.sig.suffix
is the signed cookies suffix - a signed cookie will be will use digest/encode settings from
config.crypt.hmac
/**
* stream.cookie(key, val, settings)
* @param {string} key // cookie name
* @param {string} val // cookie value
* @param {object} settings // cookie settings
**/
router.get('/', function(stream, headers, flags){
//create cookie and add to outbouheaders ~ config.cookie_parser.enabled
stream.cookie('name', 'value',{
Domain: 'localhost',
Path: '/',
Expires: Date.now(),
MaxAge: 9999,
HttpOnly: true,
SameSite: 'Lax',
Secure: true,
Priority: 'High',
Signed: true // creates a separate suffixed signed cookie for validation
})
stream.respond(stream.headers);
stream.end()
})