diff --git a/.eslintrc.yml b/.eslintrc.yml index 5b11e9fd84..587169c533 100644 --- a/.eslintrc.yml +++ b/.eslintrc.yml @@ -3,6 +3,6 @@ root: true rules: eol-last: error eqeqeq: [error, allow-null] - indent: [error, 2, { SwitchCase: 1 }] + indent: [error, 2, { MemberExpression: "off", SwitchCase: 1 }] no-trailing-spaces: error no-unused-vars: [error, { vars: all, args: none, ignoreRestSiblings: true }] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000000..cd93ab223d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,179 @@ +name: ci + +on: +- pull_request +- push + +jobs: + test: + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + name: + - Node.js 0.10 + - Node.js 0.12 + - io.js 1.x + - io.js 2.x + - io.js 3.x + - Node.js 4.x + - Node.js 5.x + - Node.js 6.x + - Node.js 7.x + - Node.js 8.x + - Node.js 9.x + - Node.js 10.x + - Node.js 11.x + - Node.js 12.x + - Node.js 13.x + - Node.js 14.x + - Node.js 15.x + - Node.js 16.x + - Node.js 17.x + - Node.js 18.x + + include: + - name: Node.js 0.10 + node-version: "0.10" + npm-i: mocha@3.5.3 nyc@10.3.2 supertest@2.0.0 + + - name: Node.js 0.12 + node-version: "0.12" + npm-i: mocha@3.5.3 nyc@10.3.2 supertest@2.0.0 + + - name: io.js 1.x + node-version: "1.8" + npm-i: mocha@3.5.3 nyc@10.3.2 supertest@2.0.0 + + - name: io.js 2.x + node-version: "2.5" + npm-i: mocha@3.5.3 nyc@10.3.2 supertest@2.0.0 + + - name: io.js 3.x + node-version: "3.3" + npm-i: mocha@3.5.3 nyc@10.3.2 supertest@2.0.0 + + - name: Node.js 4.x + node-version: "4.9" + npm-i: mocha@5.2.0 nyc@11.9.0 supertest@3.4.2 + + - name: Node.js 5.x + node-version: "5.12" + npm-i: mocha@5.2.0 nyc@11.9.0 supertest@3.4.2 + + - name: Node.js 6.x + node-version: "6.17" + npm-i: mocha@6.2.2 nyc@14.1.1 supertest@3.4.2 + + - name: Node.js 7.x + node-version: "7.10" + npm-i: mocha@6.2.2 nyc@14.1.1 supertest@6.1.6 + + - name: Node.js 8.x + node-version: "8.17" + npm-i: mocha@7.2.0 + + - name: Node.js 9.x + node-version: "9.11" + npm-i: mocha@7.2.0 + + - name: Node.js 10.x + node-version: "10.24" + npm-i: mocha@8.4.0 + + - name: Node.js 11.x + node-version: "11.15" + npm-i: mocha@8.4.0 + + - name: Node.js 12.x + node-version: "12.22" + npm-i: mocha@9.2.2 + + - name: Node.js 13.x + node-version: "13.14" + npm-i: mocha@9.2.2 + + - name: Node.js 14.x + node-version: "14.20" + + - name: Node.js 15.x + node-version: "15.14" + + - name: Node.js 16.x + node-version: "16.17" + + - name: Node.js 17.x + node-version: "17.9" + + - name: Node.js 18.x + node-version: "18.10" + + steps: + - uses: actions/checkout@v2 + + - name: Install Node.js ${{ matrix.node-version }} + shell: bash -eo pipefail -l {0} + run: | + nvm install --default ${{ matrix.node-version }} + dirname "$(nvm which ${{ matrix.node-version }})" >> "$GITHUB_PATH" + + - name: Configure npm + run: | + npm config set loglevel error + npm config set shrinkwrap false + + - name: Install npm module(s) ${{ matrix.npm-i }} + run: npm install --save-dev ${{ matrix.npm-i }} + if: matrix.npm-i != '' + + - name: Remove non-test dependencies + run: npm rm --silent --save-dev connect-redis + + - name: Setup Node.js version-specific dependencies + shell: bash + run: | + # eslint for linting + # - remove on Node.js < 12 + if [[ "$(cut -d. -f1 <<< "${{ matrix.node-version }}")" -lt 12 ]]; then + node -pe 'Object.keys(require("./package").devDependencies).join("\n")' | \ + grep -E '^eslint(-|$)' | \ + sort -r | \ + xargs -n1 npm rm --silent --save-dev + fi + + - name: Install Node.js dependencies + run: npm install + + - name: List environment + id: list_env + shell: bash + run: | + echo "node@$(node -v)" + echo "npm@$(npm -v)" + npm -s ls ||: + (npm -s ls --depth=0 ||:) | awk -F'[ @]' 'NR>1 && $2 { print "::set-output name=" $2 "::" $3 }' + + - name: Run tests + shell: bash + run: npm run test-ci + + - name: Lint code + if: steps.list_env.outputs.eslint != '' + run: npm run lint + + - name: Collect code coverage + uses: coverallsapp/github-action@master + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + flag-name: run-${{ matrix.test_number }} + parallel: true + + coverage: + needs: test + runs-on: ubuntu-latest + steps: + - name: Upload code coverage + uses: coverallsapp/github-action@master + with: + github-token: ${{ secrets.github_token }} + parallel-finished: true diff --git a/.gitignore b/.gitignore index 5fee6a2dc9..3a673d9cc0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,27 +1,15 @@ -# OS X -.DS_Store* -Icon? -._* - -# Windows -Thumbs.db -ehthumbs.db -Desktop.ini - -# Linux -.directory -*~ - - # npm node_modules package-lock.json *.log *.gz - # Coveralls +.nyc_output coverage # Benchmarking benchmarks/graphs + +# ignore additional files using core.excludesFile +# https://git-scm.com/docs/gitignore diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index c3ebc583d6..0000000000 --- a/.travis.yml +++ /dev/null @@ -1,66 +0,0 @@ -language: node_js -node_js: - - "0.10" - - "0.12" - - "1.8" - - "2.5" - - "3.3" - - "4.9" - - "5.12" - - "6.17" - - "7.10" - - "8.16" - - "9.11" - - "10.15" - - "11.15" - - "12.3" -matrix: - include: - - node_js: "13" - env: "NVM_NODEJS_ORG_MIRROR=https://nodejs.org/download/nightly" - allow_failures: - # Allow the nightly installs to fail - - env: "NVM_NODEJS_ORG_MIRROR=https://nodejs.org/download/nightly" -sudo: false -cache: - directories: - - node_modules -before_install: - # Configure npm - - | - # Skip updating shrinkwrap / lock - npm config set shrinkwrap false - # Remove all non-test dependencies - - | - # Remove example dependencies - npm rm --silent --save-dev connect-redis - # Setup Node.js version-specific dependencies - - | - # mocha for testing - # - use 3.x for Node.js < 6 - if [[ "$(cut -d. -f1 <<< "$TRAVIS_NODE_VERSION")" -lt 6 ]]; then - npm install --silent --save-dev mocha@3.5.3 - fi - - | - # supertest for http calls - # - use 2.0.0 for Node.js < 4 - if [[ "$(cut -d. -f1 <<< "$TRAVIS_NODE_VERSION")" -lt 4 ]]; then - npm install --silent --save-dev supertest@2.0.0 - fi - # Update Node.js modules - - | - # Prune and rebuild node_modules - if [[ -d node_modules ]]; then - npm prune - npm rebuild - fi -script: - # Run test script - - npm run test-ci - # Run linting - - npm run lint -after_script: - - | - # Upload coverage to coveralls - npm install --save-dev coveralls@2.12.0 - coveralls < ./coverage/lcov.info diff --git a/Charter.md b/Charter.md new file mode 100644 index 0000000000..a906e52909 --- /dev/null +++ b/Charter.md @@ -0,0 +1,92 @@ +# Express Charter + +## Section 0: Guiding Principles + +The Express project is part of the OpenJS Foundation which operates +transparently, openly, collaboratively, and ethically. +Project proposals, timelines, and status must not merely be open, but +also easily visible to outsiders. + +## Section 1: Scope + +Express is a HTTP web server framework with a simple and expressive API +which is highly aligned with Node.js core. We aim to be the best in +class for writing performant, spec compliant, and powerful web servers +in Node.js. As one of the oldest and most popular web frameworks in +the ecosystem, we have an important place for new users and experts +alike. + +### 1.1: In-scope + +Express is made of many modules spread between three GitHub Orgs: + +- [expressjs](http://github.com/expressjs/): Top level middleware and + libraries +- [pillarjs](http://github.com/pillarjs/): Components which make up + Express but can also be used for other web frameworks +- [jshttp](http://github.com/jshttp/): Low level HTTP libraries + +### 1.2: Out-of-Scope + +Section Intentionally Left Blank + +## Section 2: Relationship with OpenJS Foundation CPC. + +Technical leadership for the projects within the OpenJS Foundation is +delegated to the projects through their project charters by the OpenJS +Cross Project Council (CPC). In the case of the Express project, it is +delegated to the Express Technical Committee ("TC"). + +This Technical Committee is in charge of both the day-to-day operations +of the project, as well as its technical management. This charter can +be amended by the TC requiring at least two approvals and a minimum two +week comment period for other TC members or CPC members to object. Any +changes the CPC wishes to propose will be considered a priority but +will follow the same process. + +### 2.1 Other Formal Project Relationships + +Section Intentionally Left Blank + +## Section 3: Express Governing Body + +The Express project is managed by the Technical Committee ("TC"). +Members can be added to the TC at any time. Any committer can nominate +another committer to the TC and the TC uses its standard consensus +seeking process to evaluate whether or not to add this new member. +Members who do not participate consistently at the level of a majority +of the other members are expected to resign. + +## Section 4: Roles & Responsibilities + +The Express TC manages all aspects of both the technical and community +parts of the project. Members of the TC should attend the regular +meetings when possible, and be available for discussion of time +sensitive or important issues. + +### Section 4.1 Project Operations & Management + +Section Intentionally Left Blank + +### Section 4.2: Decision-making, Voting, and/or Elections + +The Express TC uses a "consensus seeking" process for issues that are +escalated to the TC. The group tries to find a resolution that has no +open objections among TC members. If a consensus cannot be reached +that has no objections then a majority wins vote is called. It is also +expected that the majority of decisions made by the TC are via a +consensus seeking process and that voting is only used as a last-resort. + +Resolution may involve returning the issue to committers with +suggestions on how to move forward towards a consensus. It is not +expected that a meeting of the TC will resolve all issues on its +agenda during that meeting and may prefer to continue the discussion +happening among the committers. + +### Section 4.3: Other Project Roles + +Section Intentionally Left Blank + +## Section 5: Definitions + +Section Intentionally Left Blank diff --git a/Code-Of-Conduct.md b/Code-Of-Conduct.md new file mode 100644 index 0000000000..bbb8996a65 --- /dev/null +++ b/Code-Of-Conduct.md @@ -0,0 +1,139 @@ +# Contributor Covenant Code of Conduct + +As a member of the Open JS Foundation, Express has adopted the +[Contributor Covenant 2.0][cc-20-doc]. + +If an issue arises and you cannot resolve it directly with the parties +involved, you can report it to the Express project TC through the following +email: express-coc@lists.openjsf.org + +In addition, the OpenJS Foundation maintains a Code of Conduct Panel (CoCP). +This is a foundation-wide team established to manage escalation when a reporter +believes that a report to a member project or the CPC has not been properly +handled. In order to escalate to the CoCP send an email to +coc-escalation@lists.openjsf.org. + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances + of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for +moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail +address, posting via an official social media account, or acting as an +appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +express-coc@lists.openjsf.org. All complaints will be reviewed and +investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during this +period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +project community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant, version 2.0](cc-20-doc). + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). + +[cc-20-doc]: https://www.contributor-covenant.org/version/2/0/code_of_conduct/ + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/Collaborator-Guide.md b/Collaborator-Guide.md index 75d4e7c8f2..3c73307d61 100644 --- a/Collaborator-Guide.md +++ b/Collaborator-Guide.md @@ -1,3 +1,4 @@ +# Express Collaborator Guide ## Website Issues @@ -21,7 +22,7 @@ a future release of Express. 1. [Create an issue](https://github.com/expressjs/express/issues/new) for the bug you want to fix or the feature that you want to add. -2. Create your own [fork](https://github.com/expressjs/express) on github, then +2. Create your own [fork](https://github.com/expressjs/express) on GitHub, then checkout your fork. 3. Write your code in your local copy. It's good practice to create a branch for each new issue you work on, although not compulsory. diff --git a/Contributing.md b/Contributing.md index f84c0138cb..485dee597e 100644 --- a/Contributing.md +++ b/Contributing.md @@ -14,8 +14,9 @@ contributors can be involved in decision making. * A **Committer** is a subset of contributors who have been given write access to the repository. * A **TC (Technical Committee)** is a group of committers representing the required technical expertise to resolve rare disputes. +* A **Triager** is a subset of contributors who have been given triage access to the repository. -# Logging Issues +## Logging Issues Log an issue for any question or problem you might have. When in doubt, log an issue, and any additional policies about what to include will be provided in the responses. The only @@ -27,7 +28,7 @@ add appropriate metadata before the issue is addressed. Please be courteous and respectful. Every participant is expected to follow the project's Code of Conduct. -# Contributions +## Contributions Any change to resources in this repository must be through pull requests. This applies to all changes to documentation, code, binary files, etc. Even long term committers and TC members must use @@ -41,7 +42,7 @@ weekends and other holiday periods to ensure active committers all have reasonab become involved in the discussion and review process if they wish. The default for each contribution is that it is accepted once no committer has an objection. -During review committers may also request that a specific contributor who is most versed in a +During a review, committers may also request that a specific contributor who is most versed in a particular area gives a "LGTM" before the PR can be merged. There is no additional "sign off" process for contributions to land. Once all issues brought by committers are addressed it can be landed by any committer. @@ -56,7 +57,36 @@ discuss pending contributions in order to find a resolution. It is expected that small minority of issues be brought to the TC for resolution and that discussion and compromise among committers be the default resolution mechanism. -# Becoming a Committer +## Becoming a Triager + +Anyone can become a triager! Read more about the process of being a triager in +[the triage process document](Triager-Guide.md). + +[Open an issue in `expressjs/express` repo](https://github.com/expressjs/express/issues/new) +to request the triage role. State that you have read and agree to the +[Code of Conduct](Code-Of-Conduct.md) and details of the role. + +Here is an example issue content you can copy and paste: + +``` +Title: Request triager role for + +I have read and understood the project's Code of Conduct. +I also have read and understood the process and best practices around Express triaging. + +I request for a triager role for the following GitHub organizations: + +jshttp +pillarjs +express +``` + +Once you have opened your issue, a member of the TC will add you to the `triage` team in +the organizations requested. They will then close the issue. + +Happy triaging! + +## Becoming a Committer All contributors who land a non-trivial contribution should be on-boarded in a timely manner, and added as a committer, and be given write access to the repository. @@ -64,7 +94,7 @@ and added as a committer, and be given write access to the repository. Committers are expected to follow this policy and continue to send pull requests, go through proper review, and have other committers merge their pull requests. -# TC Process +## TC Process The TC uses a "consensus seeking" process for issues that are escalated to the TC. The group tries to find a resolution that has no open objections among TC members. @@ -81,5 +111,3 @@ Members can be added to the TC at any time. Any committer can nominate another c to the TC and the TC uses its standard consensus seeking process to evaluate whether or not to add this new member. Members who do not participate consistently at the level of a majority of the other members are expected to resign. - - diff --git a/History.md b/History.md index 6e62a6ddb8..e49870fed0 100644 --- a/History.md +++ b/History.md @@ -1,3 +1,114 @@ +4.18.2 / 2022-10-08 +=================== + + * Fix regression routing a large stack in a single route + * deps: body-parser@1.20.1 + - deps: qs@6.11.0 + - perf: remove unnecessary object clone + * deps: qs@6.11.0 + +4.18.1 / 2022-04-29 +=================== + + * Fix hanging on large stack of sync routes + +4.18.0 / 2022-04-25 +=================== + + * Add "root" option to `res.download` + * Allow `options` without `filename` in `res.download` + * Deprecate string and non-integer arguments to `res.status` + * Fix behavior of `null`/`undefined` as `maxAge` in `res.cookie` + * Fix handling very large stacks of sync middleware + * Ignore `Object.prototype` values in settings through `app.set`/`app.get` + * Invoke `default` with same arguments as types in `res.format` + * Support proper 205 responses using `res.send` + * Use `http-errors` for `res.format` error + * deps: body-parser@1.20.0 + - Fix error message for json parse whitespace in `strict` + - Fix internal error when inflated body exceeds limit + - Prevent loss of async hooks context + - Prevent hanging when request already read + - deps: depd@2.0.0 + - deps: http-errors@2.0.0 + - deps: on-finished@2.4.1 + - deps: qs@6.10.3 + - deps: raw-body@2.5.1 + * deps: cookie@0.5.0 + - Add `priority` option + - Fix `expires` option to reject invalid dates + * deps: depd@2.0.0 + - Replace internal `eval` usage with `Function` constructor + - Use instance methods on `process` to check for listeners + * deps: finalhandler@1.2.0 + - Remove set content headers that break response + - deps: on-finished@2.4.1 + - deps: statuses@2.0.1 + * deps: on-finished@2.4.1 + - Prevent loss of async hooks context + * deps: qs@6.10.3 + * deps: send@0.18.0 + - Fix emitted 416 error missing headers property + - Limit the headers removed for 304 response + - deps: depd@2.0.0 + - deps: destroy@1.2.0 + - deps: http-errors@2.0.0 + - deps: on-finished@2.4.1 + - deps: statuses@2.0.1 + * deps: serve-static@1.15.0 + - deps: send@0.18.0 + * deps: statuses@2.0.1 + - Remove code 306 + - Rename `425 Unordered Collection` to standard `425 Too Early` + +4.17.3 / 2022-02-16 +=================== + + * deps: accepts@~1.3.8 + - deps: mime-types@~2.1.34 + - deps: negotiator@0.6.3 + * deps: body-parser@1.19.2 + - deps: bytes@3.1.2 + - deps: qs@6.9.7 + - deps: raw-body@2.4.3 + * deps: cookie@0.4.2 + * deps: qs@6.9.7 + * Fix handling of `__proto__` keys + * pref: remove unnecessary regexp for trust proxy + +4.17.2 / 2021-12-16 +=================== + + * Fix handling of `undefined` in `res.jsonp` + * Fix handling of `undefined` when `"json escape"` is enabled + * Fix incorrect middleware execution with unanchored `RegExp`s + * Fix `res.jsonp(obj, status)` deprecation message + * Fix typo in `res.is` JSDoc + * deps: body-parser@1.19.1 + - deps: bytes@3.1.1 + - deps: http-errors@1.8.1 + - deps: qs@6.9.6 + - deps: raw-body@2.4.2 + - deps: safe-buffer@5.2.1 + - deps: type-is@~1.6.18 + * deps: content-disposition@0.5.4 + - deps: safe-buffer@5.2.1 + * deps: cookie@0.4.1 + - Fix `maxAge` option to reject invalid values + * deps: proxy-addr@~2.0.7 + - Use `req.socket` over deprecated `req.connection` + - deps: forwarded@0.2.0 + - deps: ipaddr.js@1.9.1 + * deps: qs@6.9.6 + * deps: safe-buffer@5.2.1 + * deps: send@0.17.2 + - deps: http-errors@1.8.1 + - deps: ms@2.1.3 + - pref: ignore empty http tokens + * deps: serve-static@1.14.2 + - deps: send@0.17.2 + * deps: setprototypeof@1.2.0 + 4.17.1 / 2019-05-25 =================== diff --git a/Readme.md b/Readme.md index 1f91297312..0936816bed 100644 --- a/Readme.md +++ b/Readme.md @@ -1,12 +1,10 @@ [![Express Logo](https://i.cloudup.com/zfY6lL7eFa-3000x3000.png)](http://expressjs.com/) - Fast, unopinionated, minimalist web framework for [node](http://nodejs.org). + Fast, unopinionated, minimalist web framework for [Node.js](http://nodejs.org). - [![NPM Version][npm-image]][npm-url] - [![NPM Downloads][downloads-image]][downloads-url] - [![Linux Build][travis-image]][travis-url] - [![Windows Build][appveyor-image]][appveyor-url] - [![Test Coverage][coveralls-image]][coveralls-url] + [![NPM Version][npm-version-image]][npm-url] + [![NPM Install Size][npm-install-size-image]][npm-install-size-url] + [![NPM Downloads][npm-downloads-image]][npm-downloads-url] ```js const express = require('express') @@ -27,10 +25,13 @@ This is a [Node.js](https://nodejs.org/en/) module available through the Before installing, [download and install Node.js](https://nodejs.org/en/download/). Node.js 0.10 or higher is required. +If this is a brand new project, make sure to create a `package.json` first with +the [`npm init` command](https://docs.npmjs.com/creating-a-package-json-file). + Installation is done using the [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally): -```bash +```console $ npm install express ``` @@ -50,7 +51,7 @@ for more information. ## Docs & Community * [Website and Documentation](http://expressjs.com/) - [[website repo](https://github.com/expressjs/expressjs.com)] - * [#express](https://webchat.freenode.net/?channels=express) on freenode IRC + * [#express](https://web.libera.chat/#express) on [Libera Chat](https://libera.chat) IRC * [GitHub Organization](https://github.com/expressjs) for Official Middleware & Modules * Visit the [Wiki](https://github.com/expressjs/express/wiki) * [Google Group](https://groups.google.com/group/express-js) for discussion @@ -58,35 +59,31 @@ for more information. **PROTIP** Be sure to read [Migrating from 3.x to 4.x](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) as well as [New features in 4.x](https://github.com/expressjs/express/wiki/New-features-in-4.x). -### Security Issues - -If you discover a security vulnerability in Express, please see [Security Policies and Procedures](Security.md). - ## Quick Start The quickest way to get started with express is to utilize the executable [`express(1)`](https://github.com/expressjs/generator) to generate an application as shown below: Install the executable. The executable's major version will match Express's: -```bash +```console $ npm install -g express-generator@4 ``` Create the app: -```bash +```console $ express /tmp/foo && cd /tmp/foo ``` Install dependencies: -```bash +```console $ npm install ``` Start the server: -```bash +```console $ npm start ``` @@ -95,7 +92,7 @@ $ npm start ## Philosophy The Express philosophy is to provide small, robust tooling for HTTP servers, making - it a great solution for single page applications, web sites, hybrids, or public + it a great solution for single page applications, websites, hybrids, or public HTTP APIs. Express does not force you to use any specific ORM or template engine. With support for over @@ -106,7 +103,7 @@ $ npm start To view the examples, clone the Express repo and install the dependencies: -```bash +```console $ git clone git://github.com/expressjs/express.git --depth 1 $ cd express $ npm install @@ -114,23 +111,35 @@ $ npm install Then run whichever example you want: -```bash +```console $ node examples/content-negotiation ``` -## Tests +## Contributing + + [![Linux Build][github-actions-ci-image]][github-actions-ci-url] + [![Windows Build][appveyor-image]][appveyor-url] + [![Test Coverage][coveralls-image]][coveralls-url] + +The Express.js project welcomes all constructive contributions. Contributions take many forms, +from code for bug fixes and enhancements, to additions and fixes to documentation, additional +tests, triaging incoming pull requests and issues, and more! - To run the test suite, first install the dependencies, then run `npm test`: +See the [Contributing Guide](Contributing.md) for more technical details on contributing. -```bash +### Security Issues + +If you discover a security vulnerability in Express, please see [Security Policies and Procedures](Security.md). + +### Running Tests + +To run the test suite, first install the dependencies, then run `npm test`: + +```console $ npm install $ npm test ``` -## Contributing - -[Contributing Guide](Contributing.md) - ## People The original author of Express is [TJ Holowaychuk](https://github.com/tj) @@ -143,13 +152,15 @@ The current lead maintainer is [Douglas Christopher Wilson](https://github.com/d [MIT](LICENSE) -[npm-image]: https://img.shields.io/npm/v/express.svg -[npm-url]: https://npmjs.org/package/express -[downloads-image]: https://img.shields.io/npm/dm/express.svg -[downloads-url]: https://npmjs.org/package/express -[travis-image]: https://img.shields.io/travis/expressjs/express/master.svg?label=linux -[travis-url]: https://travis-ci.org/expressjs/express -[appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/express/master.svg?label=windows +[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/express/master?label=windows [appveyor-url]: https://ci.appveyor.com/project/dougwilson/express -[coveralls-image]: https://img.shields.io/coveralls/expressjs/express/master.svg +[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/express/master [coveralls-url]: https://coveralls.io/r/expressjs/express?branch=master +[github-actions-ci-image]: https://badgen.net/github/checks/expressjs/express/master?label=linux +[github-actions-ci-url]: https://github.com/expressjs/express/actions/workflows/ci.yml +[npm-downloads-image]: https://badgen.net/npm/dm/express +[npm-downloads-url]: https://npmcharts.com/compare/express?minimal=true +[npm-install-size-image]: https://badgen.net/packagephobia/install/express +[npm-install-size-url]: https://packagephobia.com/result?p=express +[npm-url]: https://npmjs.org/package/express +[npm-version-image]: https://badgen.net/npm/v/express diff --git a/Security.md b/Security.md index cbc5f16cde..cdcd7a6e0a 100644 --- a/Security.md +++ b/Security.md @@ -16,6 +16,10 @@ contributions. Report security bugs by emailing the lead maintainer in the Readme.md file. +To ensure the timely response to your report, please ensure that the entirety +of the report is contained within the email body and not solely behind a web +link or an attachment. + The lead maintainer will acknowledge your email within 48 hours, and will send a more detailed response within 48 hours indicating the next steps in handling your report. After the initial reply to your report, the security team will @@ -23,8 +27,7 @@ endeavor to keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance. Report security bugs in third-party modules to the person or team maintaining -the module. You can also report a vulnerability through the -[Node Security Project](https://nodesecurity.io/report). +the module. ## Disclosure Policy diff --git a/Triager-Guide.md b/Triager-Guide.md new file mode 100644 index 0000000000..a2909ef30d --- /dev/null +++ b/Triager-Guide.md @@ -0,0 +1,63 @@ +# Express Triager Guide + +## Issue Triage Process + +When a new issue or pull request is opened the issue will be labeled with `needs triage`. +If a triage team member is available they can help make sure all the required information +is provided. Depending on the issue or PR there are several next labels they can add for further +classification: + +* `needs triage`: This can be kept if the triager is unsure which next steps to take +* `awaiting more info`: If more info has been requested from the author, apply this label. +* `question`: User questions that do not appear to be bugs or enhancements. +* `discuss`: Topics for discussion. Might end in an `enhancement` or `question` label. +* `bug`: Issues that present a reasonable conviction there is a reproducible bug. +* `enhancement`: Issues that are found to be a reasonable candidate feature additions. + +In all cases, issues may be closed by maintainers if they don't receive a timely response when +further information is sought, or when additional questions are asked. + +## Approaches and Best Practices for getting into triage contributions + +Review the organization's [StatusBoard](https://expressjs.github.io/statusboard/), +pay special attention to these columns: stars, watchers, open issues, and contributors. +This gives you a general idea about the criticality and health of the repository. +Pick a few projects based on that criteria, your interests, and skills (existing or aspiring). + +Review the project's contribution guideline if present. In a nutshell, +commit to the community's standards and values. Review the +documentation, for most of the projects it is just the README.md, and +make sure you understand the key APIs, semantics, configurations, and use cases. + +It might be helpful to write your own test apps to re-affirm your +understanding of the key functions. This may identify some gaps in +documentation, record those as they might be good PR's to open. +Skim through the issue backlog; identify low hanging issues and mostly new ones. +From those, attempt to recreate issues based on the OP description and +ask questions if required. No question is a bad question! + +## Removal of Triage Role + +There are a few cases where members can be removed as triagers: + +- Breaking the CoC or project contributor guidelines +- Abuse or misuse of the role as deemed by the TC +- Lack of participation for more than 6 months + +If any of these happen we will discuss as a part of the triage portion of the regular TC meetings. +If you have questions feel free to reach out to any of the TC members. + +## Other Helpful Hints: + +- Everyone is welcome to attend the [Express Technical Committee Meetings](https://github.com/expressjs/discussions#expressjs-tc-meetings), and as a triager, it might help to get a better idea of what's happening with the project. +- When exploring the module's functionality there are a few helpful steps: + - Turn on `DEBUG=*` (see https://www.npmjs.com/package/debug) to get detailed log information + - It is also a good idea to do live debugging to follow the control flow, try using `node --inspect` + - It is a good idea to make at least one pass of reading through the entire source +- When reviewing the list of open issues there are some common types and suggested actions: + - New/unattended issues or simple questions: A good place to start + - Hard bugs & ongoing discussions: always feel free to chime in and help + - Issues that imply gaps in the documentation: open PRs with changes or help the user to do so +- For recurring issues, it is helpful to create functional examples to demonstrate (publish as gists or a repo) +- Review and identify the maintainers. If necessary, at-mention one or more of them if you are unsure what to do +- Make sure all your interactions are professional, welcoming, and respectful to the parties involved. diff --git a/appveyor.yml b/appveyor.yml index 24434cd14a..1fca21801e 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -9,38 +9,81 @@ environment: - nodejs_version: "5.12" - nodejs_version: "6.17" - nodejs_version: "7.10" - - nodejs_version: "8.16" + - nodejs_version: "8.17" - nodejs_version: "9.11" - - nodejs_version: "10.15" + - nodejs_version: "10.24" - nodejs_version: "11.15" - - nodejs_version: "12.3" + - nodejs_version: "12.22" + - nodejs_version: "13.14" + - nodejs_version: "14.20" + - nodejs_version: "15.14" + - nodejs_version: "16.17" + - nodejs_version: "17.9" + - nodejs_version: "18.10" cache: - node_modules install: # Install Node.js - ps: >- try { Install-Product node $env:nodejs_version -ErrorAction Stop } - catch { Update-NodeJsInstallation (Get-NodeJsLatestBuild $env:nodejs_version) } + catch { Update-NodeJsInstallation (Get-NodeJsLatestBuild $env:nodejs_version) x64 } # Configure npm - ps: | - # Skip updating shrinkwrap / lock + npm config set loglevel error npm config set shrinkwrap false # Remove all non-test dependencies - ps: | # Remove example dependencies npm rm --silent --save-dev connect-redis + # Remove lint dependencies + cmd.exe /c "node -pe `"Object.keys(require('./package').devDependencies).join('\n')`"" | ` + sls "^eslint(-|$)" | ` + %{ npm rm --silent --save-dev $_ } # Setup Node.js version-specific dependencies - ps: | # mocha for testing - # - use 3.x for Node.js < 6 - if ($env:nodejs_version.split(".")[0] -lt 6) { + # - use 3.x for Node.js < 4 + # - use 5.x for Node.js < 6 + # - use 6.x for Node.js < 8 + # - use 7.x for Node.js < 10 + # - use 8.x for Node.js < 12 + # - use 9.x for Node.js < 14 + if ([int]$env:nodejs_version.split(".")[0] -lt 4) { npm install --silent --save-dev mocha@3.5.3 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 6) { + npm install --silent --save-dev mocha@5.2.0 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 8) { + npm install --silent --save-dev mocha@6.2.2 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 10) { + npm install --silent --save-dev mocha@7.2.0 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 12) { + npm install --silent --save-dev mocha@8.4.0 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 14) { + npm install --silent --save-dev mocha@9.2.2 + } + - ps: | + # nyc for test coverage + # - use 10.3.2 for Node.js < 4 + # - use 11.9.0 for Node.js < 6 + # - use 14.1.1 for Node.js < 8 + if ([int]$env:nodejs_version.split(".")[0] -lt 4) { + npm install --silent --save-dev nyc@10.3.2 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 6) { + npm install --silent --save-dev nyc@11.9.0 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 8) { + npm install --silent --save-dev nyc@14.1.1 } - ps: | # supertest for http calls # - use 2.0.0 for Node.js < 4 - if ($env:nodejs_version.split(".")[0] -lt 4) { + # - use 3.4.2 for Node.js < 7 + # - use 6.1.6 for Node.js < 8 + if ([int]$env:nodejs_version.split(".")[0] -lt 4) { npm install --silent --save-dev supertest@2.0.0 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 7) { + npm install --silent --save-dev supertest@3.4.2 + } elseif ([int]$env:nodejs_version.split(".")[0] -lt 8) { + npm install --silent --save-dev supertest@6.1.6 } # Update Node.js modules - ps: | @@ -59,6 +102,4 @@ test_script: npm --version # Run test script - npm run test-ci - # Run linting - - npm run lint version: "{build}" diff --git a/benchmarks/Makefile b/benchmarks/Makefile index baf0d6fce9..ed1ddfc4f3 100644 --- a/benchmarks/Makefile +++ b/benchmarks/Makefile @@ -1,13 +1,17 @@ all: - @./run 1 middleware - @./run 5 middleware - @./run 10 middleware - @./run 15 middleware - @./run 20 middleware - @./run 30 middleware - @./run 50 middleware - @./run 100 middleware + @./run 1 middleware 50 + @./run 5 middleware 50 + @./run 10 middleware 50 + @./run 15 middleware 50 + @./run 20 middleware 50 + @./run 30 middleware 50 + @./run 50 middleware 50 + @./run 100 middleware 50 + @./run 10 middleware 100 + @./run 10 middleware 250 + @./run 10 middleware 500 + @./run 10 middleware 1000 @echo .PHONY: all diff --git a/benchmarks/middleware.js b/benchmarks/middleware.js index df4df2c5ac..fed97ba8ce 100644 --- a/benchmarks/middleware.js +++ b/benchmarks/middleware.js @@ -13,7 +13,7 @@ while (n--) { }); } -app.use(function(req, res, next){ +app.use(function(req, res){ res.send('Hello World') }); diff --git a/benchmarks/run b/benchmarks/run index 93b5bc52ff..ec8f55d564 100755 --- a/benchmarks/run +++ b/benchmarks/run @@ -4,13 +4,15 @@ echo MW=$1 node $2 & pid=$! +echo " $3 connections" + sleep 2 wrk 'http://localhost:3333/?foo[bar]=baz' \ -d 3 \ - -c 50 \ + -c $3 \ -t 8 \ - | grep 'Requests/sec' \ - | awk '{ print " " $2 }' + | grep 'Requests/sec\|Latency' \ + | awk '{ print " " $2 }' kill $pid diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000000..c19ed30a25 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,30 @@ +# Express examples + +This page contains list of examples using Express. + +- [auth](./auth) - Authentication with login and password +- [content-negotiation](./content-negotiation) - HTTP content negotiation +- [cookie-sessions](./cookie-sessions) - Working with cookie-based sessions +- [cookies](./cookies) - Working with cookies +- [downloads](./downloads) - Transferring files to client +- [ejs](./ejs) - Working with Embedded JavaScript templating (ejs) +- [error-pages](./error-pages) - Creating error pages +- [error](./error) - Working with error middleware +- [hello-world](./hello-world) - Simple request handler +- [markdown](./markdown) - Markdown as template engine +- [multi-router](./multi-router) - Working with multiple Express routers +- [multipart](./multipart) - Accepting multipart-encoded forms +- [mvc](./mvc) - MVC-style controllers +- [online](./online) - Tracking online user activity with `online` and `redis` packages +- [params](./params) - Working with route parameters +- [resource](./resource) - Multiple HTTP operations on the same resource +- [route-map](./route-map) - Organizing routes using a map +- [route-middleware](./route-middleware) - Working with route middleware +- [route-separation](./route-separation) - Organizing routes per each resource +- [search](./search) - Search API +- [session](./session) - User sessions +- [static-files](./static-files) - Serving static files +- [vhost](./vhost) - Working with virtual hosts +- [view-constructor](./view-constructor) - Rendering views dynamically +- [view-locals](./view-locals) - Saving data in request object between middleware calls +- [web-service](./web-service) - Simple API service diff --git a/examples/auth/index.js b/examples/auth/index.js index b8e854300c..36205d0f99 100644 --- a/examples/auth/index.js +++ b/examples/auth/index.js @@ -1,3 +1,5 @@ +'use strict' + /** * Module dependencies. */ @@ -59,14 +61,14 @@ function authenticate(name, pass, fn) { if (!module.parent) console.log('authenticating %s:%s', name, pass); var user = users[name]; // query the db for the given username - if (!user) return fn(new Error('cannot find user')); + if (!user) return fn(null, null) // apply the same algorithm to the POSTed password, applying // the hash against the pass / salt, if there is a match we // found the user hash({ password: pass, salt: user.salt }, function (err, pass, salt, hash) { if (err) return fn(err); if (hash === user.hash) return fn(null, user) - fn(new Error('invalid password')); + fn(null, null) }); } @@ -99,8 +101,9 @@ app.get('/login', function(req, res){ res.render('login'); }); -app.post('/login', function(req, res){ +app.post('/login', function (req, res, next) { authenticate(req.body.username, req.body.password, function(err, user){ + if (err) return next(err) if (user) { // Regenerate session when signing in // to prevent fixation diff --git a/examples/auth/views/head.ejs b/examples/auth/views/head.ejs index 0a919f4929..65386267d0 100644 --- a/examples/auth/views/head.ejs +++ b/examples/auth/views/head.ejs @@ -1,6 +1,8 @@ + + <%= title %>