appium-mac2-driver 4.5.1 → 4.6.1

package/node_modules/morgan/README.md

@@ -0,0 +1,479 @@
+# morgan
+
+[![NPM Version][npm-version-image]][npm-url]
+[![NPM Downloads][npm-downloads-image]][npm-url]
+[![Build Status][ci-image]][ci-url]
+[![Coverage Status][coveralls-image]][coveralls-url]
+
+HTTP request logger middleware for node.js
+
+> Named after [Dexter](https://en.wikipedia.org/wiki/Dexter_Morgan), a show you should not watch until completion.
+
+## Installation
+
+This is a [Node.js](https://nodejs.org/en/) module available through the
+[npm registry](https://www.npmjs.com/). Installation is done using the
+[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
+
+```sh
+$ npm install morgan
+```
+
+## API
+
+For ES Modules:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+import morgan from 'morgan'
+```
+
+For CommonJS:
+
+<!-- eslint-disable no-unused-vars -->
+
+```js
+var morgan = require('morgan')
+```
+
+### morgan(format, options)
+
+Create a new morgan logger middleware function using the given `format` and `options`.
+The `format` argument may be a string of a predefined name (see below for the names),
+a string of a format string, or a function that will produce a log entry.
+
+The `format` function will be called with three arguments `tokens`, `req`, and `res`,
+where `tokens` is an object with all defined tokens, `req` is the HTTP request and `res`
+is the HTTP response. The function is expected to return a string that will be the log
+line, or `undefined` / `null` to skip logging.
+
+#### Using a predefined format string
+
+<!-- eslint-disable no-undef -->
+
+```js
+morgan('tiny')
+```
+
+#### Using format string of predefined tokens
+
+<!-- eslint-disable no-undef -->
+
+```js
+morgan(':method :url :status :res[content-length] - :response-time ms')
+```
+
+#### Using a custom format function
+
+<!-- eslint-disable no-undef -->
+
+``` js
+morgan(function (tokens, req, res) {
+  return [
+    tokens.method(req, res),
+    tokens.url(req, res),
+    tokens.status(req, res),
+    tokens.res(req, res, 'content-length'), '-',
+    tokens['response-time'](req, res), 'ms'
+  ].join(' ')
+})
+```
+
+#### Options
+
+Morgan accepts these properties in the options object.
+
+##### immediate
+
+Write log line on request instead of response. This means that requests will
+be logged even if the server crashes, _but data from the response (like the
+response code, content length, etc.) cannot be logged_.
+
+##### skip
+
+Function to determine if logging is skipped, defaults to `false`. This function
+will be called as `skip(req, res)`.
+
+<!-- eslint-disable no-undef -->
+
+```js
+// EXAMPLE: only log error responses
+morgan('combined', {
+  skip: function (req, res) { return res.statusCode < 400 }
+})
+```
+
+##### stream
+
+Output stream for writing log lines, defaults to `process.stdout`.
+
+If the stream is in object mode (`stream.writableObjectMode` is `true`) and the
+format function returns an object, the object is written to the stream as-is,
+without a trailing newline. This allows passing structured log entries to
+loggers that accept objects:
+
+<!-- eslint-disable no-undef -->
+
+```js
+morgan(function (tokens, req, res) {
+  return {
+    method: tokens.method(req, res),
+    url: tokens.url(req, res),
+    status: Number(tokens.status(req, res))
+  }
+}, {
+  stream: {
+    writableObjectMode: true,
+    write: function (entry) {
+      // entry is the object returned by the format function
+    }
+  }
+})
+```
+
+#### Predefined Formats
+
+There are various pre-defined formats provided:
+
+##### combined
+
+Standard Apache combined log output.
+```
+:remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length] ":referrer" ":user-agent"
+# will output
+::1 - - [27/Nov/2024:06:21:42 +0000] "GET /combined HTTP/1.1" 200 2 "-" "curl/8.7.1"
+```
+
+##### common
+
+Standard Apache common log output.
+
+```
+:remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]
+# will output
+::1 - - [27/Nov/2024:06:21:46 +0000] "GET /common HTTP/1.1" 200 2
+```
+
+##### dev
+
+Concise output colored by response status for development use. The `:status`
+token will be colored green for success codes, red for server error codes,
+yellow for client error codes, cyan for redirection codes, and uncolored
+for information codes.
+
+```
+:method :url :status :response-time ms - :res[content-length]
+# will output
+GET /dev 200 0.224 ms - 2
+```
+
+Coloring is disabled when the [`NO_COLOR`](https://no-color.org) environment
+variable is set to any non-empty value, in which case the output above is
+written without any escape sequences. The variable is read once, when `morgan`
+is first required.
+
+##### short
+
+Shorter than default, also including response time.
+
+```
+:remote-addr :remote-user :method :url HTTP/:http-version :status :res[content-length] - :response-time ms
+# will output
+::1 - GET /short HTTP/1.1 200 2 - 0.283 ms
+```
+
+##### tiny
+
+The minimal output.
+
+```
+:method :url :status :res[content-length] - :response-time ms
+# will output
+GET /tiny 200 2 - 0.188 ms
+```
+
+#### Tokens
+
+##### Creating new tokens
+
+To define a token, simply invoke `morgan.token()` with the name and a callback function.
+This callback function is expected to return a string value. The value returned is then
+available as ":type" in this case:
+
+<!-- eslint-disable no-undef -->
+
+```js
+morgan.token('type', function (req, res) { return req.headers['content-type'] })
+```
+
+Calling `morgan.token()` using the same name as an existing token will overwrite that
+token definition.
+
+The token function is expected to be called with the arguments `req` and `res`, representing
+the HTTP request and HTTP response. Additionally, the token can accept further arguments of
+its choosing to customize behavior.
+
+##### :date[format]
+
+The current date and time in UTC. The available formats are:
+
+  - `clf` for the common log format (`"10/Oct/2000:13:55:36 +0000"`)
+  - `iso` for the common ISO 8601 date time format (`2000-10-10T13:55:36.000Z`)
+  - `web` for the common RFC 1123 date time format (`Tue, 10 Oct 2000 13:55:36 GMT`)
+
+If no format is given, then the default is `web`.
+
+##### :http-version
+
+The HTTP version of the request.
+
+##### :method
+
+The HTTP method of the request.
+
+##### :pid
+
+The process ID of the Node.js process handling the request.
+
+##### :referrer
+
+The Referrer header of the request. This will use the standard mis-spelled Referer header if it exists, otherwise Referrer.
+
+##### :remote-addr
+
+The remote address of the request. This will use `req.ip`, otherwise the standard `req.connection.remoteAddress` value (socket address).
+
+##### :remote-user
+
+The user authenticated as part of Basic auth for the request.
+
+##### :req[header]
+
+The given `header` of the request. If the header is not present, the
+value will be displayed as `"-"` in the log.
+
+##### :res[header]
+
+The given `header` of the response. If the header is not present, the
+value will be displayed as `"-"` in the log.
+
+##### :response-time[digits]
+
+The time between the request coming into `morgan` and when the response
+headers are written, in milliseconds.
+
+The `digits` argument is a number that specifies the number of digits to
+include on the number, defaulting to `3`, which provides microsecond precision.
+
+##### :status
+
+The status code of the response.
+
+If the request/response cycle completes before a response was sent to the
+client (for example, the TCP socket closed prematurely by a client aborting
+the request), then the status will be empty (displayed as `"-"` in the log).
+
+##### :total-time[digits]
+
+The time between the request coming into `morgan` and when the response
+has finished being written out to the connection, in milliseconds.
+
+The `digits` argument is a number that specifies the number of digits to
+include on the number, defaulting to `3`, which provides microsecond precision.
+
+##### :url
+
+The URL of the request. This will use `req.originalUrl` if it exists, otherwise `req.url`.
+
+##### :user-agent
+
+The contents of the User-Agent header of the request.
+
+### morgan.compile(format)
+
+Compile a format string into a `format` function for use by `morgan`. A format string
+is a string that represents a single log line and can utilize token syntax.
+Tokens are referenced by `:token-name`. If tokens accept arguments, they can
+be passed using `[]`, for example: `:token-name[pretty]` would pass the string
+`'pretty'` as an argument to the token `token-name`.
+
+The function returned from `morgan.compile` takes three arguments `tokens`, `req`, and
+`res`, where `tokens` is an object with all defined tokens, `req` is the HTTP request and
+`res` is the HTTP response. The function will return a string that will be the log line,
+or `undefined` / `null` to skip logging.
+
+Normally formats are defined using `morgan.format(name, format)`, but for certain
+advanced uses, this compile function is directly available.
+
+## Examples
+
+### express/connect
+
+Sample app that will log all requests in the Apache combined format to STDOUT
+
+```js
+var express = require('express')
+var morgan = require('morgan')
+
+var app = express()
+
+app.use(morgan('combined'))
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+```
+
+### vanilla http server
+
+Sample app that will log all requests in the Apache combined format to STDOUT
+
+```js
+var finalhandler = require('finalhandler')
+var http = require('http')
+var morgan = require('morgan')
+
+// create "middleware"
+var logger = morgan('combined')
+
+http.createServer(function (req, res) {
+  var done = finalhandler(req, res)
+  logger(req, res, function (err) {
+    if (err) return done(err)
+
+    // respond to request
+    res.setHeader('content-type', 'text/plain')
+    res.end('hello, world!')
+  })
+})
+```
+
+### write logs to a file
+
+#### single file
+
+Sample app that will log all requests in the Apache combined format to the file
+`access.log`.
+
+```js
+var express = require('express')
+var fs = require('fs')
+var morgan = require('morgan')
+var path = require('path')
+
+var app = express()
+
+// create a write stream (in append mode)
+var accessLogStream = fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
+
+// setup the logger
+app.use(morgan('combined', { stream: accessLogStream }))
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+```
+
+#### log file rotation
+
+Sample app that will log all requests in the Apache combined format to one log
+file per day in the `log/` directory using the
+[rotating-file-stream module](https://www.npmjs.com/package/rotating-file-stream).
+
+```js
+var express = require('express')
+var morgan = require('morgan')
+var path = require('path')
+var rfs = require('rotating-file-stream') // version 2.x
+
+var app = express()
+
+// create a rotating write stream
+var accessLogStream = rfs.createStream('access.log', {
+  interval: '1d', // rotate daily
+  path: path.join(__dirname, 'log')
+})
+
+// setup the logger
+app.use(morgan('combined', { stream: accessLogStream }))
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+```
+
+### split / dual logging
+
+The `morgan` middleware can be used as many times as needed, enabling
+combinations like:
+
+  * Log entry on request and one on response
+  * Log all requests to file, but errors to console
+  * ... and more!
+
+Sample app that will log all requests to a file using Apache format, but
+error responses are logged to the console:
+
+```js
+var express = require('express')
+var fs = require('fs')
+var morgan = require('morgan')
+var path = require('path')
+
+var app = express()
+
+// log only 4xx and 5xx responses to console
+app.use(morgan('dev', {
+  skip: function (req, res) { return res.statusCode < 400 }
+}))
+
+// log all requests to access.log
+app.use(morgan('common', {
+  stream: fs.createWriteStream(path.join(__dirname, 'access.log'), { flags: 'a' })
+}))
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+```
+
+### use custom token formats
+
+Sample app that will use custom token formats. This adds an ID to all requests and displays it using the `:id` token.
+
+```js
+var express = require('express')
+var morgan = require('morgan')
+var uuid = require('uuid')
+
+morgan.token('id', function getId (req) {
+  return req.id
+})
+
+var app = express()
+
+app.use(assignId)
+app.use(morgan(':id :method :url :response-time'))
+
+app.get('/', function (req, res) {
+  res.send('hello, world!')
+})
+
+function assignId (req, res, next) {
+  req.id = uuid.v4()
+  next()
+}
+```
+
+## License
+
+[MIT](LICENSE)
+
+[ci-image]: https://badgen.net/github/checks/expressjs/morgan/master?label=ci
+[ci-url]: https://github.com/expressjs/morgan/actions/workflows/ci.yml
+[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/morgan/master
+[coveralls-url]: https://coveralls.io/r/expressjs/morgan?branch=master
+[npm-downloads-image]: https://badgen.net/npm/dm/morgan
+[npm-url]: https://npmjs.org/package/morgan
+[npm-version-image]: https://badgen.net/npm/v/morgan