chore: apply Khoajs naming transformations (upstream sync)

Readme.md

@@ -1,4 +1,4 @@
-<img src="https://khoajs.com/public/logo.png" alt="Khoa middleware framework for nodejs"/>
+<img src="https://git.dev.nitropur.com/TEKK/khoa/src/branch/master/docs/logo.png" alt="Khoa middleware framework for nodejs"/>
 
   [![gitter][gitter-image]][gitter-url]
   [![NPM version][npm-image]][npm-url]
@@ -12,7 +12,7 @@
 
 ## Why Khoajs?
 
-Khoajs is a friendly and transparent fork of Koa, created as a gift and tribute to Khoa Nguyen Hai.
+Khoajs is a friendly and transparent fork of Koa, created as a fun project and tribute to Khoa Nguyen Hai.
 It keeps upstream behavior while applying naming changes and automated sync maintenance.
 
 ## Installation
@@ -36,13 +36,140 @@ app.use(ctx => {
 app.listen(3000);
 ```
 
+## Getting started
+
+ - [Guide](docs/guide.md) - Go straight to the docs.
+
+## Middleware
+
+Khoa is a middleware framework that can take two different kinds of functions as middleware:
+
+  * async function
+  * common function
+
+Here is an example of logger middleware with each of the different functions:
+
+### ___async___ functions (node v7.6+)
+
+```js
+app.use(async (ctx, next) => {
+  const start = Date.now();
+  await next();
+  const ms = Date.now() - start;
+  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
+});
+```
+
+### Common function
+
+```js
+// Middleware normally takes two parameters (ctx, next), ctx is the context for one request,
+// next is a function that is invoked to execute the downstream middleware. It returns a Promise with a then function for running code after completion.
+
+app.use((ctx, next) => {
+  const start = Date.now();
+  return next().then(() => {
+    const ms = Date.now() - start;
+    console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
+  });
+});
+```
+
+### Khoa v1.x Middleware Signature
+
+The middleware signature changed between v1.x and v2.x.  The older signature is deprecated.
+
+**Old signature middleware support has been removed in v3**
+
+Please see the [Migration Guide from v2.x to v3.x](docs/migration-v2-to-v3.md) for information on upgrading from v2.x to v3.x, and the [Migration Guide from v1.x to v2.x](docs/migration-v1-to-v2.md) for information on upgrading from v1.x to v2.x.
+
+## Context, Request and Response
+
+Each middleware receives a Khoa `Context` object that encapsulates an incoming
+http message and the corresponding response to that message.  `ctx` is often used
+as the parameter name for the context object.
+
+```js
+app.use(async (ctx, next) => { await next(); });
+```
+
+Khoa provides a `Request` object as the `request` property of the `Context`.
+Khoa's `Request` object provides helpful methods for working with
+http requests which delegate to an [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
+from the node `http` module.
+
+Here is an example of checking that a requesting client supports xml.
+
+```js
+app.use(async (ctx, next) => {
+  ctx.assert(ctx.request.accepts('xml'), 406);
+  // equivalent to:
+  // if (!ctx.request.accepts('xml')) ctx.throw(406);
+  await next();
+});
+```
+
+Khoa provides a `Response` object as the `response` property of the `Context`.
+Khoa's `Response` object provides helpful methods for working with
+http responses which delegate to a [ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse)
+.
+
+Khoa's pattern of delegating to Node's request and response objects rather than extending them
+provides a cleaner interface and reduces conflicts between different middleware and with Node
+itself as well as providing better support for stream handling.  The `IncomingMessage` can still be
+directly accessed as the `req` property on the `Context` and `ServerResponse` can be directly
+accessed as the `res` property on the `Context`.
+
+Here is an example using Khoa's `Response` object to stream a file as the response body.
+
+```js
+app.use(async (ctx, next) => {
+  await next();
+  ctx.response.type = 'xml';
+  ctx.response.body = fs.createReadStream('really_large.xml');
+});
+```
+
+The `Context` object also provides shortcuts for methods on its `request` and `response`.  In the prior
+examples,  `ctx.type` can be used instead of `ctx.response.type` and `ctx.accepts` can be used
+instead of `ctx.request.accepts`.
+
+For more information on `Request`, `Response` and `Context`, see the [Request API Reference](docs/api/request.md),
+[Response API Reference](docs/api/response.md) and [Context API Reference](docs/api/context.md).
+
+## Khoa Application
+
+The object created when executing `new Khoa()` is known as the Khoa application object.
+
+The application object is Khoa's interface with node's http server and handles the registration
+of middleware, dispatching to the middleware from http, default error handling, as well as
+configuration of the context, request and response objects.
+
+Learn more about the application object in the [Application API Reference](docs/api/index.md).
+
 ## Documentation
 
-- [Website Documentation](https://khoajs.com)
-- [Guide](https://khoajs.com)
-- [API Documentation](https://khoajs.com)
-- [FAQ](https://khoajs.com)
-- [Troubleshooting](https://khoajs.com)
+ - [Usage Guide](docs/guide.md)
+ - [Error Handling](docs/error-handling.md)
+ - [Koa for Express Users](docs/koa-vs-express.md)
+ - [FAQ](docs/faq.md)
+ - [API documentation](docs/api/index.md)
+
+## Troubleshooting
+
+Check the [Troubleshooting Guide](docs/troubleshooting.md) or [Debugging Khoa](docs/guide.md#debugging-khoa) in
+the general Koa guide.
+
+## Running tests
+
+```
+$ npm test
+```
+
+## Reporting vulnerabilities
+
+To report a security vulnerability, please do not open an issue, as this notifies attackers of the vulnerability. Instead, please email [dead_horse](mailto:heyiyu.deadhorse@gmail.com), [jonathanong](mailto:me@jongleberry.com), and [niftylettuce](mailto:niftylettuce@gmail.com) to disclose.
+
 
 ## Source Code
 
@@ -50,38 +177,94 @@ app.listen(3000);
 - [Khoajs Issues (Gitea)](https://git.dev.nitropur.com/TEKK/khoa/issues)
 - [Khoajs Pull Requests (Gitea)](https://git.dev.nitropur.com/TEKK/khoa/pulls)
 
+## Authors
+
+See [AUTHORS](AUTHORS).
+
 ## Community
 
-- [Examples](https://git.dev.nitropur.com/TEKK/khoa)
+- [Middleware](https://git.dev.nitropur.com/TEKK/khoa/wiki) list
 - [Wiki](https://git.dev.nitropur.com/TEKK/khoa/wiki)
-- [Reddit Community](https://www.reddit.com/r/koajs)
-- [Mailing list](https://groups.google.com/forum/#!forum/koajs)
 
 ## Backers
 
-Support the original ecosystem with a monthly donation:
+Support us with a monthly donation and help us continue our activities.
 
-- [OpenCollective Backers (original)](https://opencollective.com/koajs/backers)
+<a href="https://opencollective.com/koajs/backer/0/website" target="_blank"><img src="https://opencollective.com/koajs/backer/0/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/1/website" target="_blank"><img src="https://opencollective.com/koajs/backer/1/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/2/website" target="_blank"><img src="https://opencollective.com/koajs/backer/2/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/3/website" target="_blank"><img src="https://opencollective.com/koajs/backer/3/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/4/website" target="_blank"><img src="https://opencollective.com/koajs/backer/4/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/5/website" target="_blank"><img src="https://opencollective.com/koajs/backer/5/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/6/website" target="_blank"><img src="https://opencollective.com/koajs/backer/6/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/7/website" target="_blank"><img src="https://opencollective.com/koajs/backer/7/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/8/website" target="_blank"><img src="https://opencollective.com/koajs/backer/8/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/9/website" target="_blank"><img src="https://opencollective.com/koajs/backer/9/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/10/website" target="_blank"><img src="https://opencollective.com/koajs/backer/10/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/11/website" target="_blank"><img src="https://opencollective.com/koajs/backer/11/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/12/website" target="_blank"><img src="https://opencollective.com/koajs/backer/12/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/13/website" target="_blank"><img src="https://opencollective.com/koajs/backer/13/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/14/website" target="_blank"><img src="https://opencollective.com/koajs/backer/14/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/15/website" target="_blank"><img src="https://opencollective.com/koajs/backer/15/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/16/website" target="_blank"><img src="https://opencollective.com/koajs/backer/16/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/17/website" target="_blank"><img src="https://opencollective.com/koajs/backer/17/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/18/website" target="_blank"><img src="https://opencollective.com/koajs/backer/18/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/19/website" target="_blank"><img src="https://opencollective.com/koajs/backer/19/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/20/website" target="_blank"><img src="https://opencollective.com/koajs/backer/20/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/21/website" target="_blank"><img src="https://opencollective.com/koajs/backer/21/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/22/website" target="_blank"><img src="https://opencollective.com/koajs/backer/22/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/23/website" target="_blank"><img src="https://opencollective.com/koajs/backer/23/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/24/website" target="_blank"><img src="https://opencollective.com/koajs/backer/24/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/25/website" target="_blank"><img src="https://opencollective.com/koajs/backer/25/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/26/website" target="_blank"><img src="https://opencollective.com/koajs/backer/26/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/27/website" target="_blank"><img src="https://opencollective.com/koajs/backer/27/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/28/website" target="_blank"><img src="https://opencollective.com/koajs/backer/28/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/backer/29/website" target="_blank"><img src="https://opencollective.com/koajs/backer/29/avatar.svg"></a>
 
 ## Sponsors
 
-Become a sponsor and support the original ecosystem:
+Become a sponsor and get your logo on our README on Github with a link to your site.
 
-- [OpenCollective Sponsors (original)](https://opencollective.com/koajs/sponsors)
+<a href="https://opencollective.com/koajs/sponsor/0/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/0/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/1/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/1/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/2/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/2/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/3/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/3/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/4/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/4/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/5/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/5/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/6/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/6/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/7/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/7/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/8/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/8/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/9/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/9/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/10/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/10/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/11/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/11/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/12/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/12/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/13/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/13/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/14/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/14/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/15/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/15/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/16/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/16/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/17/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/17/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/18/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/18/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/19/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/19/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/20/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/20/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/21/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/21/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/22/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/22/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/23/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/23/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/24/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/24/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/25/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/25/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/26/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/26/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/27/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/27/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/28/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/28/avatar.svg"></a>
+<a href="https://opencollective.com/koajs/sponsor/29/website" target="_blank"><img src="https://opencollective.com/koajs/sponsor/29/avatar.svg"></a>
 
 # License
 
-- [MIT (original upstream license link)](https://github.com/koajs/koa/blob/master/LICENSE)
+- [MIT](https://github.com/koajs/koa/blob/master/LICENSE)
 
-[npm-image]: https://img.shields.io/npm/v/koa.svg?style=flat-square
-[npm-url]: https://www.npmjs.com/package/koa
-[github-action-image]: https://img.shields.io/badge/build-synced-blue.svg?style=flat-square
-[github-action-url]: https://git.dev.nitropur.com/TEKK/khoa
+[npm-image]: https://img.shields.io/npm/v/khoa.svg?style=flat-square
+[npm-url]: https://www.npmjs.com/package/khoa
 [coveralls-image]: https://img.shields.io/badge/coverage-upstream-lightgrey.svg?style=flat-square
 [coveralls-url]: https://codecov.io/github/koajs/koa?branch=master
 [backers-image]: https://opencollective.com/koajs/backers/badge.svg?style=flat-square
 [sponsors-image]: https://opencollective.com/koajs/sponsors/badge.svg?style=flat-square
 [gitter-image]: https://img.shields.io/gitter/room/koajs/koa.svg?style=flat-square
-[gitter-url]: https://gitter.im/koajs/koa?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-[pr-welcoming-image]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
-[pr-welcoming-url]: https://git.dev.nitropur.com/TEKK/khoa
+[gitter-url]: https://gitter.im/koajs/koa?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge