mirrors/etherpad-lite
1
0
Fork 0
mirror of https://github.com/ether/etherpad-lite.git synced 2025-04-24 01:16:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 25

Merge branch 'develop'

Browse source
This commit is contained in:
SamTV12345 2024-04-10 19:06:27 +02:00
commit a5f4d3ef0c
114 changed files with 8004 additions and 1495 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.github/dependabot.yml vendored
View file

@ -10,7 +10,11 @@ updates:
schedule:
interval: "daily"
- package-ecosystem: "npm"
directory: "/src"
directory: "/"
schedule:
interval: "daily"
versioning-strategy: "increase"
open-pull-requests-limit: 30
groups:
dev-dependencies:
dependency-type: "development"

8
.github/workflows/backend-tests.yml vendored
View file

@ -1,7 +1,13 @@
name: "Backend tests"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

70
.github/workflows/build-and-deploy-docs.yml vendored Normal file
View file

@ -0,0 +1,70 @@
# Workflow for deploying static content to GitHub Pages
name: Deploy Docs to GitHub Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["develop"]
paths:
- doc/** # Only run workflow when changes are made to the doc directory
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
packages: read
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v5
- uses: pnpm/action-setup@v3
name: Install pnpm
with:
version: 8
run_install: false
- name: Get pnpm store directory
shell: bash
run: |
echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- uses: actions/cache@v4
name: Setup pnpm cache
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Only install direct dependencies
run: pnpm config set auto-install-peers false
- name: Install dependencies
run: pnpm install
- name: Build app
working-directory: doc
run: pnpm run docs:build
env:
COMMIT_REF: ${{ github.sha }}
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: './doc/.vitepress/dist'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

2
.github/workflows/codeql-analysis.yml vendored
View file

@ -6,6 +6,8 @@ on:
pull_request:
# The branches below must be a subset of the branches above
branches: [develop]
paths-ignore:
- 'doc/**'
schedule:
- cron: '0 13 * * 1'

4
.github/workflows/docker.yml vendored
View file

@ -1,9 +1,13 @@
name: Docker
on:
pull_request:
paths-ignore:
- 'doc/**'
push:
branches:
- 'develop'
paths-ignore:
- 'doc/**'
tags:
- 'v?[0-9]+.[0-9]+.[0-9]+'
env:

5
.github/workflows/frontend-admin-tests.yml vendored
View file

@ -1,7 +1,10 @@
# Leave the powered by Sauce Labs bit in as this means we get additional concurrency
name: "Frontend admin tests powered by Sauce Labs"
on: [push]
on:
push:
paths-ignore:
- 'doc/**'
permissions:
contents: read # to fetch code (actions/checkout)

5
.github/workflows/frontend-tests.yml vendored
View file

@ -1,7 +1,10 @@
# Leave the powered by Sauce Labs bit in as this means we get additional concurrency
name: "Frontend tests powered by Sauce Labs"
on: [push]
on:
push:
paths-ignore:
- 'doc/**'
permissions:
contents: read # to fetch code (actions/checkout)

34
.github/workflows/lint-package-lock.yml vendored
View file

@ -1,34 +0,0 @@
name: "Lint"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
permissions:
contents: read
jobs:
lint-package-lock:
# run on pushes to any branch
# run on PRs from external forks
if: |
(github.event_name != 'pull_request')
|| (github.event.pull_request.head.repo.id != github.event.pull_request.base.repo.id)
name: package-lock.json
runs-on: ubuntu-latest
steps:
-
name: Checkout repository
uses: actions/checkout@v4
-
uses: actions/setup-node@v4
with:
node-version: 20
-
name: Run lockfile-lint on package-lock.json
run: >
npx lockfile-lint
--path src/package-lock.json
--allowed-hosts npm
--allowed-schemes https:
--allowed-schemes github:
--allowed-urls github:mapbox/node-sqlite3#593c9d498be2510d286349134537e3bf89401c4a

8
.github/workflows/load-test.yml vendored
View file

@ -1,7 +1,13 @@
name: "Loadtest"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

8
.github/workflows/perform-type-check.yml vendored
View file

@ -1,7 +1,13 @@
name: "Perform type checks"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

8
.github/workflows/rate-limit.yml vendored
View file

@ -1,7 +1,13 @@
name: "rate limit"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

8
.github/workflows/upgrade-from-latest-release.yml vendored
View file

@ -1,7 +1,13 @@
name: "Upgrade from latest release"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

8
.github/workflows/windows.yml vendored
View file

@ -1,7 +1,13 @@
name: "Windows Build"
# any branch is useful for testing before a PR is submitted
on: [push, pull_request]
on:
push:
paths-ignore:
- "doc/**"
pull_request:
paths-ignore:
- "doc/**"
permissions:
contents: read

1
.gitignore vendored
View file

@ -27,3 +27,4 @@ plugin_packages
/src/test-results
playwright-report
state.json
/src/static/oidc

12
CHANGELOG.md
View file

@ -1,3 +1,15 @@
# 2.0.2
### Notable enhancements and fixes
- Fixed the locale loading in the admin panel
- Added OAuth2.0 support for the Etherpad API. You can now log in into the Etherpad API with your admin user using OAuth2
### Compatibility changes
- The tests now require generating a token from the OAuth secret. You can find the `generateJWTToken` in the common.ts script for plugin endpoint updates.
# 2.0.1
### Notable enhancements and fixes

30
Dockerfile
View file

@ -7,8 +7,9 @@
FROM node:alpine as adminBuild
WORKDIR /opt/etherpad-lite
COPY ./admin ./admin
COPY ./ ./
RUN cd ./admin && npm install -g pnpm && pnpm install && pnpm run build --outDir ./dist
RUN cd ./ui && pnpm install && pnpm run build --outDir ./dist
FROM node:alpine as build
@ -40,6 +41,14 @@ ARG SETTINGS=./settings.json.docker
# ETHERPAD_PLUGINS="ep_codepad ep_author_neat"
ARG ETHERPAD_PLUGINS=
# local plugins to install while building the container. By default no plugins are
# installed.
# If given a value, it has to be a space-separated, quoted list of plugin names.
#
# EXAMPLE:
# ETHERPAD_LOCAL_PLUGINS="../ep_my_plugin ../ep_another_plugin"
ARG ETHERPAD_LOCAL_PLUGINS=
# Control whether abiword will be installed, enabling exports to DOC/PDF/ODT formats.
# By default, it is not installed.
# If given any value, abiword will be installed.
@ -57,7 +66,7 @@ ARG INSTALL_ABIWORD=
ARG INSTALL_SOFFICE=
# Install dependencies required for modifying access.
RUN apk add shadow bash
RUN apk add --no-cache shadow bash
# Follow the principle of least privilege: run as unprivileged user.
#
# Running as non-root enables running this image in platforms like OpenShift
@ -84,7 +93,7 @@ RUN \
mkdir -p /usr/share/man/man1 && \
npm install pnpm -g && \
apk update && apk upgrade && \
apk add \
apk add --no-cache \
ca-certificates \
curl \
git \
@ -105,11 +114,15 @@ COPY --chown=etherpad:etherpad ./pnpm-workspace.yaml ./package.json ./
FROM build as development
COPY --chown=etherpad:etherpad ./src/package.json .npmrc ./src/pnpm-lock.yaml ./src/
COPY --chown=etherpad:etherpad ./src/package.json .npmrc ./src/
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/admin/dist ./src/templates/admin
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/ui/dist ./src/static/oidc
RUN bin/installDeps.sh && \
{ [ -z "${ETHERPAD_PLUGINS}" ] || pnpm run install-plugins ${ETHERPAD_PLUGINS}; }
if [ ! -z "${ETHERPAD_PLUGINS}" ] || [ ! -z "${ETHERPAD_LOCAL_PLUGINS}" ]; then \
pnpm run install-plugins ${ETHERPAD_PLUGINS} ${ETHERPAD_LOCAL_PLUGINS:+--path ${ETHERPAD_LOCAL_PLUGINS}}; \
fi
FROM build as production
@ -118,9 +131,12 @@ ENV ETHERPAD_PRODUCTION=true
COPY --chown=etherpad:etherpad ./src ./src
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/admin/dist ./src/templates/admin
COPY --chown=etherpad:etherpad --from=adminBuild /opt/etherpad-lite/ui/dist ./src/static/oidc
RUN bin/installDeps.sh && rm -rf ~/.npm && \
{ [ -z "${ETHERPAD_PLUGINS}" ] || pnpm run install-plugins ${ETHERPAD_PLUGINS}; }
RUN bin/installDeps.sh && rm -rf ~/.npm && rm -rf ~/.local && rm -rf ~/.cache && \
if [ ! -z "${ETHERPAD_PLUGINS}" ] || [ ! -z "${ETHERPAD_LOCAL_PLUGINS}" ]; then \
pnpm run install-plugins ${ETHERPAD_PLUGINS} ${ETHERPAD_LOCAL_PLUGINS:+--path ${ETHERPAD_LOCAL_PLUGINS}}; \
fi
# Copy the configuration file.

9
README.md
View file

@ -1,6 +1,6 @@
# Etherpad: A real-time collaborative editor for the web
![Demo Etherpad Animated Jif](doc/images/etherpad_demo.gif "Etherpad in action")
![Demo Etherpad Animated Jif](doc/public/etherpad_demo.gif "Etherpad in action")
## About
@ -21,7 +21,6 @@ We're looking for maintainers and have some funding available. Please contact J
### Code Quality
[![Code Quality](https://github.com/ether/etherpad-lite/actions/workflows/codeql-analysis.yml/badge.svg?color=%2344b492)](https://github.com/ether/etherpad-lite/actions/workflows/codeql-analysis.yml)
[![package.lock](https://github.com/ether/etherpad-lite/actions/workflows/lint-package-lock.yml/badge.svg?color=%2344b492)](https://github.com/ether/etherpad-lite/actions/workflows/lint-package-lock.yml)
### Testing
@ -121,9 +120,9 @@ Find [here](doc/docker.adoc) information on running Etherpad in a container.
Etherpad is very customizable through plugins.
![Basic install](doc/images/etherpad_basic.png "Basic Installation")
![Basic install](doc/public/etherpad_basic.png "Basic Installation")
![Full Features](doc/images/etherpad_full_features.png "You can add a lot of plugins !")
![Full Features](doc/public/etherpad_full_features.png "You can add a lot of plugins !")
### Available Plugins
@ -211,7 +210,7 @@ edit `settings.json` and restart Etherpad each time.
Open http://127.0.0.1:9001/p/test#skinvariantsbuilder in your browser and start
playing!
![Skin Variant](doc/images/etherpad_skin_variants.gif "Skin variants")
![Skin Variant](doc/public/etherpad_skin_variants.gif "Skin variants")
## Helpful resources

26
admin/package.json
View file

@ -1,7 +1,7 @@
{
"name": "admin",
"private": true,
"version": "2.0.1",
"version": "2.0.2",
"type": "module",
"scripts": {
"dev": "vite",
@ -14,26 +14,26 @@
"@radix-ui/react-dialog": "^1.0.5",
"@radix-ui/react-toast": "^1.1.5",
"i18next": "^23.10.1",
"i18next-browser-languagedetector": "^7.2.0",
"lucide-react": "^0.356.0",
"i18next-browser-languagedetector": "^7.2.1",
"lucide-react": "^0.365.0",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-hook-form": "^7.51.0",
"react-hook-form": "^7.51.2",
"react-i18next": "^14.1.0",
"react-router-dom": "^6.22.3",
"zustand": "^4.5.2",
"@types/react": "^18.2.56",
"@types/react-dom": "^18.2.19",
"@typescript-eslint/eslint-plugin": "^7.0.2",
"@typescript-eslint/parser": "^7.0.2",
"@types/react": "^18.2.74",
"@types/react-dom": "^18.2.24",
"@typescript-eslint/eslint-plugin": "^7.5.0",
"@typescript-eslint/parser": "^7.5.0",
"@vitejs/plugin-react-swc": "^3.5.0",
"eslint": "^8.56.0",
"eslint": "^9.0.0",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.5",
"socket.io-client": "^4.7.4",
"typescript": "^5.2.2",
"vite": "^5.1.4",
"vite-plugin-static-copy": "^1.0.1",
"socket.io-client": "^4.7.5",
"typescript": "^5.4.4",
"vite": "^5.2.8",
"vite-plugin-static-copy": "^1.0.2",
"vite-plugin-svgr": "^4.2.0"
}
}

2
admin/src/pages/LoginScreen.tsx
View file

@ -46,7 +46,7 @@ export const LoginScreen = ()=>{
<input {...register('username', {
required: true
})} className="login-textinput input-control" type="text" placeholder="Username"/>
<div>Passwort</div>
<div>Password</div>
<span className="icon-input">
<input {...register('password', {
required: true

3
admin/vite.config.ts
View file

@ -15,7 +15,8 @@ export default defineConfig({
})],
base: '/admin',
build:{
outDir: '../src/templates/admin'
outDir: '../src/templates/admin',
emptyOutDir: true,
},
server:{
proxy: {

9
bin/installOnWindows.bat
View file

@ -19,6 +19,15 @@ IF EXIST admin (
cd /D ..
)
:: Install ui only if available
IF EXIST ui (
cd /D .\ui
dir
cmd /C pnpm i || exit /B 1
cmd /C pnpm run build || exit /B 1
cd /D ..
)
cmd /C pnpm i || exit /B 1

32
bin/installPlugins.ts
View file

@ -10,18 +10,19 @@ if (process.argv.length === 2) {
process.exit(1);
}
let plugins = process.argv.slice(2)
let installFromPath = false;
let args = process.argv.slice(2)
const thirdOptPlug = plugins[0]
let registryPlugins: string[] = [];
let localPlugins: string[] = [];
console.log("Third option: ", thirdOptPlug)
if (thirdOptPlug && thirdOptPlug.includes('path')) {
installFromPath = true
plugins.splice(plugins.indexOf('--path'), 1);
if (args.indexOf('--path') !== -1) {
const indexToSplit = args.indexOf('--path');
registryPlugins = args.slice(0, indexToSplit);
localPlugins = args.slice(indexToSplit + 1);
} else {
registryPlugins = args;
}
const persistInstalledPlugins = async () => {
const plugins:PackageData[] = []
const installedPlugins = {plugins: plugins};
@ -36,15 +37,20 @@ const persistInstalledPlugins = async () => {
};
async function run() {
for (const plugin of plugins) {
if(installFromPath) {
console.log(`Installing plugin from path: ${plugin}`);
await linkInstaller.installFromPath(plugin);
for (const plugin of registryPlugins) {
console.log(`Installing plugin from registry: ${plugin}`)
if (plugin.includes('@')) {
const [name, version] = plugin.split('@');
await linkInstaller.installPlugin(name, version);
continue;
}
console.log(`Installing plugin from registry: ${plugin}`)
await linkInstaller.installPlugin(plugin);
}
for (const plugin of localPlugins) {
console.log(`Installing plugin from path: ${plugin}`);
await linkInstaller.installFromPath(plugin);
}
}
(async () => {

8
bin/package.json
View file

@ -1,6 +1,6 @@
{
"name": "bin",
"version": "2.0.1",
"version": "2.0.2",
"description": "",
"main": "checkAllPads.js",
"directories": {
@ -11,13 +11,13 @@
"ep_etherpad-lite": "workspace:../src",
"log4js": "^6.9.1",
"semver": "^7.6.0",
"tsx": "^4.7.1",
"tsx": "^4.7.2",
"ueberdb2": "^4.2.63"
},
"devDependencies": {
"@types/node": "^20.11.27",
"@types/node": "^20.12.5",
"@types/semver": "^7.5.8",
"typescript": "^5.4.2"
"typescript": "^5.4.4"
},
"scripts": {
"checkPad": "node --import tsx checkPad.ts",

8
bin/run.sh
View file

@ -22,7 +22,7 @@ Please type 'Etherpad rocks my socks' (or restart with the '--root'
argument) if you still want to start it as root:
EOF
printf "> " >&2
read rocks
read -r rocks
[ "$rocks" = "Etherpad rocks my socks" ] || fatal "Your input was incorrect"
fi
@ -32,9 +32,11 @@ bin/installDeps.sh "$@" || exit 1
## Create the admin ui
if [ -z "$NODE_ENV" ] || [ "$NODE_ENV" = "development" ]; then
ADMIN_UI_PATH="$(dirname $0)/../admin"
ADMIN_UI_PATH="$(dirname "$0")/../admin"
UI_PATH="$(dirname "$0")/../ui"
log "Creating the admin UI..."
(cd $ADMIN_UI_PATH && pnpm run build)
(cd "$ADMIN_UI_PATH" && pnpm run build)
(cd "$UI_PATH" && pnpm run build)
else
log "Cannot create the admin UI in production mode"
fi

2
doc/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
.vitepress/cache
dist

78
doc/.vitepress/config.mts Normal file
View file

@ -0,0 +1,78 @@
import { defineConfig } from 'vitepress'
import {version} from '../../package.json'
// https://vitepress.dev/reference/site-config
const commitRef = process.env.COMMIT_REF?.slice(0, 8) || 'dev'
export default defineConfig({
title: "Etherpad Documentation",
description: "Next Generation Collaborative Document Editing",
base: '/',
themeConfig: {
search: {
provider: 'local'
},
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Home', link: '/' },
{ text: 'Getting started', link: '/docker.md' }
],
logo:'/favicon.ico',
sidebar: {
'/': [
{
link: '/',
text: 'About',
items: [
{ text: 'Docker', link: '/docker.md' },
{ text: 'Localization', link: '/localization.md' },
{ text: 'Cookies', link: '/cookies.md' },
{ text: 'Plugins', link: '/plugins.md' },
{ text: 'Stats', link: '/stats.md' },
{text: 'Skins', link: '/skins.md' },
{text: 'Demo', link: '/demo.md' },
]
},
{
text: 'API',
link: '/api/',
items: [
{ text: 'Changeset', link: '/api/changeset_library.md' },
{text: 'Editbar', link: '/api/editbar.md' },
{text: 'EditorInfo', link: '/api/editorInfo.md' },
{text: 'Embed Parameters', link: '/api/embed_parameters.md' },
{text: 'Hooks Client Side', link: '/api/hooks_client-side.md' },
{text: 'Hooks Server Side', link: '/api/hooks_server-side.md' },
{text: 'Plugins', link: '/api/pluginfw.md' },
{text: 'Toolbar', link: '/api/toolbar.md' },
{text: 'HTTP API', link: '/api/http_api.md' },
]
},
{
text: 'Old Docs',
items: [
{ text: 'Easysync description', link: '/etherpad-lite/easysync/easysync-full-description.pdf' },
{ text: 'Easysync notes', link: '/etherpad-lite/easysync/easysync-notes.pdf' }
]
}
],
'/stats': [
{
text: 'Stats',
items:[
{ text: 'Stats', link: '/stats/' }
]
}
]
},
footer: {
message: `Published under Apache License`,
copyright: `(${commitRef}) v${version} by Etherpad Foundation`
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/ether/etherpad-lite' }
]
}
})

22
doc/.vitepress/theme/components/SvgImage.vue Normal file
View file

@ -0,0 +1,22 @@
<script setup lang="ts">
defineProps<{ svg: string }>()
</script>
<template>
<figure class="svg-image-root" v-html="svg" />
</template>
<style>
.svg-image-root {
background-color: #eee;
border-radius: 8px;
padding: 1ch;
margin: 1ch 0;
}
html.dark .svg-image-root {
background-color: #313641;
}
.svg-image-root svg text {
font-family: var(--vp-font-family-base);
}
</style>

12
doc/.vitepress/theme/index.ts Normal file
View file

@ -0,0 +1,12 @@
import { h } from 'vue'
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import './styles/vars.css'
import SvgImage from './components/SvgImage.vue'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('SvgImage', SvgImage)
},
} satisfies Theme

77
doc/.vitepress/theme/styles/vars.css Normal file
View file

@ -0,0 +1,77 @@
/**
* Colors
* -------------------------------------------------------------------------- */
:root {
--vp-c-brand: #646cff;
--vp-c-brand-light: #747bff;
--vp-c-brand-lighter: #9499ff;
--vp-c-brand-lightest: #bcc0ff;
--vp-c-brand-dark: #535bf2;
--vp-c-brand-darker: #454ce1;
--vp-c-brand-dimm: rgba(100, 108, 255, 0.08);
}
/**
* Component: Button
* -------------------------------------------------------------------------- */
:root {
--vp-button-brand-border: var(--vp-c-brand-light);
--vp-button-brand-text: var(--vp-c-white);
--vp-button-brand-bg: var(--vp-c-brand);
--vp-button-brand-hover-border: var(--vp-c-brand-light);
--vp-button-brand-hover-text: var(--vp-c-white);
--vp-button-brand-hover-bg: var(--vp-c-brand-light);
--vp-button-brand-active-border: var(--vp-c-brand-light);
--vp-button-brand-active-text: var(--vp-c-white);
--vp-button-brand-active-bg: var(--vp-button-brand-bg);
}
/**
* Component: Home
* -------------------------------------------------------------------------- */
:root {
--vp-home-hero-name-color: transparent;
--vp-home-hero-name-background: -webkit-linear-gradient(
120deg,
#0f775b 30%,
#0f775b
);
--vp-home-hero-image-background-image: linear-gradient(
-45deg,
#0f775b 50%,
#0f775b 50%
);
--vp-home-hero-image-filter: blur(40px);
}
@media (min-width: 640px) {
:root {
--vp-home-hero-image-filter: blur(56px);
}
}
@media (min-width: 960px) {
:root {
--vp-home-hero-image-filter: blur(72px);
}
}
/**
* Component: Custom Block
* -------------------------------------------------------------------------- */
:root {
--vp-custom-block-tip-border: var(--vp-c-brand);
--vp-custom-block-tip-text: var(--vp-c-brand-darker);
--vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
}
.dark {
--vp-custom-block-tip-border: var(--vp-c-brand);
--vp-custom-block-tip-text: var(--vp-c-brand-lightest);
--vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
}

44
doc/api/changeset_library.md Normal file
View file

@ -0,0 +1,44 @@
# Changeset Library
The [changeset
library](https://github.com/ether/etherpad-lite/blob/develop/src/static/js/Changeset.js)
provides tools to create, read, and apply changesets.
## Changeset
```javascript
const Changeset = require('ep_etherpad-lite/static/js/Changeset');
```
A changeset describes the difference between two revisions of a document. When a
user edits a pad, the browser generates and sends a changeset to the server,
which relays it to the other users and saves a copy (so that every past revision
is accessible).
A transmitted changeset looks like this:
```
'Z:z>1|2=m=b*0|1+1$\n'
```
## Attribute Pool
```javascript
const AttributePool = require('ep_etherpad-lite/static/js/AttributePool');
```
Changesets do not include any attribute key–value pairs. Instead, they use
numeric identifiers that reference attributes kept in an [attribute
pool](https://github.com/ether/etherpad-lite/blob/develop/src/static/js/AttributePool.js).
This attribute interning reduces the transmission overhead of attributes that
are used many times.
There is one attribute pool per pad, and it includes every current and
historical attribute used in the pad.
## Further Reading
Detailed information about the changesets & Easysync protocol:
* [Easysync Protocol](https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-notes.pdf)
* [Etherpad and EasySync Technical Manual](https://github.com/ether/etherpad-lite/blob/develop/doc/easysync/easysync-full-description.pdf)

36
doc/api/editbar.md Normal file
View file

@ -0,0 +1,36 @@
# Editbar
Located in `src/static/js/pad_editbar.js`
## isEnabled()
If the editorbar contains the class `enabledtoolbar`, it is enabled.
## disable()
Disables the editorbar. This is done by adding the class `disabledtoolbar` and removing the enabledtoolbar
## toggleDropDown(dropdown)
Shows the dropdown `div.popup` whose `id` equals `dropdown`.
## registerCommand(cmd, callback)
Register a handler for a specific command. Commands are fired if the corresponding button is clicked or the corresponding select is changed.
## registerAceCommand(cmd, callback)
Creates an ace callstack and calls the callback with an ace instance (and a toolbar item, if applicable): `callback(cmd, ace, item)`.
Example:
```
toolbar.registerAceCommand("insertorderedlist", function (cmd, ace) {
ace.ace_doInsertOrderedList();
});
```
## registerDropdownCommand(cmd, dropdown)
Ties a `div.popup` where `id` equals `dropdown` to a `command` fired by clicking a button.
## triggerCommand(cmd[, item])
Triggers a command (optionally with some internal representation of the toolbar item that triggered it).

208
doc/api/editorInfo.md Normal file
View file

@ -0,0 +1,208 @@
# EditorInfo
Location: `src/static/js/ace2_inner.js`
## editorInfo.ace_replaceRange(start, end, text)
This function replaces a range (from `start` to `end`) with `text`.
## editorInfo.ace_getRep()
Returns the `rep` object. The rep object consists of the following properties:
- `lines`: Implemented as a skip list
- `selStart`: The start of the selection
- `selEnd`: The end of the selection
- `selFocusAtStart`: Whether the selection is focused at the start
- `alltext`: The entire text of the document
- `alines`: The entire text of the document, split into lines
- `apool`: The pool of attributes
## editorInfo.ace_getAuthor()
Returns the authors of the pad. If the pad has no authors, it returns an empty object.
## editorInfo.ace_inCallStack()
Returns true if the editor is in the call stack.
## editorInfo.ace_inCallStackIfNecessary(?)
Executes the function if the editor is in the call stack.
## editorInfo.ace_focus(?)
Focuses the editor.
## editorInfo.ace_importText(?)
Imports text into the editor.
## editorInfo.ace_importAText(?)
Imports text and attributes into the editor.
## editorInfo.ace_exportText(?)
Exports the text from the editor.
## editorInfo.ace_editorChangedSize(?)
Changes the size of the editor.
## editorInfo.ace_setOnKeyPress(?)
Sets the key press event.
## editorInfo.ace_setOnKeyDown(?)
Sets the key down event.
## editorInfo.ace_setNotifyDirty(?)
Sets the dirty notification.
## editorInfo.ace_dispose(?)
Disposes the editor.
## editorInfo.ace_setEditable(bool)
Sets the editor to be editable or not.
## editorInfo.ace_execCommand(?)
Executes a command.
## editorInfo.ace_callWithAce(fn, callStack, normalize)
Calls a function with the ace instance.
## editorInfo.ace_setProperty(key, value)
Sets a property.
## editorInfo.ace_setBaseText(txt)
Sets the base text.
## editorInfo.ace_setBaseAttributedText(atxt, apoolJsonObj)
Sets the base attributed text.
## editorInfo.ace_applyChangesToBase(c, optAuthor, apoolJsonObj)
Applies changes to the base.
## editorInfo.ace_prepareUserChangeset()
Prepares the user changeset.
## editorInfo.ace_applyPreparedChangesetToBase()
Applies the prepared changeset to the base.
## editorInfo.ace_setUserChangeNotificationCallback(f)
Sets the user change notification callback.
## editorInfo.ace_setAuthorInfo(author, info)
Sets the author info.
## editorInfo.ace_fastIncorp(?)
Incorporates changes quickly.
## editorInfo.ace_isCaret(?)
Returns true if the caret is at the specified position.
## editorInfo.ace_getLineAndCharForPoint(?)
Returns the line and character for a point.
## editorInfo.ace_performDocumentApplyAttributesToCharRange(?)
Applies attributes to a character range.
## editorInfo.ace_setAttributeOnSelection(attribute, enabled)
Sets an attribute on current range.
Example: `call.editorInfo.ace_setAttributeOnSelection("turkey::balls", true); // turkey is the attribute here, balls is the value
Notes: to remove the attribute pass enabled as false
## editorInfo.ace_toggleAttributeOnSelection(?)
Toggles an attribute on the current range.
## editorInfo.ace_getAttributeOnSelection(attribute, prevChar)
Returns a boolean if an attribute exists on a selected range.
prevChar value should be true if you want to get the previous Character attribute instead of the current selection for example
if the caret is at position 0,1 (after first character) it's probable you want the attributes on the character at 0,0
The attribute should be the string name of the attribute applied to the selection IE subscript
Example usage: Apply the activeButton Class to a button if an attribute is on a highlighted/selected caret position or range.
Example `var isItThere = documentAttributeManager.getAttributeOnSelection("turkey::balls", true);`
See the ep_subscript plugin for an example of this function in action.
Notes: Does not work on first or last character of a line. Suffers from a race condition if called with aceEditEvent.
## editorInfo.ace_performSelectionChange(?)
Performs a selection change.
## editorInfo.ace_doIndentOutdent(?)
Indents or outdents the selection.
## editorInfo.ace_doUndoRedo(?)
Undoes or redoes the last action.
## editorInfo.ace_doInsertUnorderedList(?)
Inserts an unordered list.
## editorInfo.ace_doInsertOrderedList(?)
Inserts an ordered list.
## editorInfo.ace_performDocumentApplyAttributesToRange()
Applies attributes to a range.
## editorInfo.ace_getAuthorInfos()
Returns an info object about the author. Object key = author_id and info includes author's bg color value.
Use to define your own authorship.
## editorInfo.ace_performDocumentReplaceRange(start, end, newText)
This function replaces a range (from [x1,y1] to [x2,y2]) with `newText`.
## editorInfo.ace_performDocumentReplaceCharRange(startChar, endChar, newText)
This function replaces a range (from y1 to y2) with `newText`.
## editorInfo.ace_renumberList(lineNum)
If you delete a line, calling this method will fix the line numbering.
## editorInfo.ace_doReturnKey()
Forces a return key at the current caret position.
## editorInfo.ace_isBlockElement(element)
Returns true if your passed element is registered as a block element.
## editorInfo.ace_getLineListType(lineNum)
Returns the line's html list type.
## editorInfo.ace_caretLine()
Returns X position of the caret.
## editorInfo.ace_caretColumn()
Returns Y position of the caret.
## editorInfo.ace_caretDocChar()
Returns the Y offset starting from [x=0,y=0]
## editorInfo.ace_isWordChar(?)
Returns true if the character is a word character.

75
doc/api/embed_parameters.md Normal file
View file

@ -0,0 +1,75 @@
# Embed parameters
You can easily embed your etherpad-lite into any webpage by using iframes. You can configure the embedded pad using embed parameters.
Example:
Cut and paste the following code into any webpage to embed a pad. The parameters below will hide the chat and the line numbers and will auto-focus on Line 4.
```
<iframe src='http://pad.test.de/p/PAD_NAME#L4?showChat=false&showLineNumbers=false' width=600 height=400></iframe>
```
## showLineNumbers
* Boolean
Default: true
## showControls
* Boolean
Default: true
## showChat
* Boolean
Default: true
## useMonospaceFont
* Boolean
Default: false
## userName
* String
Default: "unnamed"
Example: `userName=Etherpad%20User`
## userColor
* String (css hex color value)
Default: randomly chosen by pad server
Example: `userColor=%23ff9900`
## noColors
* Boolean
Default: false
## alwaysShowChat
* Boolean
Default: false
## lang
* String
Default: en
Example: `lang=ar` (translates the interface into Arabic)
## rtl
* Boolean
Default: true
Displays pad text from right to left.
## #L
* Int
Default: 0
Focuses pad at specific line number and places caret at beginning of this line
Special note: Is not a URL parameter but instead of a Hash value

38
doc/api/hooks_client-side.adoc
View file

@ -4,7 +4,7 @@ Most of these hooks are called during or in order to set up the formatting
process.
=== documentReady
Called from: src/templates/pad.html
Called from: `src/templates/pad.html`
Things in context:
@ -14,7 +14,7 @@ This hook proxies the functionality of jQuery's `$(document).ready` event.
=== aceDomLinePreProcessLineAttributes
Called from: src/static/js/domline.js
Called from: `src/static/js/domline.js`
Things in context:
@ -36,7 +36,7 @@ more.
=== aceDomLineProcessLineAttributes
Called from: src/static/js/domline.js
Called from: `src/static/js/domline.js`
Things in context:
@ -58,7 +58,7 @@ more.
=== aceCreateDomLine
Called from: src/static/js/domline.js
Called from: `src/static/js/domline.js`
Things in context:
@ -78,7 +78,7 @@ question, and cls will be the new class of the element going forward.
=== acePostWriteDomLineHTML
Called from: src/static/js/domline.js
Called from: `src/static/js/domline.js`
Things in context:
@ -89,7 +89,7 @@ page.
=== aceAttribsToClasses
Called from: src/static/js/linestylefilter.js
Called from: `src/static/js/linestylefilter.js`
Things in context:
@ -107,7 +107,7 @@ be parsed into a valid class string.
=== aceAttribClasses
Called from: src/static/js/linestylefilter.js
Called from: `src/static/js/linestylefilter.js`
Things in context:
1. Attributes - Object of Attributes
@ -127,7 +127,7 @@ exports.aceAttribClasses = function(hook_name, attr, cb){
=== aceGetFilterStack
Called from: src/static/js/linestylefilter.js
Called from: `src/static/js/linestylefilter.js`
Things in context:
@ -143,7 +143,7 @@ later used by the aceCreateDomLine hook (documented above).
=== aceEditorCSS
Called from: src/static/js/ace.js
Called from: `src/static/js/ace.js`
Things in context: None
@ -152,7 +152,7 @@ should be an array of resource urls or paths relative to the plugins directory.
=== aceInitInnerdocbodyHead
Called from: src/static/js/ace.js
Called from: `src/static/js/ace.js`
Things in context:
@ -165,7 +165,7 @@ editor HTML document.
=== aceEditEvent
Called from: src/static/js/ace2_inner.js
Called from: `src/static/js/ace2_inner.js`
Things in context:
@ -182,7 +182,7 @@ your plugin) that use the information provided by the edit event.
=== aceRegisterNonScrollableEditEvents
Called from: src/static/js/ace2_inner.js
Called from: `src/static/js/ace2_inner.js`
Things in context: None
@ -203,7 +203,7 @@ exports.aceRegisterNonScrollableEditEvents = function(){
=== aceRegisterBlockElements
Called from: src/static/js/ace2_inner.js
Called from: `src/static/js/ace2_inner.js`
Things in context: None
@ -213,7 +213,7 @@ call for those elements.
=== aceInitialized
Called from: src/static/js/ace2_inner.js
Called from: `src/static/js/ace2_inner.js`
Things in context:
@ -228,7 +228,7 @@ use in formatting hooks.
=== postAceInit
Called from: src/static/js/pad.js
Called from: `src/static/js/pad.js`
Things in context:
@ -240,7 +240,7 @@ Things in context:
=== postToolbarInit
Called from: src/static/js/pad_editbar.js
Called from: `src/static/js/pad_editbar.js`
Things in context:
@ -255,14 +255,14 @@ Usage examples:
=== postTimesliderInit
Called from: src/static/js/timeslider.js
Called from: `src/static/js/timeslider.js`
There doesn't appear to be any example available of this particular hook being
used, but it gets fired after the timeslider is all set up.
=== goToRevisionEvent
Called from: src/static/js/broadcast.js
Called from: `src/static/js/broadcast.js`
Things in context:
@ -274,7 +274,7 @@ be any example available of this particular hook being used.
=== userJoinOrUpdate
Called from: src/static/js/pad_userlist.js
Called from: `src/static/js/pad_userlist.js`
Things in context:

527
doc/api/hooks_client-side.md Normal file
View file

@ -0,0 +1,527 @@
# Client-side hooks
Most of these hooks are called during or in order to set up the formatting
process.
## documentReady
Called from: `src/templates/pad.html`
Things in context:
nothing
This hook proxies the functionality of jQuery's `$(document).ready` event.
## aceDomLinePreProcessLineAttributes
Called from: `src/static/js/domline.js`
Things in context:
1. domline - The current DOM line being processed
2. cls - The class of the current block element (useful for styling)
This hook is called for elements in the DOM that have the "lineMarkerAttribute"
set. You can add elements into this category with the aceRegisterBlockElements
hook above. This hook is run BEFORE the numbered and ordered lists logic is
applied.
The return value of this hook should have the following structure:
`{ preHtml: String, postHtml: String, processedMarker: Boolean }`
The preHtml and postHtml values will be added to the HTML display of the
element, and if processedMarker is true, the engine won't try to process it any
more.
## aceDomLineProcessLineAttributes
Called from: `src/static/js/domline.js`
Things in context:
1. domline - The current DOM line being processed
2. cls - The class of the current block element (useful for styling)
This hook is called for elements in the DOM that have the "lineMarkerAttribute"
set. You can add elements into this category with the aceRegisterBlockElements
hook above. This hook is run AFTER the ordered and numbered lists logic is
applied.
The return value of this hook should have the following structure:
`{ preHtml: String, postHtml: String, processedMarker: Boolean }`
The preHtml and postHtml values will be added to the HTML display of the
element, and if processedMarker is true, the engine won't try to process it any
more.
## aceCreateDomLine
Called from: `src/static/js/domline.js`
Things in context:
1. domline - the current DOM line being processed
2. cls - The class of the current element (useful for styling)
This hook is called for any line being processed by the formatting engine,
unless the aceDomLineProcessLineAttributes hook from above returned true, in
which case this hook is skipped.
The return value of this hook should have the following structure:
`{ extraOpenTags: String, extraCloseTags: String, cls: String }`
extraOpenTags and extraCloseTags will be added before and after the element in
question, and cls will be the new class of the element going forward.
## acePostWriteDomLineHTML
Called from: `src/static/js/domline.js`
Things in context:
1. node - the DOM node that just got written to the page
This hook is for right after a node has been fully formatted and written to the
page.
## aceAttribsToClasses
Called from: `src/static/js/linestylefilter.js`
Things in context:
1. linestylefilter - the JavaScript object that's currently processing the ace
attributes
2. key - the current attribute being processed
3. value - the value of the attribute being processed
This hook is called during the attribute processing procedure, and should be
used to translate key, value pairs into valid HTML classes that can be inserted
into the DOM.
The return value for this function should be a list of classes, which will then
be parsed into a valid class string.
## aceAttribClasses
Called from: `src/static/js/linestylefilter.js`
Things in context:
1. Attributes - Object of Attributes
This hook is called when attributes are investigated on a line. It is useful if
you want to add another attribute type or property type to a pad.
Example:
```
exports.aceAttribClasses = function(hook_name, attr, cb){
attr.sub = 'tag:sub';
cb(attr);
}
```
## aceGetFilterStack
Called from: `src/static/js/linestylefilter.js`
Things in context:
1. linestylefilter - the JavaScript object that's currently processing the ace
attributes
2. browser - an object indicating which browser is accessing the page
This hook is called to apply custom regular expression filters to a set of
styles. The one example available is the ep_linkify plugin, which adds internal
links. They use it to find the telltale `[[ ]]` syntax that signifies internal
links, and finding that syntax, they add in the internalHref attribute to be
later used by the aceCreateDomLine hook (documented above).
## aceEditorCSS
Called from: `src/static/js/ace.js`
Things in context: None
This hook is provided to allow custom CSS files to be loaded. The return value
should be an array of resource urls or paths relative to the plugins directory.
## aceInitInnerdocbodyHead
Called from: `src/static/js/ace.js`
Things in context:
1. iframeHTML - the HTML of the editor iframe up to this point, in array format
This hook is called during the creation of the editor HTML. The array should
have lines of HTML added to it, giving the plugin author a chance to add in
meta, script, link, and other tags that go into the `<head>` element of the
editor HTML document.
## aceEditEvent
Called from: `src/static/js/ace2_inner.js`
Things in context:
1. callstack - a bunch of information about the current action
2. editorInfo - information about the user who is making the change
3. rep - information about where the change is being made
4. documentAttributeManager - information about attributes in the document (this
is a mystery to me)
This hook is made available to edit the edit events that might occur when
changes are made. Currently you can change the editor information, some of the
meanings of the edit, and so on. You can also make internal changes (internal to
your plugin) that use the information provided by the edit event.
## aceRegisterNonScrollableEditEvents
Called from: `src/static/js/ace2_inner.js`
Things in context: None
When aceEditEvent (documented above) finishes processing the event, it scrolls
the viewport to make caret visible to the user, but if you don't want that
behavior to happen you can use this hook to register which edit events should
not scroll viewport. The return value of this hook should be a list of event
names.
Example:
```
exports.aceRegisterNonScrollableEditEvents = function(){
return [ 'repaginate', 'updatePageCount' ];
}
```
## aceRegisterBlockElements
Called from: `src/static/js/ace2_inner.js`
Things in context: None
The return value of this hook will add elements into the "lineMarkerAttribute"
category, making the aceDomLineProcessLineAttributes hook (documented below)
call for those elements.
## aceInitialized
Called from: `src/static/js/ace2_inner.js`
Things in context:
1. editorInfo - information about the user who will be making changes through
the interface, and a way to insert functions into the main ace object (see
ep_headings)
2. rep - information about where the user's cursor is
3. documentAttributeManager - some kind of magic
This hook is for inserting further information into the ace engine, for later
use in formatting hooks.
## postAceInit
Called from: `src/static/js/pad.js`
Things in context:
1. ace - the ace object that is applied to this editor.
2. clientVars - Object containing client-side configuration such as author ID
and plugin settings. Your plugin can manipulate this object via the
`clientVars` server-side hook.
3. pad - the pad object of the current pad.
## postToolbarInit
Called from: `src/static/js/pad_editbar.js`
Things in context:
1. ace - the ace object that is applied to this editor.
2. toolbar - Editbar instance. See below for the Editbar documentation.
Can be used to register custom actions to the toolbar.
Usage examples:
* [https://github.com/tiblu/ep_authorship_toggle]()
## postTimesliderInit
Called from: `src/static/js/timeslider.js`
There doesn't appear to be any example available of this particular hook being
used, but it gets fired after the timeslider is all set up.
## goToRevisionEvent
Called from: `src/static/js/broadcast.js`
Things in context:
1. rev - The newRevision
This hook gets fired both on timeslider load (as timeslider shows a new
revision) and when the new revision is showed to a user. There doesn't appear to
be any example available of this particular hook being used.
## userJoinOrUpdate
Called from: `src/static/js/pad_userlist.js`
Things in context:
1. info - the user information
This hook is called on the client side whenever a user joins or changes. This
can be used to create notifications or an alternate user list.
## `chatNewMessage`
Called from: `src/static/js/chat.js`
This hook runs on the client side whenever a chat message is received from the
server. It can be used to create different notifications for chat messages. Hook
functions can modify the `author`, `authorName`, `duration`, `rendered`,
`sticky`, `text`, and `timeStr` context properties to change how the message is
processed. The `text` and `timeStr` properties may contain HTML and come
pre-sanitized; plugins should be careful to sanitize any added user input to
avoid introducing an XSS vulnerability.
Context properties:
* `authorName`: The display name of the user that wrote the message.
* `author`: The author ID of the user that wrote the message.
* `text`: Sanitized message HTML, with URLs wrapped like `<a
href="url">url</a>`. (Note that `message.text` is not sanitized or processed
in any way.)
* `message`: The raw message object as received from the server, except with
time correction and a default `authorId` property if missing. Plugins must not
modify this object. Warning: Unlike `text`, `message.text` is not
pre-sanitized or processed in any way.
* `rendered` - Used to override the default message rendering. Initially set to
`null`. If the hook function sets this to a DOM element object or a jQuery
object, then that object will be used as the rendered message UI. Otherwise,
if this is set to `null`, then Etherpad will render a default UI for the
message using the other context properties.
* `sticky` (boolean): Whether the gritter notification should fade out on its
own or just sit there until manually closed.
* `timestamp`: When the chat message was sent (milliseconds since epoch),
corrected using the difference between the local clock and the server's clock.
* `timeStr`: The message timestamp as a formatted string.
* `duration`: How long (in milliseconds) to display the gritter notification (0
to disable).
## `chatSendMessage`
Called from: `src/static/js/chat.js`
This hook runs on the client side whenever the user sends a new chat message.
Plugins can mutate the message object to change the message text or add metadata
to control how the message will be rendered by the `chatNewMessage` hook.
Context properties:
* `message`: The message object that will be sent to the Etherpad server.
## collectContentPre
Called from: `src/static/js/contentcollector.js`
Things in context:
1. cc - the contentcollector object
2. state - the current state of the change being made
3. tname - the tag name of this node currently being processed
4. styl - the style applied to the node (probably CSS) -- Note the typo
5. cls - the HTML class string of the node
This hook is called before the content of a node is collected by the usual
methods. The cc object can be used to do a bunch of things that modify the
content of the pad. See, for example, the heading1 plugin for etherpad original.
E.g. if you need to apply an attribute to newly inserted characters, call
cc.doAttrib(state, "attributeName") which results in an attribute
attributeName=true.
If you want to specify also a value, call cc.doAttrib(state,
"attributeName::value") which results in an attribute attributeName=value.
## collectContentImage
Called from: `src/static/js/contentcollector.js`
Things in context:
1. cc - the contentcollector object
2. state - the current state of the change being made
3. tname - the tag name of this node currently being processed
4. style - the style applied to the node (probably CSS)
5. cls - the HTML class string of the node
6. node - the node being modified
This hook is called before the content of an image node is collected by the
usual methods. The cc object can be used to do a bunch of things that modify the
content of the pad.
Example:
```
exports.collectContentImage = function(name, context){
context.state.lineAttributes.img = context.node.outerHTML;
}
```
## collectContentPost
Called from: `src/static/js/contentcollector.js`
Things in context:
1. cc - the contentcollector object
2. state - the current state of the change being made
3. tname - the tag name of this node currently being processed
4. style - the style applied to the node (probably CSS)
5. cls - the HTML class string of the node
This hook is called after the content of a node is collected by the usual
methods. The cc object can be used to do a bunch of things that modify the
content of the pad. See, for example, the heading1 plugin for etherpad original.
## handleClientMessage_`name`
Called from: `src/static/js/collab_client.js`
Things in context:
1. payload - the data that got sent with the message (use it for custom message
content)
This hook gets called every time the client receives a message of type `name`.
This can most notably be used with the new HTTP API call, "sendClientsMessage",
which sends a custom message type to all clients connected to a pad. You can
also use this to handle existing types.
`collab_client.js` has a pretty extensive list of message types, if you want to
take a look.
## aceStartLineAndCharForPoint-aceEndLineAndCharForPoint
Called from: src/static/js/ace2_inner.js
Things in context:
1. callstack - a bunch of information about the current action
2. editorInfo - information about the user who is making the change
3. rep - information about where the change is being made
4. root - the span element of the current line
5. point - the starting/ending element where the cursor highlights
6. documentAttributeManager - information about attributes in the document
This hook is provided to allow a plugin to turn DOM node selection into
[line,char] selection. The return value should be an array of [line,char]
## aceKeyEvent
Called from: `src/static/js/ace2_inner.js`
Things in context:
1. callstack - a bunch of information about the current action
2. editorInfo - information about the user who is making the change
3. rep - information about where the change is being made
4. documentAttributeManager - information about attributes in the document
5. evt - the fired event
This hook is provided to allow a plugin to handle key events.
The return value should be true if you have handled the event.
## collectContentLineText
Called from: `src/static/js/contentcollector.js`
Things in context:
1. cc - the contentcollector object
2. state - the current state of the change being made
3. tname - the tag name of this node currently being processed
4. text - the text for that line
This hook allows you to validate/manipulate the text before it's sent to the
server side. To change the text, either:
* Set the `text` context property to the desired value and return `undefined`.
* (Deprecated) Return a string. If a hook function changes the `text` context
property, the return value is ignored. If no hook function changes `text` but
multiple hook functions return a string, the first one wins.
Example:
```
exports.collectContentLineText = (hookName, context) => {
context.text = tweakText(context.text);
};
```
## collectContentLineBreak
Called from: `src/static/js/contentcollector.js`
Things in context:
1. cc - the contentcollector object
2. state - the current state of the change being made
3. tname - the tag name of this node currently being processed
This hook is provided to allow whether the br tag should induce a new magic
domline or not. The return value should be either true(break the line) or false.
## disableAuthorColorsForThisLine
Called from: `src/static/js/linestylefilter.js`
Things in context:
1. linestylefilter - the JavaScript object that's currently processing the ace
attributes
2. text - the line text
3. class - line class
This hook is provided to allow whether a given line should be deliniated with
multiple authors. Multiple authors in one line cause the creation of magic span
lines. This might not suit you and now you can disable it and handle your own
deliniation. The return value should be either true(disable) or false.
## aceSetAuthorStyle
Called from: `src/static/js/ace2_inner.js`
Things in context:
1. dynamicCSS - css manager for inner ace
2. outerDynamicCSS - css manager for outer ace
3. parentDynamicCSS - css manager for parent document
4. info - author style info
5. author - author info
6. authorSelector - css selector for author span in inner ace
This hook is provided to allow author highlight style to be modified. Registered
hooks should return 1 if the plugin handles highlighting. If no plugin returns
1, the core will use the default background-based highlighting.
## aceSelectionChanged
Called from: `src/static/js/ace2_inner.js`
Things in context:
1. rep - information about where the user's cursor is
2. documentAttributeManager - information about attributes in the document
This hook allows a plugin to react to a cursor or selection change,
perhaps to update a UI element based on the style at the cursor location.

117
doc/api/hooks_overview.md Normal file
View file

@ -0,0 +1,117 @@
# Hooks
A hook function is registered with a hook via the plugin's `ep.json` file. See
the Plugins section for details. A hook may have many registered functions from
different plugins.
Some hooks call their registered functions one at a time until one of them
returns a value. Others always call all of their registered functions and
combine the results (if applicable).
## Registered hook functions
Note: The documentation in this section applies to every hook unless the
hook-specific documentation says otherwise.
### Arguments
Hook functions are called with three arguments:
1. `hookName` - The name of the hook being invoked.
2. `context` - An object with some relevant information about the context of the
call. See the hook-specific documentation for details.
3. `cb` - For asynchronous operations this callback can be called to signal
completion and optionally provide a return value. The callback takes a single
argument, the meaning of which depends on the hook (see the "Return values"
section for general information that applies to most hooks). This callback
always returns `undefined`.
### Expected behavior
The presence of a callback parameter suggests that every hook function can run
asynchronously. While that is the eventual goal, there are some legacy hooks
that expect their hook functions to provide a value synchronously. For such
hooks, the hook functions must do one of the following:
* Call the callback with a non-Promise value (`undefined` is acceptable) and
return `undefined`, in that order.
* Return a non-Promise value other than `undefined` (`null` is acceptable) and
never call the callback. Note that `async` functions *always* return a
Promise, so they must never be used for synchronous hooks.
* Only have two parameters (`hookName` and `context`) and return any non-Promise
value (`undefined` is acceptable).
For hooks that permit asynchronous behavior, the hook functions must do one or
more of the following:
* Return `undefined` and call the callback, in either order.
* Return something other than `undefined` (`null` is acceptable) and never call
the callback. Note that `async` functions *always* return a Promise, so they
must never call the callback.
* Only have two parameters (`hookName` and `context`).
Note that the acceptable behaviors for asynchronous hook functions is a superset
of the acceptable behaviors for synchronous hook functions.
WARNING: The number of parameters is determined by examining
[Function.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/length),
which does not count [default
parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters)
or ["rest"
parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters).
To avoid problems, do not use default or rest parameters when defining hook
functions.
### Return values
A hook function can provide a value to Etherpad in one of the following ways:
* Pass the desired value as the first argument to the callback.
* Return the desired value directly. The value must not be `undefined` unless
the hook function only has two parameters. (Hook functions with three
parameters that want to provide `undefined` should instead use the callback.)
* For hooks that permit asynchronous behavior, return a Promise that resolves to
the desired value.
* For hooks that permit asynchronous behavior, pass a Promise that resolves to
the desired value as the first argument to the callback.
Examples:
```javascript
exports.exampleOne = (hookName, context, callback) => {
return 'valueOne';
};
exports.exampleTwo = (hookName, context, callback) => {
callback('valueTwo');
return;
};
// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
exports.exampleThree = (hookName, context, callback) => {
return new Promise('valueThree');
};
// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
exports.exampleFour = (hookName, context, callback) => {
callback(new Promise('valueFour'));
return;
};
// ONLY FOR HOOKS THAT PERMIT ASYNCHRONOUS BEHAVIOR
exports.exampleFive = async (hookName, context) => {
// Note that this function is async, so it actually returns a Promise that
// is resolved to 'valueFive'.
return 'valueFive';
};
```
Etherpad collects the values provided by the hook functions into an array,
filters out all `undefined` values, then flattens the array one level.
Flattening one level makes it possible for a hook function to behave as if it
were multiple separate hook functions.
For example: Suppose a hook has eight registered functions that return the
following values: `1`, `[2]`, `['3a', '3b']` `[[4]]`, `undefined`,
`[undefined]`, `[]`, and `null`. The value returned to the caller of the hook is
`[1, 2, '3a', '3b', [4], undefined, null]`.

12
doc/api/hooks_server-side.adoc
View file

@ -2,7 +2,7 @@
These hooks are called on server-side.
=== loadSettings
Called from: src/node/server.ts
Called from: `src/node/server.ts`
Things in context:
@ -11,7 +11,7 @@ Things in context:
Use this hook to receive the global settings in your plugin.
=== shutdown
Called from: src/node/server.ts
Called from: `src/node/server.ts`
Things in context: None
@ -34,7 +34,7 @@ exports.shutdown = async (hookName, context) => {
----
=== pluginUninstall
Called from: src/static/js/pluginfw/installer.js
Called from: `src/static/js/pluginfw/installer.js`
Things in context:
@ -43,7 +43,7 @@ Things in context:
If this hook returns an error, the callback to the uninstall function gets an error as well. This mostly seems useful for handling additional features added in based on the installation of other plugins, which is pretty cool!
=== pluginInstall
Called from: src/static/js/pluginfw/installer.js
Called from: `src/static/js/pluginfw/installer.js`
Things in context:
@ -123,7 +123,7 @@ Context properties:
=== expressCloseServer
Called from: src/node/hooks/express.js
Called from: `src/node/hooks/express.js`
Things in context: Nothing
@ -142,7 +142,7 @@ exports.expressCloseServer = async () => {
----
=== eejsBlock_`<name>`
Called from: src/node/eejs/index.js
Called from: `src/node/eejs/index.js`
Things in context:

1103
doc/api/hooks_server-side.md Normal file
View file

File diff suppressed because it is too large Load diff

686
doc/api/http_api.md Normal file
View file

@ -0,0 +1,686 @@
# HTTP API
## What can I do with this API?
The API gives another web application control of the pads. The basic functions are
* create/delete pads
* grant/forbid access to pads
* get/set pad content
The API is designed in a way, so you can reuse your existing user system with their permissions, and map it to Etherpad. Means: Your web application still has to do authentication, but you can tell Etherpad via the api, which visitors should get which permissions. This allows Etherpad to fit into any web application and extend it with real-time functionality. You can embed the pads via an iframe into your website.
Take a look at [HTTP API client libraries](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) to check if a library in your favorite programming language is available.
### OpenAPI
OpenAPI (formerly swagger) definitions are exposed under `/api/openapi.json` (latest) and `/api/{version}/openapi.json`. You can use official tools like [Swagger Editor](https://editor.swagger.io/) to view and explore them.
## Examples
### Example 1
A portal (such as WordPress) wants to give a user access to a new pad. Let's assume the user have the internal id 7 and his name is michael.
Portal maps the internal userid to an etherpad author.
#### Request
```http
GET /api/1/createAuthorIfNotExistsFor?apikey=secret&name=Michael&authorMapper=7
```
### Response
```json
{"code": 0, "message":"ok", "data": {"authorID": "a.s8oes9dhwrvt0zif"}}
```
#### Request
> Portal maps the internal userid to an etherpad group:
```http
GET http://pad.domain/api/1/createGroupIfNotExistsFor?apikey=secret&groupMapper=7
```
### Response
```json
{"code": 0, "message":"ok", "data": {"groupID": "g.s8oes9dhwrvt0zif"}}
```
> Portal creates a pad in the userGroup
#### Request
```http
GET http://pad.domain/api/1/createGroupPad?apikey=secret&groupID=g.s8oes9dhwrvt0zif&padName=samplePad&text=This is the first sentence in the pad
```
#### Response
```json
{"code": 0, "message":"ok", "data": null}
```
> Portal starts the session for the user on the group:
#### Request
```http
GET http://pad.domain/api/1/createSession?apikey=secret&groupID=g.s8oes9dhwrvt0zif&authorID=a.s8oes9dhwrvt0zif&validUntil=1312201246
```
### Response
```json
{"code": 0, "message":"ok", "data": {"sessionID": "s.s8oes9dhwrvt0zif"}}
```
Portal places the cookie "sessionID" with the given value on the client and creates an iframe including the pad.
### Example 2
A portal (such as WordPress) wants to transform the contents of a pad that multiple admins edited into a blog post.
Portal retrieves the contents of the pad for entry into the db as a blog post:
> Request: `http://pad.domain/api/1/getText?apikey=secret&padID=g.s8oes9dhwrvt0zif$123`
>
> Response: `{code: 0, message:"ok", data: {text:"Welcome Text"}}`
Portal submits content into new blog post
> Portal.AddNewBlog(content)
## Usage
### API version
The latest version is `1.2.15`
The current version can be queried via /api.
### Request Format
The API is accessible via HTTP. Starting from **1.8**, API endpoints can be invoked indifferently via GET or POST.
The URL of the HTTP request is of the form: `/api/$APIVERSION/$FUNCTIONNAME`. $APIVERSION depends on the endpoint you want to use. Depending on the verb you use (GET or POST) **parameters** can be passed differently.
When invoking via GET (mandatory until **1.7.5** included), parameters must be included in the query string (example: `/api/$APIVERSION/$FUNCTIONNAME?apikey=<APIKEY>&param1=value1`). Please note that starting with nodejs 8.14+ the total size of HTTP request headers has been capped to 8192 bytes. This limits the quantity of data that can be sent in an API request.
Starting from Etherpad **1.8** it is also possible to invoke the HTTP API via POST. In this case, querystring parameters will still be accepted, but **any parameter with the same name sent via POST will take precedence**. If you need to send large chunks of text (for example, for `setText()`) it is advisable to invoke via POST.
Example with cURL using GET (toy example, no encoding):
```
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname&text=this_text_will_NOT_be_encoded_by_curl_use_next_example"
```
Example with cURL using GET (better example, encodes text):
```
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --get --data-urlencode "text=Text sent via GET with proper encoding. For big documents, please use POST"
```
Example with cURL using POST:
```
curl "http://pad.domain/api/1/setText?apikey=secret&padID=padname" --data-urlencode "text=Text sent via POST with proper encoding. For big texts (>8 KB), use this method"
```
### Response Format
Responses are valid JSON in the following format:
```json
{
"code": number,
"message": string,
"data": obj
}
```
* **code** a return code
* **0** everything ok
* **1** wrong parameters
* **2** internal error
* **3** no such function
* **4** no or wrong API Key
* **message** a status message. It's ok if everything is fine, else it contains an error message
* **data** the payload
### Overview
![API Overview](https://i.imgur.com/d0nWp.png)
## Data Types
* **groupID** a string, the unique id of a group. Format is g.16RANDOMCHARS, for example g.s8oes9dhwrvt0zif
* **sessionID** a string, the unique id of a session. Format is s.16RANDOMCHARS, for example s.s8oes9dhwrvt0zif
* **authorID** a string, the unique id of an author. Format is a.16RANDOMCHARS, for example a.s8oes9dhwrvt0zif
* **readOnlyID** a string, the unique id of a readonly relation to a pad. Format is r.16RANDOMCHARS, for example r.s8oes9dhwrvt0zif
* **padID** a string, format is GROUPID$PADNAME, for example the pad test of group g.s8oes9dhwrvt0zif has padID g.s8oes9dhwrvt0zif$test
### Authentication
Authentication works via a token that is sent with each request as a post parameter. There is a single token per Etherpad deployment. This token will be random string, generated by Etherpad at the first start. It will be saved in APIKEY.txt in the root folder of Etherpad. Only Etherpad and the requesting application knows this key. Token management will not be exposed through this API.
### Node Interoperability
All functions will also be available through a node module accessible from other node.js applications.
## API Methods
### Groups
Pads can belong to a group. The padID of grouppads is starting with a groupID like `g.asdfasdfasdfasdf$test`
#### createGroup()
* API >= 1
creates a new group
*Example returns:*
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
#### createGroupIfNotExistsFor(groupMapper)
* API >= 1
this functions helps you to map your application group ids to Etherpad group ids
*Example returns:*
* `{code: 0, message:"ok", data: {groupID: g.s8oes9dhwrvt0zif}}`
#### deleteGroup(groupID)
* API >= 1
deletes a group
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"groupID does not exist", data: null}`
#### listPads(groupID)
* API >= 1
returns all pads of this group
*Example returns:*
* `{code: 0, message:"ok", data: {padIDs : ["g.s8oes9dhwrvt0zif$test", "g.s8oes9dhwrvt0zif$test2"]}`
* `{code: 1, message:"groupID does not exist", data: null}`
#### createGroupPad(groupID, padName, [text], [authorId])
* API >= 1
* `authorId` in API >= 1.3.0
creates a new pad in this group
*Example returns:*
* `{code: 0, message:"ok", data: {padID: "g.s8oes9dhwrvt0zif$test"}`
* `{code: 1, message:"padName does already exist", data: null}`
* `{code: 1, message:"groupID does not exist", data: null}`
#### listAllGroups()
* API >= 1.1
lists all existing groups
*Example returns:*
* `{code: 0, message:"ok", data: {groupIDs: ["g.mKjkmnAbSMtCt8eL", "g.3ADWx6sbGuAiUmCy"]}}`
* `{code: 0, message:"ok", data: {groupIDs: []}}`
### Author
These authors are bound to the attributes the users choose (color and name).
#### createAuthor([name])
* API >= 1
creates a new author
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
#### createAuthorIfNotExistsFor(authorMapper [, name])
* API >= 1
this functions helps you to map your application author ids to Etherpad author ids
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif"}}`
#### listPadsOfAuthor(authorID)
* API >= 1
returns an array of all pads this author contributed to
*Example returns:*
* `{code: 0, message:"ok", data: {padIDs: ["g.s8oes9dhwrvt0zif$test", "g.s8oejklhwrvt0zif$foo"]}}`
* `{code: 1, message:"authorID does not exist", data: null}`
#### getAuthorName(authorID)
* API >= 1.1
Returns the Author Name of the author
*Example returns:*
* `{code: 0, message:"ok", data: {authorName: "John McLear"}}`
-> can't be deleted cause this would involve scanning all the pads where this author was
### Session
Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.
#### createSession(groupID, authorID, validUntil)
* API >= 1
creates a new session. validUntil is an unix timestamp in seconds
*Example returns:*
* `{code: 0, message:"ok", data: {sessionID: "s.s8oes9dhwrvt0zif"}}`
* `{code: 1, message:"groupID doesn't exist", data: null}`
* `{code: 1, message:"authorID doesn't exist", data: null}`
* `{code: 1, message:"validUntil is in the past", data: null}`
#### deleteSession(sessionID)
* API >= 1
deletes a session
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"sessionID does not exist", data: null}`
#### getSessionInfo(sessionID)
* API >= 1
returns information about a session
*Example returns:*
* `{code: 0, message:"ok", data: {authorID: "a.s8oes9dhwrvt0zif", groupID: g.s8oes9dhwrvt0zif, validUntil: 1312201246}}`
* `{code: 1, message:"sessionID does not exist", data: null}`
#### listSessionsOfGroup(groupID)
* API >= 1
returns all sessions of a group
*Example returns:*
* `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
* `{code: 1, message:"groupID does not exist", data: null}`
#### listSessionsOfAuthor(authorID)
* API >= 1
returns all sessions of an author
*Example returns:*
* `{"code":0,"message":"ok","data":{"s.oxf2ras6lvhv2132":{"groupID":"g.s8oes9dhwrvt0zif","authorID":"a.akf8finncvomlqva","validUntil":2312905480}}}`
* `{code: 1, message:"authorID does not exist", data: null}`
### Pad Content
Pad content can be updated and retrieved through the API
#### getText(padID, [rev])
* API >= 1
returns the text of a pad
*Example returns:*
* `{code: 0, message:"ok", data: {text:"Welcome Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### setText(padID, text, [authorId])
* API >= 1
* `authorId` in API >= 1.3.0
Sets the text of a pad.
If your text is long (>8 KB), please invoke via POST and include `text` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* `{code: 1, message:"text too long", data: null}`
#### appendText(padID, text, [authorId])
* API >= 1.2.13
* `authorId` in API >= 1.3.0
Appends text to a pad.
If your text is long (>8 KB), please invoke via POST and include `text` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* `{code: 1, message:"text too long", data: null}`
#### getHTML(padID, [rev])
* API >= 1
returns the text of a pad formatted as HTML
*Example returns:*
* `{code: 0, message:"ok", data: {html:"Welcome Text<br>More Text"}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### setHTML(padID, html, [authorId])
* API >= 1
* `authorId` in API >= 1.3.0
sets the text of a pad based on HTML, HTML must be well-formed. Malformed HTML will send a warning to the API log.
If `html` is long (>8 KB), please invoke via POST and include `html` parameter in the body of the request, not in the URL (since Etherpad **1.8**).
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getAttributePool(padID)
* API >= 1.2.8
returns the attribute pool of a pad
*Example returns:*
* `{ "code":0,
"message":"ok",
"data": {
"pool":{
"numToAttrib":{
"0":["author","a.X4m8bBWJBZJnWGSh"],
"1":["author","a.TotfBPzov54ihMdH"],
"2":["author","a.StiblqrzgeNTbK05"],
"3":["bold","true"]
},
"attribToNum":{
"author,a.X4m8bBWJBZJnWGSh":0,
"author,a.TotfBPzov54ihMdH":1,
"author,a.StiblqrzgeNTbK05":2,
"bold,true":3
},
"nextNum":4
}
}
}`
* `{"code":1,"message":"padID does not exist","data":null}`
#### getRevisionChangeset(padID, [rev])
* API >= 1.2.8
get the changeset at a given revision, or last revision if 'rev' is not defined.
*Example returns:*
* `{ "code" : 0,
"message" : "ok",
"data" : "Z:1>6b|5+6b$Welcome to Etherpad!\n\nThis pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!\n\nGet involved with Etherpad at https://etherpad.org\n"
}`
* `{"code":1,"message":"padID does not exist","data":null}`
* `{"code":1,"message":"rev is higher than the head revision of the pad","data":null}`
#### createDiffHTML(padID, startRev, endRev)
* API >= 1.2.7
returns an object of diffs from 2 points in a pad
*Example returns:*
* `{"code":0,"message":"ok","data":{"html":"<style>\n.authora_HKIv23mEbachFYfH {background-color: #a979d9}\n.authora_n4gEeMLsv1GivNeh {background-color: #a9b5d9}\n.removed {text-decoration: line-through; -ms-filter:'progid:DXImageTransform.Microsoft.Alpha(Opacity=80)'; filter: alpha(opacity=80); opacity: 0.8; }\n</style>Welcome to Etherpad!<br><br>This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents!<br><br>Get involved with Etherpad at <a href=\"http&#x3a;&#x2F;&#x2F;etherpad&#x2e;org\">http:&#x2F;&#x2F;etherpad.org</a><br><span class=\"authora_HKIv23mEbachFYfH\">aw</span><br><br>","authors":["a.HKIv23mEbachFYfH",""]}}`
* `{"code":4,"message":"no or wrong API Key","data":null}`
#### restoreRevision(padId, rev, [authorId])
* API >= 1.2.11
* `authorId` in API >= 1.3.0
* Example returns:*
* `{code:0, message:"ok", data:null}`
* `{code: 1, message:"padID does not exist", data: null}`
### Chat
#### getChatHistory(padID, [start, end])
* API >= 1.2.7
returns
* a part of the chat history, when `start` and `end` are given
* the whole chat history, when no extra parameters are given
*Example returns:*
* `{"code":0,"message":"ok","data":{"messages":[{"text":"foo","userId":"a.foo","time":1359199533759,"userName":"test"},{"text":"bar","userId":"a.foo","time":1359199534622,"userName":"test"}]}}`
* `{code: 1, message:"start is higher or equal to the current chatHead", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getChatHead(padID)
* API >= 1.2.7
returns the chatHead (last number of the last chat-message) of the pad
*Example returns:*
* `{code: 0, message:"ok", data: {chatHead: 42}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### appendChatMessage(padID, text, authorID [, time])
* API >= 1.2.12
creates a chat message, saves it to the database and sends it to all connected clients of this pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"text is no string", data: null}`
### Pad
Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and it's forbidden for normal pads to include a $ in the name.
#### createPad(padID, [text], [authorId])
* API >= 1
* `authorId` in API >= 1.3.0
creates a new (non-group) pad. Note that if you need to create a group Pad, you should call **createGroupPad**.
You get an error message if you use one of the following characters in the padID: "/", "?", "&" or "#".
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does already exist", data: null}`
* `{code: 1, message:"malformed padID: Remove special characters", data: null}`
#### getRevisionsCount(padID)
* API >= 1
returns the number of revisions of this pad
*Example returns:*
* `{code: 0, message:"ok", data: {revisions: 56}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getSavedRevisionsCount(padID)
* API >= 1.2.11
returns the number of saved revisions of this pad
*Example returns:*
* `{code: 0, message:"ok", data: {savedRevisions: 42}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### listSavedRevisions(padID)
* API >= 1.2.11
returns the list of saved revisions of this pad
*Example returns:*
* `{code: 0, message:"ok", data: {savedRevisions: [2, 42, 1337]}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### saveRevision(padID [, rev])
* API >= 1.2.11
saves a revision
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### padUsersCount(padID)
* API >= 1
returns the number of user that are currently editing this pad
*Example returns:*
* `{code: 0, message:"ok", data: {padUsersCount: 5}}`
#### padUsers(padID)
* API >= 1.1
returns the list of users that are currently editing this pad
*Example returns:*
* `{code: 0, message:"ok", data: {padUsers: [{colorId:"#c1a9d9","name":"username1","timestamp":1345228793126,"id":"a.n4gEeMLsvg12452n"},{"colorId":"#d9a9cd","name":"Hmmm","timestamp":1345228796042,"id":"a.n4gEeMLsvg12452n"}]}}`
* `{code: 0, message:"ok", data: {padUsers: []}}`
#### deletePad(padID)
* API >= 1
deletes a pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### copyPad(sourceID, destinationID[, force=false])
* API >= 1.2.8
copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### copyPadWithoutHistory(sourceID, destinationID, [force=false], [authorId])
* API >= 1.2.15
* `authorId` in API >= 1.3.0
copies a pad without copying the history and chat. If force is true and the destination pad exists, it will be overwritten.
Note that all the revisions will be lost! In most of the cases one should use `copyPad` API instead.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### movePad(sourceID, destinationID[, force=false])
* API >= 1.2.8
moves a pad. If force is true and the destination pad exists, it will be overwritten.
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getReadOnlyID(padID)
* API >= 1
returns the read only link of a pad
*Example returns:*
* `{code: 0, message:"ok", data: {readOnlyID: "r.s8oes9dhwrvt0zif"}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getPadID(readOnlyID)
* API >= 1.2.10
returns the id of a pad which is assigned to the readOnlyID
*Example returns:*
* `{code: 0, message:"ok", data: {padID: "p.s8oes9dhwrvt0zif"}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### setPublicStatus(padID, publicStatus)
* API >= 1
sets a boolean for the public status of a group pad
*Example returns:*
* `{code: 0, message:"ok", data: null}`
* `{code: 1, message:"padID does not exist", data: null}`
* `{code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}`
#### getPublicStatus(padID)
* API >= 1
return true of false
*Example returns:*
* `{code: 0, message:"ok", data: {publicStatus: true}}`
* `{code: 1, message:"padID does not exist", data: null}`
* `{code: 1, message:"You can only get/set the publicStatus of pads that belong to a group", data: null}`
#### listAuthorsOfPad(padID)
* API >= 1
returns an array of authors who contributed to this pad
*Example returns:*
* `{code: 0, message:"ok", data: {authorIDs : ["a.s8oes9dhwrvt0zif", "a.akf8finncvomlqva"]}`
* `{code: 1, message:"padID does not exist", data: null}`
#### getLastEdited(padID)
* API >= 1
returns the timestamp of the last revision of the pad
*Example returns:*
* `{code: 0, message:"ok", data: {lastEdited: 1340815946602}}`
* `{code: 1, message:"padID does not exist", data: null}`
#### sendClientsMessage(padID, msg)
* API >= 1.1
sends a custom message of type `msg` to the pad
*Example returns:*
```json
{"code": 0, "message":"ok", "data": {}}
```
```json
{"code": 1, "message":"padID does not exist", "data": null}
```
#### checkToken()
* API >= 1.2
returns ok when the current api token is valid
*Example returns:*
```json
{"code":0,"message":"ok","data":null}
```
```json
{"code":4,"message":"no or wrong API Key","data":null}
```
### Pads
#### listAllPads()
* API >= 1.2.1
lists all pads on this epl instance
*Example returns:*
```json
{"code": 0, "message":"ok", "data": {"padIDs": ["testPad", "thePadsOfTheOthers"]}}
```
### Global
#### getStats()
* API >= 1.2.14
get stats of the etherpad instance
*Example returns*
```json
{"code":0,"message":"ok","data":{"totalPads":3,"totalSessions": 2,"totalActivePads": 1}}
```

3
doc/api/index.md Normal file
View file

@ -0,0 +1,3 @@
# API documentation
This part of the documentation is about the API of Etherpad. It is intended for developers who want to write applications that interact with Etherpad instances or plugins.

22
doc/api/pluginfw.md Normal file
View file

@ -0,0 +1,22 @@
# Plugin Framework
`require("ep_etherpad-lite/static/js/plugingfw/plugins")`
## plugins.update
`require("ep_etherpad-lite/static/js/plugingfw/plugins").update()` will use npm
to list all installed modules and read their ep.json files, registering the
contained hooks. A hook registration is a pair of a hook name and a function
reference (filename for require() plus function name)
## hooks.callAll
`require("ep_etherpad-lite/static/js/plugingfw/hooks").callAll("hook_name",
{argname:value})` will call all hook functions registered for `hook_name` with
`{argname:value}`.
## hooks.aCallAll
?
## ...

46
doc/api/toolbar.md Normal file
View file

@ -0,0 +1,46 @@
# Toolbar controller
src/node/utils/toolbar.js
## button(opts)
* {Object} `opts`
* `command` - this command fill be fired on the editbar on click
* `localizationId` - will be set as `data-l10-id`
* `class` - here you can add additional classes to the button
Returns: {Button}
Example:
```
var orderedlist = toolbar.button({
command: "insertorderedlist",
localizationId: "pad.toolbar.ol.title",
class: "buttonicon buttonicon-insertorderedlist"
})
```
You can also create buttons with text:
```
var myButton = toolbar.button({
command: "myButton",
localizationId: "myPlugin.toolbar.myButton",
class: "buttontext"
})
```
## selectButton(opts)
* {Object} `opts`
* `id` - id of the menu item
* `selectId` - id of the select element
* `command` - this command fill be fired on the editbar on change
Returns: {SelectButton}
## SelectButton.addOption(value, text, attributes)
* {String} value - The value of this option
* {String} text - the label text used for this option
* {Object} attributes - any additional html attributes go here (e.g. `data-l10n-id`)
## registerButton(name, item)
* {String} name - used to reference the item in the toolbar config in settings.json
* {Button|SelectButton} item - the button to add

18
doc/cookies.md Normal file
View file

@ -0,0 +1,18 @@
# Cookies
Cookies used by Etherpad.
| Name | Sample value | Domain | Path | Expires/max-age | Http-only | Secure | Usage description |
|-------------------|----------------------------------|-------------|------|-----------------|-----------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| express_sid | s%3A7yCNjRmTW8ylGQ53I2IhOwYF9... | example.org | / | Session | true | true | Session ID of the [Express web framework](https://expressjs.com). When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set `trustProxy: true` in `settings.json`. Set in [webaccess.js#L131](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/hooks/express/webaccess.js#L131). |
| language | en | example.org | / | Session | false | true | The language of the UI (e.g.: `en-GB`, `it`). Set in [pad_editor.js#L111](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_editor.js#L111). |
| prefs / prefsHttp | %7B%22epThemesExtTheme%22... | example.org | /p | year 3000 | false | true | Client-side preferences (e.g.: font family, chat always visible, show authorship colors, ...). Set in [pad_cookie.js#L49](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad_cookie.js#L49). `prefs` is used if Etherpad is accessed over HTTPS, `prefsHttp` if accessed over HTTP. For more info see https://github.com/ether/etherpad-lite/issues/3179. |
| token | t.tFzkihhhBf4xKEpCK3PU | example.org | / | 60 days | false | true | A random token representing the author, of the form `t.randomstring_of_lenght_20`. The random string is generated by the client, at ([pad.js#L55-L66](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L55-L66)). This cookie is always set by the client (at [pad.js#L153-L158](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/static/js/pad.js#L153-L158)) without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at [SecurityManager.js#L33](https://github.com/ether/etherpad-lite/blob/01497aa399690e44393e91c19917d11d025df71b/src/node/db/SecurityManager.js#L33). |
For more info, visit the related discussion at https://github.com/ether/etherpad-lite/issues/3563.
Etherpad HTTP API clients may make use (if they choose so) to send another cookie:
| Name | Sample value | Domain | Usage description |
|-----------|------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sessionID | s.1c70968b333b25476a2c7bdd0e0bed17 | example.org | Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. More info - https://github.com/ether/etherpad-lite/blob/develop/doc/api/http_api.md#session |

19
doc/demo.md Normal file
View file

@ -0,0 +1,19 @@
# Demo of Etherpad
This is a demo of Etherpad. It shows how to use Etherpad and what it can do.
## The toolbar
![The toolbar](/etherpad_basic.png)
## The pad
![The pad](/etherpad_demo.gif)
## Etherpad with a virtual webcam
![Etherpad full features](/etherpad_full_features.png)
## Etherpad skin variants
![Etherpad skin variants](/etherpad_skin_variants.gif)

344
doc/docker.md Normal file
View file

@ -0,0 +1,344 @@
# Docker
The official Docker image is available on https://hub.docker.com/r/etherpad/etherpad.
## Downloading from Docker Hub
If you are ok downloading a [prebuilt image from Docker Hub](https://hub.docker.com/r/etherpad/etherpad), these are the commands:
```bash
# gets the latest published version
docker pull etherpad/etherpad
# gets a specific version
docker pull etherpad/etherpad:1.8.0
```
## Build a personalized container
If you want to use a personalized settings file, **you will have to rebuild your image**.
All of the following instructions are as a member of the `docker` group.
By default, the Etherpad Docker image is built and run in `production` mode: no development dependencies are installed, and asset bundling speeds up page load time.
### Rebuilding with custom settings
Edit `<BASEDIR>/settings.json.docker` at your will. When rebuilding the image, this file will be copied inside your image and renamed to `settings.json`.
**Each configuration parameter can also be set via an environment variable**, using the syntax `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`. For details, refer to `settings.json.template`.
### Rebuilding including some plugins
If you want to install some plugins in your container, it is sufficient to list them in the ETHERPAD_PLUGINS build variable.
The variable value has to be a space separated, double quoted list of plugin names (see examples).
Some plugins will need personalized settings. Just refer to the previous section, and include them in your custom `settings.json.docker`.
### Rebuilding including export functionality for DOC/PDF/ODT
If you want to be able to export your pads to DOC/PDF/ODT files, you can install
either Abiword or Libreoffice via setting a build variable.
#### Via Abiword
For installing Abiword, set the `INSTALL_ABIWORD` build variable to any value.
Also, you will need to configure the path to the abiword executable
via setting the `abiword` property in `<BASEDIR>/settings.json.docker` to
`/usr/bin/abiword` or via setting the environment variable `ABIWORD` to
`/usr/bin/abiword`.
#### Via Libreoffice
For installing Libreoffice instead, set the `INSTALL_SOFFICE` build variable
to any value.
Also, you will need to configure the path to the libreoffice executable
via setting the `soffice` property in `<BASEDIR>/settings.json.docker` to
`/usr/bin/soffice` or via setting the environment variable `SOFFICE` to
`/usr/bin/soffice`.
### Examples
Build a Docker image from the currently checked-out code:
```bash
docker build --tag <YOUR_USERNAME>/etherpad .
```
Include two plugins in the container:
```bash
docker build --build-arg ETHERPAD_PLUGINS="ep_comments_page ep_author_neat" --tag <YOUR_USERNAME>/etherpad .
```
## Running your instance:
To run your instance:
```bash
docker run --detach --publish <DESIRED_PORT>:9001 <YOUR_USERNAME>/etherpad
```
And point your browser to `http://<YOUR_IP>:<DESIRED_PORT>`
## Options available by default
The `settings.json.docker` available by default allows to control almost every setting via environment variables.
### General
| Variable | Description | Default |
| ------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TITLE` | The name of the instance | `Etherpad` |
| `FAVICON` | favicon default name, or a fully specified URL to your own favicon | `favicon.ico` |
| `DEFAULT_PAD_TEXT` | The default text of a pad | `Welcome to Etherpad! This pad text is synchronized as you type, so that everyone viewing this page sees the same text. This allows you to collaborate seamlessly on documents! Get involved with Etherpad at https://etherpad.org` |
| `IP` | IP which etherpad should bind at. Change to `::` for IPv6 | `0.0.0.0` |
| `PORT` | port which etherpad should bind at | `9001` |
| `ADMIN_PASSWORD` | the password for the `admin` user (leave unspecified if you do not want to create it) | |
| `USER_PASSWORD` | the password for the first user `user` (leave unspecified if you do not want to create it) | |
### Database
| Variable | Description | Default |
| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `DB_TYPE` | a database supported by https://www.npmjs.com/package/ueberdb2 | not set, thus will fall back to `DirtyDB` (please choose one instead) |
| `DB_HOST` | the host of the database | |
| `DB_PORT` | the port of the database | |
| `DB_NAME` | the database name | |
| `DB_USER` | a database user with sufficient permissions to create tables | |
| `DB_PASS` | the password for the database username | |
| `DB_CHARSET` | the character set for the tables (only required for MySQL) | |
| `DB_FILENAME` | in case `DB_TYPE` is `DirtyDB` or `sqlite`, the database file. | `var/dirty.db`, `var/etherpad.sq3` |
If your database needs additional settings, you will have to use a personalized `settings.json.docker` and rebuild the container (or otherwise put the updated `settings.json` inside your image).
### Pad Options
| Variable | Description | Default |
| -------------------------------- | ----------- | ------- |
| `PAD_OPTIONS_NO_COLORS` | | `false` |
| `PAD_OPTIONS_SHOW_CONTROLS` | | `true` |
| `PAD_OPTIONS_SHOW_CHAT` | | `true` |
| `PAD_OPTIONS_SHOW_LINE_NUMBERS` | | `true` |
| `PAD_OPTIONS_USE_MONOSPACE_FONT` | | `false` |
| `PAD_OPTIONS_USER_NAME` | | `null` |
| `PAD_OPTIONS_USER_COLOR` | | `null` |
| `PAD_OPTIONS_RTL` | | `false` |
| `PAD_OPTIONS_ALWAYS_SHOW_CHAT` | | `false` |
| `PAD_OPTIONS_CHAT_AND_USERS` | | `false` |
| `PAD_OPTIONS_LANG` | | `null` |
### Shortcuts
| Variable | Description | Default |
| ----------------------------------- | ------------------------------------------------ | ------- |
| `PAD_SHORTCUTS_ENABLED_ALT_F9` | focus on the File Menu and/or editbar | `true` |
| `PAD_SHORTCUTS_ENABLED_ALT_C` | focus on the Chat window | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_S` | save a revision | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_Z` | undo/redo | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_Y` | redo | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_I` | italic | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_B` | bold | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_U` | underline | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_H` | backspace | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_5` | strike through | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_1` | ordered list | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_2` | shows a gritter popup showing a line author | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_L` | unordered list | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_N` | ordered list | `true` |
| `PAD_SHORTCUTS_ENABLED_CMD_SHIFT_C` | clear authorship | `true` |
| `PAD_SHORTCUTS_ENABLED_DELETE` | | `true` |
| `PAD_SHORTCUTS_ENABLED_RETURN` | | `true` |
| `PAD_SHORTCUTS_ENABLED_ESC` | in mozilla versions 14-19 avoid reconnecting pad | `true` |
| `PAD_SHORTCUTS_ENABLED_TAB` | indent | `true` |
| `PAD_SHORTCUTS_ENABLED_CTRL_HOME` | scroll to top of pad | `true` |
| `PAD_SHORTCUTS_ENABLED_PAGE_UP` | | `true` |
| `PAD_SHORTCUTS_ENABLED_PAGE_DOWN` | | `true` |
### Skins
You can use the UI skin variants builder at `/p/test#skinvariantsbuilder`
For the colibris skin only, you can choose how to render the three main containers:
* toolbar (top menu with icons)
* editor (containing the text of the pad)
* background (area outside of editor, mostly visible when using page style)
For each of the 3 containers you can choose 4 color combinations:
* super-light
* light
* dark
* super-dark
For the editor container, you can also make it full width by adding `full-width-editor` variant (by default editor is rendered as a page, with a max-width of 900px).
| Variable | Description | Default |
| --------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `SKIN_NAME` | either `no-skin`, `colibris` or an existing directory under `src/static/skins` | `colibris` |
| `SKIN_VARIANTS` | multiple skin variants separated by spaces | `super-light-toolbar super-light-editor light-background` |
### Logging
| Variable | Description | Default |
| -------------------- | ---------------------------------------------------- | ------- |
| `LOGLEVEL` | valid values are `DEBUG`, `INFO`, `WARN` and `ERROR` | `INFO` |
| `DISABLE_IP_LOGGING` | Privacy: disable IP logging | `false` |
### Advanced
| Variable | Description | Default |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|
| `COOKIE_SAME_SITE` | Value of the SameSite cookie property. | `"Lax"` |
| `COOKIE_SESSION_LIFETIME` | How long (ms) a user can be away before they must log in again. | `864000000` (10 days) |
| `COOKIE_SESSION_REFRESH_INTERVAL` | How often (ms) to write the latest cookie expiration time. | `86400000` (1 day) |
| `SHOW_SETTINGS_IN_ADMIN_PAGE` | hide/show the settings.json in admin page | `true` |
| `TRUST_PROXY` | set to `true` if you are using a reverse proxy in front of Etherpad (for example: Traefik for SSL termination via Let's Encrypt). This will affect security and correctness of the logs if not done | `false` |
| `IMPORT_MAX_FILE_SIZE` | maximum allowed file size when importing a pad, in bytes. | `52428800` (50 MB) |
| `IMPORT_EXPORT_MAX_REQ_PER_IP` | maximum number of import/export calls per IP. | `10` |
| `IMPORT_EXPORT_RATE_LIMIT_WINDOW` | the call rate for import/export requests will be estimated in this time window (in milliseconds) | `90000` |
| `COMMIT_RATE_LIMIT_DURATION` | duration of the rate limit window for commits by individual users/IPs (in seconds) | `1` |
| `COMMIT_RATE_LIMIT_POINTS` | maximum number of changes per IP to allow during the rate limit window | `10` |
| `SUPPRESS_ERRORS_IN_PAD_TEXT` | Should we suppress errors from being visible in the default Pad Text? | `false` |
| `REQUIRE_SESSION` | If this option is enabled, a user must have a session to access pads. This effectively allows only group pads to be accessed. | `false` |
| `EDIT_ONLY` | Users may edit pads but not create new ones. Pad creation is only via the API. This applies both to group pads and regular pads. | `false` |
| `MINIFY` | If true, all css & js will be minified before sending to the client. This will improve the loading performance massively, but makes it difficult to debug the javascript/css | `true` |
| `MAX_AGE` | How long may clients use served javascript code (in seconds)? Not setting this may cause problems during deployment. Set to 0 to disable caching. | `21600` (6 hours) |
| `ABIWORD` | Absolute path to the Abiword executable. Abiword is needed to get advanced import/export features of pads. Setting it to null disables Abiword and will only allow plain text and HTML import/exports. | `null` |
| `SOFFICE` | This is the absolute path to the soffice executable. LibreOffice can be used in lieu of Abiword to export pads. Setting it to null disables LibreOffice exporting. | `null` |
| `ALLOW_UNKNOWN_FILE_ENDS` | Allow import of file types other than the supported ones: txt, doc, docx, rtf, odt, html & htm | `true` |
| `REQUIRE_AUTHENTICATION` | This setting is used if you require authentication of all users. Note: "/admin" always requires authentication. | `false` |
| `REQUIRE_AUTHORIZATION` | Require authorization by a module, or a user with is_admin set, see below. | `false` |
| `AUTOMATIC_RECONNECTION_TIMEOUT` | Time (in seconds) to automatically reconnect pad when a "Force reconnect" message is shown to user. Set to 0 to disable automatic reconnection. | `0` |
| `FOCUS_LINE_PERCENTAGE_ABOVE` | Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line above of the viewport. Set to 0 to disable extra scrolling | `0` |
| `FOCUS_LINE_PERCENTAGE_BELOW` | Percentage of viewport height to be additionally scrolled. e.g. 0.5, to place caret line in the middle of viewport, when user edits a line below of the viewport. Set to 0 to disable extra scrolling | `0` |
| `FOCUS_LINE_PERCENTAGE_ARROW_UP` | Percentage of viewport height to be additionally scrolled when user presses arrow up in the line of the top of the viewport. Set to 0 to let the scroll to be handled as default by Etherpad | `0` |
| `FOCUS_LINE_DURATION` | Time (in milliseconds) used to animate the scroll transition. Set to 0 to disable animation | `0` |
| `FOCUS_LINE_CARET_SCROLL` | Flag to control if it should scroll when user places the caret in the last line of the viewport | `false` |
| `SOCKETIO_MAX_HTTP_BUFFER_SIZE` | The maximum size (in bytes) of a single message accepted via Socket.IO. If a client sends a larger message, its connection gets closed to prevent DoS (memory exhaustion) attacks. | `10000` |
| `LOAD_TEST` | Allow Load Testing tools to hit the Etherpad Instance. WARNING: this will disable security on the instance. | `false` |
| `DUMP_ON_UNCLEAN_EXIT` | Enable dumping objects preventing a clean exit of Node.js. WARNING: this has a significant performance impact. | `false` |
| `EXPOSE_VERSION` | Expose Etherpad version in the web interface and in the Server http header. Do not enable on production machines. | `false` |
### Add plugin configurations
It is possible to add arbitrary configurations for plugins by setting the `EP__PLUGIN__<PLUGIN_NAME>__<CONFIG_NAME>` environment variable. It is important to separate paths with a double underscore `__`.
For example, to configure the `ep_comments` plugin to use the `comments` database, you can set the following environment variables:
The original config looks like this:
```json
"ep_comments_page": {
"highlightSelectedText": true
},
```
We have two paths ep_comments_page and highlightSelectedText, so we need to set the following environment variable:
```yaml
EP__ep_comments_page__highlightSelectedText=true
```
### Examples
Use a Postgres database, no admin user enabled:
```shell
docker run -d \
--name etherpad \
-p 9001:9001 \
-e 'DB_TYPE=postgres' \
-e 'DB_HOST=db.local' \
-e 'DB_PORT=4321' \
-e 'DB_NAME=etherpad' \
-e 'DB_USER=dbusername' \
-e 'DB_PASS=mypassword' \
etherpad/etherpad
```
Run enabling the administrative user `admin`:
```shell
docker run -d \
--name etherpad \
-p 9001:9001 \
-e 'ADMIN_PASSWORD=supersecret' \
etherpad/etherpad
```
Run a test instance running DirtyDB on a persistent volume:
```shell
docker run -d \
-v etherpad_data:/opt/etherpad-lite/var \
-p 9001:9001 \
etherpad/etherpad
```
## Ready to use Docker Compose
```yaml
version: "3.8"
# Add this file to extend the docker-compose setup, e.g.:
# docker-compose build --no-cache
# docker-compose up -d --build --force-recreate
services:
app:
build:
context: .
args:
ETHERPAD_PLUGINS:
# change from development to production if needed
target: development
tty: true
stdin_open: true
volumes:
# no volume mapping of node_modules as otherwise the build-time installed plugins will be overwritten with the mount
# the same applies to package.json and pnpm-lock.yaml in root dir as these would also get overwritten and build time installed plugins will be removed
- ./src:/opt/etherpad-lite/src
- ./bin:/opt/etherpad-lite/bin
depends_on:
- postgres
environment:
# change from development to production if needed
NODE_ENV: development
ADMIN_PASSWORD: ${DOCKER_COMPOSE_APP_DEV_ADMIN_PASSWORD}
DB_CHARSET: ${DOCKER_COMPOSE_APP_DEV_ENV_DB_CHARSET:-utf8mb4}
DB_HOST: postgres
DB_NAME: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_DATABASE:?}
DB_PASS: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_PASSWORD:?}
DB_PORT: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_PORT:-5432}
DB_TYPE: "postgres"
DB_USER: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_USER:?}
# For now, the env var DEFAULT_PAD_TEXT cannot be unset or empty; it seems to be mandatory in the latest version of etherpad
DEFAULT_PAD_TEXT: ${DOCKER_COMPOSE_APP_DEV_ENV_DEFAULT_PAD_TEXT:- }
DISABLE_IP_LOGGING: ${DOCKER_COMPOSE_APP_DEV_ENV_DISABLE_IP_LOGGING:-true}
SOFFICE: ${DOCKER_COMPOSE_APP_DEV_ENV_SOFFICE:-null}
TRUST_PROXY: ${DOCKER_COMPOSE_APP_DEV_ENV_TRUST_PROXY:-true}
restart: always
ports:
- "${DOCKER_COMPOSE_APP_DEV_PORT_PUBLISHED:-9001}:${DOCKER_COMPOSE_APP_DEV_PORT_TARGET:-9001}"
postgres:
image: postgres:15-alpine
# Pass config parameters to the mysql server.
# Find more information below when you need to generate the ssl-relevant file your self
environment:
POSTGRES_DB: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_DATABASE:?}
POSTGRES_PASSWORD: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_PASSWORD:?}
POSTGRES_PORT: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_PORT:-5432}
POSTGRES_USER: ${DOCKER_COMPOSE_POSTGRES_DEV_ENV_POSTGRES_USER:?}
PGDATA: /var/lib/postgresql/data/pgdata
restart: always
# Exposing the port is not needed unless you want to access this database instance from the host.
# Be careful when other postgres docker container are running on the same port
# ports:
# - "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data/pgdata
volumes:
postgres_data:
```

15
doc/documentation.md Normal file
View file

@ -0,0 +1,15 @@
# About this Documentation
<!-- type=misc -->
The goal of this documentation is to comprehensively explain Etherpad,
both from a reference and a conceptual point of view.
Where appropriate, property types, method arguments, and the arguments
provided to event handlers are detailed in a list underneath the topic
heading.
Every `.html` file is generated based on the corresponding
`.md` file in the `doc/api/` folder in the source tree. The
documentation is generated using the `src/bin/doc/generate.js` program.
The HTML template is located at `doc/template.html`.

39
doc/index.md Normal file
View file

@ -0,0 +1,39 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "Etherpad"
text: "Next generation collaborative document editing"
tagline: Make your documents come alive
image:
src: /favicon.ico
alt: Etherpad hero image
actions:
- theme: brand
text: Install
link: /docker
- theme: alt
text: API documentation
link: /api/
features:
- icon: ⚡️
title: Real-time editing
details: Collaborate with others in real-time. See changes as they happen in an instant
- icon: 🛠️
title: Extensible plugin framework
details: Add new features to Etherpad with plugins. Create your own or use existing ones
- icon: 💬
title: Real-time chat
details: Communicate with others while editing. Discuss changes and share ideas
- icon: 📝
title: Rich text editing
details: Format text, add images, and more. Create beautiful documents with ease
- icon: 🌐
title: Multi-language support
details: Use Etherpad in your preferred language. Localize the interface and documents
- icon: 📦
title: Easy to install
details: Get started quickly with Docker. Install Etherpad with a single command
---

114
doc/localization.md Normal file
View file

@ -0,0 +1,114 @@
# Localization
Etherpad provides a multi-language user interface, that's apart from your users' content, so users from different countries can collaborate on a single document, while still having the user interface displayed in their mother tongue.
## Translating
We rely on https://translatewiki.net to handle the translation process for us, so if you'd like to help...
1. Sign up at https://translatewiki.net
2. Visit our [TWN project page](https://translatewiki.net/wiki/Translating:Etherpad_lite)
3. Click on `Translate Etherpad lite interface`
4. Choose a target language, you'd like to translate our interface to, and hit `Fetch`
5. Start translating!
Translations will be send back to us regularly and will eventually appear in the next release.
## Implementation
### Server-side
`/src/locales` contains files for all supported languages which contain the translated strings. Translation files are simple `*.json` files and look like this:
```json
{ "pad.modals.connected": "Connecté."
, "pad.modals.uderdup": "Ouvrir dans une nouvelle fenêtre."
, "pad.toolbar.unindent.title": "Dèsindenter"
, "pad.toolbar.undo.title": "Annuler (Ctrl-Z)"
, "timeslider.pageTitle": "{{appTitle}} Curseur temporel"
, ...
}
```
Each translation consists of a key (the id of the string that is to be translated) and the translated string. Terms in curly braces must not be touched but left as they are, since they represent a dynamically changing part of the string like a variable. Imagine a message welcoming a user: `Welcome, {{userName}}!` would be translated as `Ahoy, {{userName}}!` in pirate.
### Client-side
We use a `language` cookie to save your language settings if you change them. If you don't, we autodetect your locale using information from your browser. Then, the preferred language is fed into a library called [html10n.js](https://github.com/marcelklehr/html10n.js), which loads the appropriate translations and applies them to our templates. Its features include translation params, pluralization, include rules and a nice javascript API.
## Localizing plugins
### 1. Mark the strings to translate
In the template files of your plugin, change all hardcoded messages/strings...
from:
```html
<option value="0">Heading 1</option>
```
to:
```html
<option data-l10n-id="ep_heading.h1" value="0"></option>
```
In the javascript files of your plugin, change all hardcoded messages/strings...
from:
```js
alert ('Chat');
```
to:
```js
alert(window._('pad.chat'));
```
### 2. Create translate files in the locales directory of your plugin
* The name of the file must be the language code of the language it contains translations for (see [supported lang codes](https://joker-x.github.com/languages4translatewiki/test/); e.g. en ? English, es ? Spanish...)
* The extension of the file must be `.json`
* The default language is English, so your plugin should always provide `en.json`
* In order to avoid naming conflicts, your message keys should start with the name of your plugin followed by a dot (see below)
*ep_your-plugin/locales/en.json*
```
{ "ep_your-plugin.h1": "Heading 1"
}
```
*ep_your-plugin/locales/es.json*
```
{ "ep_your-plugin.h1": "Título 1"
}
```
Every time the http server is started, it will auto-detect your messages and merge them automatically with the core messages.
### Overwrite core messages
You can overwrite Etherpad's core messages in your plugin's locale files.
For example, if you want to replace `Chat` with `Notes`, simply add...
*ep_your-plugin/locales/en.json*
```
{ "ep_your-plugin.h1": "Heading 1"
, "pad.chat": "Notes"
}
```
## Customization for Administrators
As an Etherpad administrator, it is possible to overwrite core messages as well as messages in plugins. These include error messages, labels, and user instructions. Whereas the localization in the source code is in separate files separated by locale, an administrator's custom localizations are in `settings.json` under the `customLocaleStrings` key, with each locale separated by a sub-key underneath.
For example, let's say you want to change the text on the "New Pad" button on Etherpad's home page. If you look in `locales/en.json` (or `locales/en-gb.json`) you'll see the key for this text is `"index.newPad"`. You could add the following to `settings.json`:
```
"customLocaleStrings": {
"fr": {
"index.newPad": "Créer un document"
},
"en-gb": {
"index.newPad": "Create a document"
},
"en": {
"index.newPad": "Create a document"
}
}
```

10
doc/package.json Normal file
View file

@ -0,0 +1,10 @@
{
"devDependencies": {
"vitepress": "^1.0.2"
},
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
}
}

247
doc/plugins.md Normal file
View file

@ -0,0 +1,247 @@
# Plugins
Etherpad allows you to extend its functionality with plugins. A plugin registers
hooks (functions) for certain events (thus certain features) in Etherpad to
execute its own functionality based on these events.
Publicly available plugins can be found in the npm registry (see
<https://npmjs.org>). Etherpad's naming convention for plugins is to prefix your
plugins with `ep_`. So, e.g. it's `ep_flubberworms`. Thus you can install
plugins from npm, using `npm install --no-save --legacy-peer-deps
ep_flubberworm` in Etherpad's root directory.
You can also browse to `http://yourEtherpadInstan.ce/admin/plugins`, which will
list all installed plugins and those available on npm. It even provides
functionality to search through all available plugins.
## Folder structure
Ideally a plugin has the following folder structure:
```
ep_<plugin>/
├ .github/
│ └ workflows/
│ └ npmpublish.yml ◄─ GitHub workflow to auto-publish on push
├ static/
│ ├ css/ ◄─ static .css files
│ ├ images/ ◄─ static image files
│ ├ js/
│ │ └ index.js ◄─ static client-side code
│ └ tests/
│ ├ backend/
│ │ └ specs/ ◄─ backend (server) tests
│ └ frontend/
│ └ specs/ ◄─ frontend (client) tests
├ templates/ ◄─ EJS templates (.html, .js, .css, etc.)
├ locales/
│ ├ en.json ◄─ English (US) strings
│ └ qqq.json ◄─ optional hints for translators
├ .travis.yml ◄─ Travis CI config
├ LICENSE
├ README.md
├ ep.json ◄─ Etherpad plugin definition
├ index.js ◄─ server-side code
├ package.json
└ package-lock.json
```
If your plugin includes client-side hooks, put them in `static/js/`. If you're
adding in CSS or image files, you should put those files in `static/css/ `and
`static/image/`, respectively, and templates go into `templates/`. Translations
go into `locales/`. Tests go in `static/tests/backend/specs/` and
`static/tests/frontend/specs/`.
A Standard directory structure like this makes it easier to navigate through
your code. That said, do note, that this is not actually *required* to make your
plugin run. If you want to make use of our i18n system, you need to put your
translations into `locales/`, though, in order to have them integrated. (See
"Localization" for more info on how to localize your plugin.)
## Plugin definition
Your plugin definition goes into `ep.json`. In this file you register your hook
functions, indicate the parts of your plugin and the order of execution. (A
documentation of all available events to hook into can be found in chapter
[hooks](#all_hooks).)
```json
{
"parts": [
{
"name": "nameThisPartHoweverYouWant",
"hooks": {
"authenticate": "ep_<plugin>/<file>:functionName1",
"expressCreateServer": "ep_<plugin>/<file>:functionName2"
},
"client_hooks": {
"acePopulateDOMLine": "ep_<plugin>/<file>:functionName3"
}
}
]
}
```
A hook function registration maps a hook name to a hook function specification.
The hook function specification looks like `ep_example/file.js:functionName`. It
consists of two parts separated by a colon: a module name to `require()` and the
name of a function exported by the named module. See
[`module.exports`](https://nodejs.org/docs/latest/api/modules.html#modules_module_exports)
for how to export a function.
For the module name you can omit the `.js` suffix, and if the file is `index.js`
you can use just the directory name. You can also omit the module name entirely,
in which case it defaults to the plugin name (e.g., `ep_example`).
You can also omit the function name. If you do, Etherpad will look for an
exported function whose name matches the name of the hook (e.g.,
`authenticate`).
If either the module name or the function name is omitted (or both), the colon
may also be omitted unless the provided module name contains a colon. (So if the
module name is `C:\foo.js` then the hook function specification with the
function name omitted would be `"C:\\foo.js:"`.)
Examples: Suppose the plugin name is `ep_example`. All of the following are
equivalent, and will cause the `authorize` hook to call the `exports.authorize`
function in `index.js` from the `ep_example` plugin:
* `"authorize": "ep_example/index.js:authorize"`
* `"authorize": "ep_example/index.js:"`
* `"authorize": "ep_example/index.js"`
* `"authorize": "ep_example/index:authorize"`
* `"authorize": "ep_example/index:"`
* `"authorize": "ep_example/index"`
* `"authorize": "ep_example:authorize"`
* `"authorize": "ep_example:"`
* `"authorize": "ep_example"`
* `"authorize": ":authorize"`
* `"authorize": ":"`
* `"authorize": ""`
### Client hooks and server hooks
There are server hooks, which will be executed on the server (e.g.
`expressCreateServer`), and there are client hooks, which are executed on the
client (e.g. `acePopulateDomLine`). Be sure to not make assumptions about the
environment your code is running in, e.g. don't try to access `process`, if you
know your code will be run on the client, and likewise, don't try to access
`window` on the server...
### Styling
When you install a client-side plugin (e.g. one that implements at least one
client-side hook), the plugin name is added to the `class` attribute of the div
`#editorcontainerbox` in the main window. This gives you the opportunity of
tuning the appearance of the main UI in your plugin.
For example, this is the markup with no plugins installed:
```html
<div id="editorcontainerbox" class="">
```
and this is the contents after installing `someplugin`:
```html
<div id="editorcontainerbox" class="ep_someplugin">
```
This feature was introduced in Etherpad **1.8**.
### Parts
As your plugins become more and more complex, you will find yourself in the need
to manage dependencies between plugins. E.g. you want the hooks of a certain
plugin to be executed before (or after) yours. You can also manage these
dependencies in your plugin definition file `ep.json`:
```json
{
"parts": [
{
"name": "onepart",
"pre": [],
"post": ["ep_onemoreplugin/partone"]
"hooks": {
"storeBar": "ep_monospace/plugin:storeBar",
"getFoo": "ep_monospace/plugin:getFoo",
}
},
{
"name": "otherpart",
"pre": ["ep_my_example/somepart", "ep_otherplugin/main"],
"post": [],
"hooks": {
"someEvent": "ep_my_example/otherpart:someEvent",
"another": "ep_my_example/otherpart:another"
}
}
]
}
```
Usually a plugin will add only one functionality at a time, so it will probably
only use one `part` definition to register its hooks. However, sometimes you
have to put different (unrelated) functionalities into one plugin. For this you
will want use parts, so other plugins can depend on them.
#### pre/post
The `"pre"` and `"post"` definitions, affect the order in which parts of a
plugin are executed. This ensures that plugins and their hooks are executed in
the correct order.
`"pre"` lists parts that must be executed *before* the defining part. `"post"`
lists parts that must be executed *after* the defining part.
You can, on a basic level, think of this as double-ended dependency listing. If
you have a dependency on another plugin, you can make sure it loads before yours
by putting it in `"pre"`. If you are setting up things that might need to be
used by a plugin later, you can ensure proper order by putting it in `"post"`.
Note that it would be far more sane to use `"pre"` in almost any case, but if
you want to change config variables for another plugin, or maybe modify its
environment, `"post"` could definitely be useful.
Also, note that dependencies should *also* be listed in your package.json, so
they can be `npm install`'d automagically when your plugin gets installed.
## Package definition
Your plugin must also contain a [package definition
file](https://docs.npmjs.com/files/package.json), called package.json, in the
project root - this file contains various metadata relevant to your plugin, such
as the name and version number, author, project hompage, contributors, a short
description, etc. If you publish your plugin on npm, these metadata are used for
package search etc., but it's necessary for Etherpad plugins, even if you don't
publish your plugin.
```json
{
"name": "ep_PLUGINNAME",
"version": "0.0.1",
"description": "DESCRIPTION",
"author": "USERNAME (REAL NAME) <MAIL@EXAMPLE.COM>",
"contributors": [],
"dependencies": {"MODULE": "0.3.20"},
"engines": {"node": ">=12.17.0"}
}
```
## Templates
If your plugin adds or modifies the front end HTML (e.g. adding buttons or
changing their functions), you should put the necessary HTML code for such
operations in `templates/`, in files of type ".ejs", since Etherpad uses EJS for
HTML templating. See the following link for more information about EJS:
<https://github.com/visionmedia/ejs>.
## Writing and running front-end tests for your plugin
Etherpad allows you to easily create front-end tests for plugins.
1. Create a new folder: `%your_plugin%/static/tests/frontend/specs`
2. Put your spec file in there. (Example spec files are visible in
`%etherpad_root_folder%/frontend/tests/specs`.)
3. Visit http://yourserver.com/frontend/tests and your front-end tests will run.

0
doc/easysync/README.md → doc/public/easysync/README.md
View file

0
doc/easysync/easysync-full-description.pdf → doc/public/easysync/easysync-full-description.pdf
View file

0
doc/easysync/easysync-full-description.tex → doc/public/easysync/easysync-full-description.tex
View file

0
doc/easysync/easysync-notes.pdf → doc/public/easysync/easysync-notes.pdf
View file

0
doc/easysync/easysync-notes.tex → doc/public/easysync/easysync-notes.tex
View file

0
doc/easysync/easysync-notes.txt → doc/public/easysync/easysync-notes.txt
View file

0
doc/images/etherpad_basic.png → doc/public/etherpad_basic.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Before After
Before After

0
doc/images/etherpad_demo.gif → doc/public/etherpad_demo.gif
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 874 KiB

After

Width:  |  Height:  |  Size: 874 KiB

Before After
Before After

0
doc/images/etherpad_full_features.png → doc/public/etherpad_full_features.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 90 KiB

Before After
Before After

0
doc/images/etherpad_skin_variants.gif → doc/public/etherpad_skin_variants.gif
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 533 KiB

After

Width:  |  Height:  |  Size: 533 KiB

Before After
Before After

BIN
doc/public/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 127 KiB

19
doc/skins.md Normal file
View file

@ -0,0 +1,19 @@
# Skins
You can customize Etherpad appearance using skins.
A skin is a directory located under `static/skins/<skin_name>`, with the following contents:
* `index.js`: javascript that will be run in `/`
* `index.css`: stylesheet affecting `/`
* `pad.js`: javascript that will be run in `/p/:padid`
* `pad.css`: stylesheet affecting `/p/:padid`
* `timeslider.js`: javascript that will be run in `/p/:padid/timeslider`
* `timeslider.css`: stylesheet affecting `/p/:padid/timeslider`
* `favicon.ico`: overrides the default favicon
* `robots.txt`: overrides the default `robots.txt`
You can choose a skin changing the parameter `skinName` in `settings.json`.
Since Etherpad **1.7.5**, two skins are included:
* `no-skin`: an empty skin, leaving the default Etherpad appearance unchanged, that you can use as a guidance to develop your own.
* `colibris`: a new, experimental skin, that will become the default in Etherpad 2.0.

18
doc/stats.md Normal file
View file

@ -0,0 +1,18 @@
# Statistics
Etherpad keeps track of the goings-on inside the edit machinery. If you'd like to have a look at this, just point your browser to `/stats`.
We currently measure:
- totalUsers (counter)
- connects (meter)
- disconnects (meter)
- pendingEdits (counter)
- edits (timer)
- failedChangesets (meter)
- httpRequests (timer)
- http500 (meter)
- memoryUsage (gauge)
Under the hood, we are happy to rely on [measured](https://github.com/felixge/node-measured) for all our metrics needs.
To modify or simply access our stats in your plugin, simply `require('ep_etherpad-lite/stats')` which is a [`measured.Collection`](https://yaorg.github.io/node-measured/packages/measured-core/Collection.html).

5
make_docs.js
View file

@ -52,7 +52,4 @@ createDirIfNotExists('./out/doc/api')
exec(`asciidoctor -D out/doc doc/index.adoc */**.adoc -a VERSION=${VERSION}`)
exec(`asciidoctor -D out/doc/api ./doc/api/*.adoc -a VERSION=${VERSION}`)
copyFolderSync('./doc/easysync', './out/doc/easysync')
copyFolderSync('./doc/assets', './out/doc/assets')
copyFolderSync('./doc/easysync', './out/doc/easysync')
copyFolderSync('./doc/images', './out/doc/images')
copyFolderSync('./doc/public/', './out/doc/')

6
package.json
View file

@ -30,7 +30,9 @@
"ep_etherpad-lite": "workspace:./src"
},
"devDependencies": {
"admin": "workspace:./admin"
"admin": "workspace:./admin",
"docs": "workspace:./doc",
"ui": "workspace:./ui"
},
"engines": {
"node": ">=18.18.2",
@ -41,6 +43,6 @@
"type": "git",
"url": "https://github.com/ether/etherpad-lite.git"
},
"version": "2.0.1",
"version": "2.0.2",
"license": "Apache-2.0"
}

2519
pnpm-lock.yaml generated
View file

File diff suppressed because it is too large Load diff

2
pnpm-workspace.yaml
View file

@ -2,3 +2,5 @@ packages:
- src
- admin
- bin
- doc
- ui

21
settings.json.docker
View file

@ -650,5 +650,24 @@
/*
* Enable/Disable case-insensitive pad names.
*/
"lowerCasePadIds": "${LOWER_CASE_PAD_IDS:false}"
"lowerCasePadIds": "${LOWER_CASE_PAD_IDS:false}",
"sso": {
"issuer": "${SSO_ISSUER:http://localhost:9001}",
"clients": [
{
"client_id": "${ADMIN_CLIENT:admin_client}",
"client_secret": "${ADMIN_SECRET:admin}",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"redirect_uris": ["${ADMIN_REDIRECT:http://localhost:9001/admin/}"]
},
{
"client_id": "${USER_CLIENT:user_client}",
"client_secret": "${USER_SECRET:user}",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"redirect_uris": ["${USER_REDIRECT:http://localhost:9001/}"]
}
]
}
}

22
settings.json.template
View file

@ -650,5 +650,25 @@
/*
* Enable/Disable case-insensitive pad names.
*/
"lowerCasePadIds": false
"lowerCasePadIds": false,
"sso": {
"issuer": "${SSO_ISSUER:http://localhost:9001}",
"clients": [
{
"client_id": "${ADMIN_CLIENT:admin_client}",
"client_secret": "${ADMIN_SECRET:admin}",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"redirect_uris": ["${ADMIN_REDIRECT:http://localhost:9001/admin/}"]
},
{
"client_id": "${USER_CLIENT:user_client}",
"client_secret": "${USER_SECRET:user}",
"grant_types": ["authorization_code"],
"response_types": ["code"],
"redirect_uris": ["${USER_REDIRECT:http://localhost:9001/}"]
}
]
}
}

6
src/ep.json
View file

@ -45,6 +45,12 @@
"expressPreSession": "ep_etherpad-lite/node/hooks/express/specialpages"
}
},
{
"name": "oauth2",
"hooks": {
"expressCreateServer": "ep_etherpad-lite/node/security/OAuth2Provider"
}
},
{
"name": "padurlsanitize",
"hooks": {

22
src/locales/fa.json
View file

@ -70,13 +70,13 @@
"pad.colorpicker.cancel": "لغو",
"pad.loading": "در حال بارگذاری...",
"pad.noCookie": "کلوچک یافت نشد. لطفاً اجارهٔ استفاده از کلوچک را در مرورگر خود تأیید کنید! نشست و تنظیمات شما در میان بازدیدها ذخیره نخواهد شد. این می‌تواند به این دلیل باشد که اترپد در برخی مرورگرها در یک iFrame قرار می‌گیرد. لطفاً مطمئن شوید که اترپد در زیردامنه/دامنهٔ یکسان با iFrame والد قرار دارد",
"pad.permissionDenied": "شما اجازه‌ی دسترسی به این دفترچه یادداشت را ندارید",
"pad.permissionDenied": "شما اجازهٔ دسترسی به این دفترچه یادداشت را ندارید",
"pad.settings.padSettings": "تنظیمات دفترچه یادداشت",
"pad.settings.myView": "نمای من",
"pad.settings.stickychat": "گفتگو همیشه روی صفحه نمایش باشد",
"pad.settings.chatandusers": "نمایش چت و کاربران",
"pad.settings.colorcheck": "رنگ‌های نویسندگی",
"pad.settings.linenocheck": "شماره‌ی خطوط",
"pad.settings.linenocheck": "شمارهٔ خطوط",
"pad.settings.rtlcheck": "خواندن محتوا از راست به چپ؟",
"pad.settings.fontType": "نوع قلم:",
"pad.settings.fontType.normal": "ساده",
@ -84,7 +84,7 @@
"pad.settings.about": "درباره",
"pad.settings.poweredBy": "قدرست‌گرفته از",
"pad.importExport.import_export": "درون‌ریزی/برون‌بری",
"pad.importExport.import": "بارگذاری پرونده‌ی متنی یا سند",
"pad.importExport.import": "بارگذاری پروندهٔ متنی یا سند",
"pad.importExport.importSuccessful": "موفقیت آمیز بود!",
"pad.importExport.export": "برون‌بری این دفترچه یادداشت با قالب:",
"pad.importExport.exportetherpad": "اترپد",
@ -100,10 +100,10 @@
"pad.modals.reconnecttimer": "تلاش برای اتصال مجدد",
"pad.modals.cancel": "لغو",
"pad.modals.userdup": "در پنجره‌ای دیگر باز شد",
"pad.modals.userdup.explanation": "گمان می‌رود این دفترچه یادداشت در بیش از یک پنجره‌ی مرورگر باز شده‌است.",
"pad.modals.userdup.explanation": "گمان می‌رود این دفترچه یادداشت در بیش از یک پنجرهٔ مرورگر باز شده است.",
"pad.modals.userdup.advice": "برای استفاده از این پنجره دوباره وصل شوید.",
"pad.modals.unauth": "مجاز نیست",
"pad.modals.unauth.explanation": "دسترسی شما در حین مشاهده‌ی این برگه تغییر یافته‌است. دوباره متصل شوید.",
"pad.modals.unauth.explanation": "دسترسی شما در حین مشاهدهٔ این برگه تغییر یافته است. دوباره متصل شوید.",
"pad.modals.looping.explanation": "مشکلاتی ارتباطی با سرور همگام‌سازی وجود دارد.",
"pad.modals.looping.cause": "شاید شما از طریق یک فایروال یا پروکسی ناسازگار متصل شده‌اید.",
"pad.modals.initsocketfail": "سرور در دسترس نیست.",
@ -116,10 +116,10 @@
"pad.modals.corruptPad.explanation": "پدی که شما سعی دارید دسترسی پیدا کنید خراب است.",
"pad.modals.corruptPad.cause": "این احتمالاً به دلیل تنظیمات اشتباه کارساز یا سایر رفتارهای غیرمنتظره است. لطفاً با مدیر خدمت تماس حاصل کنید.",
"pad.modals.deleted": "پاک شد.",
"pad.modals.deleted.explanation": "این دفترچه یادداشت پاک شده‌است.",
"pad.modals.rateLimited": "نرخ محدود شده‌است.",
"pad.modals.disconnected": "اتصال شما قطع شده‌است.",
"pad.modals.disconnected.explanation": "اتصال به سرور قطع شده‌است.",
"pad.modals.deleted.explanation": "این دفترچه یادداشت پاک شده است.",
"pad.modals.rateLimited": "نرخ محدود شده است.",
"pad.modals.disconnected": "اتصال شما قطع شده است.",
"pad.modals.disconnected.explanation": "اتصال به سرور قطع شده است.",
"pad.modals.disconnected.cause": "ممکن است سرور در دسترس نباشد. اگر این مشکل باز هم رخ داد مدیر حدمت را آگاه کنید.",
"pad.share": "به اشتراک‌گذاری این دفترچه یادداشت",
"pad.share.readonly": "فقط خواندنی",
@ -159,12 +159,12 @@
"pad.savedrevs.timeslider": "شما می‌توانید نسخه‌های ذخیره شده را با دیدن نوار زمان ببنید",
"pad.userlist.entername": "نام خود را بنویسید",
"pad.userlist.unnamed": "بدون نام",
"pad.editbar.clearcolors": "رنگ نویسندگی از همه‌ی سند پاک شود؟",
"pad.editbar.clearcolors": "رنگ نویسندگی از همهٔ سند پاک شود؟",
"pad.impexp.importbutton": "هم اکنون درون‌ریزی کن",
"pad.impexp.importing": "در حال درون‌ریزی...",
"pad.impexp.confirmimport": "با درون‌ریزی یک پرونده نوشتهٔ کنونی دفترچه پاک می‌شود. آیا می‌خواهید ادامه دهید؟",
"pad.impexp.convertFailed": "ما نمی‌توانیم این پرونده را درون‌ریزی کنیم. خواهشمندیم قالب دیگری برای سندتان انتخاب کرده یا بصورت دستی آنرا کپی کنید",
"pad.impexp.padHasData": "امکان درون‌ریزی این پرونده نیست زیرا این پد تغییر کرده‌است. لطفاً در پد جدید درون‌ریزی کنید.",
"pad.impexp.padHasData": "امکان درون‌ریزی این پرونده نیست زیرا این پد تغییر کرده است. لطفاً در پد جدید درون‌ریزی کنید.",
"pad.impexp.uploadFailed": "آپلود انجام نشد، دوباره تلاش کنید",
"pad.impexp.importfailed": "درون‌ریزی انجام نشد",
"pad.impexp.copypaste": "کپی پیست کنید",

2
src/node/db/API.ts
View file

@ -355,7 +355,7 @@ exports.getChatHistory = async (padID: string, start:number, end:number) => {
throw new CustomError('end is higher than the current chatHead', 'apierror');
}
// the the whole message-log and return it to the client
// the whole message-log and return it to the client
const messages = await pad.getChatMessages(start, end);
return {messages};

52
src/node/handler/APIHandler.ts
View file

@ -21,30 +21,12 @@
import {MapArrayType} from "../types/MapType";
const absolutePaths = require('../utils/AbsolutePaths');
import fs from 'fs';
const api = require('../db/API');
import log4js from 'log4js';
const padManager = require('../db/PadManager');
const randomString = require('../utils/randomstring');
const argv = require('../utils/Cli').argv;
import createHTTPError from 'http-errors';
const apiHandlerLogger = log4js.getLogger('APIHandler');
// ensure we have an apikey
let apikey:string|null = null;
const apikeyFilename = absolutePaths.makeAbsolute(argv.apikey || './APIKEY.txt');
try {
apikey = fs.readFileSync(apikeyFilename, 'utf8');
apiHandlerLogger.info(`Api key file read from: "${apikeyFilename}"`);
} catch (e) {
apiHandlerLogger.info(
`Api key file "${apikeyFilename}" not found. Creating with random contents.`);
apikey = randomString(32);
fs.writeFileSync(apikeyFilename, apikey!, 'utf8');
}
import {Http2ServerRequest, Http2ServerResponse} from "node:http2";
import {publicKeyExported} from "../security/OAuth2Provider";
import {jwtVerify} from "jose";
// a list of all functions
const version:MapArrayType<any> = {};
@ -167,21 +149,20 @@ exports.version = version;
type APIFields = {
apikey: string;
api_key: string;
padID: string;
padName: string;
}
/**
* Handles a HTTP API call
* Handles an HTTP API call
* @param {String} apiVersion the version of the api
* @param {String} functionName the name of the called function
* @param fields the params of the called function
* @req express request object
* @res express response object
* @param req express request object
* @param res express response object
*/
exports.handle = async function (apiVersion: string, functionName: string, fields: APIFields) {
exports.handle = async function (apiVersion: string, functionName: string, fields: APIFields, req: Http2ServerRequest, res: Http2ServerResponse) {
// say goodbye if this is an unknown API version
if (!(apiVersion in version)) {
throw new createHTTPError.NotFound('no such api version');
@ -192,13 +173,20 @@ exports.handle = async function (apiVersion: string, functionName: string, field
throw new createHTTPError.NotFound('no such function');
}
// check the api key!
fields.apikey = fields.apikey || fields.api_key;
if (fields.apikey !== apikey!.trim()) {
if(!req.headers.authorization) {
throw new createHTTPError.Unauthorized('no or wrong API Key');
}
try {
await jwtVerify(req.headers.authorization!.replace("Bearer ", ""), publicKeyExported!, {algorithms: ['RS256'],
requiredClaims: ["admin"]})
} catch (e) {
throw new createHTTPError.Unauthorized('no or wrong API Key');
}
// sanitize any padIDs before continuing
if (fields.padID) {
fields.padID = await padManager.sanitizePadId(fields.padID);
@ -217,7 +205,3 @@ exports.handle = async function (apiVersion: string, functionName: string, field
// call the api function
return api[functionName].apply(this, functionParams);
};
exports.exportedForTestingOnly = {
apiKey: apikey,
};

22
src/node/hooks/express/openapi.ts
View file

@ -483,14 +483,24 @@ const generateDefinitionForVersion = (version:string, style = APIPathStyle.FLAT)
...defaultResponses,
},
securitySchemes: {
ApiKey: {
type: 'apiKey',
in: 'query',
name: 'apikey',
openid: {
type: "oauth2",
flows: {
authorizationCode: {
authorizationUrl: settings.sso.issuer+"/oidc/auth",
tokenUrl: settings.sso.issuer+"/oidc/token",
scopes: {
openid: "openid",
profile: "profile",
email: "email",
admin: "admin"
}
}
},
},
},
security: [{ApiKey: []}],
},
security: [{openid: []}],
};
// build operations
@ -657,7 +667,7 @@ exports.expressPreSession = async (hookName:string, {app}:any) => {
}
// start and bind to express
api.init();
await api.init();
app.use(apiRoot, async (req:any, res:any) => {
let response = null;
try {

6
src/node/hooks/express/static.ts
View file

@ -8,7 +8,7 @@ const minify = require('../../utils/Minify');
const path = require('path');
const plugins = require('../../../static/js/pluginfw/plugin_defs');
const settings = require('../../utils/Settings');
const CachingMiddleware = require('../../utils/caching_middleware');
import CachingMiddleware from '../../utils/caching_middleware';
const Yajsml = require('etherpad-yajsml');
// Rewrite tar to include modules with no extensions and proper rooted paths.
@ -35,7 +35,9 @@ const getTar = async () => {
exports.expressPreSession = async (hookName:string, {app}:any) => {
// Cache both minified and static.
const assetCache = new CachingMiddleware();
app.all(/\/javascripts\/(.*)/, assetCache.handle.bind(assetCache));
// Cache static assets
app.all(/\/js\/(.*)/, assetCache.handle.bind(assetCache));
app.all(/\/css\/(.*)/, assetCache.handle.bind(assetCache));
// Minify will serve static files compressed (minify enabled). It also has
// file-specific hacks for ace/require-kernel/etc.

4
src/node/hooks/express/webaccess.ts
View file

@ -169,7 +169,9 @@ const checkAccess = async (req:any, res:any, next: Function) => {
if (await aCallFirst0('authnFailure', {req, res})) return;
if (await aCallFirst0('authFailure', {req, res, next})) return;
// No plugin handled the authentication failure. Fall back to basic authentication.
//res.header('WWW-Authenticate', 'Basic realm="Protected Area"');
if (!requireAdmin) {
res.header('WWW-Authenticate', 'Basic realm="Protected Area"');
}
// Delay the error response for 1s to slow down brute force attacks.
await new Promise((resolve) => setTimeout(resolve, exports.authnFailureDelayMs));
res.status(401).send('Authentication Required');

274
src/node/security/OAuth2Provider.ts Normal file
View file

@ -0,0 +1,274 @@
import {ArgsExpressType} from "../types/ArgsExpressType";
import Provider, {Account, Configuration} from 'oidc-provider';
import {generateKeyPair, exportJWK, KeyLike} from 'jose'
import MemoryAdapter from "./OIDCAdapter";
import path from "path";
const settings = require('../utils/Settings');
import {IncomingForm} from 'formidable'
import express, {Request, Response} from 'express';
import {format} from 'url'
import {ParsedUrlQuery} from "node:querystring";
import {Http2ServerRequest, Http2ServerResponse} from "node:http2";
const configuration: Configuration = {
scopes: ['openid', 'profile', 'email'],
findAccount: async (ctx, id) => {
const users = settings.users as {
[username: string]: {
password: string;
is_admin: boolean;
}
}
const usersArray1 = Object.keys(users).map((username) => ({
username,
...users[username]
}));
const account = usersArray1.find((user) => user.username === id);
if(account === undefined) {
return undefined
}
if (account.is_admin) {
return {
accountId: id,
claims: () => ({
sub: id,
admin: true
})
} as Account
} else {
return {
accountId: id,
claims: () => ({
sub: id,
})
} as Account
}
},
ttl:{
AccessToken: 1 * 60 * 60, // 1 hour in seconds
AuthorizationCode: 10 * 60, // 10 minutes in seconds
ClientCredentials: 1 * 60 * 60, // 1 hour in seconds
IdToken: 1 * 60 * 60, // 1 hour in seconds
RefreshToken: 1 * 24 * 60 * 60, // 1 day in seconds
},
claims: {
openid: ['sub'],
email: ['email'],
profile: ['name'],
admin: ['admin']
},
cookies: {
keys: ['oidc'],
},
features:{
devInteractions: {enabled: false},
},
adapter: MemoryAdapter
};
export let publicKeyExported: KeyLike|null
export let privateKeyExported: KeyLike|null
/*
This function is used to initialize the OAuth2 provider
*/
export const expressCreateServer = async (hookName: string, args: ArgsExpressType, cb: Function) => {
const {privateKey, publicKey} = await generateKeyPair('RS256');
const privateKeyJWK = await exportJWK(privateKey);
publicKeyExported = publicKey
privateKeyExported = privateKey
const oidc = new Provider(settings.sso.issuer, {
...configuration, jwks: {
keys: [
privateKeyJWK
],
},
conformIdTokenClaims: false,
claims: {
address: ['address'],
email: ['email', 'email_verified'],
phone: ['phone_number', 'phone_number_verified'],
profile: ['birthdate', 'family_name', 'gender', 'given_name', 'locale', 'middle_name', 'name',
'nickname', 'picture', 'preferred_username', 'profile', 'updated_at', 'website', 'zoneinfo'],
},
features:{
userinfo: {enabled: true},
claimsParameter: {enabled: true},
devInteractions: {enabled: false},
resourceIndicators: {enabled: true, defaultResource(ctx) {
return ctx.origin;
},
getResourceServerInfo(ctx, resourceIndicator, client) {
return {
scope: client.scope as string,
audience: 'account',
accessTokenFormat: 'jwt',
};
},
useGrantedResource(ctx, model) {
return true;
},},
jwtResponseModes: {enabled: true},
},
clientBasedCORS: (ctx, origin, client) => {
return true
},
extraTokenClaims: async (ctx, token) => {
if(token.kind === 'AccessToken') {
// Add your custom claims here. For example:
const users = settings.users as {
[username: string]: {
password: string;
is_admin: boolean;
}
}
const usersArray1 = Object.keys(users).map((username) => ({
username,
...users[username]
}));
const account = usersArray1.find((user) => user.username === token.accountId);
return {
admin: account?.is_admin
};
}
},
clients: settings.sso.clients
});
args.app.post('/interaction/:uid', async (req: Http2ServerRequest, res: Http2ServerResponse, next:Function) => {
const formid = new IncomingForm();
try {
// @ts-ignore
const {login, password} = (await formid.parse(req))[0]
const {prompt, jti, session,cid, params, grantId} = await oidc.interactionDetails(req, res);
const client = await oidc.Client.find(params.client_id as string);
switch (prompt.name) {
case 'login': {
const users = settings.users as {
[username: string]: {
password: string;
admin: boolean;
}
}
const usersArray1 = Object.keys(users).map((username) => ({
username,
...users[username]
}));
const account = usersArray1.find((user) => user.username === login as unknown as string && user.password === password as unknown as string);
if (!account) {
res.setHeader('Content-Type', 'application/json');
res.end(JSON.stringify({error: "Invalid login"}));
}
if (account) {
await oidc.interactionFinished(req, res, {
login: {accountId: account.username}
}, {mergeWithLastSubmission: false});
}
break;
}
case 'consent': {
let grant;
if (grantId) {
// we'll be modifying existing grant in existing session
grant = await oidc.Grant.find(grantId);
} else {
// we're establishing a new grant
grant = new oidc.Grant({
accountId: session!.accountId,
clientId: params.client_id as string,
});
}
if (prompt.details.missingOIDCScope) {
// @ts-ignore
grant!.addOIDCScope(prompt.details.missingOIDCScope.join(' '));
}
if (prompt.details.missingOIDCClaims) {
grant!.addOIDCClaims(prompt.details.missingOIDCClaims as string[]);
}
if (prompt.details.missingResourceScopes) {
for (const [indicator, scope] of Object.entries(prompt.details.missingResourceScopes)) {
grant!.addResourceScope(indicator, scope.join(' '));
}
}
const result = {consent: {grantId: await grant!.save()}};
await oidc.interactionFinished(req, res, result, {
mergeWithLastSubmission: true,
});
break;
}
}
await next();
} catch (err:any) {
return res.writeHead(500).end(err.message);
}
})
args.app.get('/interaction/:uid', async (req: Request, res: Response, next: Function) => {
try {
const {
uid, prompt, params, session,
} = await oidc.interactionDetails(req, res);
params["state"] = uid
switch (prompt.name) {
case 'login': {
res.redirect(format({
pathname: '/views/login.html',
query: params as ParsedUrlQuery
}))
break
}
case 'consent': {
res.redirect(format({
pathname: '/views/consent.html',
query: params as ParsedUrlQuery
}))
break
}
default:
return res.sendFile(path.join(settings.root,'src','static', 'oidc','login.html'));
}
} catch (err) {
return next(err);
}
});
args.app.use('/views/', express.static(path.join(settings.root,'src','static', 'oidc'), {maxAge: 1000 * 60 * 60 * 24}));
/*
oidc.on('authorization.error', (ctx, error) => {
console.log('authorization.error', error);
})
oidc.on('server_error', (ctx, error) => {
console.log('server_error', error);
})
oidc.on('grant.error', (ctx, error) => {
console.log('grant.error', error);
})
oidc.on('introspection.error', (ctx, error) => {
console.log('introspection.error', error);
})
oidc.on('revocation.error', (ctx, error) => {
console.log('revocation.error', error);
})*/
args.app.use("/oidc", oidc.callback());
//cb();
}

5
src/node/security/OAuth2User.ts Normal file
View file

@ -0,0 +1,5 @@
export type OAuth2User = {
username: string;
password: string;
admin: boolean;
}

115
src/node/security/OIDCAdapter.ts Normal file
View file

@ -0,0 +1,115 @@
import {LRUCache} from 'lru-cache';
import type {Adapter, AdapterPayload} from "oidc-provider";
const options = {
max: 500,
sizeCalculation: (item:any, key:any) => {
return 1
},
// for use with tracking overall storage size
maxSize: 5000,
// how long to live in ms
ttl: 1000 * 60 * 5,
// return stale items before removing from cache?
allowStale: false,
updateAgeOnGet: false,
updateAgeOnHas: false,
}
const epochTime = (date = Date.now()) => Math.floor(date / 1000);
const storage = new LRUCache<string,AdapterPayload|string[]|string>(options);
function grantKeyFor(id: string) {
return `grant:${id}`;
}
function userCodeKeyFor(userCode:string) {
return `userCode:${userCode}`;
}
class MemoryAdapter implements Adapter{
private readonly name: string;
constructor(name:string) {
this.name = name;
}
key(id:string) {
return `${this.name}:${id}`;
}
destroy(id:string) {
const key = this.key(id);
const found = storage.get(key) as AdapterPayload;
const grantId = found && found.grantId;
storage.delete(key);
if (grantId) {
const grantKey = grantKeyFor(grantId);
(storage.get(grantKey) as string[])!.forEach(token => storage.delete(token));
storage.delete(grantKey);
}
return Promise.resolve();
}
consume(id: string) {
(storage.get(this.key(id)) as AdapterPayload)!.consumed = epochTime();
return Promise.resolve();
}
find(id: string): Promise<AdapterPayload | void | undefined> {
if (storage.has(this.key(id))){
return Promise.resolve<AdapterPayload>(storage.get(this.key(id)) as AdapterPayload);
}
return Promise.resolve<undefined>(undefined)
}
findByUserCode(userCode: string) {
const id = storage.get(userCodeKeyFor(userCode)) as string;
return this.find(id);
}
upsert(id: string, payload: {
iat: number;
exp: number;
uid: string;
kind: string;
jti: string;
accountId: string;
loginTs: number;
}, expiresIn: number) {
const key = this.key(id);
storage.set(key, payload, {ttl: expiresIn * 1000});
return Promise.resolve();
}
findByUid(uid: string): Promise<AdapterPayload | void | undefined> {
for(const [_, value] of storage.entries()){
if(typeof value ==="object" && "uid" in value && value.uid === uid){
return Promise.resolve(value);
}
}
return Promise.resolve(undefined);
}
revokeByGrantId(grantId: string): Promise<void | undefined> {
const grantKey = grantKeyFor(grantId);
const grant = storage.get(grantKey) as string[];
if (grant) {
grant.forEach((token) => storage.delete(token));
storage.delete(grantKey);
}
return Promise.resolve();
}
}
export default MemoryAdapter

5
src/node/utils/Cli.ts
View file

@ -45,10 +45,5 @@ for (let i = 0; i < argv.length; i++) {
exports.argv.sessionkey = arg;
}
// Override location of APIKEY.txt file
if (prevArg === '--apikey') {
exports.argv.apikey = arg;
}
prevArg = arg;
}

111
src/node/utils/Settings.ts
View file

@ -27,6 +27,10 @@
* limitations under the License.
*/
import {MapArrayType} from "../types/MapType";
import {SettingsNode, SettingsTree} from "./SettingsTree";
import {coerce} from "semver";
const absolutePaths = require('./AbsolutePaths');
const deepEqual = require('fast-deep-equal/es6');
const fs = require('fs');
@ -50,10 +54,12 @@ const nonSettings = [
// This is a function to make it easy to create a new instance. It is important to not reuse a
// config object after passing it to log4js.configure() because that method mutates the object. :(
const defaultLogConfig = (level:string) => ({appenders: {console: {type: 'console'}},
const defaultLogConfig = (level: string) => ({
appenders: {console: {type: 'console'}},
categories: {
default: {appenders: ['console'], level},
}});
}
});
const defaultLogLevel = 'INFO';
const initLogging = (config: any) => {
@ -336,6 +342,13 @@ exports.requireAuthentication = false;
exports.requireAuthorization = false;
exports.users = {};
/*
* This setting is used for configuring sso
*/
exports.sso = {
issuer: "http://localhost:9001"
}
/*
* Show settings in admin page, by default it is true
*/
@ -554,11 +567,16 @@ const coerceValue = (stringValue:string) => {
}
switch (stringValue) {
case 'true': return true;
case 'false': return false;
case 'undefined': return undefined;
case 'null': return null;
default: return stringValue;
case 'true':
return true;
case 'false':
return false;
case 'undefined':
return undefined;
case 'null':
return null;
default:
return stringValue;
}
};
@ -598,14 +616,16 @@ const coerceValue = (stringValue:string) => {
*
* see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter
*/
const lookupEnvironmentVariables = (obj: object) => {
const stringifiedAndReplaced = JSON.stringify(obj, (key, value) => {
const lookupEnvironmentVariables = (obj: MapArrayType<any>) => {
const replaceEnvs = (obj: MapArrayType<any>) => {
for (let [key, value] of Object.entries(obj)) {
/*
* the first invocation of replacer() is with an empty key. Just go on, or
* we would zap the entire object.
*/
if (key === '') {
return value;
obj[key] = value;
continue
}
/*
@ -616,10 +636,23 @@ const lookupEnvironmentVariables = (obj: object) => {
* The environment variable expansion syntax "${ENV_VAR}" is just a string
* of specific form, after all.
*/
if (typeof value !== 'string') {
return value;
if(key === 'undefined' || value === undefined) {
delete obj[key]
continue
}
if ((typeof value !== 'string' && typeof value !== 'object') || value === null) {
obj[key] = value;
continue
}
if (typeof obj[key] === "object") {
replaceEnvs(obj[key]);
continue
}
/*
* Let's check if the string value looks like a variable expansion (e.g.:
* "${ENV_VAR}" or "${ENV_VAR:default_value}")
@ -629,8 +662,8 @@ const lookupEnvironmentVariables = (obj: object) => {
if (match == null) {
// no match: use the value literally, without any substitution
return value;
obj[key] = value;
continue
}
/*
@ -651,14 +684,16 @@ const lookupEnvironmentVariables = (obj: object) => {
* We have to return null, because if we just returned undefined, the
* configuration item "key" would be stripped from the returned object.
*/
return null;
obj[key] = null;
continue
}
if ((envVarValue === undefined) && (defaultValue !== undefined)) {
logger.debug(`Environment variable "${envVarName}" not found for ` +
`configuration key "${key}". Falling back to default value.`);
return coerceValue(defaultValue);
obj[key] = coerceValue(defaultValue);
continue
}
// envVarName contained some value.
@ -670,14 +705,42 @@ const lookupEnvironmentVariables = (obj: object) => {
logger.debug(
`Configuration key "${key}" will be read from environment variable "${envVarName}"`);
return coerceValue(envVarValue!);
});
obj[key] = coerceValue(envVarValue!);
}
return obj
}
const newSettings = JSON.parse(stringifiedAndReplaced);
replaceEnvs(obj);
return newSettings;
// Add plugin ENV variables
/**
* If the key contains a double underscore, it's a plugin variable
* E.g.
*/
let treeEntries = new Map<string, string | undefined>
const root = new SettingsNode("EP")
for (let [env, envVal] of Object.entries(process.env)) {
if (!env.startsWith("EP")) continue
treeEntries.set(env, envVal)
}
treeEntries.forEach((value, key) => {
let pathToKey = key.split("__")
let currentNode = root
let depth = 0
depth++
currentNode.addChild(pathToKey, value!)
})
//console.log(root.collectFromLeafsUpwards())
const rooting = root.collectFromLeafsUpwards()
console.log("Rooting is", rooting.ADMIN)
obj = Object.assign(obj, rooting)
return obj;
};
/**
* - reads the JSON configuration file settingsFilename from disk
* - strips the comments
@ -718,9 +781,7 @@ const parseSettings = (settingsFilename:string, isSettings:boolean) => {
logger.info(`${settingsType} loaded from: ${settingsFilename}`);
const replacedSettings = lookupEnvironmentVariables(settings);
return replacedSettings;
return lookupEnvironmentVariables(settings);
} catch (e: any) {
logger.error(`There was an error processing your ${settingsType} ` +
`file from ${settingsFilename}: ${e.message}`);
@ -814,7 +875,8 @@ exports.reloadSettings = () => {
try {
exports.sessionKey = fs.readFileSync(sessionkeyFilename, 'utf8');
logger.info(`Session key loaded from: ${sessionkeyFilename}`);
} catch (err) { /* ignored */ }
} catch (err) { /* ignored */
}
const keyRotationEnabled = exports.cookie.keyRotationInterval && exports.cookie.sessionLifetime;
if (!exports.sessionKey && !keyRotationEnabled) {
logger.info(
@ -870,4 +932,3 @@ exports.exportedForTestingOnly = {
// initially load settings
exports.reloadSettings();

112
src/node/utils/SettingsTree.ts Normal file
View file

@ -0,0 +1,112 @@
import {MapArrayType} from "../types/MapType";
export class SettingsTree {
private children: Map<string, SettingsNode>;
constructor() {
this.children = new Map();
}
public addChild(key: string, value: string) {
this.children.set(key, new SettingsNode(key, value));
}
public removeChild(key: string) {
this.children.delete(key);
}
public getChild(key: string) {
return this.children.get(key);
}
public hasChild(key: string) {
return this.children.has(key);
}
}
export class SettingsNode {
private readonly key: string;
private value: string | number | boolean | null | undefined;
private children: MapArrayType<SettingsNode>;
constructor(key: string, value?: string | number | boolean | null | undefined) {
this.key = key;
this.value = value;
this.children = {}
}
public addChild(path: string[], value: string) {
let currentNode:SettingsNode = this;
for (let i = 0; i < path.length; i++) {
const key = path[i];
/*
Skip the current node if the key is the same as the current node's key
*/
if (key === this.key ) {
continue
}
/*
If the current node does not have a child with the key, create a new node with the key
*/
if (!currentNode.hasChild(key)) {
currentNode = currentNode.children[key] = new SettingsNode(key, this.coerceValue(value));
} else {
/*
Else move to the child node
*/
currentNode = currentNode.getChild(key);
}
}
}
public collectFromLeafsUpwards() {
let collected:MapArrayType<any> = {};
for (const key in this.children) {
const child = this.children[key];
if (child.hasChildren()) {
collected[key] = child.collectFromLeafsUpwards();
} else {
collected[key] = child.value;
}
}
return collected;
}
coerceValue = (stringValue: string) => {
// cooked from https://stackoverflow.com/questions/175739/built-in-way-in-javascript-to-check-if-a-string-is-a-valid-number
// @ts-ignore
const isNumeric = !isNaN(stringValue) && !isNaN(parseFloat(stringValue) && isFinite(stringValue));
if (isNumeric) {
// detected numeric string. Coerce to a number
return +stringValue;
}
switch (stringValue) {
case 'true':
return true;
case 'false':
return false;
case 'undefined':
return undefined;
case 'null':
return null;
default:
return stringValue;
}
};
public hasChildren() {
return Object.keys(this.children).length > 0;
}
public getChild(key: string) {
return this.children[key];
}
public hasChild(key: string) {
return this.children[key] !== undefined;
}
}

17
src/node/utils/caching_middleware.ts
View file

@ -16,14 +16,14 @@
* limitations under the License.
*/
const Buffer = require('buffer').Buffer;
const fs = require('fs');
import {Buffer} from 'node:buffer'
import fs from 'fs';
const fsp = fs.promises;
const path = require('path');
const zlib = require('zlib');
import path from 'path';
import zlib from 'zlib';
const settings = require('./Settings');
const existsSync = require('./path_exists');
const util = require('util');
import util from 'util';
/*
* The crypto module can be absent on reduced node installations.
@ -37,10 +37,10 @@ const util = require('util');
*/
const _crypto = require('crypto');
import _crypto from 'crypto';
let CACHE_DIR = path.join(settings.root, 'var/');
let CACHE_DIR: string|undefined = path.join(settings.root, 'var/');
CACHE_DIR = existsSync(CACHE_DIR) ? CACHE_DIR : undefined;
type Headers = {
@ -84,7 +84,7 @@ if (_crypto) {
should replace this.
*/
module.exports = class CachingMiddleware {
export default class CachingMiddleware {
handle(req: any, res: any, next: any) {
this._handle(req, res, next).catch((err) => next(err || new Error(err)));
}
@ -188,6 +188,7 @@ module.exports = class CachingMiddleware {
await Promise.all([
fsp.writeFile(`${CACHE_DIR}minified_${cacheKey}`, buffer).catch(() => {}),
util.promisify(zlib.gzip)(buffer)
// @ts-ignore
.then((content: string) => fsp.writeFile(`${CACHE_DIR}minified_${cacheKey}.gz`, content))
.catch(() => {}),
]);

2
src/node/utils/padDiff.ts
View file

@ -449,7 +449,7 @@ class PadDiff {
// this method is 80% like Changeset.inverse. I just changed so instead of reverting,
// it adds deletions and attribute changes to to the atext.
// it adds deletions and attribute changes to the atext.
PadDiff.prototype._createDeletionChangeset = function (cs, startAText, apool) {
};

33
src/package.json
View file

@ -38,22 +38,25 @@
"ejs": "^3.1.9",
"etherpad-require-kernel": "^1.0.16",
"etherpad-yajsml": "0.0.12",
"express": "4.18.3",
"express": "4.19.2",
"express-rate-limit": "^7.2.0",
"express-session": "npm:@etherpad/express-session@^1.18.2",
"fast-deep-equal": "^3.1.3",
"find-root": "1.1.0",
"formidable": "^3.5.1",
"http-errors": "^2.0.0",
"jose": "^5.2.4",
"js-cookie": "^3.0.5",
"jsdom": "^24.0.0",
"jsonminify": "0.4.2",
"jsonwebtoken": "^9.0.2",
"languages4translatewiki": "0.1.3",
"live-plugin-manager-pnpm": "^0.18.1",
"live-plugin-manager": "^0.19.0",
"lodash.clonedeep": "4.5.0",
"log4js": "^6.9.1",
"measured-core": "^2.0.0",
"mime-types": "^2.1.35",
"oidc-provider": "^8.4.5",
"openapi-backend": "^5.10.6",
"proxy-addr": "^2.0.7",
"rate-limiter-flexible": "^5.0.0",
@ -65,43 +68,47 @@
"socket.io": "^4.7.5",
"socket.io-client": "^4.7.5",
"superagent": "^8.1.2",
"terser": "^5.29.2",
"terser": "^5.30.3",
"threads": "^1.7.0",
"tinycon": "0.6.8",
"tsx": "^4.7.1",
"tsx": "^4.7.2",
"ueberdb2": "^4.2.63",
"underscore": "1.13.6",
"unorm": "1.6.0",
"wtfnode": "^0.9.1"
"wtfnode": "^0.9.2",
"lru-cache": "^10.2.0"
},
"bin": {
"etherpad-healthcheck": "../bin/etherpad-healthcheck",
"etherpad-lite": "node/server.ts"
},
"devDependencies": {
"@playwright/test": "^1.43.0",
"@types/async": "^3.2.24",
"@types/express": "^4.17.21",
"@types/formidable": "^3.4.5",
"@types/http-errors": "^2.0.4",
"@types/jsdom": "^21.1.6",
"@types/jsonwebtoken": "^9.0.6",
"@types/mocha": "^10.0.6",
"@types/node": "^20.11.28",
"@types/node": "^20.12.5",
"@types/oidc-provider": "^8.4.4",
"@types/semver": "^7.5.8",
"@types/sinon": "^17.0.3",
"@types/supertest": "^6.0.2",
"@types/semver": "^7.5.8",
"@types/underscore": "^1.11.15",
"eslint": "^8.57.0",
"eslint-config-etherpad": "^3.0.22",
"eslint": "^9.0.0",
"eslint-config-etherpad": "^4.0.4",
"etherpad-cli-client": "^3.0.2",
"mocha": "^10.3.0",
"mocha": "^10.4.0",
"mocha-froth": "^0.2.10",
"nodeify": "^1.0.1",
"openapi-schema-validation": "^0.4.2",
"@playwright/test": "^1.42.1",
"set-cookie-parser": "^2.6.0",
"sinon": "^17.0.1",
"split-grid": "^1.0.11",
"supertest": "^6.3.4",
"typescript": "^5.4.2"
"typescript": "^5.4.4"
},
"engines": {
"node": ">=18.18.2",
@ -125,6 +132,6 @@
"test-admin": "npx playwright test tests/frontend-new/admin-spec --workers 1",
"test-admin:ui": "npx playwright test tests/frontend-new/admin-spec --ui --workers 1"
},
"version": "2.0.1",
"version": "2.0.2",
"license": "Apache-2.0"
}

3
src/static/js/pluginfw/LinkInstaller.ts
View file

@ -1,4 +1,4 @@
import {IPluginInfo, PluginManager} from "live-plugin-manager-pnpm";
import {IPluginInfo, PluginManager} from "live-plugin-manager";
import path from "path";
import {node_modules, pluginInstallPath} from "./installer";
import {accessSync, constants, rmSync, symlinkSync, unlinkSync} from "node:fs";
@ -19,6 +19,7 @@ export class LinkInstaller {
constructor() {
this.livePluginManager = new PluginManager({
pluginsPath: pluginInstallPath,
hostRequire: undefined,
cwd: path.join(settings.root, 'src')
});
this.dependenciesMap = new Map();

2
src/static/js/pluginfw/hooks.js
View file

@ -69,7 +69,7 @@ const flatten1 = (array) => array.reduce((a, b) => a.concat(b), []);
// A hook function settles when it provides a value (via callback or return) or throws. If a hook
// function attempts to settle again (e.g., call the callback again, or call the callback and also
// return a value) then the second attempt has no effect except either an error message is logged or
// there will be an unhandled promise rejection depending on whether the the subsequent attempt is a
// there will be an unhandled promise rejection depending on whether the subsequent attempt is a
// duplicate (same value or error) or different, respectively.
//
// See the tests in src/tests/backend/specs/hooks.js for examples of supported and prohibited

81
src/tests/backend/common.ts
View file

@ -13,18 +13,20 @@ const server = require('../../node/server');
const setCookieParser = require('set-cookie-parser');
const settings = require('../../node/utils/Settings');
import supertest from 'supertest';
import TestAgent from "supertest/lib/agent";
import {Http2Server} from "node:http2";
import {SignJWT} from "jose";
import {privateKeyExported} from "../../node/security/OAuth2Provider";
const webaccess = require('../../node/hooks/express/webaccess');
const backups:MapArrayType<any> = {};
let agentPromise:Promise<any>|null = null;
exports.apiKey = apiHandler.exportedForTestingOnly.apiKey;
exports.agent = null;
exports.baseUrl = null;
exports.httpServer = null;
exports.logger = log4js.getLogger('test');
export let agent: TestAgent|null = null;
export let baseUrl:string|null = null;
export let httpServer: Http2Server|null = null;
export const logger = log4js.getLogger('test');
const logger = exports.logger;
const logLevel = logger.level;
// Mocha doesn't monitor unhandled Promise rejections, so convert them to uncaught exceptions.
@ -33,10 +35,37 @@ process.on('unhandledRejection', (reason: string) => { throw reason; });
before(async function () {
this.timeout(60000);
await exports.init();
await init();
});
exports.init = async function () {
export const generateJWTToken = () => {
const jwt = new SignJWT({
sub: 'admin',
jti: '123',
exp: Math.floor(Date.now() / 1000) + 60 * 60,
aud: 'account',
iss: 'http://localhost:9001',
admin: true
})
jwt.setProtectedHeader({alg: 'RS256'})
return jwt.sign(privateKeyExported!)
}
export const generateJWTTokenUser = () => {
const jwt = new SignJWT({
sub: 'admin',
jti: '123',
exp: Math.floor(Date.now() / 1000) + 60 * 60,
aud: 'account',
iss: 'http://localhost:9001',
})
jwt.setProtectedHeader({alg: 'RS256'})
return jwt.sign(privateKeyExported!)
}
export const init = async function () {
if (agentPromise != null) return await agentPromise;
let agentResolve;
agentPromise = new Promise((resolve) => { agentResolve = resolve; });
@ -53,11 +82,13 @@ exports.init = async function () {
settings.ip = 'localhost';
settings.importExportRateLimiting = {max: 999999};
settings.commitRateLimiting = {duration: 0.001, points: 1e6};
exports.httpServer = await server.start();
exports.baseUrl = `http://localhost:${exports.httpServer.address().port}`;
logger.debug(`HTTP server at ${exports.baseUrl}`);
httpServer = await server.start();
// @ts-ignore
baseUrl = `http://localhost:${httpServer!.address()!.port}`;
logger.debug(`HTTP server at ${baseUrl}`);
// Create a supertest user agent for the HTTP server.
exports.agent = supertest(exports.baseUrl);
agent = supertest(baseUrl)
//.set('Authorization', `Bearer ${await generateJWTToken()}`);
// Speed up authn tests.
backups.authnFailureDelayMs = webaccess.authnFailureDelayMs;
webaccess.authnFailureDelayMs = 0;
@ -69,8 +100,8 @@ exports.init = async function () {
await server.exit();
});
agentResolve!(exports.agent);
return exports.agent;
agentResolve!(agent);
return agent;
};
/**
@ -81,7 +112,7 @@ exports.init = async function () {
* @param {string} event - The socket.io Socket event to listen for.
* @returns The argument(s) passed to the event handler.
*/
exports.waitForSocketEvent = async (socket: any, event:string) => {
export const waitForSocketEvent = async (socket: any, event:string) => {
const errorEvents = [
'error',
'connect_error',
@ -136,7 +167,7 @@ exports.waitForSocketEvent = async (socket: any, event:string) => {
* nullish, no cookies are passed to the server.
* @returns {io.Socket} A socket.io client Socket object.
*/
exports.connect = async (res:any = null) => {
export const connect = async (res:any = null) => {
// Convert the `set-cookie` header(s) into a `cookie` header.
const resCookies = (res == null) ? {} : setCookieParser.parse(res, {map: true});
const reqCookieHdr = Object.entries(resCookies).map(
@ -148,14 +179,14 @@ exports.connect = async (res:any = null) => {
if (res) {
padId = res.req.path.split('/p/')[1];
}
const socket = io(`${exports.baseUrl}/`, {
const socket = io(`${baseUrl}/`, {
forceNew: true, // Different tests will have different query parameters.
// socketio.js-client on node.js doesn't support cookies (see https://git.io/JU8u9), so the
// express_sid cookie must be passed as a query parameter.
query: {cookie: reqCookieHdr, padId},
});
try {
await exports.waitForSocketEvent(socket, 'connect');
await waitForSocketEvent(socket, 'connect');
} catch (e) {
socket.close();
throw e;
@ -173,7 +204,7 @@ exports.connect = async (res:any = null) => {
* @param token
* @returns The CLIENT_VARS message from the server.
*/
exports.handshake = async (socket: any, padId:string, token = padutils.generateAuthorToken()) => {
export const handshake = async (socket: any, padId:string, token = padutils.generateAuthorToken()) => {
logger.debug('sending CLIENT_READY...');
socket.emit('message', {
component: 'pad',
@ -183,7 +214,7 @@ exports.handshake = async (socket: any, padId:string, token = padutils.generateA
token,
});
logger.debug('waiting for CLIENT_VARS response...');
const msg = await exports.waitForSocketEvent(socket, 'message');
const msg = await waitForSocketEvent(socket, 'message');
logger.debug('received CLIENT_VARS message');
return msg;
};
@ -191,7 +222,7 @@ exports.handshake = async (socket: any, padId:string, token = padutils.generateA
/**
* Convenience wrapper around `socket.send()` that waits for acknowledgement.
*/
exports.sendMessage = async (socket: any, message:any) => await new Promise<void>((resolve, reject) => {
export const sendMessage = async (socket: any, message:any) => await new Promise<void>((resolve, reject) => {
socket.emit('message', message, (errInfo:{
name: string,
message: string,
@ -210,7 +241,7 @@ exports.sendMessage = async (socket: any, message:any) => await new Promise<void
/**
* Convenience function to send a USER_CHANGES message. Waits for acknowledgement.
*/
exports.sendUserChanges = async (socket:any, data:any) => await exports.sendMessage(socket, {
export const sendUserChanges = async (socket:any, data:any) => await sendMessage(socket, {
type: 'COLLABROOM',
component: 'pad',
data: {
@ -232,8 +263,8 @@ exports.sendUserChanges = async (socket:any, data:any) => await exports.sendMess
* common.sendUserChanges(socket, {baseRev: rev, changeset}),
* ]);
*/
exports.waitForAcceptCommit = async (socket:any, wantRev: number) => {
const msg = await exports.waitForSocketEvent(socket, 'message');
export const waitForAcceptCommit = async (socket:any, wantRev: number) => {
const msg = await waitForSocketEvent(socket, 'message');
assert.deepEqual(msg, {
type: 'COLLABROOM',
data: {
@ -252,7 +283,7 @@ const alphabet = 'abcdefghijklmnopqrstuvwxyz';
* @param {string} [charset] - Characters to pick from.
* @returns {string}
*/
exports.randomString = (len: number = 10, charset: string = `${alphabet}${alphabet.toUpperCase()}0123456789`): string => {
export const randomString = (len: number = 10, charset: string = `${alphabet}${alphabet.toUpperCase()}0123456789`): string => {
let ret = '';
while (ret.length < len) ret += charset[Math.floor(Math.random() * charset.length)];
return ret;

10
src/tests/backend/fuzzImportTest.ts
View file

@ -7,13 +7,12 @@ const common = require('./common');
const host = `http://${settings.ip}:${settings.port}`;
const froth = require('mocha-froth');
const axios = require('axios');
const apiKey = common.apiKey;
const apiVersion = 1;
const testPadId = `TEST_fuzz${makeid()}`;
const endPoint = function (point: string, version?:number) {
version = version || apiVersion;
return `/api/${version}/${point}?apikey=${apiKey}`;
return `/api/${version}/${point}}`;
};
console.log('Testing against padID', testPadId);
@ -29,7 +28,12 @@ setTimeout(() => {
}, 5000); // wait 5 seconds
async function runTest(number: number) {
await axios.get(`${host + endPoint('createPad')}&padID=${testPadId}`)
await axios
.get(`${host + endPoint('createPad')}?padID=${testPadId}`, {
headers: {
Authorization: await common.generateJWTToken(),
}
})
.then(() => {
const req = axios.post(`${host}/p/${testPadId}/import`)
.then(() => {

3
src/tests/backend/specs/api/api.ts
View file

@ -12,7 +12,6 @@ const common = require('../../common');
const validateOpenAPI = require('openapi-schema-validation').validate;
let agent: any;
const apiKey = common.apiKey;
let apiVersion = 1;
const makeid = () => {
@ -27,7 +26,7 @@ const makeid = () => {
const testPadId = makeid();
const endPoint = (point:string) => `/api/${apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point:string) => `/api/${apiVersion}/${point}`;
describe(__filename, function () {
before(async function () { agent = await common.init(); });

27
src/tests/backend/specs/api/characterEncoding.ts
View file

@ -6,17 +6,18 @@
* TODO: maybe unify those two files and merge in a single one.
*/
import {generateJWTToken, generateJWTTokenUser} from "../../common";
const assert = require('assert').strict;
const common = require('../../common');
const fs = require('fs');
const fsp = fs.promises;
let agent:any;
const apiKey = common.apiKey;
let apiVersion = 1;
const testPadId = makeid();
const endPoint = (point:string, version?:number) => `/api/${version || apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point:string, version?:number) => `/api/${version || apiVersion}/${point}`;
describe(__filename, function () {
before(async function () { agent = await common.init(); });
@ -24,28 +25,38 @@ describe(__filename, function () {
describe('Sanity checks', function () {
it('can connect', async function () {
await agent.get('/api/')
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
});
it('finds the version tag', async function () {
const res = await agent.get('/api/')
.set("Authorization", await generateJWTToken())
.expect(200);
apiVersion = res.body.currentVersion;
assert(apiVersion);
});
it('errors with invalid APIKey', async function () {
it('errors with invalid OAuth token', async function () {
// This is broken because Etherpad doesn't handle HTTP codes properly see #2343
// If your APIKey is password you deserve to fail all tests anyway
await agent.get(`/api/${apiVersion}/createPad?apikey=password&padID=test`)
await agent.get(`/api/${apiVersion}/createPad?padID=test`)
.set("Authorization", (await generateJWTToken()).substring(0,10))
.expect(401);
});
it('errors with unprivileged OAuth token', async function () {
// This is broken because Etherpad doesn't handle HTTP codes properly see #2343
await agent.get(`/api/${apiVersion}/createPad?padID=test`)
.set("Authorization", (await generateJWTTokenUser()).substring(0,10))
.expect(401);
});
});
describe('Tests', function () {
it('creates a new Pad', async function () {
const res = await agent.get(`${endPoint('createPad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('createPad')}?padID=${testPadId}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -53,6 +64,7 @@ describe(__filename, function () {
it('Sets the HTML of a Pad attempting to weird utf8 encoded content', async function () {
const res = await agent.post(endPoint('setHTML'))
.set("Authorization", await generateJWTToken())
.send({
padID: testPadId,
html: await fsp.readFile('tests/backend/specs/api/emojis.html', 'utf8'),
@ -63,7 +75,8 @@ describe(__filename, function () {
});
it('get the HTML of Pad with emojis', async function () {
const res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.match(res.body.data.html, /&#127484/);

25
src/tests/backend/specs/api/chat.ts
View file

@ -1,17 +1,18 @@
'use strict';
import {generateJWTToken} from "../../common";
const common = require('../../common');
import {strict as assert} from "assert";
let agent:any;
const apiKey = common.apiKey;
let apiVersion = 1;
let authorID = '';
const padID = makeid();
const timestamp = Date.now();
const endPoint = (point:string) => `/api/${apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point:string) => `/api/${apiVersion}/${point}`;
describe(__filename, function () {
before(async function () { agent = await common.init(); });
@ -42,16 +43,18 @@ describe(__filename, function () {
describe('Chat functionality', function () {
it('creates a new Pad', async function () {
await agent.get(`${endPoint('createPad')}&padID=${padID}`)
await agent.get(`${endPoint('createPad')}?padID=${padID}`)
.set("authorization", await generateJWTToken())
.expect(200)
.expect((res:any) => {
if (res.body.code !== 0) throw new Error('Unable to create new Pad');
})
.expect('Content-Type', /json/)
.expect(200);
.expect('Content-Type', /json/);
});
it('Creates an author with a name set', async function () {
await agent.get(endPoint('createAuthor'))
.set("authorization", await generateJWTToken())
.expect((res:any) => {
if (res.body.code !== 0 || !res.body.data.authorID) {
throw new Error('Unable to create author');
@ -63,7 +66,8 @@ describe(__filename, function () {
});
it('Gets the head of chat before the first chat msg', async function () {
await agent.get(`${endPoint('getChatHead')}&padID=${padID}`)
await agent.get(`${endPoint('getChatHead')}?padID=${padID}`)
.set("authorization", await generateJWTToken())
.expect((res:any) => {
if (res.body.data.chatHead !== -1) throw new Error('Chat Head Length is wrong');
if (res.body.code !== 0) throw new Error('Unable to get chat head');
@ -73,8 +77,9 @@ describe(__filename, function () {
});
it('Adds a chat message to the pad', async function () {
await agent.get(`${endPoint('appendChatMessage')}&padID=${padID}&text=blalblalbha` +
await agent.get(`${endPoint('appendChatMessage')}?padID=${padID}&text=blalblalbha` +
`&authorID=${authorID}&time=${timestamp}`)
.set("authorization", await generateJWTToken())
.expect((res:any) => {
if (res.body.code !== 0) throw new Error('Unable to create chat message');
})
@ -83,7 +88,8 @@ describe(__filename, function () {
});
it('Gets the head of chat', async function () {
await agent.get(`${endPoint('getChatHead')}&padID=${padID}`)
await agent.get(`${endPoint('getChatHead')}?padID=${padID}`)
.set("authorization", await generateJWTToken())
.expect((res:any) => {
if (res.body.data.chatHead !== 0) throw new Error('Chat Head Length is wrong');
@ -94,7 +100,8 @@ describe(__filename, function () {
});
it('Gets Chat History of a Pad', async function () {
await agent.get(`${endPoint('getChatHistory')}&padID=${padID}`)
await agent.get(`${endPoint('getChatHistory')}?padID=${padID}`)
.set("authorization", await generateJWTToken())
.expect('Content-Type', /json/)
.expect(200)
.expect((res:any) => {

1
src/tests/backend/specs/api/fuzzImportTest.ts
View file

@ -9,7 +9,6 @@ const settings = require('../../../container/loadSettings.js').loadSettings();
const host = "http://" + settings.ip + ":" + settings.port;
const apiKey = common.apiKey;
var apiVersion = 1;
var testPadId = "TEST_fuzz" + makeid();

15
src/tests/backend/specs/api/importexport.ts
View file

@ -11,10 +11,9 @@ import {MapArrayType} from "../../../../node/types/MapType";
const common = require('../../common');
let agent:any;
const apiKey = common.apiKey;
const apiVersion = 1;
const endPoint = (point: string, version?:string) => `/api/${version || apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point: string, version?:string) => `/api/${version || apiVersion}/${point}`;
const testImports:MapArrayType<any> = {
'malformed': {
@ -243,29 +242,33 @@ describe(__filename, function () {
}
it('createPad', async function () {
const res = await agent.get(`${endPoint('createPad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('createPad')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('setHTML', async function () {
const res = await agent.get(`${endPoint('setHTML')}&padID=${testPadId}` +
const res = await agent.get(`${endPoint('setHTML')}?padID=${testPadId}` +
`&html=${encodeURIComponent(test.input)}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('getHTML', async function () {
const res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.html, test.wantHTML);
});
it('getText', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, test.wantText);

75
src/tests/backend/specs/api/importexportGetPost.ts
View file

@ -5,6 +5,8 @@
*/
import {MapArrayType} from "../../../../node/types/MapType";
import {SuperTestStatic} from "supertest";
import TestAgent from "supertest/lib/agent";
const assert = require('assert').strict;
const common = require('../../common');
@ -21,8 +23,7 @@ const wordXDoc = fs.readFileSync(`${__dirname}/test.docx`);
const odtDoc = fs.readFileSync(`${__dirname}/test.odt`);
const pdfDoc = fs.readFileSync(`${__dirname}/test.pdf`);
let agent:any;
const apiKey = common.apiKey;
let agent: TestAgent;
const apiVersion = 1;
const testPadId = makeid();
const testPadIdEnc = encodeURIComponent(testPadId);
@ -41,6 +42,7 @@ describe(__filename, function () {
describe('Connectivity', function () {
it('can connect', async function () {
await agent.get('/api/')
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/);
});
@ -49,6 +51,7 @@ describe(__filename, function () {
describe('API Versioning', function () {
it('finds the version tag', async function () {
await agent.get('/api/')
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect((res:any) => assert(res.body.currentVersion));
});
@ -103,14 +106,17 @@ describe(__filename, function () {
});
it('creates a new Pad, imports content to it, checks that content', async function () {
await agent.get(`${endPoint('createPad')}&padID=${testPadId}`)
await agent.get(`${endPoint('createPad')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => assert.equal(res.body.code, 0));
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect((res:any) => assert.equal(res.body.data.text, padText.toString()));
});
@ -122,9 +128,11 @@ describe(__filename, function () {
beforeEach(async function () {
if (readOnlyId != null) return;
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
const res = await agent.get(`${endPoint('getReadOnlyID')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getReadOnlyID')}?padID=${testPadId}`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => assert.equal(res.body.code, 0));
@ -145,7 +153,8 @@ describe(__filename, function () {
// This ought to be before(), but it must run after the top-level beforeEach() above.
beforeEach(async function () {
if (text != null) return;
let req = agent.get(`/p/${readOnlyId}/export/${exportType}`);
let req = agent.get(`/p/${readOnlyId}/export/${exportType}`)
.set("authorization", await common.generateJWTToken());
if (authn) req = req.auth('user', 'user-password');
const res = await req
.expect(200)
@ -163,6 +172,7 @@ describe(__filename, function () {
it('re-import to read-only pad ID gives 403 forbidden', async function () {
let req = agent.post(`/p/${readOnlyId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', Buffer.from(text), {
filename: `/test.${exportType}`,
contentType: 'text/plain',
@ -175,6 +185,7 @@ describe(__filename, function () {
// The new pad ID must differ from testPadId because Etherpad refuses to import
// .etherpad files on top of a pad that already has edits.
let req = agent.post(`/p/${testPadId}_import/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', Buffer.from(text), {
filename: `/test.${exportType}`,
contentType: 'text/plain',
@ -200,6 +211,7 @@ describe(__filename, function () {
// TODO: fix support for .doc files..
it('Tries to import .doc that uses soffice or abiword', async function () {
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', wordDoc, {filename: '/test.doc', contentType: 'application/msword'})
.expect(200)
.expect('Content-Type', /json/)
@ -212,6 +224,7 @@ describe(__filename, function () {
it('exports DOC', async function () {
await agent.get(`/p/${testPadId}/export/doc`)
.set("authorization", await common.generateJWTToken())
.buffer(true).parse(superagent.parse['application/octet-stream'])
.expect(200)
.expect((res:any) => assert(res.body.length >= 9000));
@ -219,6 +232,7 @@ describe(__filename, function () {
it('Tries to import .docx that uses soffice or abiword', async function () {
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', wordXDoc, {
filename: '/test.docx',
contentType:
@ -235,6 +249,7 @@ describe(__filename, function () {
it('exports DOC from imported DOCX', async function () {
await agent.get(`/p/${testPadId}/export/doc`)
.set("authorization", await common.generateJWTToken())
.buffer(true).parse(superagent.parse['application/octet-stream'])
.expect(200)
.expect((res:any) => assert(res.body.length >= 9100));
@ -242,6 +257,7 @@ describe(__filename, function () {
it('Tries to import .pdf that uses soffice or abiword', async function () {
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', pdfDoc, {filename: '/test.pdf', contentType: 'application/pdf'})
.expect(200)
.expect('Content-Type', /json/)
@ -254,6 +270,7 @@ describe(__filename, function () {
it('exports PDF', async function () {
await agent.get(`/p/${testPadId}/export/pdf`)
.set("authorization", await common.generateJWTToken())
.buffer(true).parse(superagent.parse['application/octet-stream'])
.expect(200)
.expect((res:any) => assert(res.body.length >= 1000));
@ -261,6 +278,7 @@ describe(__filename, function () {
it('Tries to import .odt that uses soffice or abiword', async function () {
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', odtDoc, {filename: '/test.odt', contentType: 'application/odt'})
.expect(200)
.expect('Content-Type', /json/)
@ -273,6 +291,7 @@ describe(__filename, function () {
it('exports ODT', async function () {
await agent.get(`/p/${testPadId}/export/odt`)
.set("authorization", await common.generateJWTToken())
.buffer(true).parse(superagent.parse['application/octet-stream'])
.expect(200)
.expect((res:any) => assert(res.body.length >= 7000));
@ -282,6 +301,7 @@ describe(__filename, function () {
it('Tries to import .etherpad', async function () {
this.timeout(3000);
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', etherpadDoc, {
filename: '/test.etherpad',
contentType: 'application/etherpad',
@ -298,6 +318,7 @@ describe(__filename, function () {
it('exports Etherpad', async function () {
this.timeout(3000);
await agent.get(`/p/${testPadId}/export/etherpad`)
.set("authorization", await common.generateJWTToken())
.buffer(true).parse(superagent.parse.text)
.expect(200)
.expect(/hello/);
@ -306,6 +327,7 @@ describe(__filename, function () {
it('exports HTML for this Etherpad file', async function () {
this.timeout(3000);
await agent.get(`/p/${testPadId}/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.expect('content-type', 'text/html; charset=utf-8')
.expect(/<ul class="bullet"><li><ul class="bullet"><li>hello<\/ul><\/li><\/ul>/);
@ -315,6 +337,7 @@ describe(__filename, function () {
this.timeout(3000);
settings.allowUnknownFileEnds = false;
await agent.post(`/p/${testPadId}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.xasdasdxx', contentType: 'weirdness/jobby'})
.expect(400)
.expect('Content-Type', /json/)
@ -380,6 +403,8 @@ describe(__filename, function () {
// that a buggy makeGoodExport() doesn't cause checks to accidentally pass.
const records = makeGoodExport();
await deleteTestPad();
const importedPads = await importEtherpad(records)
console.log(importedPads)
await importEtherpad(records)
.expect(200)
.expect('Content-Type', /json/)
@ -389,6 +414,7 @@ describe(__filename, function () {
data: {directDatabaseAccess: true},
}));
await agent.get(`/p/${testPadId}/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /foo/));
@ -397,19 +423,19 @@ describe(__filename, function () {
it('missing rev', async function () {
const records:MapArrayType<any> = makeGoodExport();
delete records['pad:testing:revs:0'];
await importEtherpad(records).expect(500);
importEtherpad(records).expect(500);
});
it('bad changeset', async function () {
const records = makeGoodExport();
records['pad:testing:revs:0'].changeset = 'garbage';
await importEtherpad(records).expect(500);
importEtherpad(records).expect(500);
});
it('missing attrib in pool', async function () {
const records = makeGoodExport();
records['pad:testing'].pool.nextNum++;
await importEtherpad(records).expect(500);
(importEtherpad(records)).expect(500);
});
it('extra attrib in pool', async function () {
@ -417,7 +443,7 @@ describe(__filename, function () {
const pool = records['pad:testing'].pool;
// @ts-ignore
pool.numToAttrib[pool.nextNum] = ['key', 'value'];
await importEtherpad(records).expect(500);
(importEtherpad(records)).expect(500);
});
it('changeset refers to non-existent attrib', async function () {
@ -434,19 +460,19 @@ describe(__filename, function () {
text: 'asdffoo\n',
attribs: '*1+4|1+4',
};
await importEtherpad(records).expect(500);
(importEtherpad(records)).expect(500);
});
it('pad atext does not match', async function () {
const records = makeGoodExport();
records['pad:testing'].atext.attribs = `*0${records['pad:testing'].atext.attribs}`;
await importEtherpad(records).expect(500);
(importEtherpad(records)).expect(500);
});
it('missing chat message', async function () {
const records:MapArrayType<any> = makeGoodExport();
delete records['pad:testing:chat:0'];
await importEtherpad(records).expect(500);
importEtherpad(records).expect(500);
});
});
@ -543,6 +569,7 @@ describe(__filename, function () {
data: {directDatabaseAccess: true},
}));
await agent.get(`/p/${testPadId}/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.equal(res.text, 'oofoo\n'));
@ -550,6 +577,7 @@ describe(__filename, function () {
it('txt request rev 1', async function () {
await agent.get(`/p/${testPadId}/1/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.equal(res.text, 'ofoo\n'));
@ -557,6 +585,7 @@ describe(__filename, function () {
it('txt request rev 2', async function () {
await agent.get(`/p/${testPadId}/2/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.equal(res.text, 'oofoo\n'));
@ -564,6 +593,7 @@ describe(__filename, function () {
it('txt request rev 1test returns rev 1', async function () {
await agent.get(`/p/${testPadId}/1test/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.equal(res.text, 'ofoo\n'));
@ -571,6 +601,7 @@ describe(__filename, function () {
it('txt request rev test1 is 403', async function () {
await agent.get(`/p/${testPadId}/test1/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(500)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /rev is not a number/));
@ -578,6 +609,7 @@ describe(__filename, function () {
it('txt request rev 5 returns head rev', async function () {
await agent.get(`/p/${testPadId}/5/export/txt`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.equal(res.text, 'oofoo\n'));
@ -585,6 +617,7 @@ describe(__filename, function () {
it('html request rev 1', async function () {
await agent.get(`/p/${testPadId}/1/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /ofoo<br>/));
@ -592,6 +625,7 @@ describe(__filename, function () {
it('html request rev 2', async function () {
await agent.get(`/p/${testPadId}/2/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /oofoo<br>/));
@ -599,6 +633,7 @@ describe(__filename, function () {
it('html request rev 1test returns rev 1', async function () {
await agent.get(`/p/${testPadId}/1test/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /ofoo<br>/));
@ -606,6 +641,7 @@ describe(__filename, function () {
it('html request rev test1 results in 500 response', async function () {
await agent.get(`/p/${testPadId}/test1/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(500)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /rev is not a number/));
@ -613,6 +649,7 @@ describe(__filename, function () {
it('html request rev 5 returns head rev', async function () {
await agent.get(`/p/${testPadId}/5/export/html`)
.set("authorization", await common.generateJWTToken())
.expect(200)
.buffer(true).parse(superagent.parse.text)
.expect((res:any) => assert.match(res.text, /oofoo<br>/));
@ -643,6 +680,7 @@ describe(__filename, function () {
it('!authn !exist -> create', async function () {
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
assert(await padManager.doesPadExist(testPadId));
@ -653,6 +691,7 @@ describe(__filename, function () {
it('!authn exist -> replace', async function () {
const pad = await createTestPad('before import');
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
assert(await padManager.doesPadExist(testPadId));
@ -662,6 +701,7 @@ describe(__filename, function () {
it('authn anonymous !exist -> fail', async function () {
settings.requireAuthentication = true;
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(401);
assert(!(await padManager.doesPadExist(testPadId)));
@ -671,6 +711,7 @@ describe(__filename, function () {
settings.requireAuthentication = true;
const pad = await createTestPad('before import\n');
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(401);
assert.equal(pad.text(), 'before import\n');
@ -679,6 +720,7 @@ describe(__filename, function () {
it('authn user create !exist -> create', async function () {
settings.requireAuthentication = true;
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
@ -691,6 +733,7 @@ describe(__filename, function () {
settings.requireAuthentication = true;
authorize = () => 'modify';
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(403);
@ -701,6 +744,7 @@ describe(__filename, function () {
settings.requireAuthentication = true;
authorize = () => 'readOnly';
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(403);
@ -711,6 +755,7 @@ describe(__filename, function () {
settings.requireAuthentication = true;
const pad = await createTestPad('before import\n');
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
@ -722,6 +767,7 @@ describe(__filename, function () {
authorize = () => 'modify';
const pad = await createTestPad('before import\n');
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(200);
@ -733,6 +779,7 @@ describe(__filename, function () {
settings.requireAuthentication = true;
authorize = () => 'readOnly';
await agent.post(`/p/${testPadIdEnc}/import`)
.set("authorization", await common.generateJWTToken())
.auth('user', 'user-password')
.attach('file', padText, {filename: '/test.txt', contentType: 'text/plain'})
.expect(403);
@ -744,7 +791,7 @@ describe(__filename, function () {
const endPoint = (point: string, version?:string) => {
return `/api/${version || apiVersion}/${point}?apikey=${apiKey}`;
return `/api/${version || apiVersion}/${point}`;
};
function makeid() {

4
src/tests/backend/specs/api/instance.ts
View file

@ -8,10 +8,9 @@
const common = require('../../common');
let agent:any;
const apiKey = common.apiKey;
const apiVersion = '1.2.14';
const endPoint = (point: string, version?: number) => `/api/${version || apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point: string, version?: number) => `/api/${version || apiVersion}/${point}`;
describe(__filename, function () {
before(async function () { agent = await common.init(); });
@ -27,6 +26,7 @@ describe(__filename, function () {
describe('getStats', function () {
it('Gets the stats of a running instance', async function () {
await agent.get(endPoint('getStats'))
.set("Authorization", await common.generateJWTToken())
.expect((res:any) => {
if (res.body.code !== 0) throw new Error('getStats() failed');

196
src/tests/backend/specs/api/pad.ts
View file

@ -12,7 +12,6 @@ const common = require('../../common');
const padManager = require('../../../../node/db/PadManager');
let agent:any;
const apiKey = common.apiKey;
let apiVersion = 1;
const testPadId = makeid();
const newPadId = makeid();
@ -21,7 +20,7 @@ const anotherPadId = makeid();
let lastEdited = '';
const text = generateLongText();
const endPoint = (point: string, version?: string) => `/api/${version || apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point: string, version?: string) => `/api/${version || apiVersion}/${point}`;
/*
* Html document with nested lists of different types, to test its import and
@ -60,10 +59,10 @@ describe(__filename, function () {
});
describe('Sanity checks', function () {
it('errors with invalid APIKey', async function () {
it('errors with invalid oauth token', async function () {
// This is broken because Etherpad doesn't handle HTTP codes properly see #2343
// If your APIKey is password you deserve to fail all tests anyway
await agent.get(`/api/${apiVersion}/createPad?apikey=password&padID=test`)
await agent.get(`/api/${apiVersion}/createPad?padID=test`)
.set("Authorization", (await common.generateJWTToken()).substring(0, 10))
.expect(401);
});
});
@ -113,20 +112,23 @@ describe(__filename, function () {
describe('Tests', function () {
it('deletes a Pad that does not exist', async function () {
await agent.get(`${endPoint('deletePad')}&padID=${testPadId}`)
await agent.get(`${endPoint('deletePad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200) // @TODO: we shouldn't expect 200 here since the pad may not exist
.expect('Content-Type', /json/);
});
it('creates a new Pad', async function () {
const res = await agent.get(`${endPoint('createPad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('createPad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('gets revision count of Pad', async function () {
const res = await agent.get(`${endPoint('getRevisionsCount')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -134,7 +136,8 @@ describe(__filename, function () {
});
it('gets saved revisions count of Pad', async function () {
const res = await agent.get(`${endPoint('getSavedRevisionsCount')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getSavedRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -142,7 +145,8 @@ describe(__filename, function () {
});
it('gets saved revision list of Pad', async function () {
const res = await agent.get(`${endPoint('listSavedRevisions')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('listSavedRevisions')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -150,7 +154,8 @@ describe(__filename, function () {
});
it('get the HTML of Pad', async function () {
const res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(res.body.data.html.length > 1);
@ -158,13 +163,15 @@ describe(__filename, function () {
it('list all pads', async function () {
const res = await agent.get(endPoint('listAllPads'))
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(res.body.data.padIDs.includes(testPadId));
});
it('deletes the Pad', async function () {
const res = await agent.get(`${endPoint('deletePad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('deletePad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -172,27 +179,31 @@ describe(__filename, function () {
it('list all pads again', async function () {
const res = await agent.get(endPoint('listAllPads'))
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(!res.body.data.padIDs.includes(testPadId));
});
it('get the HTML of a Pad -- Should return a failure', async function () {
const res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 1);
});
it('creates a new Pad with text', async function () {
const res = await agent.get(`${endPoint('createPad')}&padID=${testPadId}&text=testText`)
const res = await agent.get(`${endPoint('createPad')}?padID=${testPadId}&text=testText`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('gets the Pad text and expect it to be testText with trailing \\n', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, 'testText\n');
@ -200,6 +211,7 @@ describe(__filename, function () {
it('set text', async function () {
const res = await agent.post(endPoint('setText'))
.set("Authorization", (await common.generateJWTToken()))
.send({
padID: testPadId,
text: 'testTextTwo',
@ -210,28 +222,32 @@ describe(__filename, function () {
});
it('gets the Pad text', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, 'testTextTwo\n');
});
it('gets Revision Count of a Pad', async function () {
const res = await agent.get(`${endPoint('getRevisionsCount')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.revisions, 1);
});
it('saves Revision', async function () {
const res = await agent.get(`${endPoint('saveRevision')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('saveRevision')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('gets saved revisions count of Pad again', async function () {
const res = await agent.get(`${endPoint('getSavedRevisionsCount')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getSavedRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -239,7 +255,8 @@ describe(__filename, function () {
});
it('gets saved revision list of Pad again', async function () {
const res = await agent.get(`${endPoint('listSavedRevisions')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('listSavedRevisions')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -247,28 +264,32 @@ describe(__filename, function () {
});
it('gets User Count of a Pad', async function () {
const res = await agent.get(`${endPoint('padUsersCount')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('padUsersCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.padUsersCount, 0);
});
it('Gets the Read Only ID of a Pad', async function () {
const res = await agent.get(`${endPoint('getReadOnlyID')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getReadOnlyID')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(res.body.data.readOnlyID);
});
it('Get Authors of the Pad', async function () {
const res = await agent.get(`${endPoint('listAuthorsOfPad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('listAuthorsOfPad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.authorIDs.length, 0);
});
it('Get When Pad was left Edited', async function () {
const res = await agent.get(`${endPoint('getLastEdited')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getLastEdited')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(res.body.data.lastEdited);
@ -277,6 +298,7 @@ describe(__filename, function () {
it('set text again', async function () {
const res = await agent.post(endPoint('setText'))
.set("Authorization", (await common.generateJWTToken()))
.send({
padID: testPadId,
text: 'testTextThree',
@ -287,35 +309,40 @@ describe(__filename, function () {
});
it('Get When Pad was left Edited again', async function () {
const res = await agent.get(`${endPoint('getLastEdited')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getLastEdited')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert(res.body.data.lastEdited > lastEdited);
});
it('gets User Count of a Pad again', async function () {
const res = await agent.get(`${endPoint('padUsers')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('padUsers')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.padUsers.length, 0);
});
it('deletes a Pad', async function () {
const res = await agent.get(`${endPoint('deletePad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('deletePad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('creates the Pad again', async function () {
const res = await agent.get(`${endPoint('createPad')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('createPad')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('Sets text on a pad Id', async function () {
const res = await agent.post(`${endPoint('setText')}&padID=${testPadId}`)
const res = await agent.post(`${endPoint('setText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.field({text})
.expect(200)
.expect('Content-Type', /json/);
@ -323,7 +350,8 @@ describe(__filename, function () {
});
it('Gets text on a pad Id', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -331,7 +359,8 @@ describe(__filename, function () {
});
it('Sets text on a pad Id including an explicit newline', async function () {
const res = await agent.post(`${endPoint('setText')}&padID=${testPadId}`)
const res = await agent.post(`${endPoint('setText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.field({text: `${text}\n`})
.expect(200)
.expect('Content-Type', /json/);
@ -339,7 +368,8 @@ describe(__filename, function () {
});
it("Gets text on a pad Id and doesn't have an excess newline", async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -347,7 +377,8 @@ describe(__filename, function () {
});
it('Gets when pad was last edited', async function () {
const res = await agent.get(`${endPoint('getLastEdited')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getLastEdited')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.notEqual(res.body.lastEdited, 0);
@ -355,14 +386,16 @@ describe(__filename, function () {
it('Move a Pad to a different Pad ID', async function () {
const res = await agent.get(
`${endPoint('movePad')}&sourceID=${testPadId}&destinationID=${newPadId}&force=true`)
`${endPoint('movePad')}?sourceID=${testPadId}&destinationID=${newPadId}&force=true`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('Gets text from new pad', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${newPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${newPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, `${text}\n`);
@ -370,21 +403,24 @@ describe(__filename, function () {
it('Move pad back to original ID', async function () {
const res = await agent.get(
`${endPoint('movePad')}&sourceID=${newPadId}&destinationID=${testPadId}&force=false`)
`${endPoint('movePad')}?sourceID=${newPadId}&destinationID=${testPadId}&force=false`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('Get text using original ID', async function () {
const res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, `${text}\n`);
});
it('Get last edit of original ID', async function () {
const res = await agent.get(`${endPoint('getLastEdited')}&padID=${testPadId}`)
const res = await agent.get(`${endPoint('getLastEdited')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.notEqual(res.body.lastEdited, 0);
@ -392,11 +428,13 @@ describe(__filename, function () {
it('Append text to a pad Id', async function () {
let res = await agent.get(
`${endPoint('appendText', '1.2.13')}&padID=${testPadId}&text=hello`)
`${endPoint('appendText', '1.2.13')}?padID=${testPadId}&text=hello`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -404,7 +442,8 @@ describe(__filename, function () {
});
it('getText of old revision', async function () {
let res = await agent.get(`${endPoint('getRevisionsCount')}&padID=${testPadId}`)
let res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -412,7 +451,8 @@ describe(__filename, function () {
assert(rev != null);
assert(Number.isInteger(rev));
assert(rev > 0);
res = await agent.get(`${endPoint('getText')}&padID=${testPadId}&rev=${rev - 1}`)
res = await agent.get(`${endPoint('getText')}?padID=${testPadId}&rev=${rev - 1}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -422,6 +462,7 @@ describe(__filename, function () {
it('Sets the HTML of a Pad attempting to pass ugly HTML', async function () {
const html = '<div><b>Hello HTML</title></head></div>';
const res = await agent.post(endPoint('setHTML'))
.set("Authorization", (await common.generateJWTToken()))
.send({
padID: testPadId,
html,
@ -433,6 +474,7 @@ describe(__filename, function () {
it('Pad with complex nested lists of different types', async function () {
let res = await agent.post(endPoint('setHTML'))
.set("Authorization", (await common.generateJWTToken()))
.send({
padID: testPadId,
html: ulHtml,
@ -440,7 +482,8 @@ describe(__filename, function () {
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
const receivedHtml = res.body.data.html.replace('<br></body>', '</body>').toLowerCase();
@ -448,11 +491,13 @@ describe(__filename, function () {
});
it('Pad with white space between list items', async function () {
let res = await agent.get(`${endPoint('setHTML')}&padID=${testPadId}&html=${ulSpaceHtml}`)
let res = await agent.get(`${endPoint('setHTML')}?padID=${testPadId}&html=${ulSpaceHtml}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getHTML')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getHTML')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
const receivedHtml = res.body.data.html.replace('<br></body>', '</body>').toLowerCase();
@ -461,7 +506,8 @@ describe(__filename, function () {
it('errors if pad can be created', async function () {
await Promise.all(['/', '%23', '%3F', '%26'].map(async (badUrlChar) => {
const res = await agent.get(`${endPoint('createPad')}&padID=${badUrlChar}`)
const res = await agent.get(`${endPoint('createPad')}?padID=${badUrlChar}`)
.set("Authorization", (await common.generateJWTToken()))
.expect('Content-Type', /json/);
assert.equal(res.body.code, 1);
}));
@ -469,49 +515,57 @@ describe(__filename, function () {
it('copies the content of a existent pad', async function () {
const res = await agent.get(
`${endPoint('copyPad')}&sourceID=${testPadId}&destinationID=${copiedPadId}&force=true`)
`${endPoint('copyPad')}?sourceID=${testPadId}&destinationID=${copiedPadId}&force=true`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
});
it('does not add an useless revision', async function () {
let res = await agent.post(`${endPoint('setText')}&padID=${testPadId}`)
let res = await agent.post(`${endPoint('setText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.field({text: 'identical text\n'})
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getText')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.text, 'identical text\n');
res = await agent.get(`${endPoint('getRevisionsCount')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
const revCount = res.body.data.revisions;
res = await agent.post(`${endPoint('setText')}&padID=${testPadId}`)
res = await agent.post(`${endPoint('setText')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.field({text: 'identical text\n'})
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getRevisionsCount')}&padID=${testPadId}`)
res = await agent.get(`${endPoint('getRevisionsCount')}?padID=${testPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.data.revisions, revCount);
});
it('creates a new Pad with empty text', async function () {
await agent.get(`${endPoint('createPad')}&padID=${anotherPadId}&text=`)
await agent.get(`${endPoint('createPad')}?padID=${anotherPadId}&text=`)
.set("Authorization", (await common.generateJWTToken()))
.expect('Content-Type', /json/)
.expect(200)
.expect((res:any) => {
assert.equal(res.body.code, 0, 'Unable to create new Pad');
});
await agent.get(`${endPoint('getText')}&padID=${anotherPadId}`)
await agent.get(`${endPoint('getText')}?padID=${anotherPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect('Content-Type', /json/)
.expect(200)
.expect((res:any) => {
@ -521,7 +575,8 @@ describe(__filename, function () {
});
it('deletes with empty text', async function () {
await agent.get(`${endPoint('deletePad')}&padID=${anotherPadId}`)
await agent.get(`${endPoint('deletePad')}?padID=${anotherPadId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect('Content-Type', /json/)
.expect(200)
.expect((res: any) => {
@ -543,8 +598,9 @@ describe(__filename, function () {
});
it('returns a successful response', async function () {
const res = await agent.get(`${endPoint('copyPadWithoutHistory')}&sourceID=${sourcePadId}` +
const res = await agent.get(`${endPoint('copyPadWithoutHistory')}?sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=false`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -552,10 +608,12 @@ describe(__filename, function () {
// this test validates if the source pad's text and attributes are kept
it('creates a new pad with the same content as the source pad', async function () {
let res = await agent.get(`${endPoint('copyPadWithoutHistory')}&sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=false`);
let res = await agent.get(`${endPoint('copyPadWithoutHistory')}?sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=false`)
.set("Authorization", (await common.generateJWTToken()));
assert.equal(res.body.code, 0);
res = await agent.get(`${endPoint('getHTML')}&padID=${newPad}`)
res = await agent.get(`${endPoint('getHTML')}?padID=${newPad}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200);
const receivedHtml = res.body.data.html.replace('<br><br></body>', '</body>').toLowerCase();
assert.equal(receivedHtml, expectedHtml);
@ -564,8 +622,9 @@ describe(__filename, function () {
it('copying to a non-existent group throws an error', async function () {
const padWithNonExistentGroup = `notExistentGroup$${newPad}`;
const res = await agent.get(`${endPoint('copyPadWithoutHistory')}` +
`&sourceID=${sourcePadId}` +
`?sourceID=${sourcePadId}` +
`&destinationID=${padWithNonExistentGroup}&force=true`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200);
assert.equal(res.body.code, 1);
});
@ -577,16 +636,18 @@ describe(__filename, function () {
it('force=false fails', async function () {
const res = await agent.get(`${endPoint('copyPadWithoutHistory')}` +
`&sourceID=${sourcePadId}` +
`?sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=false`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200);
assert.equal(res.body.code, 1);
});
it('force=true succeeds', async function () {
const res = await agent.get(`${endPoint('copyPadWithoutHistory')}` +
`&sourceID=${sourcePadId}` +
`?sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=true`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200);
assert.equal(res.body.code, 0);
});
@ -613,7 +674,8 @@ describe(__filename, function () {
// state between the two attribute pools caused corruption.
const getHtml = async (padId:string) => {
const res = await agent.get(`${endPoint('getHTML')}&padID=${padId}`)
const res = await agent.get(`${endPoint('getHTML')}?padID=${padId}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);
@ -622,6 +684,7 @@ describe(__filename, function () {
const setBody = async (padId: string, bodyHtml: string) => {
await agent.post(endPoint('setHTML'))
.set("Authorization", (await common.generateJWTToken()))
.send({padID: padId, html: `<!DOCTYPE HTML><html><body>${bodyHtml}</body></html>`})
.expect(200)
.expect('Content-Type', /json/)
@ -631,8 +694,9 @@ describe(__filename, function () {
const origHtml = await getHtml(sourcePadId);
assert.doesNotMatch(origHtml, /<strong>/);
assert.doesNotMatch(origHtml, /<em>/);
await agent.get(`${endPoint('copyPadWithoutHistory')}&sourceID=${sourcePadId}` +
await agent.get(`${endPoint('copyPadWithoutHistory')}?sourceID=${sourcePadId}` +
`&destinationID=${newPad}&force=false`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => assert.equal(res.body.code, 0));
@ -672,8 +736,10 @@ describe(__filename, function () {
*/
const createNewPadWithHtml = async (padId: string, html: string) => {
await agent.get(`${endPoint('createPad')}&padID=${padId}`);
await agent.get(`${endPoint('createPad')}?padID=${padId}`)
.set("Authorization", (await common.generateJWTToken()));
await agent.post(endPoint('setHTML'))
.set("Authorization", (await common.generateJWTToken()))
.send({
padID: padId,
html,

3
src/tests/backend/specs/api/restoreRevision.ts
View file

@ -14,13 +14,14 @@ describe(__filename, function () {
let pad: PadType;
const restoreRevision = async (v:string, padId: string, rev: number, authorId:string|null = null) => {
// @ts-ignore
const p = new URLSearchParams(Object.entries({
apikey: common.apiKey,
padID: padId,
rev,
...(authorId == null ? {} : {authorId}),
}));
const res = await agent.get(`/api/${v}/restoreRevision?${p}`)
.set("Authorization", (await common.generateJWTToken()))
.expect(200)
.expect('Content-Type', /json/);
assert.equal(res.body.code, 0);

113
src/tests/backend/specs/api/sessionsAndGroups.ts
View file

@ -1,25 +1,33 @@
'use strict';
import {agent, generateJWTToken, init, logger} from "../../common";
import TestAgent from "supertest/lib/agent";
import supertest from "supertest";
const assert = require('assert').strict;
const common = require('../../common');
const db = require('../../../../node/db/DB');
let agent:any;
const apiKey = common.apiKey;
let apiVersion = 1;
let groupID = '';
let authorID = '';
let sessionID = '';
let padID = makeid();
const endPoint = (point:string) => `/api/${apiVersion}/${point}?apikey=${apiKey}`;
const endPoint = (point:string) => {
return `/api/${apiVersion}/${point}`;
}
let preparedAgent: TestAgent<supertest.Test>
describe(__filename, function () {
before(async function () { agent = await common.init(); });
before(async function () {
preparedAgent = await init();
});
describe('API Versioning', function () {
it('errors if can not connect', async function () {
await agent.get('/api/')
await agent!.get('/api/')
.set('Accept', 'application/json')
.expect(200)
.expect((res:any) => {
assert(res.body.currentVersion);
@ -60,7 +68,8 @@ describe(__filename, function () {
describe('API: Group creation and deletion', function () {
it('createGroup', async function () {
await agent.get(endPoint('createGroup'))
await agent!.get(endPoint('createGroup'))
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -71,7 +80,8 @@ describe(__filename, function () {
});
it('listSessionsOfGroup for empty group', async function () {
await agent.get(`${endPoint('listSessionsOfGroup')}&groupID=${groupID}`)
await agent!.get(`${endPoint('listSessionsOfGroup')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -81,7 +91,9 @@ describe(__filename, function () {
});
it('deleteGroup', async function () {
await agent.get(`${endPoint('deleteGroup')}&groupID=${groupID}`)
await agent!
.get(`${endPoint('deleteGroup')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -92,7 +104,8 @@ describe(__filename, function () {
it('createGroupIfNotExistsFor', async function () {
const mapper = makeid();
let groupId: string;
await agent.get(`${endPoint('createGroupIfNotExistsFor')}&groupMapper=${mapper}`)
await preparedAgent.get(`${endPoint('createGroupIfNotExistsFor')}?groupMapper=${mapper}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -101,7 +114,8 @@ describe(__filename, function () {
assert(groupId);
});
// Passing the same mapper should return the same group ID.
await agent.get(`${endPoint('createGroupIfNotExistsFor')}&groupMapper=${mapper}`)
await preparedAgent.get(`${endPoint('createGroupIfNotExistsFor')}?groupMapper=${mapper}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -110,7 +124,8 @@ describe(__filename, function () {
});
// Deleting the group should clean up the mapping.
assert.equal(await db.get(`mapper2group:${mapper}`), groupId!);
await agent.get(`${endPoint('deleteGroup')}&groupID=${groupId!}`)
await preparedAgent.get(`${endPoint('deleteGroup')}?groupID=${groupId!}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -122,7 +137,8 @@ describe(__filename, function () {
// Test coverage for https://github.com/ether/etherpad-lite/issues/4227
// Creates a group, creates 2 sessions, 2 pads and then deletes the group.
it('createGroup', async function () {
await agent.get(endPoint('createGroup'))
await preparedAgent.get(endPoint('createGroup'))
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -133,7 +149,8 @@ describe(__filename, function () {
});
it('createAuthor', async function () {
await agent.get(endPoint('createAuthor'))
await preparedAgent.get(endPoint('createAuthor'))
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -144,8 +161,9 @@ describe(__filename, function () {
});
it('createSession', async function () {
await agent.get(`${endPoint('createSession')}&authorID=${authorID}&groupID=${groupID}` +
await preparedAgent.get(`${endPoint('createSession')}?authorID=${authorID}&groupID=${groupID}` +
'&validUntil=999999999999')
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -156,8 +174,9 @@ describe(__filename, function () {
});
it('createSession', async function () {
await agent.get(`${endPoint('createSession')}&authorID=${authorID}&groupID=${groupID}` +
await preparedAgent.get(`${endPoint('createSession')}?authorID=${authorID}&groupID=${groupID}` +
'&validUntil=999999999999')
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -168,7 +187,8 @@ describe(__filename, function () {
});
it('createGroupPad', async function () {
await agent.get(`${endPoint('createGroupPad')}&groupID=${groupID}&padName=x1234567`)
await preparedAgent.get(`${endPoint('createGroupPad')}?groupID=${groupID}&padName=x1234567`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -177,7 +197,8 @@ describe(__filename, function () {
});
it('createGroupPad', async function () {
await agent.get(`${endPoint('createGroupPad')}&groupID=${groupID}&padName=x12345678`)
await preparedAgent.get(`${endPoint('createGroupPad')}?groupID=${groupID}&padName=x12345678`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -186,7 +207,8 @@ describe(__filename, function () {
});
it('deleteGroup', async function () {
await agent.get(`${endPoint('deleteGroup')}&groupID=${groupID}`)
await preparedAgent.get(`${endPoint('deleteGroup')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -198,7 +220,8 @@ describe(__filename, function () {
describe('API: Author creation', function () {
it('createGroup', async function () {
await agent.get(endPoint('createGroup'))
await preparedAgent.get(endPoint('createGroup'))
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -209,7 +232,8 @@ describe(__filename, function () {
});
it('createAuthor', async function () {
await agent.get(endPoint('createAuthor'))
await preparedAgent.get(endPoint('createAuthor'))
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -219,7 +243,8 @@ describe(__filename, function () {
});
it('createAuthor with name', async function () {
await agent.get(`${endPoint('createAuthor')}&name=john`)
await preparedAgent.get(`${endPoint('createAuthor')}?name=john`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -230,7 +255,8 @@ describe(__filename, function () {
});
it('createAuthorIfNotExistsFor', async function () {
await agent.get(`${endPoint('createAuthorIfNotExistsFor')}&authorMapper=chris`)
await preparedAgent.get(`${endPoint('createAuthorIfNotExistsFor')}?authorMapper=chris`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -240,7 +266,8 @@ describe(__filename, function () {
});
it('getAuthorName', async function () {
await agent.get(`${endPoint('getAuthorName')}&authorID=${authorID}`)
await preparedAgent.get(`${endPoint('getAuthorName')}?authorID=${authorID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -252,8 +279,9 @@ describe(__filename, function () {
describe('API: Sessions', function () {
it('createSession', async function () {
await agent.get(`${endPoint('createSession')}&authorID=${authorID}&groupID=${groupID}` +
await preparedAgent.get(`${endPoint('createSession')}?authorID=${authorID}&groupID=${groupID}` +
'&validUntil=999999999999')
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -264,7 +292,8 @@ describe(__filename, function () {
});
it('getSessionInfo', async function () {
await agent.get(`${endPoint('getSessionInfo')}&sessionID=${sessionID}`)
await preparedAgent.get(`${endPoint('getSessionInfo')}?sessionID=${sessionID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -276,7 +305,8 @@ describe(__filename, function () {
});
it('listSessionsOfGroup', async function () {
await agent.get(`${endPoint('listSessionsOfGroup')}&groupID=${groupID}`)
await preparedAgent.get(`${endPoint('listSessionsOfGroup')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -286,7 +316,8 @@ describe(__filename, function () {
});
it('deleteSession', async function () {
await agent.get(`${endPoint('deleteSession')}&sessionID=${sessionID}`)
await preparedAgent.get(`${endPoint('deleteSession')}?sessionID=${sessionID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -295,7 +326,8 @@ describe(__filename, function () {
});
it('getSessionInfo of deleted session', async function () {
await agent.get(`${endPoint('getSessionInfo')}&sessionID=${sessionID}`)
await preparedAgent.get(`${endPoint('getSessionInfo')}?sessionID=${sessionID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -306,7 +338,8 @@ describe(__filename, function () {
describe('API: Group pad management', function () {
it('listPads', async function () {
await agent.get(`${endPoint('listPads')}&groupID=${groupID}`)
await preparedAgent.get(`${endPoint('listPads')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -316,7 +349,8 @@ describe(__filename, function () {
});
it('createGroupPad', async function () {
await agent.get(`${endPoint('createGroupPad')}&groupID=${groupID}&padName=${padID}`)
await preparedAgent.get(`${endPoint('createGroupPad')}?groupID=${groupID}&padName=${padID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -326,10 +360,11 @@ describe(__filename, function () {
});
it('listPads after creating a group pad', async function () {
await agent.get(`${endPoint('listPads')}&groupID=${groupID}`)
await preparedAgent.get(`${endPoint('listPads')}?groupID=${groupID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
.expect((res) => {
assert.equal(res.body.code, 0);
assert.equal(res.body.data.padIDs.length, 1);
});
@ -338,7 +373,8 @@ describe(__filename, function () {
describe('API: Pad security', function () {
it('getPublicStatus', async function () {
await agent.get(`${endPoint('getPublicStatus')}&padID=${padID}`)
await preparedAgent.get(`${endPoint('getPublicStatus')}?padID=${padID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -348,7 +384,8 @@ describe(__filename, function () {
});
it('setPublicStatus', async function () {
await agent.get(`${endPoint('setPublicStatus')}&padID=${padID}&publicStatus=true`)
await preparedAgent.get(`${endPoint('setPublicStatus')}?padID=${padID}&publicStatus=true`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -357,7 +394,8 @@ describe(__filename, function () {
});
it('getPublicStatus after changing public status', async function () {
await agent.get(`${endPoint('getPublicStatus')}&padID=${padID}`)
await preparedAgent.get(`${endPoint('getPublicStatus')}?padID=${padID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {
@ -373,7 +411,8 @@ describe(__filename, function () {
describe('API: Misc', function () {
it('listPadsOfAuthor', async function () {
await agent.get(`${endPoint('listPadsOfAuthor')}&authorID=${authorID}`)
await preparedAgent.get(`${endPoint('listPadsOfAuthor')}?authorID=${authorID}`)
.set("Authorization", await generateJWTToken())
.expect(200)
.expect('Content-Type', /json/)
.expect((res:any) => {

31
src/tests/backend/specs/settings.ts
View file

@ -58,4 +58,35 @@ describe(__filename, function () {
});
});
});
describe("Parse plugin settings", function () {
before(async function () {
process.env["EP__ADMIN__PASSWORD"] = "test"
})
it('should parse plugin settings', async function () {
let settings = parseSettings(path.join(__dirname, 'settings.json'), true);
assert.equal(settings.ADMIN.PASSWORD, "test");
})
it('should bundle settings with same path', async function () {
process.env["EP__ADMIN__USERNAME"] = "test"
let settings = parseSettings(path.join(__dirname, 'settings.json'), true);
assert.deepEqual(settings.ADMIN, {PASSWORD: "test", USERNAME: "test"});
})
it("Can set the ep themes", async function () {
process.env["EP__ep_themes__default_theme"] = "hacker"
let settings = parseSettings(path.join(__dirname, 'settings.json'), true);
assert.deepEqual(settings.ep_themes, {"default_theme": "hacker"});
})
it("can set the ep_webrtc settings", async function () {
process.env["EP__ep_webrtc__enabled"] = "true"
let settings = parseSettings(path.join(__dirname, 'settings.json'), true);
assert.deepEqual(settings.ep_webrtc, {"enabled": true});
})
})
});

Some files were not shown because too many files have changed in this diff Show more