From 1a7bc1b8e2efa8654893b15eb05464feb0324805 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Mon, 20 Apr 2026 11:14:48 +0200 Subject: [PATCH 1/9] ZOOKEEPER-5020: Improve ZooKeeper website --- zookeeper-docs/pom.xml | 64 - .../main/resources/markdown/html/footer.html | 18 - .../main/resources/markdown/html/header.html | 149 - .../src/main/resources/markdown/index.md | 65 - .../main/resources/markdown/releasenotes.md | 267 - .../main/resources/markdown/skin/basic.css | 167 - .../main/resources/markdown/skin/chapter.gif | Bin 49 -> 0 bytes .../resources/markdown/skin/chapter_open.gif | Bin 49 -> 0 bytes .../main/resources/markdown/skin/current.gif | Bin 54 -> 0 bytes .../main/resources/markdown/skin/getBlank.js | 40 - .../main/resources/markdown/skin/getMenu.js | 45 - .../markdown/skin/header_white_line.gif | Bin 37 -> 0 bytes .../src/main/resources/markdown/skin/init.js | 57 - .../markdown/skin/instruction_arrow.png | Bin 285 -> 0 bytes .../src/main/resources/markdown/skin/menu.js | 48 - .../src/main/resources/markdown/skin/page.gif | Bin 79 -> 0 bytes .../main/resources/markdown/skin/print.css | 54 - .../main/resources/markdown/skin/printer.gif | Bin 603 -> 0 bytes .../main/resources/markdown/skin/profile.css | 159 - .../main/resources/markdown/skin/prototype.js | 7588 ------- .../main/resources/markdown/skin/screen.css | 531 - .../main/resources/markdown/zookeeperAdmin.md | 3078 --- .../resources/markdown/zookeeperAuditLogs.md | 140 - .../main/resources/markdown/zookeeperCLI.md | 574 - .../markdown/zookeeperHierarchicalQuorums.md | 47 - .../resources/markdown/zookeeperInternals.md | 382 - .../main/resources/markdown/zookeeperJMX.md | 130 - .../resources/markdown/zookeeperMonitor.md | 287 - .../resources/markdown/zookeeperObservers.md | 138 - .../markdown/zookeeperOracleQuorums.md | 202 - .../markdown/zookeeperProgrammers.md | 1668 -- .../resources/markdown/zookeeperQuotas.md | 85 - .../resources/markdown/zookeeperReconfig.md | 908 - .../markdown/zookeeperSnapshotAndRestore.md | 68 - .../resources/markdown/zookeeperStarted.md | 373 - .../main/resources/markdown/zookeeperTools.md | 698 - .../resources/markdown/zookeeperTutorial.md | 666 - .../resources/markdown/zookeeperUseCases.md | 385 - zookeeper-website/.gitignore | 43 + zookeeper-website/Dockerfile | 40 + zookeeper-website/README.md | 620 + zookeeper-website/app/app.css | 287 + .../components/docs/layout/docs/client.tsx | 166 + .../app/components/docs/layout/docs/index.tsx | 330 + .../docs/layout/docs/page/client.tsx | 421 + .../docs/layout/docs/page/index.tsx | 282 + .../components/docs/layout/docs/sidebar.tsx | 285 + .../docs/layout/language-toggle.tsx | 79 + .../app/components/docs/layout/link-item.tsx | 136 + .../components/docs/layout/search-toggle.tsx | 96 + .../app/components/docs/layout/shared.tsx | 120 + .../components/docs/layout/sidebar/base.tsx | 471 + .../docs/layout/sidebar/link-item.tsx | 83 + .../docs/layout/sidebar/page-tree.tsx | 130 + .../docs/layout/sidebar/tabs/dropdown.tsx | 128 + .../docs/layout/sidebar/tabs/index.tsx | 107 + .../components/docs/layout/theme-toggle.tsx | 103 + .../app/components/docs/older-docs-picker.tsx | 73 + .../app/components/docs/search/create-db.ts | 110 + .../docs/search/create-from-source.ts | 141 + .../components/docs/search/docs-search.tsx | 80 + .../app/components/docs/search/static.ts | 329 + .../components/docs/search/use-docs-search.ts | 138 + .../app/components/docs/search/utils.ts | 83 + .../app/components/docs/toc/clerk.tsx | 189 + .../app/components/docs/toc/default.tsx | 73 + .../app/components/docs/toc/index.tsx | 144 + .../app/components/getting-started.tsx | 77 + zookeeper-website/app/components/link.tsx | 30 + zookeeper-website/app/components/links.ts | 128 + .../app/components/mdx-components.tsx | 152 + .../app/components/site-footer.tsx | 123 + .../app/components/site-navbar.tsx | 655 + .../app/components/theme-toggle.tsx | 37 + zookeeper-website/app/lib/current-version.ts | 19 + .../app/lib/released-docs-versions.ts | 69 + zookeeper-website/app/lib/source.ts | 25 + zookeeper-website/app/lib/theme-provider.tsx | 94 + zookeeper-website/app/lib/urls.ts | 37 + zookeeper-website/app/lib/utils.ts | 39 + .../app/pages/_docs/docs-layout.tsx | 33 + .../administrators-guide/administration.mdx | 170 + .../administrators-guide/best-practices.mdx | 56 + .../administrators-guide/commands.mdx | 382 + ...ommunication-using-the-netty-framework.mdx | 152 + .../configuration-parameters.mdx | 1699 ++ .../data-file-management.mdx | 94 + .../administrators-guide/deployment.mdx | 280 + .../admin-ops/administrators-guide/index.mdx | 4 + .../admin-ops/administrators-guide/meta.json | 12 + .../pages/_docs/docs/_mdx/admin-ops/cli.mdx | 605 + .../admin-ops/dynamic-reconfiguration.mdx | 725 + .../pages/_docs/docs/_mdx/admin-ops/jmx.mdx | 96 + .../pages/_docs/docs/_mdx/admin-ops/meta.json | 15 + .../_mdx/admin-ops/monitor-and-audit-logs.mdx | 371 + .../docs/_mdx/admin-ops/observers-guide.mdx | 110 + .../_docs/docs/_mdx/admin-ops/quorums.mdx | 230 + .../_docs/docs/_mdx/admin-ops/quota-guide.mdx | 51 + .../admin-ops/snapshot-and-restore-guide.mdx | 65 + .../pages/_docs/docs/_mdx/admin-ops/tools.mdx | 642 + .../docs/_mdx/developer/basic-tutorial.mdx | 645 + .../docs/_mdx/developer/java-example.mdx | 868 +- .../pages/_docs/docs/_mdx/developer/meta.json | 11 + .../access-control-using-acls.mdx | 283 + .../developer/programmers-guide/bindings.mdx | 260 + ...blocks-a-guide-to-zookeeper-operations.mdx | 96 + .../consistency-guarantees.mdx | 68 + .../programmers-guide/data-model.mdx | 208 + ...as-common-problems-and-troubleshooting.mdx | 51 + .../developer/programmers-guide/index.mdx | 38 + .../developer/programmers-guide/meta.json | 14 + .../pluggable-authentication.mdx | 115 + .../developer/programmers-guide/sessions.mdx | 272 + .../developer/programmers-guide/watches.mdx | 145 + .../_docs/docs/_mdx/developer/recipes.mdx | 187 +- .../_docs/docs/_mdx/developer/use-cases.mdx | 463 + .../app/pages/_docs/docs/_mdx/index.mdx | 142 +- .../app/pages/_docs/docs/_mdx/meta.json | 17 + .../docs/_mdx/miscellaneous/internals.mdx | 310 + .../_docs/docs/_mdx/miscellaneous/meta.json | 10 + .../pages/_docs/docs/_mdx/overview/meta.json | 8 + .../_docs/docs/_mdx/overview/quick-start.mdx | 338 + .../docs/_mdx/overview/release-notes.mdx | 289 + .../app/pages/_docs/docs/index.tsx | 172 + .../app/pages/_landing/bylaws/content.md | 126 + .../app/pages/_landing/bylaws/index.tsx | 24 + .../pages/_landing/credits/developers.json | 47 + .../_landing/credits/developers.json.d.ts | 27 + .../app/pages/_landing/credits/index.tsx | 121 + .../app/pages/_landing/events/content.md | 68 + .../app/pages/_landing/events/index.tsx | 24 + .../app/pages/_landing/home/community.tsx | 100 + .../app/pages/_landing/home/feature-card.tsx | 52 + .../app/pages/_landing/home/features.tsx | 65 + .../app/pages/_landing/home/hero.tsx | 111 + .../app/pages/_landing/home/index.tsx | 33 + .../app/pages/_landing/home/integrations.tsx | 64 + .../app/pages/_landing/home/use-cases.tsx | 98 + .../app/pages/_landing/irc/content.md | 30 + .../app/pages/_landing/irc/index.tsx | 24 + .../app/pages/_landing/landing-layout.tsx | 33 + .../pages/_landing/mailing-lists/content.md | 79 + .../pages/_landing/mailing-lists/index.tsx | 24 + .../app/pages/_landing/news/content.md | 647 + .../app/pages/_landing/news/index.tsx | 24 + .../app/pages/_landing/releases/content.md | 67 + .../app/pages/_landing/releases/index.tsx | 24 + .../app/pages/_landing/security/content.md | 265 + .../app/pages/_landing/security/index.tsx | 24 + .../pages/_landing/version-control/content.md | 33 + .../pages/_landing/version-control/index.tsx | 24 + zookeeper-website/app/root.tsx | 127 + zookeeper-website/app/routes.ts | 47 + .../app/routes/_api/llms-full.ts | 33 + zookeeper-website/app/routes/_api/search.ts | 28 + zookeeper-website/app/routes/_docs/docs.tsx | 36 + .../app/routes/_landing/bylaws.tsx | 34 + .../app/routes/_landing/credits.tsx | 35 + .../app/routes/_landing/events.tsx | 35 + .../app/routes/_landing/home.tsx | 35 + zookeeper-website/app/routes/_landing/irc.tsx | 34 + .../app/routes/_landing/mailing-lists.tsx | 35 + .../app/routes/_landing/news.tsx | 34 + .../app/routes/_landing/releases.tsx | 35 + .../app/routes/_landing/security.tsx | 35 + .../app/routes/_landing/version-control.tsx | 35 + zookeeper-website/app/ui/accordion.tsx | 82 + zookeeper-website/app/ui/alert-dialog.tsx | 173 + zookeeper-website/app/ui/alert.tsx | 84 + zookeeper-website/app/ui/aspect-ratio.tsx | 27 + zookeeper-website/app/ui/avatar.tsx | 69 + zookeeper-website/app/ui/badge.tsx | 64 + zookeeper-website/app/ui/breadcrumb.tsx | 127 + zookeeper-website/app/ui/button-group.tsx | 101 + zookeeper-website/app/ui/button.tsx | 81 + zookeeper-website/app/ui/card.tsx | 110 + zookeeper-website/app/ui/collapsible.tsx | 65 + zookeeper-website/app/ui/command.tsx | 218 + zookeeper-website/app/ui/dialog.tsx | 159 + zookeeper-website/app/ui/dropdown-menu.tsx | 275 + zookeeper-website/app/ui/input-group.tsx | 172 + zookeeper-website/app/ui/input.tsx | 39 + zookeeper-website/app/ui/item.tsx | 211 + zookeeper-website/app/ui/label.tsx | 40 + zookeeper-website/app/ui/menubar.tsx | 292 + zookeeper-website/app/ui/navigation-menu.tsx | 184 + zookeeper-website/app/ui/pagination.tsx | 145 + zookeeper-website/app/ui/popover.tsx | 49 + zookeeper-website/app/ui/scroll-area.tsx | 78 + zookeeper-website/app/ui/separator.tsx | 44 + zookeeper-website/app/ui/spinner.tsx | 34 + zookeeper-website/app/ui/table.tsx | 132 + zookeeper-website/app/ui/tabs.tsx | 82 + zookeeper-website/app/ui/textarea.tsx | 36 + zookeeper-website/app/ui/tooltip.tsx | 77 + zookeeper-website/cli.json | 13 + zookeeper-website/e2e-tests/docs.spec.ts | 263 + .../e2e-tests/landing-page.spec.ts | 179 + .../e2e-tests/older-docs-picker.spec.ts | 206 + zookeeper-website/e2e-tests/theme.spec.ts | 123 + zookeeper-website/eslint.config.js | 183 + zookeeper-website/global.d.ts | 31 + zookeeper-website/package-lock.json | 16462 ++++++++++++++++ zookeeper-website/package.json | 118 + zookeeper-website/playwright.config.ts | 70 + .../plugins/released-docs-versions.ts | 41 + zookeeper-website/prettier.config.js | 25 + zookeeper-website/public/.htaccess | 1 + zookeeper-website/public/404.html | 37 + .../public/docs-images}/2pc.jpg | Bin .../public/docs-images}/bk-overview.jpg | Bin .../public/docs-images}/favicon.ico | Bin .../public/docs-images}/state_dia.dia | Bin .../public/docs-images}/state_dia.jpg | Bin .../public/docs-images}/zkAuditLogs.jpg | Bin .../public/docs-images}/zkarch.jpg | Bin .../public/docs-images}/zkcomponents.jpg | Bin .../public/docs-images}/zknamespace.jpg | Bin .../public/docs-images}/zkperfRW-3.2.jpg | Bin .../public/docs-images}/zkperfRW.jpg | Bin .../public/docs-images}/zkperfreliability.jpg | Bin .../public/docs-images}/zkservice.jpg | Bin .../public/docs-images}/zookeeper_small.gif | Bin zookeeper-website/public/favicon.ico | Bin 0 -> 32038 bytes .../fonts/inter-latin-wght-italic.woff2 | Bin 0 -> 51832 bytes .../fonts/inter-latin-wght-normal.woff2 | Bin 0 -> 48256 bytes .../public/images/dark-theme-large-logo.svg | 182 + .../public/images/large-logo.svg | 182 + zookeeper-website/public/images/logo.svg | 1 + zookeeper-website/react-router.config.ts | 36 + zookeeper-website/source.config.ts | 42 + zookeeper-website/tsconfig.json | 27 + zookeeper-website/unit-tests/home.test.tsx | 93 + .../unit-tests/markdown.test.tsx | 184 + .../unit-tests/navigation.test.tsx | 138 + .../unit-tests/older-docs-picker.test.tsx | 187 + .../unit-tests/released-docs-versions.test.ts | 104 + zookeeper-website/unit-tests/setup.ts | 25 + .../unit-tests/theme-toggle.test.tsx | 66 + zookeeper-website/unit-tests/utils.tsx | 34 + zookeeper-website/vite.config.ts | 66 + zookeeper-website/vitest.config.ts | 58 + 242 files changed, 42203 insertions(+), 19755 deletions(-) delete mode 100644 zookeeper-docs/pom.xml delete mode 100644 zookeeper-docs/src/main/resources/markdown/html/footer.html delete mode 100644 zookeeper-docs/src/main/resources/markdown/html/header.html delete mode 100644 zookeeper-docs/src/main/resources/markdown/index.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/releasenotes.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/basic.css delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/chapter.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/chapter_open.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/current.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/getBlank.js delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/getMenu.js delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/header_white_line.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/init.js delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/instruction_arrow.png delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/menu.js delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/page.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/print.css delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/printer.gif delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/profile.css delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/prototype.js delete mode 100644 zookeeper-docs/src/main/resources/markdown/skin/screen.css delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperAuditLogs.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperCLI.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperHierarchicalQuorums.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperJMX.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperMonitor.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperObservers.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperOracleQuorums.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperProgrammers.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperQuotas.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperReconfig.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperSnapshotAndRestore.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperStarted.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperTools.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperTutorial.md delete mode 100644 zookeeper-docs/src/main/resources/markdown/zookeeperUseCases.md create mode 100644 zookeeper-website/.gitignore create mode 100644 zookeeper-website/Dockerfile create mode 100644 zookeeper-website/README.md create mode 100644 zookeeper-website/app/app.css create mode 100644 zookeeper-website/app/components/docs/layout/docs/client.tsx create mode 100644 zookeeper-website/app/components/docs/layout/docs/index.tsx create mode 100644 zookeeper-website/app/components/docs/layout/docs/page/client.tsx create mode 100644 zookeeper-website/app/components/docs/layout/docs/page/index.tsx create mode 100644 zookeeper-website/app/components/docs/layout/docs/sidebar.tsx create mode 100644 zookeeper-website/app/components/docs/layout/language-toggle.tsx create mode 100644 zookeeper-website/app/components/docs/layout/link-item.tsx create mode 100644 zookeeper-website/app/components/docs/layout/search-toggle.tsx create mode 100644 zookeeper-website/app/components/docs/layout/shared.tsx create mode 100644 zookeeper-website/app/components/docs/layout/sidebar/base.tsx create mode 100644 zookeeper-website/app/components/docs/layout/sidebar/link-item.tsx create mode 100644 zookeeper-website/app/components/docs/layout/sidebar/page-tree.tsx create mode 100644 zookeeper-website/app/components/docs/layout/sidebar/tabs/dropdown.tsx create mode 100644 zookeeper-website/app/components/docs/layout/sidebar/tabs/index.tsx create mode 100644 zookeeper-website/app/components/docs/layout/theme-toggle.tsx create mode 100644 zookeeper-website/app/components/docs/older-docs-picker.tsx create mode 100644 zookeeper-website/app/components/docs/search/create-db.ts create mode 100644 zookeeper-website/app/components/docs/search/create-from-source.ts create mode 100644 zookeeper-website/app/components/docs/search/docs-search.tsx create mode 100644 zookeeper-website/app/components/docs/search/static.ts create mode 100644 zookeeper-website/app/components/docs/search/use-docs-search.ts create mode 100644 zookeeper-website/app/components/docs/search/utils.ts create mode 100644 zookeeper-website/app/components/docs/toc/clerk.tsx create mode 100644 zookeeper-website/app/components/docs/toc/default.tsx create mode 100644 zookeeper-website/app/components/docs/toc/index.tsx create mode 100644 zookeeper-website/app/components/getting-started.tsx create mode 100644 zookeeper-website/app/components/link.tsx create mode 100644 zookeeper-website/app/components/links.ts create mode 100644 zookeeper-website/app/components/mdx-components.tsx create mode 100644 zookeeper-website/app/components/site-footer.tsx create mode 100644 zookeeper-website/app/components/site-navbar.tsx create mode 100644 zookeeper-website/app/components/theme-toggle.tsx create mode 100644 zookeeper-website/app/lib/current-version.ts create mode 100644 zookeeper-website/app/lib/released-docs-versions.ts create mode 100644 zookeeper-website/app/lib/source.ts create mode 100644 zookeeper-website/app/lib/theme-provider.tsx create mode 100644 zookeeper-website/app/lib/urls.ts create mode 100644 zookeeper-website/app/lib/utils.ts create mode 100644 zookeeper-website/app/pages/_docs/docs-layout.tsx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/administration.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/best-practices.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/commands.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/communication-using-the-netty-framework.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/configuration-parameters.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/data-file-management.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/deployment.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/index.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/cli.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/dynamic-reconfiguration.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/jmx.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/monitor-and-audit-logs.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/observers-guide.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quorums.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quota-guide.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/snapshot-and-restore-guide.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/basic-tutorial.mdx rename zookeeper-docs/src/main/resources/markdown/javaExample.md => zookeeper-website/app/pages/_docs/docs/_mdx/developer/java-example.mdx (50%) create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/access-control-using-acls.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/bindings.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/building-blocks-a-guide-to-zookeeper-operations.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/consistency-guarantees.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/data-model.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/gotchas-common-problems-and-troubleshooting.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/index.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/pluggable-authentication.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/sessions.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/watches.mdx rename zookeeper-docs/src/main/resources/markdown/recipes.md => zookeeper-website/app/pages/_docs/docs/_mdx/developer/recipes.mdx (69%) create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/developer/use-cases.mdx rename zookeeper-docs/src/main/resources/markdown/zookeeperOver.md => zookeeper-website/app/pages/_docs/docs/_mdx/index.mdx (73%) create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/internals.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/overview/meta.json create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/overview/quick-start.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/_mdx/overview/release-notes.mdx create mode 100644 zookeeper-website/app/pages/_docs/docs/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/bylaws/content.md create mode 100644 zookeeper-website/app/pages/_landing/bylaws/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/credits/developers.json create mode 100644 zookeeper-website/app/pages/_landing/credits/developers.json.d.ts create mode 100644 zookeeper-website/app/pages/_landing/credits/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/events/content.md create mode 100644 zookeeper-website/app/pages/_landing/events/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/community.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/feature-card.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/features.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/hero.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/integrations.tsx create mode 100644 zookeeper-website/app/pages/_landing/home/use-cases.tsx create mode 100644 zookeeper-website/app/pages/_landing/irc/content.md create mode 100644 zookeeper-website/app/pages/_landing/irc/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/landing-layout.tsx create mode 100644 zookeeper-website/app/pages/_landing/mailing-lists/content.md create mode 100644 zookeeper-website/app/pages/_landing/mailing-lists/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/news/content.md create mode 100644 zookeeper-website/app/pages/_landing/news/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/releases/content.md create mode 100644 zookeeper-website/app/pages/_landing/releases/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/security/content.md create mode 100644 zookeeper-website/app/pages/_landing/security/index.tsx create mode 100644 zookeeper-website/app/pages/_landing/version-control/content.md create mode 100644 zookeeper-website/app/pages/_landing/version-control/index.tsx create mode 100644 zookeeper-website/app/root.tsx create mode 100644 zookeeper-website/app/routes.ts create mode 100644 zookeeper-website/app/routes/_api/llms-full.ts create mode 100644 zookeeper-website/app/routes/_api/search.ts create mode 100644 zookeeper-website/app/routes/_docs/docs.tsx create mode 100644 zookeeper-website/app/routes/_landing/bylaws.tsx create mode 100644 zookeeper-website/app/routes/_landing/credits.tsx create mode 100644 zookeeper-website/app/routes/_landing/events.tsx create mode 100644 zookeeper-website/app/routes/_landing/home.tsx create mode 100644 zookeeper-website/app/routes/_landing/irc.tsx create mode 100644 zookeeper-website/app/routes/_landing/mailing-lists.tsx create mode 100644 zookeeper-website/app/routes/_landing/news.tsx create mode 100644 zookeeper-website/app/routes/_landing/releases.tsx create mode 100644 zookeeper-website/app/routes/_landing/security.tsx create mode 100644 zookeeper-website/app/routes/_landing/version-control.tsx create mode 100644 zookeeper-website/app/ui/accordion.tsx create mode 100644 zookeeper-website/app/ui/alert-dialog.tsx create mode 100644 zookeeper-website/app/ui/alert.tsx create mode 100644 zookeeper-website/app/ui/aspect-ratio.tsx create mode 100644 zookeeper-website/app/ui/avatar.tsx create mode 100644 zookeeper-website/app/ui/badge.tsx create mode 100644 zookeeper-website/app/ui/breadcrumb.tsx create mode 100644 zookeeper-website/app/ui/button-group.tsx create mode 100644 zookeeper-website/app/ui/button.tsx create mode 100644 zookeeper-website/app/ui/card.tsx create mode 100644 zookeeper-website/app/ui/collapsible.tsx create mode 100644 zookeeper-website/app/ui/command.tsx create mode 100644 zookeeper-website/app/ui/dialog.tsx create mode 100644 zookeeper-website/app/ui/dropdown-menu.tsx create mode 100644 zookeeper-website/app/ui/input-group.tsx create mode 100644 zookeeper-website/app/ui/input.tsx create mode 100644 zookeeper-website/app/ui/item.tsx create mode 100644 zookeeper-website/app/ui/label.tsx create mode 100644 zookeeper-website/app/ui/menubar.tsx create mode 100644 zookeeper-website/app/ui/navigation-menu.tsx create mode 100644 zookeeper-website/app/ui/pagination.tsx create mode 100644 zookeeper-website/app/ui/popover.tsx create mode 100644 zookeeper-website/app/ui/scroll-area.tsx create mode 100644 zookeeper-website/app/ui/separator.tsx create mode 100644 zookeeper-website/app/ui/spinner.tsx create mode 100644 zookeeper-website/app/ui/table.tsx create mode 100644 zookeeper-website/app/ui/tabs.tsx create mode 100644 zookeeper-website/app/ui/textarea.tsx create mode 100644 zookeeper-website/app/ui/tooltip.tsx create mode 100644 zookeeper-website/cli.json create mode 100644 zookeeper-website/e2e-tests/docs.spec.ts create mode 100644 zookeeper-website/e2e-tests/landing-page.spec.ts create mode 100644 zookeeper-website/e2e-tests/older-docs-picker.spec.ts create mode 100644 zookeeper-website/e2e-tests/theme.spec.ts create mode 100644 zookeeper-website/eslint.config.js create mode 100644 zookeeper-website/global.d.ts create mode 100644 zookeeper-website/package-lock.json create mode 100644 zookeeper-website/package.json create mode 100644 zookeeper-website/playwright.config.ts create mode 100644 zookeeper-website/plugins/released-docs-versions.ts create mode 100644 zookeeper-website/prettier.config.js create mode 100644 zookeeper-website/public/.htaccess create mode 100644 zookeeper-website/public/404.html rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/2pc.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/bk-overview.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/favicon.ico (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/state_dia.dia (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/state_dia.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkAuditLogs.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkarch.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkcomponents.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zknamespace.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkperfRW-3.2.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkperfRW.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkperfreliability.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zkservice.jpg (100%) rename {zookeeper-docs/src/main/resources/markdown/images => zookeeper-website/public/docs-images}/zookeeper_small.gif (100%) create mode 100644 zookeeper-website/public/favicon.ico create mode 100644 zookeeper-website/public/fonts/inter-latin-wght-italic.woff2 create mode 100644 zookeeper-website/public/fonts/inter-latin-wght-normal.woff2 create mode 100644 zookeeper-website/public/images/dark-theme-large-logo.svg create mode 100644 zookeeper-website/public/images/large-logo.svg create mode 100644 zookeeper-website/public/images/logo.svg create mode 100644 zookeeper-website/react-router.config.ts create mode 100644 zookeeper-website/source.config.ts create mode 100644 zookeeper-website/tsconfig.json create mode 100644 zookeeper-website/unit-tests/home.test.tsx create mode 100644 zookeeper-website/unit-tests/markdown.test.tsx create mode 100644 zookeeper-website/unit-tests/navigation.test.tsx create mode 100644 zookeeper-website/unit-tests/older-docs-picker.test.tsx create mode 100644 zookeeper-website/unit-tests/released-docs-versions.test.ts create mode 100644 zookeeper-website/unit-tests/setup.ts create mode 100644 zookeeper-website/unit-tests/theme-toggle.test.tsx create mode 100644 zookeeper-website/unit-tests/utils.tsx create mode 100644 zookeeper-website/vite.config.ts create mode 100644 zookeeper-website/vitest.config.ts diff --git a/zookeeper-docs/pom.xml b/zookeeper-docs/pom.xml deleted file mode 100644 index 9fd096092b5..00000000000 --- a/zookeeper-docs/pom.xml +++ /dev/null @@ -1,64 +0,0 @@ - - - - 4.0.0 - - org.apache.zookeeper - parent - 3.10.0-SNAPSHOT - - - zookeeper-docs - Apache ZooKeeper - Documentation - Documentation - pom - - - - - com.ruleoftech - markdown-page-generator-plugin - 2.1.0 - - - process-sources - - generate - - - - - ${project.basedir}/src/main/resources/markdown/html/header.html - ${project.basedir}/src/main/resources/markdown/html/footer.html - images,skin - TABLES,FENCED_CODE_BLOCKS - - - - maven-deploy-plugin - - - true - - - - - diff --git a/zookeeper-docs/src/main/resources/markdown/html/footer.html b/zookeeper-docs/src/main/resources/markdown/html/footer.html deleted file mode 100644 index 71d0c805feb..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/html/footer.html +++ /dev/null @@ -1,18 +0,0 @@ - -
 
- - - - \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/html/header.html b/zookeeper-docs/src/main/resources/markdown/html/header.html deleted file mode 100644 index c308b2d8894..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/html/header.html +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - ZooKeeper: Because Coordinating Distributed Systems is a Zoo - - - - - - - - - - -
-
- Apache > ZooKeeper -
-
- -
-
-   - -
-
- -
-
-
-
-
- -
-
-   -
- -
diff --git a/zookeeper-docs/src/main/resources/markdown/index.md b/zookeeper-docs/src/main/resources/markdown/index.md deleted file mode 100644 index d3e3864f342..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/index.md +++ /dev/null @@ -1,65 +0,0 @@ - - -## ZooKeeper: Because Coordinating Distributed Systems is a Zoo - -ZooKeeper is a high-performance coordination service for -distributed applications. It exposes common services - such as -naming, configuration management, synchronization, and group -services - in a simple interface so you don't have to write them -from scratch. You can use it off-the-shelf to implement -consensus, group management, leader election, and presence -protocols. And you can build on it for your own, specific needs. - -The following documents describe concepts and procedures to get -you started using ZooKeeper. If you have more questions, please -ask the [mailing list](http://zookeeper.apache.org/mailing_lists.html) or browse the -archives. - -+ **ZooKeeper Overview** - Technical Overview Documents for Client Developers, Administrators, and Contributors - + [Overview](zookeeperOver.html) - a bird's eye view of ZooKeeper, including design concepts and architecture - + [Getting Started](zookeeperStarted.html) - a tutorial-style guide for developers to install, run, and program to ZooKeeper - + [Release Notes](releasenotes.html) - new developer and user facing features, improvements, and incompatibilities -+ **Developers** - Documents for Developers using the ZooKeeper Client API - + [API Docs](apidocs/zookeeper-server/index.html) - the technical reference to ZooKeeper Client APIs - + [Programmer's Guide](zookeeperProgrammers.html) - a client application developer's guide to ZooKeeper - + [ZooKeeper Use Cases](zookeeperUseCases.html) - a series of use cases using the ZooKeeper. - + [ZooKeeper Java Example](javaExample.html) - a simple Zookeeper client application, written in Java - + [Barrier and Queue Tutorial](zookeeperTutorial.html) - sample implementations of barriers and queues - + [ZooKeeper Recipes](recipes.html) - higher level solutions to common problems in distributed applications -+ **Administrators & Operators** - Documents for Administrators and Operations Engineers of ZooKeeper Deployments - + [Administrator's Guide](zookeeperAdmin.html) - a guide for system administrators and anyone else who might deploy ZooKeeper - + [Quota Guide](zookeeperQuotas.html) - a guide for system administrators on Quotas in ZooKeeper. - + [Snapshot and Restore Guide](zookeeperSnapshotAndRestore.html) - a guide for system administrators on take snapshot and restore ZooKeeper. - + [JMX](zookeeperJMX.html) - how to enable JMX in ZooKeeper - + [Hierarchical Quorums](zookeeperHierarchicalQuorums.html) - a guide on how to use hierarchical quorums - + [Oracle Quorum](zookeeperOracleQuorums.html) - the introduction to Oracle Quorum increases the availability of a cluster of 2 ZooKeeper instances with a failure detector. - + [Observers](zookeeperObservers.html) - non-voting ensemble members that easily improve ZooKeeper's scalability - + [Dynamic Reconfiguration](zookeeperReconfig.html) - a guide on how to use dynamic reconfiguration in ZooKeeper - + [ZooKeeper CLI](zookeeperCLI.html) - a guide on how to use the ZooKeeper command line interface - + [ZooKeeper Tools](zookeeperTools.html) - a guide on how to use a series of tools for ZooKeeper - + [ZooKeeper Monitor](zookeeperMonitor.html) - a guide on how to monitor the ZooKeeper - + [Audit Logging](zookeeperAuditLogs.html) - a guide on how to configure audit logs in ZooKeeper Server and what contents are logged. -+ **Contributors** - Documents for Developers Contributing to the ZooKeeper Open Source Project - + [ZooKeeper Internals](zookeeperInternals.html) - assorted topics on the inner workings of ZooKeeper -+ **Miscellaneous ZooKeeper Documentation** - + [Wiki](https://cwiki.apache.org/confluence/display/ZOOKEEPER) - + [FAQ](https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ) - diff --git a/zookeeper-docs/src/main/resources/markdown/releasenotes.md b/zookeeper-docs/src/main/resources/markdown/releasenotes.md deleted file mode 100644 index a27b6ffdd12..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/releasenotes.md +++ /dev/null @@ -1,267 +0,0 @@ - - -# ZooKeeper 3.0.0 Release Notes - -* [Migration Instructions when Upgrading to 3.0.0](#migration) - * [Migrating Client Code](#migration_code) - * [Watch Management](#Watch+Management) - * [Java API](#Java+API) - * [C API](#C+API) - * [Migrating Server Data](#migration_data) - * [Migrating Server Configuration](#migration_config) -* [Changes Since ZooKeeper 2.2.1](#changes) - -These release notes include new developer and user facing incompatibilities, features, and major improvements. - -* [Migration Instructions](#migration) -* [Changes](#changes) - - -## Migration Instructions when Upgrading to 3.0.0 -
- -*You should only have to read this section if you are upgrading from a previous version of ZooKeeper to version 3.0.0, otw skip down to [changes](#changes)* - -A small number of changes in this release have resulted in non-backward compatible Zookeeper client user code and server instance data. The following instructions provide details on how to migrate code and date from version 2.2.1 to version 3.0.0. - -Note: ZooKeeper increments the major version number (major.minor.fix) when backward incompatible changes are made to the source base. As part of the migration from SourceForge we changed the package structure (com.yahoo.zookeeper.* to org.apache.zookeeper.*) and felt it was a good time to incorporate some changes that we had been withholding. As a result the following will be required when migrating from 2.2.1 to 3.0.0 version of ZooKeeper. - -* [Migrating Client Code](#migration_code) -* [Migrating Server Data](#migration_data) -* [Migrating Server Configuration](#migration_config) - - -### Migrating Client Code - -The underlying client-server protocol has changed in version 3.0.0 -of ZooKeeper. As a result clients must be upgraded along with -serving clusters to ensure proper operation of the system (old -pre-3.0.0 clients are not guaranteed to operate against upgraded -3.0.0 servers and vice-versa). - - -#### Watch Management - -In previous releases of ZooKeeper any watches registered by clients were lost if the client lost a connection to a ZooKeeper server. -This meant that developers had to track watches they were interested in and reregister them if a session disconnect event was received. -In this release the client library tracks watches that a client has registered and reregisters the watches when a connection is made to a new server. -Applications that still manually reregister interest should continue working properly as long as they are able to handle unsolicited watches. -For example, an old application may register a watch for /foo and /goo, lose the connection, and reregister only /goo. -As long as the application is able to receive a notification for /foo, (probably ignoring it) it does not need to be changed. -One caveat to the watch management: it is possible to miss an event for the creation and deletion of a znode if watching for creation and both the create and delete happens while the client is disconnected from ZooKeeper. - -This release also allows clients to specify call specific watch functions. -This gives the developer the ability to modularize logic in different watch functions rather than cramming everything in the watch function attached to the ZooKeeper handle. -Call specific watch functions receive all session events for as long as they are active, but will only receive the watch callbacks for which they are registered. - - -#### Java API - -1. The java package structure has changed from **com.yahoo.zookeeper*** to **org.apache.zookeeper***. This will probably affect all of your java code which makes use of ZooKeeper APIs (typically import statements) -1. A number of constants used in the client ZooKeeper API were re-specified using enums (rather than ints). See [ZOOKEEPER-7](https://issues.apache.org/jira/browse/ZOOKEEPER-7), [ZOOKEEPER-132](https://issues.apache.org/jira/browse/ZOOKEEPER-132) and [ZOOKEEPER-139](https://issues.apache.org/jira/browse/ZOOKEEPER-139) for full details -1. [ZOOKEEPER-18](https://issues.apache.org/jira/browse/ZOOKEEPER-18) removed KeeperStateChanged, use KeeperStateDisconnected instead - -Also see [the current Java API](http://zookeeper.apache.org/docs/current/apidocs/zookeeper-server/index.html) - - -#### C API - -1. A number of constants used in the client ZooKeeper API were renamed in order to reduce namespace collision, see [ZOOKEEPER-6](https://issues.apache.org/jira/browse/ZOOKEEPER-6) for full details - - -### Migrating Server Data -The following issues resulted in changes to the on-disk data format (the snapshot and transaction log files contained within the ZK data directory) and require a migration utility to be run. - -* [ZOOKEEPER-27 Unique DB identifiers for servers and clients](https://issues.apache.org/jira/browse/ZOOKEEPER-27) -* [ZOOKEEPER-32 CRCs for ZooKeeper data](https://issues.apache.org/jira/browse/ZOOKEEPER-32) -* [ZOOKEEPER-33 Better ACL management](https://issues.apache.org/jira/browse/ZOOKEEPER-33) -* [ZOOKEEPER-38 headers (version+) in log/snap files](https://issues.apache.org/jira/browse/ZOOKEEPER-38) - -**The following must be run once, and only once, when upgrading the ZooKeeper server instances to version 3.0.0.** - -###### Note -> The and directories referenced below are specified by the *dataLogDir* - and *dataDir* specification in your ZooKeeper config file respectively. *dataLogDir* defaults to - the value of *dataDir* if not specified explicitly in the ZooKeeper server config file (in which - case provide the same directory for both parameters to the upgrade utility). - -1. Shutdown the ZooKeeper server cluster. -1. Backup your and directories -1. Run upgrade using - * `bin/zkServer.sh upgrade ` - - or - - * `java -classpath pathtolog4j:pathtozookeeper.jar UpgradeMain ` - - where is the directory where all transaction logs (log.*) are stored. is the directory where all the snapshots (snapshot.*) are stored. -1. Restart the cluster. - -If you have any failure during the upgrade procedure keep reading to sanitize your database. - -This is how upgrade works in ZooKeeper. This will help you troubleshoot in case you have problems while upgrading - -1. Upgrade moves files from `` and `` to `/version-1/` and `/version-1` respectively (version-1 sub-directory is created by the upgrade utility). -1. Upgrade creates a new version sub-directory `/version-2` and `/version-2` -1. Upgrade reads the old database from `/version-1` and `/version-1` into the memory and creates a new upgraded snapshot. -1. Upgrade writes the new database in `/version-2`. - -Troubleshooting. - - -1. In case you start ZooKeeper 3.0 without upgrading from 2.0 on a 2.0 database - the servers will start up with an empty database. - This is because the servers assume that `/version-2` and `/version-2` will have the database to start with. Since this will be empty - in case of no upgrade, the servers will start with an empty database. In such a case, shutdown the ZooKeeper servers, remove the version-2 directory (remember - this will lead to loss of updates after you started 3.0.) - and then start the upgrade procedure. -1. If the upgrade fails while trying to rename files into the version-1 directory, you should try and move all the files under `/version-1` - and `/version-1` to `` and `` respectively. Then try upgrade again. -1. If you do not wish to run with ZooKeeper 3.0 and prefer to run with ZooKeeper 2.0 and have already upgraded - you can run ZooKeeper 2 with - the `` and `` directories changed to `/version-1` and `/version-1`. Remember that you will lose all the updates that you made after the upgrade. - - -### Migrating Server Configuration - -There is a significant change to the ZooKeeper server configuration file. - -The default election algorithm, specified by the *electionAlg* configuration attribute, has -changed from a default of *0* to a default of *3*. See -[Cluster Options](zookeeperAdmin.html#sc_clusterOptions) section of the administrators guide, specifically -the *electionAlg* and *server.X* properties. - -You will either need to explicitly set *electionAlg* to its previous default value -of *0* or change your *server.X* options to include the leader election port. - - - -## Changes Since ZooKeeper 2.2.1 - -Version 2.2.1 code, documentation, binaries, etc... are still accessible on [SourceForge](http://sourceforge.net/projects/zookeeper) - -| Issue | Notes | -|-------|-------| -|[ZOOKEEPER-43](https://issues.apache.org/jira/browse/ZOOKEEPER-43)|Server side of auto reset watches.| -|[ZOOKEEPER-132](https://issues.apache.org/jira/browse/ZOOKEEPER-132)|Create Enum to replace CreateFlag in ZooKepper.create method| -|[ZOOKEEPER-139](https://issues.apache.org/jira/browse/ZOOKEEPER-139)|Create Enums for WatcherEvent's KeeperState and EventType| -|[ZOOKEEPER-18](https://issues.apache.org/jira/browse/ZOOKEEPER-18)|keeper state inconsistency| -|[ZOOKEEPER-38](https://issues.apache.org/jira/browse/ZOOKEEPER-38)|headers in log/snap files| -|[ZOOKEEPER-8](https://issues.apache.org/jira/browse/ZOOKEEPER-8)|Stat enchaned to include num of children and size| -|[ZOOKEEPER-6](https://issues.apache.org/jira/browse/ZOOKEEPER-6)|List of problem identifiers in zookeeper.h| -|[ZOOKEEPER-7](https://issues.apache.org/jira/browse/ZOOKEEPER-7)|Use enums rather than ints for types and state| -|[ZOOKEEPER-27](https://issues.apache.org/jira/browse/ZOOKEEPER-27)|Unique DB identifiers for servers and clients| -|[ZOOKEEPER-32](https://issues.apache.org/jira/browse/ZOOKEEPER-32)|CRCs for ZooKeeper data| -|[ZOOKEEPER-33](https://issues.apache.org/jira/browse/ZOOKEEPER-33)|Better ACL management| -|[ZOOKEEPER-203](https://issues.apache.org/jira/browse/ZOOKEEPER-203)|fix datadir typo in releasenotes| -|[ZOOKEEPER-145](https://issues.apache.org/jira/browse/ZOOKEEPER-145)|write detailed release notes for users migrating from 2.x to 3.0| -|[ZOOKEEPER-23](https://issues.apache.org/jira/browse/ZOOKEEPER-23)|Auto reset of watches on reconnect| -|[ZOOKEEPER-191](https://issues.apache.org/jira/browse/ZOOKEEPER-191)|forrest docs for upgrade.| -|[ZOOKEEPER-201](https://issues.apache.org/jira/browse/ZOOKEEPER-201)|validate magic number when reading snapshot and transaction logs| -|[ZOOKEEPER-200](https://issues.apache.org/jira/browse/ZOOKEEPER-200)|the magic number for snapshot and log must be different| -|[ZOOKEEPER-199](https://issues.apache.org/jira/browse/ZOOKEEPER-199)|fix log messages in persistence code| -|[ZOOKEEPER-197](https://issues.apache.org/jira/browse/ZOOKEEPER-197)|create checksums for snapshots| -|[ZOOKEEPER-198](https://issues.apache.org/jira/browse/ZOOKEEPER-198)|apache license header missing from FollowerSyncRequest.java| -|[ZOOKEEPER-5](https://issues.apache.org/jira/browse/ZOOKEEPER-5)|Upgrade Feature in Zookeeper server.| -|[ZOOKEEPER-194](https://issues.apache.org/jira/browse/ZOOKEEPER-194)|Fix terminology in zookeeperAdmin.xml| -|[ZOOKEEPER-151](https://issues.apache.org/jira/browse/ZOOKEEPER-151)|Document change to server configuration| -|[ZOOKEEPER-193](https://issues.apache.org/jira/browse/ZOOKEEPER-193)|update java example doc to compile with latest zookeeper| -|[ZOOKEEPER-187](https://issues.apache.org/jira/browse/ZOOKEEPER-187)|CreateMode api docs missing| -|[ZOOKEEPER-186](https://issues.apache.org/jira/browse/ZOOKEEPER-186)|add new "releasenotes.xml" to forrest documentation| -|[ZOOKEEPER-190](https://issues.apache.org/jira/browse/ZOOKEEPER-190)|Reorg links to docs and navs to docs into related sections| -|[ZOOKEEPER-189](https://issues.apache.org/jira/browse/ZOOKEEPER-189)|forrest build not validated xml of input documents| -|[ZOOKEEPER-188](https://issues.apache.org/jira/browse/ZOOKEEPER-188)|Check that election port is present for all servers| -|[ZOOKEEPER-185](https://issues.apache.org/jira/browse/ZOOKEEPER-185)|Improved version of FLETest| -|[ZOOKEEPER-184](https://issues.apache.org/jira/browse/ZOOKEEPER-184)|tests: An explicit include directive is needed for the usage of memcpy functions| -|[ZOOKEEPER-183](https://issues.apache.org/jira/browse/ZOOKEEPER-183)|Array subscript is above array bounds in od_completion, src/cli.c.| -|[ZOOKEEPER-182](https://issues.apache.org/jira/browse/ZOOKEEPER-182)|zookeeper_init accepts empty host-port string and returns valid pointer to zhandle_t.| -|[ZOOKEEPER-17](https://issues.apache.org/jira/browse/ZOOKEEPER-17)|zookeeper_init doc needs clarification| -|[ZOOKEEPER-181](https://issues.apache.org/jira/browse/ZOOKEEPER-181)|Some Source Forge Documents did not get moved over: javaExample, zookeeperTutorial, zookeeperInternals| -|[ZOOKEEPER-180](https://issues.apache.org/jira/browse/ZOOKEEPER-180)|Placeholder sections needed in document for new topics that the umbrella jira discusses| -|[ZOOKEEPER-179](https://issues.apache.org/jira/browse/ZOOKEEPER-179)|Programmer's Guide "Basic Operations" section is missing content| -|[ZOOKEEPER-178](https://issues.apache.org/jira/browse/ZOOKEEPER-178)|FLE test.| -|[ZOOKEEPER-159](https://issues.apache.org/jira/browse/ZOOKEEPER-159)|Cover two corner cases of leader election| -|[ZOOKEEPER-156](https://issues.apache.org/jira/browse/ZOOKEEPER-156)|update programmer guide with acl details from old wiki page| -|[ZOOKEEPER-154](https://issues.apache.org/jira/browse/ZOOKEEPER-154)|reliability graph diagram in overview doc needs context| -|[ZOOKEEPER-157](https://issues.apache.org/jira/browse/ZOOKEEPER-157)|Peer can't find existing leader| -|[ZOOKEEPER-155](https://issues.apache.org/jira/browse/ZOOKEEPER-155)|improve "the zookeeper project" section of overview doc| -|[ZOOKEEPER-140](https://issues.apache.org/jira/browse/ZOOKEEPER-140)|Deadlock in QuorumCnxManager| -|[ZOOKEEPER-147](https://issues.apache.org/jira/browse/ZOOKEEPER-147)|This is version of the documents with most of the [tbd...] scrubbed out| -|[ZOOKEEPER-150](https://issues.apache.org/jira/browse/ZOOKEEPER-150)|zookeeper build broken| -|[ZOOKEEPER-136](https://issues.apache.org/jira/browse/ZOOKEEPER-136)|sync causes hang in all followers of quorum.| -|[ZOOKEEPER-134](https://issues.apache.org/jira/browse/ZOOKEEPER-134)|findbugs cleanup| -|[ZOOKEEPER-133](https://issues.apache.org/jira/browse/ZOOKEEPER-133)|hudson tests failing intermittently| -|[ZOOKEEPER-144](https://issues.apache.org/jira/browse/ZOOKEEPER-144)|add tostring support for watcher event, and enums for event type/state| -|[ZOOKEEPER-21](https://issues.apache.org/jira/browse/ZOOKEEPER-21)|Improve zk ctor/watcher| -|[ZOOKEEPER-142](https://issues.apache.org/jira/browse/ZOOKEEPER-142)|Provide Javadoc as to the maximum size of the data byte array that may be stored within a znode| -|[ZOOKEEPER-93](https://issues.apache.org/jira/browse/ZOOKEEPER-93)|Create Documentation for Zookeeper| -|[ZOOKEEPER-117](https://issues.apache.org/jira/browse/ZOOKEEPER-117)|threading issues in Leader election| -|[ZOOKEEPER-137](https://issues.apache.org/jira/browse/ZOOKEEPER-137)|client watcher objects can lose events| -|[ZOOKEEPER-131](https://issues.apache.org/jira/browse/ZOOKEEPER-131)|Old leader election can elect a dead leader over and over again| -|[ZOOKEEPER-130](https://issues.apache.org/jira/browse/ZOOKEEPER-130)|update build.xml to support apache release process| -|[ZOOKEEPER-118](https://issues.apache.org/jira/browse/ZOOKEEPER-118)|findbugs flagged switch statement in followerrequestprocessor.run| -|[ZOOKEEPER-115](https://issues.apache.org/jira/browse/ZOOKEEPER-115)|Potential NPE in QuorumCnxManager| -|[ZOOKEEPER-114](https://issues.apache.org/jira/browse/ZOOKEEPER-114)|cleanup ugly event messages in zookeeper client| -|[ZOOKEEPER-112](https://issues.apache.org/jira/browse/ZOOKEEPER-112)|src/java/main ZooKeeper.java has test code embedded into it.| -|[ZOOKEEPER-39](https://issues.apache.org/jira/browse/ZOOKEEPER-39)|Use Watcher objects rather than boolean on read operations.| -|[ZOOKEEPER-97](https://issues.apache.org/jira/browse/ZOOKEEPER-97)|supports optional output directory in code generator.| -|[ZOOKEEPER-101](https://issues.apache.org/jira/browse/ZOOKEEPER-101)|Integrate ZooKeeper with "violations" feature on hudson| -|[ZOOKEEPER-105](https://issues.apache.org/jira/browse/ZOOKEEPER-105)|Catch Zookeeper exceptions and print on the stderr.| -|[ZOOKEEPER-42](https://issues.apache.org/jira/browse/ZOOKEEPER-42)|Change Leader Election to fast tcp.| -|[ZOOKEEPER-48](https://issues.apache.org/jira/browse/ZOOKEEPER-48)|auth_id now handled correctly when no auth ids present| -|[ZOOKEEPER-44](https://issues.apache.org/jira/browse/ZOOKEEPER-44)|Create sequence flag children with prefixes of 0's so that they can be lexicographically sorted.| -|[ZOOKEEPER-108](https://issues.apache.org/jira/browse/ZOOKEEPER-108)|Fix sync operation reordering on a Quorum.| -|[ZOOKEEPER-25](https://issues.apache.org/jira/browse/ZOOKEEPER-25)|Fuse module for Zookeeper.| -|[ZOOKEEPER-58](https://issues.apache.org/jira/browse/ZOOKEEPER-58)|Race condition on ClientCnxn.java| -|[ZOOKEEPER-56](https://issues.apache.org/jira/browse/ZOOKEEPER-56)|Add clover support to build.xml.| -|[ZOOKEEPER-75](https://issues.apache.org/jira/browse/ZOOKEEPER-75)|register the ZooKeeper mailing lists with nabble.com| -|[ZOOKEEPER-54](https://issues.apache.org/jira/browse/ZOOKEEPER-54)|remove sleeps in the tests.| -|[ZOOKEEPER-55](https://issues.apache.org/jira/browse/ZOOKEEPER-55)|build.xml fails to retrieve a release number from SVN and the ant target "dist" fails| -|[ZOOKEEPER-89](https://issues.apache.org/jira/browse/ZOOKEEPER-89)|invoke WhenOwnerListener.whenNotOwner when the ZK connection fails| -|[ZOOKEEPER-90](https://issues.apache.org/jira/browse/ZOOKEEPER-90)|invoke WhenOwnerListener.whenNotOwner when the ZK session expires and the znode is the leader| -|[ZOOKEEPER-82](https://issues.apache.org/jira/browse/ZOOKEEPER-82)|Make the ZooKeeperServer more DI friendly.| -|[ZOOKEEPER-110](https://issues.apache.org/jira/browse/ZOOKEEPER-110)|Build script relies on svnant, which is not compatible with subversion 1.5 working copies| -|[ZOOKEEPER-111](https://issues.apache.org/jira/browse/ZOOKEEPER-111)|Significant cleanup of existing tests.| -|[ZOOKEEPER-122](https://issues.apache.org/jira/browse/ZOOKEEPER-122)|Fix NPE in jute's Utils.toCSVString.| -|[ZOOKEEPER-123](https://issues.apache.org/jira/browse/ZOOKEEPER-123)|Fix the wrong class is specified for the logger.| -|[ZOOKEEPER-2](https://issues.apache.org/jira/browse/ZOOKEEPER-2)|Fix synchronization issues in QuorumPeer and FastLeader election.| -|[ZOOKEEPER-125](https://issues.apache.org/jira/browse/ZOOKEEPER-125)|Remove unwanted class declaration in FastLeaderElection.| -|[ZOOKEEPER-61](https://issues.apache.org/jira/browse/ZOOKEEPER-61)|Address in client/server test cases.| -|[ZOOKEEPER-75](https://issues.apache.org/jira/browse/ZOOKEEPER-75)|cleanup the library directory| -|[ZOOKEEPER-109](https://issues.apache.org/jira/browse/ZOOKEEPER-109)|cleanup of NPE and Resource issue nits found by static analysis| -|[ZOOKEEPER-76](https://issues.apache.org/jira/browse/ZOOKEEPER-76)|Commit 677109 removed the cobertura library, but not the build targets.| -|[ZOOKEEPER-63](https://issues.apache.org/jira/browse/ZOOKEEPER-63)|Race condition in client close| -|[ZOOKEEPER-70](https://issues.apache.org/jira/browse/ZOOKEEPER-70)|Add skeleton forrest doc structure for ZooKeeper| -|[ZOOKEEPER-79](https://issues.apache.org/jira/browse/ZOOKEEPER-79)|Document jacob's leader election on the wiki recipes page| -|[ZOOKEEPER-73](https://issues.apache.org/jira/browse/ZOOKEEPER-73)|Move ZK wiki from SourceForge to Apache| -|[ZOOKEEPER-72](https://issues.apache.org/jira/browse/ZOOKEEPER-72)|Initial creation/setup of ZooKeeper ASF site.| -|[ZOOKEEPER-71](https://issues.apache.org/jira/browse/ZOOKEEPER-71)|Determine what to do re ZooKeeper Changelog| -|[ZOOKEEPER-68](https://issues.apache.org/jira/browse/ZOOKEEPER-68)|parseACLs in ZooKeeper.java fails to parse elements of ACL, should be lastIndexOf rather than IndexOf| -|[ZOOKEEPER-130](https://issues.apache.org/jira/browse/ZOOKEEPER-130)|update build.xml to support apache release process.| -|[ZOOKEEPER-131](https://issues.apache.org/jira/browse/ZOOKEEPER-131)|Fix Old leader election can elect a dead leader over and over again.| -|[ZOOKEEPER-137](https://issues.apache.org/jira/browse/ZOOKEEPER-137)|client watcher objects can lose events| -|[ZOOKEEPER-117](https://issues.apache.org/jira/browse/ZOOKEEPER-117)|threading issues in Leader election| -|[ZOOKEEPER-128](https://issues.apache.org/jira/browse/ZOOKEEPER-128)|test coverage on async client operations needs to be improved| -|[ZOOKEEPER-127](https://issues.apache.org/jira/browse/ZOOKEEPER-127)|Use of non-standard election ports in config breaks services| -|[ZOOKEEPER-53](https://issues.apache.org/jira/browse/ZOOKEEPER-53)|tests failing on solaris.| -|[ZOOKEEPER-172](https://issues.apache.org/jira/browse/ZOOKEEPER-172)|FLE Test| -|[ZOOKEEPER-41](https://issues.apache.org/jira/browse/ZOOKEEPER-41)|Sample startup script| -|[ZOOKEEPER-33](https://issues.apache.org/jira/browse/ZOOKEEPER-33)|Better ACL management| -|[ZOOKEEPER-49](https://issues.apache.org/jira/browse/ZOOKEEPER-49)|SetACL does not work| -|[ZOOKEEPER-20](https://issues.apache.org/jira/browse/ZOOKEEPER-20)|Child watches are not triggered when the node is deleted| -|[ZOOKEEPER-15](https://issues.apache.org/jira/browse/ZOOKEEPER-15)|handle failure better in build.xml:test| -|[ZOOKEEPER-11](https://issues.apache.org/jira/browse/ZOOKEEPER-11)|ArrayList is used instead of List| -|[ZOOKEEPER-45](https://issues.apache.org/jira/browse/ZOOKEEPER-45)|Restructure the SVN repository after initial import | -|[ZOOKEEPER-1](https://issues.apache.org/jira/browse/ZOOKEEPER-1)|Initial ZooKeeper code contribution from Yahoo!| diff --git a/zookeeper-docs/src/main/resources/markdown/skin/basic.css b/zookeeper-docs/src/main/resources/markdown/skin/basic.css deleted file mode 100644 index 01c383da891..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/basic.css +++ /dev/null @@ -1,167 +0,0 @@ -/* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -/** - * General - */ - -img { border: 0; } - -#content table { - border: 0; - width: 100%; -} -/*Hack to get IE to render the table at 100%*/ -* html #content table { margin-left: -3px; } - -#content th, -#content td { - margin: 0; - padding: 0; - vertical-align: top; -} - -.clearboth { - clear: both; -} - -.note, .warning, .fixme { - clear:right; - border: solid black 1px; - margin: 1em 3em; -} - -.note .label { - background: #369; - color: white; - font-weight: bold; - padding: 5px 10px; -} -.note .content { - background: #F0F0FF; - color: black; - line-height: 120%; - font-size: 90%; - padding: 5px 10px; -} -.warning .label { - background: #C00; - color: white; - font-weight: bold; - padding: 5px 10px; -} -.warning .content { - background: #FFF0F0; - color: black; - line-height: 120%; - font-size: 90%; - padding: 5px 10px; -} -.fixme .label { - background: #C6C600; - color: black; - font-weight: bold; - padding: 5px 10px; -} -.fixme .content { - padding: 5px 10px; -} - -/** - * Typography - */ - -body { - font-family: verdana, "Trebuchet MS", arial, helvetica, sans-serif; - font-size: 100%; -} - -#content { - font-family: Georgia, Palatino, Times, serif; - font-size: 95%; -} -#tabs { - font-size: 70%; -} -#menu { - font-size: 80%; -} -#footer { - font-size: 70%; -} - -h1, h2, h3, h4, h5, h6 { - font-family: "Trebuchet MS", verdana, arial, helvetica, sans-serif; - font-weight: bold; - margin-top: 1em; - margin-bottom: .5em; -} - -h1 { - margin-top: 0; - margin-bottom: 1em; - font-size: 1.4em; -} -#content h1 { - font-size: 160%; - margin-bottom: .5em; -} -#menu h1 { - margin: 0; - padding: 10px; - background: #336699; - color: white; -} -h2 { font-size: 120%; } -h3 { font-size: 100%; } -h4 { font-size: 90%; } -h5 { font-size: 80%; } -h6 { font-size: 75%; } - -p { - line-height: 120%; - text-align: left; - margin-top: .5em; - margin-bottom: 1em; -} - -#content li, -#content th, -#content td, -#content li ul, -#content li ol{ - margin-top: .5em; - margin-bottom: .5em; -} - - -#content li li, -#minitoc-area li{ - margin-top: 0em; - margin-bottom: 0em; -} - -#content .attribution { - text-align: right; - font-style: italic; - font-size: 85%; - margin-top: 1em; -} - -.codefrag { - font-family: "Courier New", Courier, monospace; - font-size: 110%; -} \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/skin/chapter.gif b/zookeeper-docs/src/main/resources/markdown/skin/chapter.gif deleted file mode 100644 index d3d8245d0c7693b5b6c6f25ca9d615858656d4ad..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 49 zcmZ?wbhEHbWMN=uXkcJiy6xEi|Nj+#vM@3*Ff!;c00Bsbfr-O~Pb~Az>JSYEYXC!` B3(^1p diff --git a/zookeeper-docs/src/main/resources/markdown/skin/chapter_open.gif b/zookeeper-docs/src/main/resources/markdown/skin/chapter_open.gif deleted file mode 100644 index eecce18b50a0146d663334eb5b38691fa40b4d5a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 49 zcmZ?wbhEHbWM^PuXkcJiy6xEi|Nj+#vM@3*Ff!;c00Bsbfr+Dqzfm%aH&TPa8UR61 B3ljhU diff --git a/zookeeper-docs/src/main/resources/markdown/skin/current.gif b/zookeeper-docs/src/main/resources/markdown/skin/current.gif deleted file mode 100644 index fd82c082012faa682ecd4e68d2eedef9ae2e6231..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 54 zcmZ?wbhEHb - * - */ - diff --git a/zookeeper-docs/src/main/resources/markdown/skin/getMenu.js b/zookeeper-docs/src/main/resources/markdown/skin/getMenu.js deleted file mode 100644 index 6878b2653b8..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/getMenu.js +++ /dev/null @@ -1,45 +0,0 @@ -/* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -/** - * This script, when included in a html file, can be used to make collapsible menus - * - * Typical usage: - * - */ - -if (document.getElementById){ - document.write('') -} - - -function SwitchMenu(obj, thePath) -{ -var open = 'url("'+thePath + 'chapter_open.gif")'; -var close = 'url("'+thePath + 'chapter.gif")'; - if(document.getElementById) { - var el = document.getElementById(obj); - var title = document.getElementById(obj+'Title'); - - if(el.style.display != "block"){ - title.style.backgroundImage = open; - el.style.display = "block"; - }else{ - title.style.backgroundImage = close; - el.style.display = "none"; - } - }// end - if(document.getElementById) -}//end - function SwitchMenu(obj) diff --git a/zookeeper-docs/src/main/resources/markdown/skin/header_white_line.gif b/zookeeper-docs/src/main/resources/markdown/skin/header_white_line.gif deleted file mode 100644 index 369cae8dcf2da7d30c4ed7a8781b6bdf95a022d6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 37 pcmZ?wbh9u|6k%XwXkcLY|NsA?3y*XdfB+=Iz{JwhKa-Wg8UV|E3E%(# diff --git a/zookeeper-docs/src/main/resources/markdown/skin/init.js b/zookeeper-docs/src/main/resources/markdown/skin/init.js deleted file mode 100644 index fa40beb7545..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/init.js +++ /dev/null @@ -1,57 +0,0 @@ -/* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -/** - * This script, when included in a html file, can be used to make collapsible menus - * - * Typical usage: - * - */ - -function getFileName(url){ - var fileName = url.substring(url.lastIndexOf('/')+1); - return fileName; -} - -function init(){ - var url = window .location.pathname; - var fileName = getFileName(url); - - var menuItemGroup = document.getElementById("menu").children; - - for (i = 0; i < menuItemGroup.length; i++) { - if("menutitle" === menuItemGroup[i].className){ - continue; - } - var menuItem = menuItemGroup[i].children; - if(menuItem.length>0){ - for (j = 0; j < menuItem.length; j++) { - if(menuItem[j].firstElementChild != null){ - var linkItem = menuItem[j].firstElementChild; - if('a' === linkItem.localName){ - var linkFile = getFileName(linkItem.href); - if(fileName === linkFile && linkItem.href.lastIndexOf("apidocs/zookeeper-server/index.html")<0){ - linkItem.className = "selected"; - linkItem.parentNode.parentNode.className = "selectedmenuitemgroup"; - var title = document.getElementById(linkItem.parentNode.parentNode.id+"Title"); - title.className="menutitle selected"; - } - } - } - } - } - } -} diff --git a/zookeeper-docs/src/main/resources/markdown/skin/instruction_arrow.png b/zookeeper-docs/src/main/resources/markdown/skin/instruction_arrow.png deleted file mode 100644 index 0fbc72452bf9885757882932eb78d14b44403466..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 285 zcmeAS@N?(olHy`uVBq!ia0vp^fn9o^tnS&|T3i>qxFe$? f}PJadT6$68(tDnm{r-UW|L@jfU diff --git a/zookeeper-docs/src/main/resources/markdown/skin/menu.js b/zookeeper-docs/src/main/resources/markdown/skin/menu.js deleted file mode 100644 index 06ea471dc57..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/menu.js +++ /dev/null @@ -1,48 +0,0 @@ -/* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -/** - * This script, when included in a html file, can be used to make collapsible menus - * - * Typical usage: - * - */ - -if (document.getElementById){ - document.write('') -} - -function SwitchMenu(obj) -{ - if(document.getElementById) { - var el = document.getElementById(obj); - var title = document.getElementById(obj+'Title'); - - if(obj.indexOf("_selected_")==0&&el.style.display == ""){ - el.style.display = "block"; - title.className = "pagegroupselected"; - } - - if(el.style.display != "block"){ - el.style.display = "block"; - title.className = "pagegroupopen"; - } - else{ - el.style.display = "none"; - title.className = "pagegroup"; - } - }// end - if(document.getElementById) -}//end - function SwitchMenu(obj) diff --git a/zookeeper-docs/src/main/resources/markdown/skin/page.gif b/zookeeper-docs/src/main/resources/markdown/skin/page.gif deleted file mode 100644 index a144d3295be63ebed0bc574146851a5a392fed89..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 79 zcmZ?wbhEHbdhCYGe8D3oWGWGIAWq$;?3`UWs4{$yd~ fVqj#@VE_V<76vBXp8m=M4RQ+_jm%nu85yhr=axdUs$VmXNZB}bC%VxwSp6_waJ)d|kVIc)zPRqeIZZsP!%PWP&!rJ{ccrcVef_824V*rcNe`YK8X6u^&TVfiYDOC!)l_wikn`gg#xkmuz4&!! zCzsZ~Q+eXo?}^E*8nm^kOS`apx&1SHP xOSk{*ch5;mUqxD8)P4*PsMYcJGhc`tpL?Kv*ou)#zg(Cser$hB&OAcs)<55`ex3jT diff --git a/zookeeper-docs/src/main/resources/markdown/skin/profile.css b/zookeeper-docs/src/main/resources/markdown/skin/profile.css deleted file mode 100644 index 190e74f32ac..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/profile.css +++ /dev/null @@ -1,159 +0,0 @@ - - -/* ==================== aural ============================ */ - -@media aural { - h1, h2, h3, h4, h5, h6 { voice-family: paul, male; stress: 20; richness: 90 } - h1 { pitch: x-low; pitch-range: 90 } - h2 { pitch: x-low; pitch-range: 80 } - h3 { pitch: low; pitch-range: 70 } - h4 { pitch: medium; pitch-range: 60 } - h5 { pitch: medium; pitch-range: 50 } - h6 { pitch: medium; pitch-range: 40 } - li, dt, dd { pitch: medium; richness: 60 } - dt { stress: 80 } - pre, code, tt { pitch: medium; pitch-range: 0; stress: 0; richness: 80 } - em { pitch: medium; pitch-range: 60; stress: 60; richness: 50 } - strong { pitch: medium; pitch-range: 60; stress: 90; richness: 90 } - dfn { pitch: high; pitch-range: 60; stress: 60 } - s, strike { richness: 0 } - i { pitch: medium; pitch-range: 60; stress: 60; richness: 50 } - b { pitch: medium; pitch-range: 60; stress: 90; richness: 90 } - u { richness: 0 } - - :link { voice-family: harry, male } - :visited { voice-family: betty, female } - :active { voice-family: betty, female; pitch-range: 80; pitch: x-high } -} - -#top { background-color: #FFFFFF;} - -#top .header .current { background-color: #4C6C8F;} -#top .header .current a:link { color: #ffffff; } -#top .header .current a:visited { color: #ffffff; } -#top .header .current a:hover { color: #ffffff; } - -#tabs li { background-color: #E5E4D9 ;} -#tabs li a:link { color: #000000; } -#tabs li a:visited { color: #000000; } -#tabs li a:hover { color: #000000; } - -#level2tabs a.selected { background-color: #4C6C8F ;} -#level2tabs a:link { color: #ffffff; } -#level2tabs a:visited { color: #ffffff; } -#level2tabs a:hover { color: #ffffff; } - -#level2tabs { background-color: #E5E4D9;} -#level2tabs a.unselected:link { color: #000000; } -#level2tabs a.unselected:visited { color: #000000; } -#level2tabs a.unselected:hover { color: #000000; } - -.heading { background-color: #E5E4D9;} - -.boxed { background-color: #E5E4D9;} -.underlined_5 {border-bottom: solid 5px #E5E4D9;} -.underlined_10 {border-bottom: solid 10px #E5E4D9;} -table caption { -background-color: #E5E4D9; -color: #000000; -} - -#feedback { -color: #FFFFFF; -background: #4C6C8F; -text-align: center; -} -#feedback #feedbackto { -color: #FFFFFF; -} - -#publishedStrip { -color: #FFFFFF; -background: #4C6C8F; -} - -#publishedStrip { -color: #000000; -background: #E5E4D9; -} - -#menu a.selected { background-color: #CFDCED; - border-color: #999999; - color: #000000;} -#menu a.selected:visited { color: #000000;} - -#menu { border-color: #999999;} -#menu .menupageitemgroup { border-color: #999999;} - -#menu { background-color: #4C6C8F;} -#menu { color: #ffffff;} -#menu a:link { color: #ffffff;} -#menu a:visited { color: #ffffff;} -#menu a:hover { -background-color: #4C6C8F; -color: #ffffff;} - -#menu h1 { -color: #000000; -background-color: #cfdced; -} - -#top .searchbox { -background-color: #E5E4D9 ; -color: #000000; -} - -#menu .menupageitemgroup { -background-color: #E5E4D9; -} -#menu .menupageitem { -color: #000000; -} -#menu .menupageitem a:link { color: #000000;} -#menu .menupageitem a:visited { color: #000000;} -#menu .menupageitem a:hover { -background-color: #E5E4D9; -color: #000000; -} - -body{ -background-color: #ffffff; -color: #000000; -} -a:link { color:#0000ff} -a:visited { color:#009999} -a:hover { color:#6587ff} - - -.ForrestTable { background-color: #ccc;} - -.ForrestTable td { background-color: #ffffff;} - -.highlight { background-color: #ffff00;} - -.fixme { border-color: #c60;} - -.note { border-color: #069;} - -.warning { border-color: #900;} - -#footer { background-color: #E5E4D9;} -/* extra-css */ - - p.quote { - margin-left: 2em; - padding: .5em; - background-color: #f0f0f0; - font-family: monospace; - } - - pre { - margin-left: 0em; - padding: 0.5em; - background-color: #f0f0f0; - font-family: monospace; - } - - - - \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/skin/prototype.js b/zookeeper-docs/src/main/resources/markdown/skin/prototype.js deleted file mode 100644 index cc89dafcd6a..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/prototype.js +++ /dev/null @@ -1,7588 +0,0 @@ -/* Prototype JavaScript framework, version 1.7.3 - * (c) 2005-2010 Sam Stephenson - * - * Prototype is freely distributable under the terms of an MIT-style license. - * For details, see the Prototype web site: http://www.prototypejs.org/ - * - *--------------------------------------------------------------------------*/ - -var Prototype = { - - Version: '1.7.3', - - Browser: (function(){ - var ua = navigator.userAgent; - var isOpera = Object.prototype.toString.call(window.opera) == '[object Opera]'; - return { - IE: !!window.attachEvent && !isOpera, - Opera: isOpera, - WebKit: ua.indexOf('AppleWebKit/') > -1, - Gecko: ua.indexOf('Gecko') > -1 && ua.indexOf('KHTML') === -1, - MobileSafari: /Apple.*Mobile/.test(ua) - } - })(), - - BrowserFeatures: { - XPath: !!document.evaluate, - - SelectorsAPI: !!document.querySelector, - - ElementExtensions: (function() { - var constructor = window.Element || window.HTMLElement; - return !!(constructor && constructor.prototype); - })(), - SpecificElementExtensions: (function() { - if (typeof window.HTMLDivElement !== 'undefined') - return true; - - var div = document.createElement('div'), - form = document.createElement('form'), - isSupported = false; - - if (div['__proto__'] && (div['__proto__'] !== form['__proto__'])) { - isSupported = true; - } - - div = form = null; - - return isSupported; - })() - }, - - ScriptFragment: ']*>([\\S\\s]*?)<\/script\\s*>', - JSONFilter: /^\/\*-secure-([\s\S]*)\*\/\s*$/, - - emptyFunction: function() { }, - - K: function(x) { return x } -}; - -if (Prototype.Browser.MobileSafari) - Prototype.BrowserFeatures.SpecificElementExtensions = false; -/* Based on Alex Arnell's inheritance implementation. */ - -var Class = (function() { - - var IS_DONTENUM_BUGGY = (function(){ - for (var p in { toString: 1 }) { - if (p === 'toString') return false; - } - return true; - })(); - - function subclass() {}; - function create() { - var parent = null, properties = $A(arguments); - if (Object.isFunction(properties[0])) - parent = properties.shift(); - - function klass() { - this.initialize.apply(this, arguments); - } - - Object.extend(klass, Class.Methods); - klass.superclass = parent; - klass.subclasses = []; - - if (parent) { - subclass.prototype = parent.prototype; - klass.prototype = new subclass; - parent.subclasses.push(klass); - } - - for (var i = 0, length = properties.length; i < length; i++) - klass.addMethods(properties[i]); - - if (!klass.prototype.initialize) - klass.prototype.initialize = Prototype.emptyFunction; - - klass.prototype.constructor = klass; - return klass; - } - - function addMethods(source) { - var ancestor = this.superclass && this.superclass.prototype, - properties = Object.keys(source); - - if (IS_DONTENUM_BUGGY) { - if (source.toString != Object.prototype.toString) - properties.push("toString"); - if (source.valueOf != Object.prototype.valueOf) - properties.push("valueOf"); - } - - for (var i = 0, length = properties.length; i < length; i++) { - var property = properties[i], value = source[property]; - if (ancestor && Object.isFunction(value) && - value.argumentNames()[0] == "$super") { - var method = value; - value = (function(m) { - return function() { return ancestor[m].apply(this, arguments); }; - })(property).wrap(method); - - value.valueOf = (function(method) { - return function() { return method.valueOf.call(method); }; - })(method); - - value.toString = (function(method) { - return function() { return method.toString.call(method); }; - })(method); - } - this.prototype[property] = value; - } - - return this; - } - - return { - create: create, - Methods: { - addMethods: addMethods - } - }; -})(); -(function() { - - var _toString = Object.prototype.toString, - _hasOwnProperty = Object.prototype.hasOwnProperty, - NULL_TYPE = 'Null', - UNDEFINED_TYPE = 'Undefined', - BOOLEAN_TYPE = 'Boolean', - NUMBER_TYPE = 'Number', - STRING_TYPE = 'String', - OBJECT_TYPE = 'Object', - FUNCTION_CLASS = '[object Function]', - BOOLEAN_CLASS = '[object Boolean]', - NUMBER_CLASS = '[object Number]', - STRING_CLASS = '[object String]', - ARRAY_CLASS = '[object Array]', - DATE_CLASS = '[object Date]', - NATIVE_JSON_STRINGIFY_SUPPORT = window.JSON && - typeof JSON.stringify === 'function' && - JSON.stringify(0) === '0' && - typeof JSON.stringify(Prototype.K) === 'undefined'; - - - - var DONT_ENUMS = ['toString', 'toLocaleString', 'valueOf', - 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', 'constructor']; - - var IS_DONTENUM_BUGGY = (function(){ - for (var p in { toString: 1 }) { - if (p === 'toString') return false; - } - return true; - })(); - - function Type(o) { - switch(o) { - case null: return NULL_TYPE; - case (void 0): return UNDEFINED_TYPE; - } - var type = typeof o; - switch(type) { - case 'boolean': return BOOLEAN_TYPE; - case 'number': return NUMBER_TYPE; - case 'string': return STRING_TYPE; - } - return OBJECT_TYPE; - } - - function extend(destination, source) { - for (var property in source) - destination[property] = source[property]; - return destination; - } - - function inspect(object) { - try { - if (isUndefined(object)) return 'undefined'; - if (object === null) return 'null'; - return object.inspect ? object.inspect() : String(object); - } catch (e) { - if (e instanceof RangeError) return '...'; - throw e; - } - } - - function toJSON(value) { - return Str('', { '': value }, []); - } - - function Str(key, holder, stack) { - var value = holder[key]; - if (Type(value) === OBJECT_TYPE && typeof value.toJSON === 'function') { - value = value.toJSON(key); - } - - var _class = _toString.call(value); - - switch (_class) { - case NUMBER_CLASS: - case BOOLEAN_CLASS: - case STRING_CLASS: - value = value.valueOf(); - } - - switch (value) { - case null: return 'null'; - case true: return 'true'; - case false: return 'false'; - } - - var type = typeof value; - switch (type) { - case 'string': - return value.inspect(true); - case 'number': - return isFinite(value) ? String(value) : 'null'; - case 'object': - - for (var i = 0, length = stack.length; i < length; i++) { - if (stack[i] === value) { - throw new TypeError("Cyclic reference to '" + value + "' in object"); - } - } - stack.push(value); - - var partial = []; - if (_class === ARRAY_CLASS) { - for (var i = 0, length = value.length; i < length; i++) { - var str = Str(i, value, stack); - partial.push(typeof str === 'undefined' ? 'null' : str); - } - partial = '[' + partial.join(',') + ']'; - } else { - var keys = Object.keys(value); - for (var i = 0, length = keys.length; i < length; i++) { - var key = keys[i], str = Str(key, value, stack); - if (typeof str !== "undefined") { - partial.push(key.inspect(true)+ ':' + str); - } - } - partial = '{' + partial.join(',') + '}'; - } - stack.pop(); - return partial; - } - } - - function stringify(object) { - return JSON.stringify(object); - } - - function toQueryString(object) { - return $H(object).toQueryString(); - } - - function toHTML(object) { - return object && object.toHTML ? object.toHTML() : String.interpret(object); - } - - function keys(object) { - if (Type(object) !== OBJECT_TYPE) { throw new TypeError(); } - var results = []; - for (var property in object) { - if (_hasOwnProperty.call(object, property)) - results.push(property); - } - - if (IS_DONTENUM_BUGGY) { - for (var i = 0; property = DONT_ENUMS[i]; i++) { - if (_hasOwnProperty.call(object, property)) - results.push(property); - } - } - - return results; - } - - function values(object) { - var results = []; - for (var property in object) - results.push(object[property]); - return results; - } - - function clone(object) { - return extend({ }, object); - } - - function isElement(object) { - return !!(object && object.nodeType == 1); - } - - function isArray(object) { - return _toString.call(object) === ARRAY_CLASS; - } - - var hasNativeIsArray = (typeof Array.isArray == 'function') - && Array.isArray([]) && !Array.isArray({}); - - if (hasNativeIsArray) { - isArray = Array.isArray; - } - - function isHash(object) { - return object instanceof Hash; - } - - function isFunction(object) { - return _toString.call(object) === FUNCTION_CLASS; - } - - function isString(object) { - return _toString.call(object) === STRING_CLASS; - } - - function isNumber(object) { - return _toString.call(object) === NUMBER_CLASS; - } - - function isDate(object) { - return _toString.call(object) === DATE_CLASS; - } - - function isUndefined(object) { - return typeof object === "undefined"; - } - - extend(Object, { - extend: extend, - inspect: inspect, - toJSON: NATIVE_JSON_STRINGIFY_SUPPORT ? stringify : toJSON, - toQueryString: toQueryString, - toHTML: toHTML, - keys: Object.keys || keys, - values: values, - clone: clone, - isElement: isElement, - isArray: isArray, - isHash: isHash, - isFunction: isFunction, - isString: isString, - isNumber: isNumber, - isDate: isDate, - isUndefined: isUndefined - }); -})(); -Object.extend(Function.prototype, (function() { - var slice = Array.prototype.slice; - - function update(array, args) { - var arrayLength = array.length, length = args.length; - while (length--) array[arrayLength + length] = args[length]; - return array; - } - - function merge(array, args) { - array = slice.call(array, 0); - return update(array, args); - } - - function argumentNames() { - var names = this.toString().match(/^[\s\(]*function[^(]*\(([^)]*)\)/)[1] - .replace(/\/\/.*?[\r\n]|\/\*(?:.|[\r\n])*?\*\//g, '') - .replace(/\s+/g, '').split(','); - return names.length == 1 && !names[0] ? [] : names; - } - - - function bind(context) { - if (arguments.length < 2 && Object.isUndefined(arguments[0])) - return this; - - if (!Object.isFunction(this)) - throw new TypeError("The object is not callable."); - - var nop = function() {}; - var __method = this, args = slice.call(arguments, 1); - - var bound = function() { - var a = merge(args, arguments); - var c = this instanceof bound ? this : context; - return __method.apply(c, a); - }; - - nop.prototype = this.prototype; - bound.prototype = new nop(); - - return bound; - } - - function bindAsEventListener(context) { - var __method = this, args = slice.call(arguments, 1); - return function(event) { - var a = update([event || window.event], args); - return __method.apply(context, a); - } - } - - function curry() { - if (!arguments.length) return this; - var __method = this, args = slice.call(arguments, 0); - return function() { - var a = merge(args, arguments); - return __method.apply(this, a); - } - } - - function delay(timeout) { - var __method = this, args = slice.call(arguments, 1); - timeout = timeout * 1000; - return window.setTimeout(function() { - return __method.apply(__method, args); - }, timeout); - } - - function defer() { - var args = update([0.01], arguments); - return this.delay.apply(this, args); - } - - function wrap(wrapper) { - var __method = this; - return function() { - var a = update([__method.bind(this)], arguments); - return wrapper.apply(this, a); - } - } - - function methodize() { - if (this._methodized) return this._methodized; - var __method = this; - return this._methodized = function() { - var a = update([this], arguments); - return __method.apply(null, a); - }; - } - - var extensions = { - argumentNames: argumentNames, - bindAsEventListener: bindAsEventListener, - curry: curry, - delay: delay, - defer: defer, - wrap: wrap, - methodize: methodize - }; - - if (!Function.prototype.bind) - extensions.bind = bind; - - return extensions; -})()); - - - -(function(proto) { - - - function toISOString() { - return this.getUTCFullYear() + '-' + - (this.getUTCMonth() + 1).toPaddedString(2) + '-' + - this.getUTCDate().toPaddedString(2) + 'T' + - this.getUTCHours().toPaddedString(2) + ':' + - this.getUTCMinutes().toPaddedString(2) + ':' + - this.getUTCSeconds().toPaddedString(2) + 'Z'; - } - - - function toJSON() { - return this.toISOString(); - } - - if (!proto.toISOString) proto.toISOString = toISOString; - if (!proto.toJSON) proto.toJSON = toJSON; - -})(Date.prototype); - - -RegExp.prototype.match = RegExp.prototype.test; - -RegExp.escape = function(str) { - return String(str).replace(/([.*+?^=!:${}()|[\]\/\\])/g, '\\$1'); -}; -var PeriodicalExecuter = Class.create({ - initialize: function(callback, frequency) { - this.callback = callback; - this.frequency = frequency; - this.currentlyExecuting = false; - - this.registerCallback(); - }, - - registerCallback: function() { - this.timer = setInterval(this.onTimerEvent.bind(this), this.frequency * 1000); - }, - - execute: function() { - this.callback(this); - }, - - stop: function() { - if (!this.timer) return; - clearInterval(this.timer); - this.timer = null; - }, - - onTimerEvent: function() { - if (!this.currentlyExecuting) { - try { - this.currentlyExecuting = true; - this.execute(); - this.currentlyExecuting = false; - } catch(e) { - this.currentlyExecuting = false; - throw e; - } - } - } -}); -Object.extend(String, { - interpret: function(value) { - return value == null ? '' : String(value); - }, - specialChar: { - '\b': '\\b', - '\t': '\\t', - '\n': '\\n', - '\f': '\\f', - '\r': '\\r', - '\\': '\\\\' - } -}); - -Object.extend(String.prototype, (function() { - var NATIVE_JSON_PARSE_SUPPORT = window.JSON && - typeof JSON.parse === 'function' && - JSON.parse('{"test": true}').test; - - function prepareReplacement(replacement) { - if (Object.isFunction(replacement)) return replacement; - var template = new Template(replacement); - return function(match) { return template.evaluate(match) }; - } - - function isNonEmptyRegExp(regexp) { - return regexp.source && regexp.source !== '(?:)'; - } - - - function gsub(pattern, replacement) { - var result = '', source = this, match; - replacement = prepareReplacement(replacement); - - if (Object.isString(pattern)) - pattern = RegExp.escape(pattern); - - if (!(pattern.length || isNonEmptyRegExp(pattern))) { - replacement = replacement(''); - return replacement + source.split('').join(replacement) + replacement; - } - - while (source.length > 0) { - match = source.match(pattern) - if (match && match[0].length > 0) { - result += source.slice(0, match.index); - result += String.interpret(replacement(match)); - source = source.slice(match.index + match[0].length); - } else { - result += source, source = ''; - } - } - return result; - } - - function sub(pattern, replacement, count) { - replacement = prepareReplacement(replacement); - count = Object.isUndefined(count) ? 1 : count; - - return this.gsub(pattern, function(match) { - if (--count < 0) return match[0]; - return replacement(match); - }); - } - - function scan(pattern, iterator) { - this.gsub(pattern, iterator); - return String(this); - } - - function truncate(length, truncation) { - length = length || 30; - truncation = Object.isUndefined(truncation) ? '...' : truncation; - return this.length > length ? - this.slice(0, length - truncation.length) + truncation : String(this); - } - - function strip() { - return this.replace(/^\s+/, '').replace(/\s+$/, ''); - } - - function stripTags() { - return this.replace(/<\w+(\s+("[^"]*"|'[^']*'|[^>])+)?(\/)?>|<\/\w+>/gi, ''); - } - - function stripScripts() { - return this.replace(new RegExp(Prototype.ScriptFragment, 'img'), ''); - } - - function extractScripts() { - var matchAll = new RegExp(Prototype.ScriptFragment, 'img'), - matchOne = new RegExp(Prototype.ScriptFragment, 'im'); - return (this.match(matchAll) || []).map(function(scriptTag) { - return (scriptTag.match(matchOne) || ['', ''])[1]; - }); - } - - function evalScripts() { - return this.extractScripts().map(function(script) { return eval(script); }); - } - - function escapeHTML() { - return this.replace(/&/g,'&').replace(//g,'>'); - } - - function unescapeHTML() { - return this.stripTags().replace(/</g,'<').replace(/>/g,'>').replace(/&/g,'&'); - } - - - function toQueryParams(separator) { - var match = this.strip().match(/([^?#]*)(#.*)?$/); - if (!match) return { }; - - return match[1].split(separator || '&').inject({ }, function(hash, pair) { - if ((pair = pair.split('='))[0]) { - var key = decodeURIComponent(pair.shift()), - value = pair.length > 1 ? pair.join('=') : pair[0]; - - if (value != undefined) { - value = value.gsub('+', ' '); - value = decodeURIComponent(value); - } - - if (key in hash) { - if (!Object.isArray(hash[key])) hash[key] = [hash[key]]; - hash[key].push(value); - } - else hash[key] = value; - } - return hash; - }); - } - - function toArray() { - return this.split(''); - } - - function succ() { - return this.slice(0, this.length - 1) + - String.fromCharCode(this.charCodeAt(this.length - 1) + 1); - } - - function times(count) { - return count < 1 ? '' : new Array(count + 1).join(this); - } - - function camelize() { - return this.replace(/-+(.)?/g, function(match, chr) { - return chr ? chr.toUpperCase() : ''; - }); - } - - function capitalize() { - return this.charAt(0).toUpperCase() + this.substring(1).toLowerCase(); - } - - function underscore() { - return this.replace(/::/g, '/') - .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2') - .replace(/([a-z\d])([A-Z])/g, '$1_$2') - .replace(/-/g, '_') - .toLowerCase(); - } - - function dasherize() { - return this.replace(/_/g, '-'); - } - - function inspect(useDoubleQuotes) { - var escapedString = this.replace(/[\x00-\x1f\\]/g, function(character) { - if (character in String.specialChar) { - return String.specialChar[character]; - } - return '\\u00' + character.charCodeAt().toPaddedString(2, 16); - }); - if (useDoubleQuotes) return '"' + escapedString.replace(/"/g, '\\"') + '"'; - return "'" + escapedString.replace(/'/g, '\\\'') + "'"; - } - - function unfilterJSON(filter) { - return this.replace(filter || Prototype.JSONFilter, '$1'); - } - - function isJSON() { - var str = this; - if (str.blank()) return false; - str = str.replace(/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g, '@'); - str = str.replace(/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g, ']'); - str = str.replace(/(?:^|:|,)(?:\s*\[)+/g, ''); - return (/^[\],:{}\s]*$/).test(str); - } - - function evalJSON(sanitize) { - var json = this.unfilterJSON(), - cx = /[\u00ad\u0600-\u0604\u070f\u17b4\u17b5\u200c-\u200f\u2028-\u202f\u2060-\u206f\ufeff\ufff0-\uffff\u0000]/g; - if (cx.test(json)) { - json = json.replace(cx, function (a) { - return '\\u' + ('0000' + a.charCodeAt(0).toString(16)).slice(-4); - }); - } - try { - if (!sanitize || json.isJSON()) return eval('(' + json + ')'); - } catch (e) { } - throw new SyntaxError('Badly formed JSON string: ' + this.inspect()); - } - - function parseJSON() { - var json = this.unfilterJSON(); - return JSON.parse(json); - } - - function include(pattern) { - return this.indexOf(pattern) > -1; - } - - function startsWith(pattern, position) { - position = Object.isNumber(position) ? position : 0; - return this.lastIndexOf(pattern, position) === position; - } - - function endsWith(pattern, position) { - pattern = String(pattern); - position = Object.isNumber(position) ? position : this.length; - if (position < 0) position = 0; - if (position > this.length) position = this.length; - var d = position - pattern.length; - return d >= 0 && this.indexOf(pattern, d) === d; - } - - function empty() { - return this == ''; - } - - function blank() { - return /^\s*$/.test(this); - } - - function interpolate(object, pattern) { - return new Template(this, pattern).evaluate(object); - } - - return { - gsub: gsub, - sub: sub, - scan: scan, - truncate: truncate, - strip: String.prototype.trim || strip, - stripTags: stripTags, - stripScripts: stripScripts, - extractScripts: extractScripts, - evalScripts: evalScripts, - escapeHTML: escapeHTML, - unescapeHTML: unescapeHTML, - toQueryParams: toQueryParams, - parseQuery: toQueryParams, - toArray: toArray, - succ: succ, - times: times, - camelize: camelize, - capitalize: capitalize, - underscore: underscore, - dasherize: dasherize, - inspect: inspect, - unfilterJSON: unfilterJSON, - isJSON: isJSON, - evalJSON: NATIVE_JSON_PARSE_SUPPORT ? parseJSON : evalJSON, - include: include, - startsWith: String.prototype.startsWith || startsWith, - endsWith: String.prototype.endsWith || endsWith, - empty: empty, - blank: blank, - interpolate: interpolate - }; -})()); - -var Template = Class.create({ - initialize: function(template, pattern) { - this.template = template.toString(); - this.pattern = pattern || Template.Pattern; - }, - - evaluate: function(object) { - if (object && Object.isFunction(object.toTemplateReplacements)) - object = object.toTemplateReplacements(); - - return this.template.gsub(this.pattern, function(match) { - if (object == null) return (match[1] + ''); - - var before = match[1] || ''; - if (before == '\\') return match[2]; - - var ctx = object, expr = match[3], - pattern = /^([^.[]+|\[((?:.*?[^\\])?)\])(\.|\[|$)/; - - match = pattern.exec(expr); - if (match == null) return before; - - while (match != null) { - var comp = match[1].startsWith('[') ? match[2].replace(/\\\\]/g, ']') : match[1]; - ctx = ctx[comp]; - if (null == ctx || '' == match[3]) break; - expr = expr.substring('[' == match[3] ? match[1].length : match[0].length); - match = pattern.exec(expr); - } - - return before + String.interpret(ctx); - }); - } -}); -Template.Pattern = /(^|.|\r|\n)(#\{(.*?)\})/; - -var $break = { }; - -var Enumerable = (function() { - function each(iterator, context) { - try { - this._each(iterator, context); - } catch (e) { - if (e != $break) throw e; - } - return this; - } - - function eachSlice(number, iterator, context) { - var index = -number, slices = [], array = this.toArray(); - if (number < 1) return array; - while ((index += number) < array.length) - slices.push(array.slice(index, index+number)); - return slices.collect(iterator, context); - } - - function all(iterator, context) { - iterator = iterator || Prototype.K; - var result = true; - this.each(function(value, index) { - result = result && !!iterator.call(context, value, index, this); - if (!result) throw $break; - }, this); - return result; - } - - function any(iterator, context) { - iterator = iterator || Prototype.K; - var result = false; - this.each(function(value, index) { - if (result = !!iterator.call(context, value, index, this)) - throw $break; - }, this); - return result; - } - - function collect(iterator, context) { - iterator = iterator || Prototype.K; - var results = []; - this.each(function(value, index) { - results.push(iterator.call(context, value, index, this)); - }, this); - return results; - } - - function detect(iterator, context) { - var result; - this.each(function(value, index) { - if (iterator.call(context, value, index, this)) { - result = value; - throw $break; - } - }, this); - return result; - } - - function findAll(iterator, context) { - var results = []; - this.each(function(value, index) { - if (iterator.call(context, value, index, this)) - results.push(value); - }, this); - return results; - } - - function grep(filter, iterator, context) { - iterator = iterator || Prototype.K; - var results = []; - - if (Object.isString(filter)) - filter = new RegExp(RegExp.escape(filter)); - - this.each(function(value, index) { - if (filter.match(value)) - results.push(iterator.call(context, value, index, this)); - }, this); - return results; - } - - function include(object) { - if (Object.isFunction(this.indexOf) && this.indexOf(object) != -1) - return true; - - var found = false; - this.each(function(value) { - if (value == object) { - found = true; - throw $break; - } - }); - return found; - } - - function inGroupsOf(number, fillWith) { - fillWith = Object.isUndefined(fillWith) ? null : fillWith; - return this.eachSlice(number, function(slice) { - while(slice.length < number) slice.push(fillWith); - return slice; - }); - } - - function inject(memo, iterator, context) { - this.each(function(value, index) { - memo = iterator.call(context, memo, value, index, this); - }, this); - return memo; - } - - function invoke(method) { - var args = $A(arguments).slice(1); - return this.map(function(value) { - return value[method].apply(value, args); - }); - } - - function max(iterator, context) { - iterator = iterator || Prototype.K; - var result; - this.each(function(value, index) { - value = iterator.call(context, value, index, this); - if (result == null || value >= result) - result = value; - }, this); - return result; - } - - function min(iterator, context) { - iterator = iterator || Prototype.K; - var result; - this.each(function(value, index) { - value = iterator.call(context, value, index, this); - if (result == null || value < result) - result = value; - }, this); - return result; - } - - function partition(iterator, context) { - iterator = iterator || Prototype.K; - var trues = [], falses = []; - this.each(function(value, index) { - (iterator.call(context, value, index, this) ? - trues : falses).push(value); - }, this); - return [trues, falses]; - } - - function pluck(property) { - var results = []; - this.each(function(value) { - results.push(value[property]); - }); - return results; - } - - function reject(iterator, context) { - var results = []; - this.each(function(value, index) { - if (!iterator.call(context, value, index, this)) - results.push(value); - }, this); - return results; - } - - function sortBy(iterator, context) { - return this.map(function(value, index) { - return { - value: value, - criteria: iterator.call(context, value, index, this) - }; - }, this).sort(function(left, right) { - var a = left.criteria, b = right.criteria; - return a < b ? -1 : a > b ? 1 : 0; - }).pluck('value'); - } - - function toArray() { - return this.map(); - } - - function zip() { - var iterator = Prototype.K, args = $A(arguments); - if (Object.isFunction(args.last())) - iterator = args.pop(); - - var collections = [this].concat(args).map($A); - return this.map(function(value, index) { - return iterator(collections.pluck(index)); - }); - } - - function size() { - return this.toArray().length; - } - - function inspect() { - return '#'; - } - - - - - - - - - - return { - each: each, - eachSlice: eachSlice, - all: all, - every: all, - any: any, - some: any, - collect: collect, - map: collect, - detect: detect, - findAll: findAll, - select: findAll, - filter: findAll, - grep: grep, - include: include, - member: include, - inGroupsOf: inGroupsOf, - inject: inject, - invoke: invoke, - max: max, - min: min, - partition: partition, - pluck: pluck, - reject: reject, - sortBy: sortBy, - toArray: toArray, - entries: toArray, - zip: zip, - size: size, - inspect: inspect, - find: detect - }; -})(); - -function $A(iterable) { - if (!iterable) return []; - if ('toArray' in Object(iterable)) return iterable.toArray(); - var length = iterable.length || 0, results = new Array(length); - while (length--) results[length] = iterable[length]; - return results; -} - - -function $w(string) { - if (!Object.isString(string)) return []; - string = string.strip(); - return string ? string.split(/\s+/) : []; -} - -Array.from = $A; - - -(function() { - var arrayProto = Array.prototype, - slice = arrayProto.slice, - _each = arrayProto.forEach; // use native browser JS 1.6 implementation if available - - function each(iterator, context) { - for (var i = 0, length = this.length >>> 0; i < length; i++) { - if (i in this) iterator.call(context, this[i], i, this); - } - } - if (!_each) _each = each; - - function clear() { - this.length = 0; - return this; - } - - function first() { - return this[0]; - } - - function last() { - return this[this.length - 1]; - } - - function compact() { - return this.select(function(value) { - return value != null; - }); - } - - function flatten() { - return this.inject([], function(array, value) { - if (Object.isArray(value)) - return array.concat(value.flatten()); - array.push(value); - return array; - }); - } - - function without() { - var values = slice.call(arguments, 0); - return this.select(function(value) { - return !values.include(value); - }); - } - - function reverse(inline) { - return (inline === false ? this.toArray() : this)._reverse(); - } - - function uniq(sorted) { - return this.inject([], function(array, value, index) { - if (0 == index || (sorted ? array.last() != value : !array.include(value))) - array.push(value); - return array; - }); - } - - function intersect(array) { - return this.uniq().findAll(function(item) { - return array.indexOf(item) !== -1; - }); - } - - - function clone() { - return slice.call(this, 0); - } - - function size() { - return this.length; - } - - function inspect() { - return '[' + this.map(Object.inspect).join(', ') + ']'; - } - - function indexOf(item, i) { - if (this == null) throw new TypeError(); - - var array = Object(this), length = array.length >>> 0; - if (length === 0) return -1; - - i = Number(i); - if (isNaN(i)) { - i = 0; - } else if (i !== 0 && isFinite(i)) { - i = (i > 0 ? 1 : -1) * Math.floor(Math.abs(i)); - } - - if (i > length) return -1; - - var k = i >= 0 ? i : Math.max(length - Math.abs(i), 0); - for (; k < length; k++) - if (k in array && array[k] === item) return k; - return -1; - } - - - function lastIndexOf(item, i) { - if (this == null) throw new TypeError(); - - var array = Object(this), length = array.length >>> 0; - if (length === 0) return -1; - - if (!Object.isUndefined(i)) { - i = Number(i); - if (isNaN(i)) { - i = 0; - } else if (i !== 0 && isFinite(i)) { - i = (i > 0 ? 1 : -1) * Math.floor(Math.abs(i)); - } - } else { - i = length; - } - - var k = i >= 0 ? Math.min(i, length - 1) : - length - Math.abs(i); - - for (; k >= 0; k--) - if (k in array && array[k] === item) return k; - return -1; - } - - function concat(_) { - var array = [], items = slice.call(arguments, 0), item, n = 0; - items.unshift(this); - for (var i = 0, length = items.length; i < length; i++) { - item = items[i]; - if (Object.isArray(item) && !('callee' in item)) { - for (var j = 0, arrayLength = item.length; j < arrayLength; j++) { - if (j in item) array[n] = item[j]; - n++; - } - } else { - array[n++] = item; - } - } - array.length = n; - return array; - } - - - function wrapNative(method) { - return function() { - if (arguments.length === 0) { - return method.call(this, Prototype.K); - } else if (arguments[0] === undefined) { - var args = slice.call(arguments, 1); - args.unshift(Prototype.K); - return method.apply(this, args); - } else { - return method.apply(this, arguments); - } - }; - } - - - function map(iterator) { - if (this == null) throw new TypeError(); - iterator = iterator || Prototype.K; - - var object = Object(this); - var results = [], context = arguments[1], n = 0; - - for (var i = 0, length = object.length >>> 0; i < length; i++) { - if (i in object) { - results[n] = iterator.call(context, object[i], i, object); - } - n++; - } - results.length = n; - return results; - } - - if (arrayProto.map) { - map = wrapNative(Array.prototype.map); - } - - function filter(iterator) { - if (this == null || !Object.isFunction(iterator)) - throw new TypeError(); - - var object = Object(this); - var results = [], context = arguments[1], value; - - for (var i = 0, length = object.length >>> 0; i < length; i++) { - if (i in object) { - value = object[i]; - if (iterator.call(context, value, i, object)) { - results.push(value); - } - } - } - return results; - } - - if (arrayProto.filter) { - filter = Array.prototype.filter; - } - - function some(iterator) { - if (this == null) throw new TypeError(); - iterator = iterator || Prototype.K; - var context = arguments[1]; - - var object = Object(this); - for (var i = 0, length = object.length >>> 0; i < length; i++) { - if (i in object && iterator.call(context, object[i], i, object)) { - return true; - } - } - - return false; - } - - if (arrayProto.some) { - some = wrapNative(Array.prototype.some); - } - - function every(iterator) { - if (this == null) throw new TypeError(); - iterator = iterator || Prototype.K; - var context = arguments[1]; - - var object = Object(this); - for (var i = 0, length = object.length >>> 0; i < length; i++) { - if (i in object && !iterator.call(context, object[i], i, object)) { - return false; - } - } - - return true; - } - - if (arrayProto.every) { - every = wrapNative(Array.prototype.every); - } - - - Object.extend(arrayProto, Enumerable); - - if (arrayProto.entries === Enumerable.entries) { - delete arrayProto.entries; - } - - if (!arrayProto._reverse) - arrayProto._reverse = arrayProto.reverse; - - Object.extend(arrayProto, { - _each: _each, - - map: map, - collect: map, - select: filter, - filter: filter, - findAll: filter, - some: some, - any: some, - every: every, - all: every, - - clear: clear, - first: first, - last: last, - compact: compact, - flatten: flatten, - without: without, - reverse: reverse, - uniq: uniq, - intersect: intersect, - clone: clone, - toArray: clone, - size: size, - inspect: inspect - }); - - var CONCAT_ARGUMENTS_BUGGY = (function() { - return [].concat(arguments)[0][0] !== 1; - })(1,2); - - if (CONCAT_ARGUMENTS_BUGGY) arrayProto.concat = concat; - - if (!arrayProto.indexOf) arrayProto.indexOf = indexOf; - if (!arrayProto.lastIndexOf) arrayProto.lastIndexOf = lastIndexOf; -})(); -function $H(object) { - return new Hash(object); -}; - -var Hash = Class.create(Enumerable, (function() { - function initialize(object) { - this._object = Object.isHash(object) ? object.toObject() : Object.clone(object); - } - - - function _each(iterator, context) { - var i = 0; - for (var key in this._object) { - var value = this._object[key], pair = [key, value]; - pair.key = key; - pair.value = value; - iterator.call(context, pair, i); - i++; - } - } - - function set(key, value) { - return this._object[key] = value; - } - - function get(key) { - if (this._object[key] !== Object.prototype[key]) - return this._object[key]; - } - - function unset(key) { - var value = this._object[key]; - delete this._object[key]; - return value; - } - - function toObject() { - return Object.clone(this._object); - } - - - - function keys() { - return this.pluck('key'); - } - - function values() { - return this.pluck('value'); - } - - function index(value) { - var match = this.detect(function(pair) { - return pair.value === value; - }); - return match && match.key; - } - - function merge(object) { - return this.clone().update(object); - } - - function update(object) { - return new Hash(object).inject(this, function(result, pair) { - result.set(pair.key, pair.value); - return result; - }); - } - - function toQueryPair(key, value) { - if (Object.isUndefined(value)) return key; - - value = String.interpret(value); - - value = value.gsub(/(\r)?\n/, '\r\n'); - value = encodeURIComponent(value); - value = value.gsub(/%20/, '+'); - return key + '=' + value; - } - - function toQueryString() { - return this.inject([], function(results, pair) { - var key = encodeURIComponent(pair.key), values = pair.value; - - if (values && typeof values == 'object') { - if (Object.isArray(values)) { - var queryValues = []; - for (var i = 0, len = values.length, value; i < len; i++) { - value = values[i]; - queryValues.push(toQueryPair(key, value)); - } - return results.concat(queryValues); - } - } else results.push(toQueryPair(key, values)); - return results; - }).join('&'); - } - - function inspect() { - return '#'; - } - - function clone() { - return new Hash(this); - } - - return { - initialize: initialize, - _each: _each, - set: set, - get: get, - unset: unset, - toObject: toObject, - toTemplateReplacements: toObject, - keys: keys, - values: values, - index: index, - merge: merge, - update: update, - toQueryString: toQueryString, - inspect: inspect, - toJSON: toObject, - clone: clone - }; -})()); - -Hash.from = $H; -Object.extend(Number.prototype, (function() { - function toColorPart() { - return this.toPaddedString(2, 16); - } - - function succ() { - return this + 1; - } - - function times(iterator, context) { - $R(0, this, true).each(iterator, context); - return this; - } - - function toPaddedString(length, radix) { - var string = this.toString(radix || 10); - return '0'.times(length - string.length) + string; - } - - function abs() { - return Math.abs(this); - } - - function round() { - return Math.round(this); - } - - function ceil() { - return Math.ceil(this); - } - - function floor() { - return Math.floor(this); - } - - return { - toColorPart: toColorPart, - succ: succ, - times: times, - toPaddedString: toPaddedString, - abs: abs, - round: round, - ceil: ceil, - floor: floor - }; -})()); - -function $R(start, end, exclusive) { - return new ObjectRange(start, end, exclusive); -} - -var ObjectRange = Class.create(Enumerable, (function() { - function initialize(start, end, exclusive) { - this.start = start; - this.end = end; - this.exclusive = exclusive; - } - - function _each(iterator, context) { - var value = this.start, i; - for (i = 0; this.include(value); i++) { - iterator.call(context, value, i); - value = value.succ(); - } - } - - function include(value) { - if (value < this.start) - return false; - if (this.exclusive) - return value < this.end; - return value <= this.end; - } - - return { - initialize: initialize, - _each: _each, - include: include - }; -})()); - - - -var Abstract = { }; - - -var Try = { - these: function() { - var returnValue; - - for (var i = 0, length = arguments.length; i < length; i++) { - var lambda = arguments[i]; - try { - returnValue = lambda(); - break; - } catch (e) { } - } - - return returnValue; - } -}; - -var Ajax = { - getTransport: function() { - return Try.these( - function() {return new XMLHttpRequest()}, - function() {return new ActiveXObject('Msxml2.XMLHTTP')}, - function() {return new ActiveXObject('Microsoft.XMLHTTP')} - ) || false; - }, - - activeRequestCount: 0 -}; - -Ajax.Responders = { - responders: [], - - _each: function(iterator, context) { - this.responders._each(iterator, context); - }, - - register: function(responder) { - if (!this.include(responder)) - this.responders.push(responder); - }, - - unregister: function(responder) { - this.responders = this.responders.without(responder); - }, - - dispatch: function(callback, request, transport, json) { - this.each(function(responder) { - if (Object.isFunction(responder[callback])) { - try { - responder[callback].apply(responder, [request, transport, json]); - } catch (e) { } - } - }); - } -}; - -Object.extend(Ajax.Responders, Enumerable); - -Ajax.Responders.register({ - onCreate: function() { Ajax.activeRequestCount++ }, - onComplete: function() { Ajax.activeRequestCount-- } -}); -Ajax.Base = Class.create({ - initialize: function(options) { - this.options = { - method: 'post', - asynchronous: true, - contentType: 'application/x-www-form-urlencoded', - encoding: 'UTF-8', - parameters: '', - evalJSON: true, - evalJS: true - }; - Object.extend(this.options, options || { }); - - this.options.method = this.options.method.toLowerCase(); - - if (Object.isHash(this.options.parameters)) - this.options.parameters = this.options.parameters.toObject(); - } -}); -Ajax.Request = Class.create(Ajax.Base, { - _complete: false, - - initialize: function($super, url, options) { - $super(options); - this.transport = Ajax.getTransport(); - this.request(url); - }, - - request: function(url) { - this.url = url; - this.method = this.options.method; - var params = Object.isString(this.options.parameters) ? - this.options.parameters : - Object.toQueryString(this.options.parameters); - - if (!['get', 'post'].include(this.method)) { - params += (params ? '&' : '') + "_method=" + this.method; - this.method = 'post'; - } - - if (params && this.method === 'get') { - this.url += (this.url.include('?') ? '&' : '?') + params; - } - - this.parameters = params.toQueryParams(); - - try { - var response = new Ajax.Response(this); - if (this.options.onCreate) this.options.onCreate(response); - Ajax.Responders.dispatch('onCreate', this, response); - - this.transport.open(this.method.toUpperCase(), this.url, - this.options.asynchronous); - - if (this.options.asynchronous) this.respondToReadyState.bind(this).defer(1); - - this.transport.onreadystatechange = this.onStateChange.bind(this); - this.setRequestHeaders(); - - this.body = this.method == 'post' ? (this.options.postBody || params) : null; - this.transport.send(this.body); - - /* Force Firefox to handle ready state 4 for synchronous requests */ - if (!this.options.asynchronous && this.transport.overrideMimeType) - this.onStateChange(); - - } - catch (e) { - this.dispatchException(e); - } - }, - - onStateChange: function() { - var readyState = this.transport.readyState; - if (readyState > 1 && !((readyState == 4) && this._complete)) - this.respondToReadyState(this.transport.readyState); - }, - - setRequestHeaders: function() { - var headers = { - 'X-Requested-With': 'XMLHttpRequest', - 'X-Prototype-Version': Prototype.Version, - 'Accept': 'text/javascript, text/html, application/xml, text/xml, */*' - }; - - if (this.method == 'post') { - headers['Content-type'] = this.options.contentType + - (this.options.encoding ? '; charset=' + this.options.encoding : ''); - - /* Force "Connection: close" for older Mozilla browsers to work - * around a bug where XMLHttpRequest sends an incorrect - * Content-length header. See Mozilla Bugzilla #246651. - */ - if (this.transport.overrideMimeType && - (navigator.userAgent.match(/Gecko\/(\d{4})/) || [0,2005])[1] < 2005) - headers['Connection'] = 'close'; - } - - if (typeof this.options.requestHeaders == 'object') { - var extras = this.options.requestHeaders; - - if (Object.isFunction(extras.push)) - for (var i = 0, length = extras.length; i < length; i += 2) - headers[extras[i]] = extras[i+1]; - else - $H(extras).each(function(pair) { headers[pair.key] = pair.value }); - } - - for (var name in headers) - if (headers[name] != null) - this.transport.setRequestHeader(name, headers[name]); - }, - - success: function() { - var status = this.getStatus(); - return !status || (status >= 200 && status < 300) || status == 304; - }, - - getStatus: function() { - try { - if (this.transport.status === 1223) return 204; - return this.transport.status || 0; - } catch (e) { return 0 } - }, - - respondToReadyState: function(readyState) { - var state = Ajax.Request.Events[readyState], response = new Ajax.Response(this); - - if (state == 'Complete') { - try { - this._complete = true; - (this.options['on' + response.status] - || this.options['on' + (this.success() ? 'Success' : 'Failure')] - || Prototype.emptyFunction)(response, response.headerJSON); - } catch (e) { - this.dispatchException(e); - } - - var contentType = response.getHeader('Content-type'); - if (this.options.evalJS == 'force' - || (this.options.evalJS && this.isSameOrigin() && contentType - && contentType.match(/^\s*(text|application)\/(x-)?(java|ecma)script(;.*)?\s*$/i))) - this.evalResponse(); - } - - try { - (this.options['on' + state] || Prototype.emptyFunction)(response, response.headerJSON); - Ajax.Responders.dispatch('on' + state, this, response, response.headerJSON); - } catch (e) { - this.dispatchException(e); - } - - if (state == 'Complete') { - this.transport.onreadystatechange = Prototype.emptyFunction; - } - }, - - isSameOrigin: function() { - var m = this.url.match(/^\s*https?:\/\/[^\/]*/); - return !m || (m[0] == '#{protocol}//#{domain}#{port}'.interpolate({ - protocol: location.protocol, - domain: document.domain, - port: location.port ? ':' + location.port : '' - })); - }, - - getHeader: function(name) { - try { - return this.transport.getResponseHeader(name) || null; - } catch (e) { return null; } - }, - - evalResponse: function() { - try { - return eval((this.transport.responseText || '').unfilterJSON()); - } catch (e) { - this.dispatchException(e); - } - }, - - dispatchException: function(exception) { - (this.options.onException || Prototype.emptyFunction)(this, exception); - Ajax.Responders.dispatch('onException', this, exception); - } -}); - -Ajax.Request.Events = - ['Uninitialized', 'Loading', 'Loaded', 'Interactive', 'Complete']; - - - - - - - - -Ajax.Response = Class.create({ - initialize: function(request){ - this.request = request; - var transport = this.transport = request.transport, - readyState = this.readyState = transport.readyState; - - if ((readyState > 2 && !Prototype.Browser.IE) || readyState == 4) { - this.status = this.getStatus(); - this.statusText = this.getStatusText(); - this.responseText = String.interpret(transport.responseText); - this.headerJSON = this._getHeaderJSON(); - } - - if (readyState == 4) { - var xml = transport.responseXML; - this.responseXML = Object.isUndefined(xml) ? null : xml; - this.responseJSON = this._getResponseJSON(); - } - }, - - status: 0, - - statusText: '', - - getStatus: Ajax.Request.prototype.getStatus, - - getStatusText: function() { - try { - return this.transport.statusText || ''; - } catch (e) { return '' } - }, - - getHeader: Ajax.Request.prototype.getHeader, - - getAllHeaders: function() { - try { - return this.getAllResponseHeaders(); - } catch (e) { return null } - }, - - getResponseHeader: function(name) { - return this.transport.getResponseHeader(name); - }, - - getAllResponseHeaders: function() { - return this.transport.getAllResponseHeaders(); - }, - - _getHeaderJSON: function() { - var json = this.getHeader('X-JSON'); - if (!json) return null; - - try { - json = decodeURIComponent(escape(json)); - } catch(e) { - } - - try { - return json.evalJSON(this.request.options.sanitizeJSON || - !this.request.isSameOrigin()); - } catch (e) { - this.request.dispatchException(e); - } - }, - - _getResponseJSON: function() { - var options = this.request.options; - if (!options.evalJSON || (options.evalJSON != 'force' && - !(this.getHeader('Content-type') || '').include('application/json')) || - this.responseText.blank()) - return null; - try { - return this.responseText.evalJSON(options.sanitizeJSON || - !this.request.isSameOrigin()); - } catch (e) { - this.request.dispatchException(e); - } - } -}); - -Ajax.Updater = Class.create(Ajax.Request, { - initialize: function($super, container, url, options) { - this.container = { - success: (container.success || container), - failure: (container.failure || (container.success ? null : container)) - }; - - options = Object.clone(options); - var onComplete = options.onComplete; - options.onComplete = (function(response, json) { - this.updateContent(response.responseText); - if (Object.isFunction(onComplete)) onComplete(response, json); - }).bind(this); - - $super(url, options); - }, - - updateContent: function(responseText) { - var receiver = this.container[this.success() ? 'success' : 'failure'], - options = this.options; - - if (!options.evalScripts) responseText = responseText.stripScripts(); - - if (receiver = $(receiver)) { - if (options.insertion) { - if (Object.isString(options.insertion)) { - var insertion = { }; insertion[options.insertion] = responseText; - receiver.insert(insertion); - } - else options.insertion(receiver, responseText); - } - else receiver.update(responseText); - } - } -}); - -Ajax.PeriodicalUpdater = Class.create(Ajax.Base, { - initialize: function($super, container, url, options) { - $super(options); - this.onComplete = this.options.onComplete; - - this.frequency = (this.options.frequency || 2); - this.decay = (this.options.decay || 1); - - this.updater = { }; - this.container = container; - this.url = url; - - this.start(); - }, - - start: function() { - this.options.onComplete = this.updateComplete.bind(this); - this.onTimerEvent(); - }, - - stop: function() { - this.updater.options.onComplete = undefined; - clearTimeout(this.timer); - (this.onComplete || Prototype.emptyFunction).apply(this, arguments); - }, - - updateComplete: function(response) { - if (this.options.decay) { - this.decay = (response.responseText == this.lastText ? - this.decay * this.options.decay : 1); - - this.lastText = response.responseText; - } - this.timer = this.onTimerEvent.bind(this).delay(this.decay * this.frequency); - }, - - onTimerEvent: function() { - this.updater = new Ajax.Updater(this.container, this.url, this.options); - } -}); - -(function(GLOBAL) { - - var UNDEFINED; - var SLICE = Array.prototype.slice; - - var DIV = document.createElement('div'); - - - function $(element) { - if (arguments.length > 1) { - for (var i = 0, elements = [], length = arguments.length; i < length; i++) - elements.push($(arguments[i])); - return elements; - } - - if (Object.isString(element)) - element = document.getElementById(element); - return Element.extend(element); - } - - GLOBAL.$ = $; - - - if (!GLOBAL.Node) GLOBAL.Node = {}; - - if (!GLOBAL.Node.ELEMENT_NODE) { - Object.extend(GLOBAL.Node, { - ELEMENT_NODE: 1, - ATTRIBUTE_NODE: 2, - TEXT_NODE: 3, - CDATA_SECTION_NODE: 4, - ENTITY_REFERENCE_NODE: 5, - ENTITY_NODE: 6, - PROCESSING_INSTRUCTION_NODE: 7, - COMMENT_NODE: 8, - DOCUMENT_NODE: 9, - DOCUMENT_TYPE_NODE: 10, - DOCUMENT_FRAGMENT_NODE: 11, - NOTATION_NODE: 12 - }); - } - - var ELEMENT_CACHE = {}; - - function shouldUseCreationCache(tagName, attributes) { - if (tagName === 'select') return false; - if ('type' in attributes) return false; - return true; - } - - var HAS_EXTENDED_CREATE_ELEMENT_SYNTAX = (function(){ - try { - var el = document.createElement(''); - return el.tagName.toLowerCase() === 'input' && el.name === 'x'; - } - catch(err) { - return false; - } - })(); - - - var oldElement = GLOBAL.Element; - function Element(tagName, attributes) { - attributes = attributes || {}; - tagName = tagName.toLowerCase(); - - if (HAS_EXTENDED_CREATE_ELEMENT_SYNTAX && attributes.name) { - tagName = '<' + tagName + ' name="' + attributes.name + '">'; - delete attributes.name; - return Element.writeAttribute(document.createElement(tagName), attributes); - } - - if (!ELEMENT_CACHE[tagName]) - ELEMENT_CACHE[tagName] = Element.extend(document.createElement(tagName)); - - var node = shouldUseCreationCache(tagName, attributes) ? - ELEMENT_CACHE[tagName].cloneNode(false) : document.createElement(tagName); - - return Element.writeAttribute(node, attributes); - } - - GLOBAL.Element = Element; - - Object.extend(GLOBAL.Element, oldElement || {}); - if (oldElement) GLOBAL.Element.prototype = oldElement.prototype; - - Element.Methods = { ByTag: {}, Simulated: {} }; - - var methods = {}; - - var INSPECT_ATTRIBUTES = { id: 'id', className: 'class' }; - function inspect(element) { - element = $(element); - var result = '<' + element.tagName.toLowerCase(); - - var attribute, value; - for (var property in INSPECT_ATTRIBUTES) { - attribute = INSPECT_ATTRIBUTES[property]; - value = (element[property] || '').toString(); - if (value) result += ' ' + attribute + '=' + value.inspect(true); - } - - return result + '>'; - } - - methods.inspect = inspect; - - - function visible(element) { - return $(element).getStyle('display') !== 'none'; - } - - function toggle(element, bool) { - element = $(element); - if (typeof bool !== 'boolean') - bool = !Element.visible(element); - Element[bool ? 'show' : 'hide'](element); - - return element; - } - - function hide(element) { - element = $(element); - element.style.display = 'none'; - return element; - } - - function show(element) { - element = $(element); - element.style.display = ''; - return element; - } - - - Object.extend(methods, { - visible: visible, - toggle: toggle, - hide: hide, - show: show - }); - - - function remove(element) { - element = $(element); - element.parentNode.removeChild(element); - return element; - } - - var SELECT_ELEMENT_INNERHTML_BUGGY = (function(){ - var el = document.createElement("select"), - isBuggy = true; - el.innerHTML = ""; - if (el.options && el.options[0]) { - isBuggy = el.options[0].nodeName.toUpperCase() !== "OPTION"; - } - el = null; - return isBuggy; - })(); - - var TABLE_ELEMENT_INNERHTML_BUGGY = (function(){ - try { - var el = document.createElement("table"); - if (el && el.tBodies) { - el.innerHTML = "test"; - var isBuggy = typeof el.tBodies[0] == "undefined"; - el = null; - return isBuggy; - } - } catch (e) { - return true; - } - })(); - - var LINK_ELEMENT_INNERHTML_BUGGY = (function() { - try { - var el = document.createElement('div'); - el.innerHTML = ""; - var isBuggy = (el.childNodes.length === 0); - el = null; - return isBuggy; - } catch(e) { - return true; - } - })(); - - var ANY_INNERHTML_BUGGY = SELECT_ELEMENT_INNERHTML_BUGGY || - TABLE_ELEMENT_INNERHTML_BUGGY || LINK_ELEMENT_INNERHTML_BUGGY; - - var SCRIPT_ELEMENT_REJECTS_TEXTNODE_APPENDING = (function () { - var s = document.createElement("script"), - isBuggy = false; - try { - s.appendChild(document.createTextNode("")); - isBuggy = !s.firstChild || - s.firstChild && s.firstChild.nodeType !== 3; - } catch (e) { - isBuggy = true; - } - s = null; - return isBuggy; - })(); - - function update(element, content) { - element = $(element); - - var descendants = element.getElementsByTagName('*'), - i = descendants.length; - while (i--) purgeElement(descendants[i]); - - if (content && content.toElement) - content = content.toElement(); - - if (Object.isElement(content)) - return element.update().insert(content); - - - content = Object.toHTML(content); - var tagName = element.tagName.toUpperCase(); - - if (tagName === 'SCRIPT' && SCRIPT_ELEMENT_REJECTS_TEXTNODE_APPENDING) { - element.text = content; - return element; - } - - if (ANY_INNERHTML_BUGGY) { - if (tagName in INSERTION_TRANSLATIONS.tags) { - while (element.firstChild) - element.removeChild(element.firstChild); - - var nodes = getContentFromAnonymousElement(tagName, content.stripScripts()); - for (var i = 0, node; node = nodes[i]; i++) - element.appendChild(node); - - } else if (LINK_ELEMENT_INNERHTML_BUGGY && Object.isString(content) && content.indexOf(' -1) { - while (element.firstChild) - element.removeChild(element.firstChild); - - var nodes = getContentFromAnonymousElement(tagName, - content.stripScripts(), true); - - for (var i = 0, node; node = nodes[i]; i++) - element.appendChild(node); - } else { - element.innerHTML = content.stripScripts(); - } - } else { - element.innerHTML = content.stripScripts(); - } - - content.evalScripts.bind(content).defer(); - return element; - } - - function replace(element, content) { - element = $(element); - - if (content && content.toElement) { - content = content.toElement(); - } else if (!Object.isElement(content)) { - content = Object.toHTML(content); - var range = element.ownerDocument.createRange(); - range.selectNode(element); - content.evalScripts.bind(content).defer(); - content = range.createContextualFragment(content.stripScripts()); - } - - element.parentNode.replaceChild(content, element); - return element; - } - - var INSERTION_TRANSLATIONS = { - before: function(element, node) { - element.parentNode.insertBefore(node, element); - }, - top: function(element, node) { - element.insertBefore(node, element.firstChild); - }, - bottom: function(element, node) { - element.appendChild(node); - }, - after: function(element, node) { - element.parentNode.insertBefore(node, element.nextSibling); - }, - - tags: { - TABLE: ['', '
', 1], - TBODY: ['', '
', 2], - TR: ['', '
', 3], - TD: ['
', '
', 4], - SELECT: ['', 1] - } - }; - - var tags = INSERTION_TRANSLATIONS.tags; - - Object.extend(tags, { - THEAD: tags.TBODY, - TFOOT: tags.TBODY, - TH: tags.TD - }); - - function replace_IE(element, content) { - element = $(element); - if (content && content.toElement) - content = content.toElement(); - if (Object.isElement(content)) { - element.parentNode.replaceChild(content, element); - return element; - } - - content = Object.toHTML(content); - var parent = element.parentNode, tagName = parent.tagName.toUpperCase(); - - if (tagName in INSERTION_TRANSLATIONS.tags) { - var nextSibling = Element.next(element); - var fragments = getContentFromAnonymousElement( - tagName, content.stripScripts()); - - parent.removeChild(element); - - var iterator; - if (nextSibling) - iterator = function(node) { parent.insertBefore(node, nextSibling) }; - else - iterator = function(node) { parent.appendChild(node); } - - fragments.each(iterator); - } else { - element.outerHTML = content.stripScripts(); - } - - content.evalScripts.bind(content).defer(); - return element; - } - - if ('outerHTML' in document.documentElement) - replace = replace_IE; - - function isContent(content) { - if (Object.isUndefined(content) || content === null) return false; - - if (Object.isString(content) || Object.isNumber(content)) return true; - if (Object.isElement(content)) return true; - if (content.toElement || content.toHTML) return true; - - return false; - } - - function insertContentAt(element, content, position) { - position = position.toLowerCase(); - var method = INSERTION_TRANSLATIONS[position]; - - if (content && content.toElement) content = content.toElement(); - if (Object.isElement(content)) { - method(element, content); - return element; - } - - content = Object.toHTML(content); - var tagName = ((position === 'before' || position === 'after') ? - element.parentNode : element).tagName.toUpperCase(); - - var childNodes = getContentFromAnonymousElement(tagName, content.stripScripts()); - - if (position === 'top' || position === 'after') childNodes.reverse(); - - for (var i = 0, node; node = childNodes[i]; i++) - method(element, node); - - content.evalScripts.bind(content).defer(); - } - - function insert(element, insertions) { - element = $(element); - - if (isContent(insertions)) - insertions = { bottom: insertions }; - - for (var position in insertions) - insertContentAt(element, insertions[position], position); - - return element; - } - - function wrap(element, wrapper, attributes) { - element = $(element); - - if (Object.isElement(wrapper)) { - $(wrapper).writeAttribute(attributes || {}); - } else if (Object.isString(wrapper)) { - wrapper = new Element(wrapper, attributes); - } else { - wrapper = new Element('div', wrapper); - } - - if (element.parentNode) - element.parentNode.replaceChild(wrapper, element); - - wrapper.appendChild(element); - - return wrapper; - } - - function cleanWhitespace(element) { - element = $(element); - var node = element.firstChild; - - while (node) { - var nextNode = node.nextSibling; - if (node.nodeType === Node.TEXT_NODE && !/\S/.test(node.nodeValue)) - element.removeChild(node); - node = nextNode; - } - return element; - } - - function empty(element) { - return $(element).innerHTML.blank(); - } - - function getContentFromAnonymousElement(tagName, html, force) { - var t = INSERTION_TRANSLATIONS.tags[tagName], div = DIV; - - var workaround = !!t; - if (!workaround && force) { - workaround = true; - t = ['', '', 0]; - } - - if (workaround) { - div.innerHTML = ' ' + t[0] + html + t[1]; - div.removeChild(div.firstChild); - for (var i = t[2]; i--; ) - div = div.firstChild; - } else { - div.innerHTML = html; - } - - return $A(div.childNodes); - } - - function clone(element, deep) { - if (!(element = $(element))) return; - var clone = element.cloneNode(deep); - if (!HAS_UNIQUE_ID_PROPERTY) { - clone._prototypeUID = UNDEFINED; - if (deep) { - var descendants = Element.select(clone, '*'), - i = descendants.length; - while (i--) - descendants[i]._prototypeUID = UNDEFINED; - } - } - return Element.extend(clone); - } - - function purgeElement(element) { - var uid = getUniqueElementID(element); - if (uid) { - Element.stopObserving(element); - if (!HAS_UNIQUE_ID_PROPERTY) - element._prototypeUID = UNDEFINED; - delete Element.Storage[uid]; - } - } - - function purgeCollection(elements) { - var i = elements.length; - while (i--) - purgeElement(elements[i]); - } - - function purgeCollection_IE(elements) { - var i = elements.length, element, uid; - while (i--) { - element = elements[i]; - uid = getUniqueElementID(element); - delete Element.Storage[uid]; - delete Event.cache[uid]; - } - } - - if (HAS_UNIQUE_ID_PROPERTY) { - purgeCollection = purgeCollection_IE; - } - - - function purge(element) { - if (!(element = $(element))) return; - purgeElement(element); - - var descendants = element.getElementsByTagName('*'), - i = descendants.length; - - while (i--) purgeElement(descendants[i]); - - return null; - } - - Object.extend(methods, { - remove: remove, - update: update, - replace: replace, - insert: insert, - wrap: wrap, - cleanWhitespace: cleanWhitespace, - empty: empty, - clone: clone, - purge: purge - }); - - - - function recursivelyCollect(element, property, maximumLength) { - element = $(element); - maximumLength = maximumLength || -1; - var elements = []; - - while (element = element[property]) { - if (element.nodeType === Node.ELEMENT_NODE) - elements.push(Element.extend(element)); - - if (elements.length === maximumLength) break; - } - - return elements; - } - - - function ancestors(element) { - return recursivelyCollect(element, 'parentNode'); - } - - function descendants(element) { - return Element.select(element, '*'); - } - - function firstDescendant(element) { - element = $(element).firstChild; - while (element && element.nodeType !== Node.ELEMENT_NODE) - element = element.nextSibling; - - return $(element); - } - - function immediateDescendants(element) { - var results = [], child = $(element).firstChild; - - while (child) { - if (child.nodeType === Node.ELEMENT_NODE) - results.push(Element.extend(child)); - - child = child.nextSibling; - } - - return results; - } - - function previousSiblings(element) { - return recursivelyCollect(element, 'previousSibling'); - } - - function nextSiblings(element) { - return recursivelyCollect(element, 'nextSibling'); - } - - function siblings(element) { - element = $(element); - var previous = previousSiblings(element), - next = nextSiblings(element); - return previous.reverse().concat(next); - } - - function match(element, selector) { - element = $(element); - - if (Object.isString(selector)) - return Prototype.Selector.match(element, selector); - - return selector.match(element); - } - - - function _recursivelyFind(element, property, expression, index) { - element = $(element), expression = expression || 0, index = index || 0; - if (Object.isNumber(expression)) { - index = expression, expression = null; - } - - while (element = element[property]) { - if (element.nodeType !== 1) continue; - if (expression && !Prototype.Selector.match(element, expression)) - continue; - if (--index >= 0) continue; - - return Element.extend(element); - } - } - - - function up(element, expression, index) { - element = $(element); - - if (arguments.length === 1) return $(element.parentNode); - return _recursivelyFind(element, 'parentNode', expression, index); - } - - function down(element, expression, index) { - if (arguments.length === 1) return firstDescendant(element); - element = $(element), expression = expression || 0, index = index || 0; - - if (Object.isNumber(expression)) - index = expression, expression = '*'; - - var node = Prototype.Selector.select(expression, element)[index]; - return Element.extend(node); - } - - function previous(element, expression, index) { - return _recursivelyFind(element, 'previousSibling', expression, index); - } - - function next(element, expression, index) { - return _recursivelyFind(element, 'nextSibling', expression, index); - } - - function select(element) { - element = $(element); - var expressions = SLICE.call(arguments, 1).join(', '); - return Prototype.Selector.select(expressions, element); - } - - function adjacent(element) { - element = $(element); - var expressions = SLICE.call(arguments, 1).join(', '); - var siblings = Element.siblings(element), results = []; - for (var i = 0, sibling; sibling = siblings[i]; i++) { - if (Prototype.Selector.match(sibling, expressions)) - results.push(sibling); - } - - return results; - } - - function descendantOf_DOM(element, ancestor) { - element = $(element), ancestor = $(ancestor); - if (!element || !ancestor) return false; - while (element = element.parentNode) - if (element === ancestor) return true; - return false; - } - - function descendantOf_contains(element, ancestor) { - element = $(element), ancestor = $(ancestor); - if (!element || !ancestor) return false; - if (!ancestor.contains) return descendantOf_DOM(element, ancestor); - return ancestor.contains(element) && ancestor !== element; - } - - function descendantOf_compareDocumentPosition(element, ancestor) { - element = $(element), ancestor = $(ancestor); - if (!element || !ancestor) return false; - return (element.compareDocumentPosition(ancestor) & 8) === 8; - } - - var descendantOf; - if (DIV.compareDocumentPosition) { - descendantOf = descendantOf_compareDocumentPosition; - } else if (DIV.contains) { - descendantOf = descendantOf_contains; - } else { - descendantOf = descendantOf_DOM; - } - - - Object.extend(methods, { - recursivelyCollect: recursivelyCollect, - ancestors: ancestors, - descendants: descendants, - firstDescendant: firstDescendant, - immediateDescendants: immediateDescendants, - previousSiblings: previousSiblings, - nextSiblings: nextSiblings, - siblings: siblings, - match: match, - up: up, - down: down, - previous: previous, - next: next, - select: select, - adjacent: adjacent, - descendantOf: descendantOf, - - getElementsBySelector: select, - - childElements: immediateDescendants - }); - - - var idCounter = 1; - function identify(element) { - element = $(element); - var id = Element.readAttribute(element, 'id'); - if (id) return id; - - do { id = 'anonymous_element_' + idCounter++ } while ($(id)); - - Element.writeAttribute(element, 'id', id); - return id; - } - - - function readAttribute(element, name) { - return $(element).getAttribute(name); - } - - function readAttribute_IE(element, name) { - element = $(element); - - var table = ATTRIBUTE_TRANSLATIONS.read; - if (table.values[name]) - return table.values[name](element, name); - - if (table.names[name]) name = table.names[name]; - - if (name.include(':')) { - if (!element.attributes || !element.attributes[name]) return null; - return element.attributes[name].value; - } - - return element.getAttribute(name); - } - - function readAttribute_Opera(element, name) { - if (name === 'title') return element.title; - return element.getAttribute(name); - } - - var PROBLEMATIC_ATTRIBUTE_READING = (function() { - DIV.setAttribute('onclick', []); - var value = DIV.getAttribute('onclick'); - var isFunction = Object.isArray(value); - DIV.removeAttribute('onclick'); - return isFunction; - })(); - - if (PROBLEMATIC_ATTRIBUTE_READING) { - readAttribute = readAttribute_IE; - } else if (Prototype.Browser.Opera) { - readAttribute = readAttribute_Opera; - } - - - function writeAttribute(element, name, value) { - element = $(element); - var attributes = {}, table = ATTRIBUTE_TRANSLATIONS.write; - - if (typeof name === 'object') { - attributes = name; - } else { - attributes[name] = Object.isUndefined(value) ? true : value; - } - - for (var attr in attributes) { - name = table.names[attr] || attr; - value = attributes[attr]; - if (table.values[attr]) { - value = table.values[attr](element, value); - if (Object.isUndefined(value)) continue; - } - if (value === false || value === null) - element.removeAttribute(name); - else if (value === true) - element.setAttribute(name, name); - else element.setAttribute(name, value); - } - - return element; - } - - var PROBLEMATIC_HAS_ATTRIBUTE_WITH_CHECKBOXES = (function () { - if (!HAS_EXTENDED_CREATE_ELEMENT_SYNTAX) { - return false; - } - var checkbox = document.createElement(''); - checkbox.checked = true; - var node = checkbox.getAttributeNode('checked'); - return !node || !node.specified; - })(); - - function hasAttribute(element, attribute) { - attribute = ATTRIBUTE_TRANSLATIONS.has[attribute] || attribute; - var node = $(element).getAttributeNode(attribute); - return !!(node && node.specified); - } - - function hasAttribute_IE(element, attribute) { - if (attribute === 'checked') { - return element.checked; - } - return hasAttribute(element, attribute); - } - - GLOBAL.Element.Methods.Simulated.hasAttribute = - PROBLEMATIC_HAS_ATTRIBUTE_WITH_CHECKBOXES ? - hasAttribute_IE : hasAttribute; - - function classNames(element) { - return new Element.ClassNames(element); - } - - var regExpCache = {}; - function getRegExpForClassName(className) { - if (regExpCache[className]) return regExpCache[className]; - - var re = new RegExp("(^|\\s+)" + className + "(\\s+|$)"); - regExpCache[className] = re; - return re; - } - - function hasClassName(element, className) { - if (!(element = $(element))) return; - - var elementClassName = element.className; - - if (elementClassName.length === 0) return false; - if (elementClassName === className) return true; - - return getRegExpForClassName(className).test(elementClassName); - } - - function addClassName(element, className) { - if (!(element = $(element))) return; - - if (!hasClassName(element, className)) - element.className += (element.className ? ' ' : '') + className; - - return element; - } - - function removeClassName(element, className) { - if (!(element = $(element))) return; - - element.className = element.className.replace( - getRegExpForClassName(className), ' ').strip(); - - return element; - } - - function toggleClassName(element, className, bool) { - if (!(element = $(element))) return; - - if (Object.isUndefined(bool)) - bool = !hasClassName(element, className); - - var method = Element[bool ? 'addClassName' : 'removeClassName']; - return method(element, className); - } - - var ATTRIBUTE_TRANSLATIONS = {}; - - var classProp = 'className', forProp = 'for'; - - DIV.setAttribute(classProp, 'x'); - if (DIV.className !== 'x') { - DIV.setAttribute('class', 'x'); - if (DIV.className === 'x') - classProp = 'class'; - } - - var LABEL = document.createElement('label'); - LABEL.setAttribute(forProp, 'x'); - if (LABEL.htmlFor !== 'x') { - LABEL.setAttribute('htmlFor', 'x'); - if (LABEL.htmlFor === 'x') - forProp = 'htmlFor'; - } - LABEL = null; - - function _getAttr(element, attribute) { - return element.getAttribute(attribute); - } - - function _getAttr2(element, attribute) { - return element.getAttribute(attribute, 2); - } - - function _getAttrNode(element, attribute) { - var node = element.getAttributeNode(attribute); - return node ? node.value : ''; - } - - function _getFlag(element, attribute) { - return $(element).hasAttribute(attribute) ? attribute : null; - } - - DIV.onclick = Prototype.emptyFunction; - var onclickValue = DIV.getAttribute('onclick'); - - var _getEv; - - if (String(onclickValue).indexOf('{') > -1) { - _getEv = function(element, attribute) { - var value = element.getAttribute(attribute); - if (!value) return null; - value = value.toString(); - value = value.split('{')[1]; - value = value.split('}')[0]; - return value.strip(); - }; - } - else if (onclickValue === '') { - _getEv = function(element, attribute) { - var value = element.getAttribute(attribute); - if (!value) return null; - return value.strip(); - }; - } - - ATTRIBUTE_TRANSLATIONS.read = { - names: { - 'class': classProp, - 'className': classProp, - 'for': forProp, - 'htmlFor': forProp - }, - - values: { - style: function(element) { - return element.style.cssText.toLowerCase(); - }, - title: function(element) { - return element.title; - } - } - }; - - ATTRIBUTE_TRANSLATIONS.write = { - names: { - className: 'class', - htmlFor: 'for', - cellpadding: 'cellPadding', - cellspacing: 'cellSpacing' - }, - - values: { - checked: function(element, value) { - value = !!value; - element.checked = value; - return value ? 'checked' : null; - }, - - style: function(element, value) { - element.style.cssText = value ? value : ''; - } - } - }; - - ATTRIBUTE_TRANSLATIONS.has = { names: {} }; - - Object.extend(ATTRIBUTE_TRANSLATIONS.write.names, - ATTRIBUTE_TRANSLATIONS.read.names); - - var CAMEL_CASED_ATTRIBUTE_NAMES = $w('colSpan rowSpan vAlign dateTime ' + - 'accessKey tabIndex encType maxLength readOnly longDesc frameBorder'); - - for (var i = 0, attr; attr = CAMEL_CASED_ATTRIBUTE_NAMES[i]; i++) { - ATTRIBUTE_TRANSLATIONS.write.names[attr.toLowerCase()] = attr; - ATTRIBUTE_TRANSLATIONS.has.names[attr.toLowerCase()] = attr; - } - - Object.extend(ATTRIBUTE_TRANSLATIONS.read.values, { - href: _getAttr2, - src: _getAttr2, - type: _getAttr, - action: _getAttrNode, - disabled: _getFlag, - checked: _getFlag, - readonly: _getFlag, - multiple: _getFlag, - onload: _getEv, - onunload: _getEv, - onclick: _getEv, - ondblclick: _getEv, - onmousedown: _getEv, - onmouseup: _getEv, - onmouseover: _getEv, - onmousemove: _getEv, - onmouseout: _getEv, - onfocus: _getEv, - onblur: _getEv, - onkeypress: _getEv, - onkeydown: _getEv, - onkeyup: _getEv, - onsubmit: _getEv, - onreset: _getEv, - onselect: _getEv, - onchange: _getEv - }); - - - Object.extend(methods, { - identify: identify, - readAttribute: readAttribute, - writeAttribute: writeAttribute, - classNames: classNames, - hasClassName: hasClassName, - addClassName: addClassName, - removeClassName: removeClassName, - toggleClassName: toggleClassName - }); - - - function normalizeStyleName(style) { - if (style === 'float' || style === 'styleFloat') - return 'cssFloat'; - return style.camelize(); - } - - function normalizeStyleName_IE(style) { - if (style === 'float' || style === 'cssFloat') - return 'styleFloat'; - return style.camelize(); - } - - function setStyle(element, styles) { - element = $(element); - var elementStyle = element.style, match; - - if (Object.isString(styles)) { - elementStyle.cssText += ';' + styles; - if (styles.include('opacity')) { - var opacity = styles.match(/opacity:\s*(\d?\.?\d*)/)[1]; - Element.setOpacity(element, opacity); - } - return element; - } - - for (var property in styles) { - if (property === 'opacity') { - Element.setOpacity(element, styles[property]); - } else { - var value = styles[property]; - if (property === 'float' || property === 'cssFloat') { - property = Object.isUndefined(elementStyle.styleFloat) ? - 'cssFloat' : 'styleFloat'; - } - elementStyle[property] = value; - } - } - - return element; - } - - - function getStyle(element, style) { - element = $(element); - style = normalizeStyleName(style); - - var value = element.style[style]; - if (!value || value === 'auto') { - var css = document.defaultView.getComputedStyle(element, null); - value = css ? css[style] : null; - } - - if (style === 'opacity') return value ? parseFloat(value) : 1.0; - return value === 'auto' ? null : value; - } - - function getStyle_Opera(element, style) { - switch (style) { - case 'height': case 'width': - if (!Element.visible(element)) return null; - - var dim = parseInt(getStyle(element, style), 10); - - if (dim !== element['offset' + style.capitalize()]) - return dim + 'px'; - - return Element.measure(element, style); - - default: return getStyle(element, style); - } - } - - function getStyle_IE(element, style) { - element = $(element); - style = normalizeStyleName_IE(style); - - var value = element.style[style]; - if (!value && element.currentStyle) { - value = element.currentStyle[style]; - } - - if (style === 'opacity') { - if (!STANDARD_CSS_OPACITY_SUPPORTED) - return getOpacity_IE(element); - else return value ? parseFloat(value) : 1.0; - } - - if (value === 'auto') { - if ((style === 'width' || style === 'height') && Element.visible(element)) - return Element.measure(element, style) + 'px'; - return null; - } - - return value; - } - - function stripAlphaFromFilter_IE(filter) { - return (filter || '').replace(/alpha\([^\)]*\)/gi, ''); - } - - function hasLayout_IE(element) { - if (!element.currentStyle || !element.currentStyle.hasLayout) - element.style.zoom = 1; - return element; - } - - var STANDARD_CSS_OPACITY_SUPPORTED = (function() { - DIV.style.cssText = "opacity:.55"; - return /^0.55/.test(DIV.style.opacity); - })(); - - function setOpacity(element, value) { - element = $(element); - if (value == 1 || value === '') value = ''; - else if (value < 0.00001) value = 0; - element.style.opacity = value; - return element; - } - - function setOpacity_IE(element, value) { - if (STANDARD_CSS_OPACITY_SUPPORTED) - return setOpacity(element, value); - - element = hasLayout_IE($(element)); - var filter = Element.getStyle(element, 'filter'), - style = element.style; - - if (value == 1 || value === '') { - filter = stripAlphaFromFilter_IE(filter); - if (filter) style.filter = filter; - else style.removeAttribute('filter'); - return element; - } - - if (value < 0.00001) value = 0; - - style.filter = stripAlphaFromFilter_IE(filter) + - ' alpha(opacity=' + (value * 100) + ')'; - - return element; - } - - - function getOpacity(element) { - return Element.getStyle(element, 'opacity'); - } - - function getOpacity_IE(element) { - if (STANDARD_CSS_OPACITY_SUPPORTED) - return getOpacity(element); - - var filter = Element.getStyle(element, 'filter'); - if (filter.length === 0) return 1.0; - var match = (filter || '').match(/alpha\(opacity=(.*)\)/i); - if (match && match[1]) return parseFloat(match[1]) / 100; - return 1.0; - } - - - Object.extend(methods, { - setStyle: setStyle, - getStyle: getStyle, - setOpacity: setOpacity, - getOpacity: getOpacity - }); - - if ('styleFloat' in DIV.style) { - methods.getStyle = getStyle_IE; - methods.setOpacity = setOpacity_IE; - methods.getOpacity = getOpacity_IE; - } - - var UID = 0; - - GLOBAL.Element.Storage = { UID: 1 }; - - function getUniqueElementID(element) { - if (element === window) return 0; - - if (typeof element._prototypeUID === 'undefined') - element._prototypeUID = Element.Storage.UID++; - return element._prototypeUID; - } - - function getUniqueElementID_IE(element) { - if (element === window) return 0; - if (element == document) return 1; - return element.uniqueID; - } - - var HAS_UNIQUE_ID_PROPERTY = ('uniqueID' in DIV); - if (HAS_UNIQUE_ID_PROPERTY) - getUniqueElementID = getUniqueElementID_IE; - - function getStorage(element) { - if (!(element = $(element))) return; - - var uid = getUniqueElementID(element); - - if (!Element.Storage[uid]) - Element.Storage[uid] = $H(); - - return Element.Storage[uid]; - } - - function store(element, key, value) { - if (!(element = $(element))) return; - var storage = getStorage(element); - if (arguments.length === 2) { - storage.update(key); - } else { - storage.set(key, value); - } - return element; - } - - function retrieve(element, key, defaultValue) { - if (!(element = $(element))) return; - var storage = getStorage(element), value = storage.get(key); - - if (Object.isUndefined(value)) { - storage.set(key, defaultValue); - value = defaultValue; - } - - return value; - } - - - Object.extend(methods, { - getStorage: getStorage, - store: store, - retrieve: retrieve - }); - - - var Methods = {}, ByTag = Element.Methods.ByTag, - F = Prototype.BrowserFeatures; - - if (!F.ElementExtensions && ('__proto__' in DIV)) { - GLOBAL.HTMLElement = {}; - GLOBAL.HTMLElement.prototype = DIV['__proto__']; - F.ElementExtensions = true; - } - - function checkElementPrototypeDeficiency(tagName) { - if (typeof window.Element === 'undefined') return false; - if (!HAS_EXTENDED_CREATE_ELEMENT_SYNTAX) return false; - var proto = window.Element.prototype; - if (proto) { - var id = '_' + (Math.random() + '').slice(2), - el = document.createElement(tagName); - proto[id] = 'x'; - var isBuggy = (el[id] !== 'x'); - delete proto[id]; - el = null; - return isBuggy; - } - - return false; - } - - var HTMLOBJECTELEMENT_PROTOTYPE_BUGGY = - checkElementPrototypeDeficiency('object'); - - function extendElementWith(element, methods) { - for (var property in methods) { - var value = methods[property]; - if (Object.isFunction(value) && !(property in element)) - element[property] = value.methodize(); - } - } - - var EXTENDED = {}; - function elementIsExtended(element) { - var uid = getUniqueElementID(element); - return (uid in EXTENDED); - } - - function extend(element) { - if (!element || elementIsExtended(element)) return element; - if (element.nodeType !== Node.ELEMENT_NODE || element == window) - return element; - - var methods = Object.clone(Methods), - tagName = element.tagName.toUpperCase(); - - if (ByTag[tagName]) Object.extend(methods, ByTag[tagName]); - - extendElementWith(element, methods); - EXTENDED[getUniqueElementID(element)] = true; - return element; - } - - function extend_IE8(element) { - if (!element || elementIsExtended(element)) return element; - - var t = element.tagName; - if (t && (/^(?:object|applet|embed)$/i.test(t))) { - extendElementWith(element, Element.Methods); - extendElementWith(element, Element.Methods.Simulated); - extendElementWith(element, Element.Methods.ByTag[t.toUpperCase()]); - } - - return element; - } - - if (F.SpecificElementExtensions) { - extend = HTMLOBJECTELEMENT_PROTOTYPE_BUGGY ? extend_IE8 : Prototype.K; - } - - function addMethodsToTagName(tagName, methods) { - tagName = tagName.toUpperCase(); - if (!ByTag[tagName]) ByTag[tagName] = {}; - Object.extend(ByTag[tagName], methods); - } - - function mergeMethods(destination, methods, onlyIfAbsent) { - if (Object.isUndefined(onlyIfAbsent)) onlyIfAbsent = false; - for (var property in methods) { - var value = methods[property]; - if (!Object.isFunction(value)) continue; - if (!onlyIfAbsent || !(property in destination)) - destination[property] = value.methodize(); - } - } - - function findDOMClass(tagName) { - var klass; - var trans = { - "OPTGROUP": "OptGroup", "TEXTAREA": "TextArea", "P": "Paragraph", - "FIELDSET": "FieldSet", "UL": "UList", "OL": "OList", "DL": "DList", - "DIR": "Directory", "H1": "Heading", "H2": "Heading", "H3": "Heading", - "H4": "Heading", "H5": "Heading", "H6": "Heading", "Q": "Quote", - "INS": "Mod", "DEL": "Mod", "A": "Anchor", "IMG": "Image", "CAPTION": - "TableCaption", "COL": "TableCol", "COLGROUP": "TableCol", "THEAD": - "TableSection", "TFOOT": "TableSection", "TBODY": "TableSection", "TR": - "TableRow", "TH": "TableCell", "TD": "TableCell", "FRAMESET": - "FrameSet", "IFRAME": "IFrame" - }; - if (trans[tagName]) klass = 'HTML' + trans[tagName] + 'Element'; - if (window[klass]) return window[klass]; - klass = 'HTML' + tagName + 'Element'; - if (window[klass]) return window[klass]; - klass = 'HTML' + tagName.capitalize() + 'Element'; - if (window[klass]) return window[klass]; - - var element = document.createElement(tagName), - proto = element['__proto__'] || element.constructor.prototype; - - element = null; - return proto; - } - - function addMethods(methods) { - if (arguments.length === 0) addFormMethods(); - - if (arguments.length === 2) { - var tagName = methods; - methods = arguments[1]; - } - - if (!tagName) { - Object.extend(Element.Methods, methods || {}); - } else { - if (Object.isArray(tagName)) { - for (var i = 0, tag; tag = tagName[i]; i++) - addMethodsToTagName(tag, methods); - } else { - addMethodsToTagName(tagName, methods); - } - } - - var ELEMENT_PROTOTYPE = window.HTMLElement ? HTMLElement.prototype : - Element.prototype; - - if (F.ElementExtensions) { - mergeMethods(ELEMENT_PROTOTYPE, Element.Methods); - mergeMethods(ELEMENT_PROTOTYPE, Element.Methods.Simulated, true); - } - - if (F.SpecificElementExtensions) { - for (var tag in Element.Methods.ByTag) { - var klass = findDOMClass(tag); - if (Object.isUndefined(klass)) continue; - mergeMethods(klass.prototype, ByTag[tag]); - } - } - - Object.extend(Element, Element.Methods); - Object.extend(Element, Element.Methods.Simulated); - delete Element.ByTag; - delete Element.Simulated; - - Element.extend.refresh(); - - ELEMENT_CACHE = {}; - } - - Object.extend(GLOBAL.Element, { - extend: extend, - addMethods: addMethods - }); - - if (extend === Prototype.K) { - GLOBAL.Element.extend.refresh = Prototype.emptyFunction; - } else { - GLOBAL.Element.extend.refresh = function() { - if (Prototype.BrowserFeatures.ElementExtensions) return; - Object.extend(Methods, Element.Methods); - Object.extend(Methods, Element.Methods.Simulated); - - EXTENDED = {}; - }; - } - - function addFormMethods() { - Object.extend(Form, Form.Methods); - Object.extend(Form.Element, Form.Element.Methods); - Object.extend(Element.Methods.ByTag, { - "FORM": Object.clone(Form.Methods), - "INPUT": Object.clone(Form.Element.Methods), - "SELECT": Object.clone(Form.Element.Methods), - "TEXTAREA": Object.clone(Form.Element.Methods), - "BUTTON": Object.clone(Form.Element.Methods) - }); - } - - Element.addMethods(methods); - - function destroyCache_IE() { - DIV = null; - ELEMENT_CACHE = null; - } - - if (window.attachEvent) - window.attachEvent('onunload', destroyCache_IE); - -})(this); -(function() { - - function toDecimal(pctString) { - var match = pctString.match(/^(\d+)%?$/i); - if (!match) return null; - return (Number(match[1]) / 100); - } - - function getRawStyle(element, style) { - element = $(element); - - var value = element.style[style]; - if (!value || value === 'auto') { - var css = document.defaultView.getComputedStyle(element, null); - value = css ? css[style] : null; - } - - if (style === 'opacity') return value ? parseFloat(value) : 1.0; - return value === 'auto' ? null : value; - } - - function getRawStyle_IE(element, style) { - var value = element.style[style]; - if (!value && element.currentStyle) { - value = element.currentStyle[style]; - } - return value; - } - - function getContentWidth(element, context) { - var boxWidth = element.offsetWidth; - - var bl = getPixelValue(element, 'borderLeftWidth', context) || 0; - var br = getPixelValue(element, 'borderRightWidth', context) || 0; - var pl = getPixelValue(element, 'paddingLeft', context) || 0; - var pr = getPixelValue(element, 'paddingRight', context) || 0; - - return boxWidth - bl - br - pl - pr; - } - - if (!Object.isUndefined(document.documentElement.currentStyle) && !Prototype.Browser.Opera) { - getRawStyle = getRawStyle_IE; - } - - - function getPixelValue(value, property, context) { - var element = null; - if (Object.isElement(value)) { - element = value; - value = getRawStyle(element, property); - } - - if (value === null || Object.isUndefined(value)) { - return null; - } - - if ((/^(?:-)?\d+(\.\d+)?(px)?$/i).test(value)) { - return window.parseFloat(value); - } - - var isPercentage = value.include('%'), isViewport = (context === document.viewport); - - if (/\d/.test(value) && element && element.runtimeStyle && !(isPercentage && isViewport)) { - var style = element.style.left, rStyle = element.runtimeStyle.left; - element.runtimeStyle.left = element.currentStyle.left; - element.style.left = value || 0; - value = element.style.pixelLeft; - element.style.left = style; - element.runtimeStyle.left = rStyle; - - return value; - } - - if (element && isPercentage) { - context = context || element.parentNode; - var decimal = toDecimal(value), whole = null; - - var isHorizontal = property.include('left') || property.include('right') || - property.include('width'); - - var isVertical = property.include('top') || property.include('bottom') || - property.include('height'); - - if (context === document.viewport) { - if (isHorizontal) { - whole = document.viewport.getWidth(); - } else if (isVertical) { - whole = document.viewport.getHeight(); - } - } else { - if (isHorizontal) { - whole = $(context).measure('width'); - } else if (isVertical) { - whole = $(context).measure('height'); - } - } - - return (whole === null) ? 0 : whole * decimal; - } - - return 0; - } - - function toCSSPixels(number) { - if (Object.isString(number) && number.endsWith('px')) - return number; - return number + 'px'; - } - - function isDisplayed(element) { - while (element && element.parentNode) { - var display = element.getStyle('display'); - if (display === 'none') { - return false; - } - element = $(element.parentNode); - } - return true; - } - - var hasLayout = Prototype.K; - if ('currentStyle' in document.documentElement) { - hasLayout = function(element) { - if (!element.currentStyle.hasLayout) { - element.style.zoom = 1; - } - return element; - }; - } - - function cssNameFor(key) { - if (key.include('border')) key = key + '-width'; - return key.camelize(); - } - - Element.Layout = Class.create(Hash, { - initialize: function($super, element, preCompute) { - $super(); - this.element = $(element); - - Element.Layout.PROPERTIES.each( function(property) { - this._set(property, null); - }, this); - - if (preCompute) { - this._preComputing = true; - this._begin(); - Element.Layout.PROPERTIES.each( this._compute, this ); - this._end(); - this._preComputing = false; - } - }, - - _set: function(property, value) { - return Hash.prototype.set.call(this, property, value); - }, - - set: function(property, value) { - throw "Properties of Element.Layout are read-only."; - }, - - get: function($super, property) { - var value = $super(property); - return value === null ? this._compute(property) : value; - }, - - _begin: function() { - if (this._isPrepared()) return; - - var element = this.element; - if (isDisplayed(element)) { - this._setPrepared(true); - return; - } - - - var originalStyles = { - position: element.style.position || '', - width: element.style.width || '', - visibility: element.style.visibility || '', - display: element.style.display || '' - }; - - element.store('prototype_original_styles', originalStyles); - - var position = getRawStyle(element, 'position'), width = element.offsetWidth; - - if (width === 0 || width === null) { - element.style.display = 'block'; - width = element.offsetWidth; - } - - var context = (position === 'fixed') ? document.viewport : - element.parentNode; - - var tempStyles = { - visibility: 'hidden', - display: 'block' - }; - - if (position !== 'fixed') tempStyles.position = 'absolute'; - - element.setStyle(tempStyles); - - var positionedWidth = element.offsetWidth, newWidth; - if (width && (positionedWidth === width)) { - newWidth = getContentWidth(element, context); - } else if (position === 'absolute' || position === 'fixed') { - newWidth = getContentWidth(element, context); - } else { - var parent = element.parentNode, pLayout = $(parent).getLayout(); - - newWidth = pLayout.get('width') - - this.get('margin-left') - - this.get('border-left') - - this.get('padding-left') - - this.get('padding-right') - - this.get('border-right') - - this.get('margin-right'); - } - - element.setStyle({ width: newWidth + 'px' }); - - this._setPrepared(true); - }, - - _end: function() { - var element = this.element; - var originalStyles = element.retrieve('prototype_original_styles'); - element.store('prototype_original_styles', null); - element.setStyle(originalStyles); - this._setPrepared(false); - }, - - _compute: function(property) { - var COMPUTATIONS = Element.Layout.COMPUTATIONS; - if (!(property in COMPUTATIONS)) { - throw "Property not found."; - } - - return this._set(property, COMPUTATIONS[property].call(this, this.element)); - }, - - _isPrepared: function() { - return this.element.retrieve('prototype_element_layout_prepared', false); - }, - - _setPrepared: function(bool) { - return this.element.store('prototype_element_layout_prepared', bool); - }, - - toObject: function() { - var args = $A(arguments); - var keys = (args.length === 0) ? Element.Layout.PROPERTIES : - args.join(' ').split(' '); - var obj = {}; - keys.each( function(key) { - if (!Element.Layout.PROPERTIES.include(key)) return; - var value = this.get(key); - if (value != null) obj[key] = value; - }, this); - return obj; - }, - - toHash: function() { - var obj = this.toObject.apply(this, arguments); - return new Hash(obj); - }, - - toCSS: function() { - var args = $A(arguments); - var keys = (args.length === 0) ? Element.Layout.PROPERTIES : - args.join(' ').split(' '); - var css = {}; - - keys.each( function(key) { - if (!Element.Layout.PROPERTIES.include(key)) return; - if (Element.Layout.COMPOSITE_PROPERTIES.include(key)) return; - - var value = this.get(key); - if (value != null) css[cssNameFor(key)] = value + 'px'; - }, this); - return css; - }, - - inspect: function() { - return "#"; - } - }); - - Object.extend(Element.Layout, { - PROPERTIES: $w('height width top left right bottom border-left border-right border-top border-bottom padding-left padding-right padding-top padding-bottom margin-top margin-bottom margin-left margin-right padding-box-width padding-box-height border-box-width border-box-height margin-box-width margin-box-height'), - - COMPOSITE_PROPERTIES: $w('padding-box-width padding-box-height margin-box-width margin-box-height border-box-width border-box-height'), - - COMPUTATIONS: { - 'height': function(element) { - if (!this._preComputing) this._begin(); - - var bHeight = this.get('border-box-height'); - if (bHeight <= 0) { - if (!this._preComputing) this._end(); - return 0; - } - - var bTop = this.get('border-top'), - bBottom = this.get('border-bottom'); - - var pTop = this.get('padding-top'), - pBottom = this.get('padding-bottom'); - - if (!this._preComputing) this._end(); - - return bHeight - bTop - bBottom - pTop - pBottom; - }, - - 'width': function(element) { - if (!this._preComputing) this._begin(); - - var bWidth = this.get('border-box-width'); - if (bWidth <= 0) { - if (!this._preComputing) this._end(); - return 0; - } - - var bLeft = this.get('border-left'), - bRight = this.get('border-right'); - - var pLeft = this.get('padding-left'), - pRight = this.get('padding-right'); - - if (!this._preComputing) this._end(); - return bWidth - bLeft - bRight - pLeft - pRight; - }, - - 'padding-box-height': function(element) { - var height = this.get('height'), - pTop = this.get('padding-top'), - pBottom = this.get('padding-bottom'); - - return height + pTop + pBottom; - }, - - 'padding-box-width': function(element) { - var width = this.get('width'), - pLeft = this.get('padding-left'), - pRight = this.get('padding-right'); - - return width + pLeft + pRight; - }, - - 'border-box-height': function(element) { - if (!this._preComputing) this._begin(); - var height = element.offsetHeight; - if (!this._preComputing) this._end(); - return height; - }, - - 'border-box-width': function(element) { - if (!this._preComputing) this._begin(); - var width = element.offsetWidth; - if (!this._preComputing) this._end(); - return width; - }, - - 'margin-box-height': function(element) { - var bHeight = this.get('border-box-height'), - mTop = this.get('margin-top'), - mBottom = this.get('margin-bottom'); - - if (bHeight <= 0) return 0; - - return bHeight + mTop + mBottom; - }, - - 'margin-box-width': function(element) { - var bWidth = this.get('border-box-width'), - mLeft = this.get('margin-left'), - mRight = this.get('margin-right'); - - if (bWidth <= 0) return 0; - - return bWidth + mLeft + mRight; - }, - - 'top': function(element) { - var offset = element.positionedOffset(); - return offset.top; - }, - - 'bottom': function(element) { - var offset = element.positionedOffset(), - parent = element.getOffsetParent(), - pHeight = parent.measure('height'); - - var mHeight = this.get('border-box-height'); - - return pHeight - mHeight - offset.top; - }, - - 'left': function(element) { - var offset = element.positionedOffset(); - return offset.left; - }, - - 'right': function(element) { - var offset = element.positionedOffset(), - parent = element.getOffsetParent(), - pWidth = parent.measure('width'); - - var mWidth = this.get('border-box-width'); - - return pWidth - mWidth - offset.left; - }, - - 'padding-top': function(element) { - return getPixelValue(element, 'paddingTop'); - }, - - 'padding-bottom': function(element) { - return getPixelValue(element, 'paddingBottom'); - }, - - 'padding-left': function(element) { - return getPixelValue(element, 'paddingLeft'); - }, - - 'padding-right': function(element) { - return getPixelValue(element, 'paddingRight'); - }, - - 'border-top': function(element) { - return getPixelValue(element, 'borderTopWidth'); - }, - - 'border-bottom': function(element) { - return getPixelValue(element, 'borderBottomWidth'); - }, - - 'border-left': function(element) { - return getPixelValue(element, 'borderLeftWidth'); - }, - - 'border-right': function(element) { - return getPixelValue(element, 'borderRightWidth'); - }, - - 'margin-top': function(element) { - return getPixelValue(element, 'marginTop'); - }, - - 'margin-bottom': function(element) { - return getPixelValue(element, 'marginBottom'); - }, - - 'margin-left': function(element) { - return getPixelValue(element, 'marginLeft'); - }, - - 'margin-right': function(element) { - return getPixelValue(element, 'marginRight'); - } - } - }); - - if ('getBoundingClientRect' in document.documentElement) { - Object.extend(Element.Layout.COMPUTATIONS, { - 'right': function(element) { - var parent = hasLayout(element.getOffsetParent()); - var rect = element.getBoundingClientRect(), - pRect = parent.getBoundingClientRect(); - - return (pRect.right - rect.right).round(); - }, - - 'bottom': function(element) { - var parent = hasLayout(element.getOffsetParent()); - var rect = element.getBoundingClientRect(), - pRect = parent.getBoundingClientRect(); - - return (pRect.bottom - rect.bottom).round(); - } - }); - } - - Element.Offset = Class.create({ - initialize: function(left, top) { - this.left = left.round(); - this.top = top.round(); - - this[0] = this.left; - this[1] = this.top; - }, - - relativeTo: function(offset) { - return new Element.Offset( - this.left - offset.left, - this.top - offset.top - ); - }, - - inspect: function() { - return "#".interpolate(this); - }, - - toString: function() { - return "[#{left}, #{top}]".interpolate(this); - }, - - toArray: function() { - return [this.left, this.top]; - } - }); - - function getLayout(element, preCompute) { - return new Element.Layout(element, preCompute); - } - - function measure(element, property) { - return $(element).getLayout().get(property); - } - - function getHeight(element) { - return Element.getDimensions(element).height; - } - - function getWidth(element) { - return Element.getDimensions(element).width; - } - - function getDimensions(element) { - element = $(element); - var display = Element.getStyle(element, 'display'); - - if (display && display !== 'none') { - return { width: element.offsetWidth, height: element.offsetHeight }; - } - - var style = element.style; - var originalStyles = { - visibility: style.visibility, - position: style.position, - display: style.display - }; - - var newStyles = { - visibility: 'hidden', - display: 'block' - }; - - if (originalStyles.position !== 'fixed') - newStyles.position = 'absolute'; - - Element.setStyle(element, newStyles); - - var dimensions = { - width: element.offsetWidth, - height: element.offsetHeight - }; - - Element.setStyle(element, originalStyles); - - return dimensions; - } - - function getOffsetParent(element) { - element = $(element); - - function selfOrBody(element) { - return isHtml(element) ? $(document.body) : $(element); - } - - if (isDocument(element) || isDetached(element) || isBody(element) || isHtml(element)) - return $(document.body); - - var isInline = (Element.getStyle(element, 'display') === 'inline'); - if (!isInline && element.offsetParent) return selfOrBody(element.offsetParent); - - while ((element = element.parentNode) && element !== document.body) { - if (Element.getStyle(element, 'position') !== 'static') { - return selfOrBody(element); - } - } - - return $(document.body); - } - - - function cumulativeOffset(element) { - element = $(element); - var valueT = 0, valueL = 0; - if (element.parentNode) { - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - element = element.offsetParent; - } while (element); - } - return new Element.Offset(valueL, valueT); - } - - function positionedOffset(element) { - element = $(element); - - var layout = element.getLayout(); - - var valueT = 0, valueL = 0; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - element = element.offsetParent; - if (element) { - if (isBody(element)) break; - var p = Element.getStyle(element, 'position'); - if (p !== 'static') break; - } - } while (element); - - valueL -= layout.get('margin-left'); - valueT -= layout.get('margin-top'); - - return new Element.Offset(valueL, valueT); - } - - function cumulativeScrollOffset(element) { - var valueT = 0, valueL = 0; - do { - if (element === document.body) { - var bodyScrollNode = document.documentElement || document.body.parentNode || document.body; - valueT += !Object.isUndefined(window.pageYOffset) ? window.pageYOffset : bodyScrollNode.scrollTop || 0; - valueL += !Object.isUndefined(window.pageXOffset) ? window.pageXOffset : bodyScrollNode.scrollLeft || 0; - break; - } else { - valueT += element.scrollTop || 0; - valueL += element.scrollLeft || 0; - element = element.parentNode; - } - } while (element); - return new Element.Offset(valueL, valueT); - } - - function viewportOffset(forElement) { - var valueT = 0, valueL = 0, docBody = document.body; - - forElement = $(forElement); - var element = forElement; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - if (element.offsetParent == docBody && - Element.getStyle(element, 'position') == 'absolute') break; - } while (element = element.offsetParent); - - element = forElement; - do { - if (element != docBody) { - valueT -= element.scrollTop || 0; - valueL -= element.scrollLeft || 0; - } - } while (element = element.parentNode); - return new Element.Offset(valueL, valueT); - } - - function absolutize(element) { - element = $(element); - - if (Element.getStyle(element, 'position') === 'absolute') { - return element; - } - - var offsetParent = getOffsetParent(element); - var eOffset = element.viewportOffset(), - pOffset = offsetParent.viewportOffset(); - - var offset = eOffset.relativeTo(pOffset); - var layout = element.getLayout(); - - element.store('prototype_absolutize_original_styles', { - position: element.getStyle('position'), - left: element.getStyle('left'), - top: element.getStyle('top'), - width: element.getStyle('width'), - height: element.getStyle('height') - }); - - element.setStyle({ - position: 'absolute', - top: offset.top + 'px', - left: offset.left + 'px', - width: layout.get('width') + 'px', - height: layout.get('height') + 'px' - }); - - return element; - } - - function relativize(element) { - element = $(element); - if (Element.getStyle(element, 'position') === 'relative') { - return element; - } - - var originalStyles = - element.retrieve('prototype_absolutize_original_styles'); - - if (originalStyles) element.setStyle(originalStyles); - return element; - } - - - function scrollTo(element) { - element = $(element); - var pos = Element.cumulativeOffset(element); - window.scrollTo(pos.left, pos.top); - return element; - } - - - function makePositioned(element) { - element = $(element); - var position = Element.getStyle(element, 'position'), styles = {}; - if (position === 'static' || !position) { - styles.position = 'relative'; - if (Prototype.Browser.Opera) { - styles.top = 0; - styles.left = 0; - } - Element.setStyle(element, styles); - Element.store(element, 'prototype_made_positioned', true); - } - return element; - } - - function undoPositioned(element) { - element = $(element); - var storage = Element.getStorage(element), - madePositioned = storage.get('prototype_made_positioned'); - - if (madePositioned) { - storage.unset('prototype_made_positioned'); - Element.setStyle(element, { - position: '', - top: '', - bottom: '', - left: '', - right: '' - }); - } - return element; - } - - function makeClipping(element) { - element = $(element); - - var storage = Element.getStorage(element), - madeClipping = storage.get('prototype_made_clipping'); - - if (Object.isUndefined(madeClipping)) { - var overflow = Element.getStyle(element, 'overflow'); - storage.set('prototype_made_clipping', overflow); - if (overflow !== 'hidden') - element.style.overflow = 'hidden'; - } - - return element; - } - - function undoClipping(element) { - element = $(element); - var storage = Element.getStorage(element), - overflow = storage.get('prototype_made_clipping'); - - if (!Object.isUndefined(overflow)) { - storage.unset('prototype_made_clipping'); - element.style.overflow = overflow || ''; - } - - return element; - } - - function clonePosition(element, source, options) { - options = Object.extend({ - setLeft: true, - setTop: true, - setWidth: true, - setHeight: true, - offsetTop: 0, - offsetLeft: 0 - }, options || {}); - - var docEl = document.documentElement; - - source = $(source); - element = $(element); - var p, delta, layout, styles = {}; - - if (options.setLeft || options.setTop) { - p = Element.viewportOffset(source); - delta = [0, 0]; - if (Element.getStyle(element, 'position') === 'absolute') { - var parent = Element.getOffsetParent(element); - if (parent !== document.body) delta = Element.viewportOffset(parent); - } - } - - function pageScrollXY() { - var x = 0, y = 0; - if (Object.isNumber(window.pageXOffset)) { - x = window.pageXOffset; - y = window.pageYOffset; - } else if (document.body && (document.body.scrollLeft || document.body.scrollTop)) { - x = document.body.scrollLeft; - y = document.body.scrollTop; - } else if (docEl && (docEl.scrollLeft || docEl.scrollTop)) { - x = docEl.scrollLeft; - y = docEl.scrollTop; - } - return { x: x, y: y }; - } - - var pageXY = pageScrollXY(); - - - if (options.setWidth || options.setHeight) { - layout = Element.getLayout(source); - } - - if (options.setLeft) - styles.left = (p[0] + pageXY.x - delta[0] + options.offsetLeft) + 'px'; - if (options.setTop) - styles.top = (p[1] + pageXY.y - delta[1] + options.offsetTop) + 'px'; - - var currentLayout = element.getLayout(); - - if (options.setWidth) { - styles.width = layout.get('width') + 'px'; - } - if (options.setHeight) { - styles.height = layout.get('height') + 'px'; - } - - return Element.setStyle(element, styles); - } - - - if (Prototype.Browser.IE) { - getOffsetParent = getOffsetParent.wrap( - function(proceed, element) { - element = $(element); - - if (isDocument(element) || isDetached(element) || isBody(element) || isHtml(element)) - return $(document.body); - - var position = element.getStyle('position'); - if (position !== 'static') return proceed(element); - - element.setStyle({ position: 'relative' }); - var value = proceed(element); - element.setStyle({ position: position }); - return value; - } - ); - - positionedOffset = positionedOffset.wrap(function(proceed, element) { - element = $(element); - if (!element.parentNode) return new Element.Offset(0, 0); - var position = element.getStyle('position'); - if (position !== 'static') return proceed(element); - - var offsetParent = element.getOffsetParent(); - if (offsetParent && offsetParent.getStyle('position') === 'fixed') - hasLayout(offsetParent); - - element.setStyle({ position: 'relative' }); - var value = proceed(element); - element.setStyle({ position: position }); - return value; - }); - } else if (Prototype.Browser.Webkit) { - cumulativeOffset = function(element) { - element = $(element); - var valueT = 0, valueL = 0; - do { - valueT += element.offsetTop || 0; - valueL += element.offsetLeft || 0; - if (element.offsetParent == document.body) { - if (Element.getStyle(element, 'position') == 'absolute') break; - } - - element = element.offsetParent; - } while (element); - - return new Element.Offset(valueL, valueT); - }; - } - - - Element.addMethods({ - getLayout: getLayout, - measure: measure, - getWidth: getWidth, - getHeight: getHeight, - getDimensions: getDimensions, - getOffsetParent: getOffsetParent, - cumulativeOffset: cumulativeOffset, - positionedOffset: positionedOffset, - cumulativeScrollOffset: cumulativeScrollOffset, - viewportOffset: viewportOffset, - absolutize: absolutize, - relativize: relativize, - scrollTo: scrollTo, - makePositioned: makePositioned, - undoPositioned: undoPositioned, - makeClipping: makeClipping, - undoClipping: undoClipping, - clonePosition: clonePosition - }); - - function isBody(element) { - return element.nodeName.toUpperCase() === 'BODY'; - } - - function isHtml(element) { - return element.nodeName.toUpperCase() === 'HTML'; - } - - function isDocument(element) { - return element.nodeType === Node.DOCUMENT_NODE; - } - - function isDetached(element) { - return element !== document.body && - !Element.descendantOf(element, document.body); - } - - if ('getBoundingClientRect' in document.documentElement) { - Element.addMethods({ - viewportOffset: function(element) { - element = $(element); - if (isDetached(element)) return new Element.Offset(0, 0); - - var rect = element.getBoundingClientRect(), - docEl = document.documentElement; - return new Element.Offset(rect.left - docEl.clientLeft, - rect.top - docEl.clientTop); - } - }); - } - - -})(); - -(function() { - - var IS_OLD_OPERA = Prototype.Browser.Opera && - (window.parseFloat(window.opera.version()) < 9.5); - var ROOT = null; - function getRootElement() { - if (ROOT) return ROOT; - ROOT = IS_OLD_OPERA ? document.body : document.documentElement; - return ROOT; - } - - function getDimensions() { - return { width: this.getWidth(), height: this.getHeight() }; - } - - function getWidth() { - return getRootElement().clientWidth; - } - - function getHeight() { - return getRootElement().clientHeight; - } - - function getScrollOffsets() { - var x = window.pageXOffset || document.documentElement.scrollLeft || - document.body.scrollLeft; - var y = window.pageYOffset || document.documentElement.scrollTop || - document.body.scrollTop; - - return new Element.Offset(x, y); - } - - document.viewport = { - getDimensions: getDimensions, - getWidth: getWidth, - getHeight: getHeight, - getScrollOffsets: getScrollOffsets - }; - -})(); -window.$$ = function() { - var expression = $A(arguments).join(', '); - return Prototype.Selector.select(expression, document); -}; - -Prototype.Selector = (function() { - - function select() { - throw new Error('Method "Prototype.Selector.select" must be defined.'); - } - - function match() { - throw new Error('Method "Prototype.Selector.match" must be defined.'); - } - - function find(elements, expression, index) { - index = index || 0; - var match = Prototype.Selector.match, length = elements.length, matchIndex = 0, i; - - for (i = 0; i < length; i++) { - if (match(elements[i], expression) && index == matchIndex++) { - return Element.extend(elements[i]); - } - } - } - - function extendElements(elements) { - for (var i = 0, length = elements.length; i < length; i++) { - Element.extend(elements[i]); - } - return elements; - } - - - var K = Prototype.K; - - return { - select: select, - match: match, - find: find, - extendElements: (Element.extend === K) ? K : extendElements, - extendElement: Element.extend - }; -})(); -Prototype._original_property = window.Sizzle; - -;(function () { - function fakeDefine(fn) { - Prototype._actual_sizzle = fn(); - } - fakeDefine.amd = true; - - if (typeof define !== 'undefined' && define.amd) { - Prototype._original_define = define; - Prototype._actual_sizzle = null; - window.define = fakeDefine; - } -})(); - -/*! - * Sizzle CSS Selector Engine v1.10.18 - * http://sizzlejs.com/ - * - * Copyright 2013 jQuery Foundation, Inc. and other contributors - * Released under the MIT license - * http://jquery.org/license - * - * Date: 2014-02-05 - */ -(function( window ) { - -var i, - support, - Expr, - getText, - isXML, - compile, - select, - outermostContext, - sortInput, - hasDuplicate, - - setDocument, - document, - docElem, - documentIsHTML, - rbuggyQSA, - rbuggyMatches, - matches, - contains, - - expando = "sizzle" + -(new Date()), - preferredDoc = window.document, - dirruns = 0, - done = 0, - classCache = createCache(), - tokenCache = createCache(), - compilerCache = createCache(), - sortOrder = function( a, b ) { - if ( a === b ) { - hasDuplicate = true; - } - return 0; - }, - - strundefined = typeof undefined, - MAX_NEGATIVE = 1 << 31, - - hasOwn = ({}).hasOwnProperty, - arr = [], - pop = arr.pop, - push_native = arr.push, - push = arr.push, - slice = arr.slice, - indexOf = arr.indexOf || function( elem ) { - var i = 0, - len = this.length; - for ( ; i < len; i++ ) { - if ( this[i] === elem ) { - return i; - } - } - return -1; - }, - - booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped", - - - whitespace = "[\\x20\\t\\r\\n\\f]", - characterEncoding = "(?:\\\\.|[\\w-]|[^\\x00-\\xa0])+", - - identifier = characterEncoding.replace( "w", "w#" ), - - attributes = "\\[" + whitespace + "*(" + characterEncoding + ")" + whitespace + - "*(?:([*^$|!~]?=)" + whitespace + "*(?:(['\"])((?:\\\\.|[^\\\\])*?)\\3|(" + identifier + ")|)|)" + whitespace + "*\\]", - - pseudos = ":(" + characterEncoding + ")(?:\\(((['\"])((?:\\\\.|[^\\\\])*?)\\3|((?:\\\\.|[^\\\\()[\\]]|" + attributes.replace( 3, 8 ) + ")*)|.*)\\)|)", - - rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + whitespace + "+$", "g" ), - - rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), - rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + "*" ), - - rattributeQuotes = new RegExp( "=" + whitespace + "*([^\\]'\"]*?)" + whitespace + "*\\]", "g" ), - - rpseudo = new RegExp( pseudos ), - ridentifier = new RegExp( "^" + identifier + "$" ), - - matchExpr = { - "ID": new RegExp( "^#(" + characterEncoding + ")" ), - "CLASS": new RegExp( "^\\.(" + characterEncoding + ")" ), - "TAG": new RegExp( "^(" + characterEncoding.replace( "w", "w*" ) + ")" ), - "ATTR": new RegExp( "^" + attributes ), - "PSEUDO": new RegExp( "^" + pseudos ), - "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + whitespace + - "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + whitespace + - "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), - "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), - "needsContext": new RegExp( "^" + whitespace + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + - whitespace + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) - }, - - rinputs = /^(?:input|select|textarea|button)$/i, - rheader = /^h\d$/i, - - rnative = /^[^{]+\{\s*\[native \w/, - - rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, - - rsibling = /[+~]/, - rescape = /'|\\/g, - - runescape = new RegExp( "\\\\([\\da-f]{1,6}" + whitespace + "?|(" + whitespace + ")|.)", "ig" ), - funescape = function( _, escaped, escapedWhitespace ) { - var high = "0x" + escaped - 0x10000; - return high !== high || escapedWhitespace ? - escaped : - high < 0 ? - String.fromCharCode( high + 0x10000 ) : - String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); - }; - -try { - push.apply( - (arr = slice.call( preferredDoc.childNodes )), - preferredDoc.childNodes - ); - arr[ preferredDoc.childNodes.length ].nodeType; -} catch ( e ) { - push = { apply: arr.length ? - - function( target, els ) { - push_native.apply( target, slice.call(els) ); - } : - - function( target, els ) { - var j = target.length, - i = 0; - while ( (target[j++] = els[i++]) ) {} - target.length = j - 1; - } - }; -} - -function Sizzle( selector, context, results, seed ) { - var match, elem, m, nodeType, - i, groups, old, nid, newContext, newSelector; - - if ( ( context ? context.ownerDocument || context : preferredDoc ) !== document ) { - setDocument( context ); - } - - context = context || document; - results = results || []; - - if ( !selector || typeof selector !== "string" ) { - return results; - } - - if ( (nodeType = context.nodeType) !== 1 && nodeType !== 9 ) { - return []; - } - - if ( documentIsHTML && !seed ) { - - if ( (match = rquickExpr.exec( selector )) ) { - if ( (m = match[1]) ) { - if ( nodeType === 9 ) { - elem = context.getElementById( m ); - if ( elem && elem.parentNode ) { - if ( elem.id === m ) { - results.push( elem ); - return results; - } - } else { - return results; - } - } else { - if ( context.ownerDocument && (elem = context.ownerDocument.getElementById( m )) && - contains( context, elem ) && elem.id === m ) { - results.push( elem ); - return results; - } - } - - } else if ( match[2] ) { - push.apply( results, context.getElementsByTagName( selector ) ); - return results; - - } else if ( (m = match[3]) && support.getElementsByClassName && context.getElementsByClassName ) { - push.apply( results, context.getElementsByClassName( m ) ); - return results; - } - } - - if ( support.qsa && (!rbuggyQSA || !rbuggyQSA.test( selector )) ) { - nid = old = expando; - newContext = context; - newSelector = nodeType === 9 && selector; - - if ( nodeType === 1 && context.nodeName.toLowerCase() !== "object" ) { - groups = tokenize( selector ); - - if ( (old = context.getAttribute("id")) ) { - nid = old.replace( rescape, "\\$&" ); - } else { - context.setAttribute( "id", nid ); - } - nid = "[id='" + nid + "'] "; - - i = groups.length; - while ( i-- ) { - groups[i] = nid + toSelector( groups[i] ); - } - newContext = rsibling.test( selector ) && testContext( context.parentNode ) || context; - newSelector = groups.join(","); - } - - if ( newSelector ) { - try { - push.apply( results, - newContext.querySelectorAll( newSelector ) - ); - return results; - } catch(qsaError) { - } finally { - if ( !old ) { - context.removeAttribute("id"); - } - } - } - } - } - - return select( selector.replace( rtrim, "$1" ), context, results, seed ); -} - -/** - * Create key-value caches of limited size - * @returns {Function(string, Object)} Returns the Object data after storing it on itself with - * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) - * deleting the oldest entry - */ -function createCache() { - var keys = []; - - function cache( key, value ) { - if ( keys.push( key + " " ) > Expr.cacheLength ) { - delete cache[ keys.shift() ]; - } - return (cache[ key + " " ] = value); - } - return cache; -} - -/** - * Mark a function for special use by Sizzle - * @param {Function} fn The function to mark - */ -function markFunction( fn ) { - fn[ expando ] = true; - return fn; -} - -/** - * Support testing using an element - * @param {Function} fn Passed the created div and expects a boolean result - */ -function assert( fn ) { - var div = document.createElement("div"); - - try { - return !!fn( div ); - } catch (e) { - return false; - } finally { - if ( div.parentNode ) { - div.parentNode.removeChild( div ); - } - div = null; - } -} - -/** - * Adds the same handler for all of the specified attrs - * @param {String} attrs Pipe-separated list of attributes - * @param {Function} handler The method that will be applied - */ -function addHandle( attrs, handler ) { - var arr = attrs.split("|"), - i = attrs.length; - - while ( i-- ) { - Expr.attrHandle[ arr[i] ] = handler; - } -} - -/** - * Checks document order of two siblings - * @param {Element} a - * @param {Element} b - * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b - */ -function siblingCheck( a, b ) { - var cur = b && a, - diff = cur && a.nodeType === 1 && b.nodeType === 1 && - ( ~b.sourceIndex || MAX_NEGATIVE ) - - ( ~a.sourceIndex || MAX_NEGATIVE ); - - if ( diff ) { - return diff; - } - - if ( cur ) { - while ( (cur = cur.nextSibling) ) { - if ( cur === b ) { - return -1; - } - } - } - - return a ? 1 : -1; -} - -/** - * Returns a function to use in pseudos for input types - * @param {String} type - */ -function createInputPseudo( type ) { - return function( elem ) { - var name = elem.nodeName.toLowerCase(); - return name === "input" && elem.type === type; - }; -} - -/** - * Returns a function to use in pseudos for buttons - * @param {String} type - */ -function createButtonPseudo( type ) { - return function( elem ) { - var name = elem.nodeName.toLowerCase(); - return (name === "input" || name === "button") && elem.type === type; - }; -} - -/** - * Returns a function to use in pseudos for positionals - * @param {Function} fn - */ -function createPositionalPseudo( fn ) { - return markFunction(function( argument ) { - argument = +argument; - return markFunction(function( seed, matches ) { - var j, - matchIndexes = fn( [], seed.length, argument ), - i = matchIndexes.length; - - while ( i-- ) { - if ( seed[ (j = matchIndexes[i]) ] ) { - seed[j] = !(matches[j] = seed[j]); - } - } - }); - }); -} - -/** - * Checks a node for validity as a Sizzle context - * @param {Element|Object=} context - * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value - */ -function testContext( context ) { - return context && typeof context.getElementsByTagName !== strundefined && context; -} - -support = Sizzle.support = {}; - -/** - * Detects XML nodes - * @param {Element|Object} elem An element or a document - * @returns {Boolean} True iff elem is a non-HTML XML node - */ -isXML = Sizzle.isXML = function( elem ) { - var documentElement = elem && (elem.ownerDocument || elem).documentElement; - return documentElement ? documentElement.nodeName !== "HTML" : false; -}; - -/** - * Sets document-related variables once based on the current document - * @param {Element|Object} [doc] An element or document object to use to set the document - * @returns {Object} Returns the current document - */ -setDocument = Sizzle.setDocument = function( node ) { - var hasCompare, - doc = node ? node.ownerDocument || node : preferredDoc, - parent = doc.defaultView; - - if ( doc === document || doc.nodeType !== 9 || !doc.documentElement ) { - return document; - } - - document = doc; - docElem = doc.documentElement; - - documentIsHTML = !isXML( doc ); - - if ( parent && parent !== parent.top ) { - if ( parent.addEventListener ) { - parent.addEventListener( "unload", function() { - setDocument(); - }, false ); - } else if ( parent.attachEvent ) { - parent.attachEvent( "onunload", function() { - setDocument(); - }); - } - } - - /* Attributes - ---------------------------------------------------------------------- */ - - support.attributes = assert(function( div ) { - div.className = "i"; - return !div.getAttribute("className"); - }); - - /* getElement(s)By* - ---------------------------------------------------------------------- */ - - support.getElementsByTagName = assert(function( div ) { - div.appendChild( doc.createComment("") ); - return !div.getElementsByTagName("*").length; - }); - - support.getElementsByClassName = rnative.test( doc.getElementsByClassName ) && assert(function( div ) { - div.innerHTML = "
"; - - div.firstChild.className = "i"; - return div.getElementsByClassName("i").length === 2; - }); - - support.getById = assert(function( div ) { - docElem.appendChild( div ).id = expando; - return !doc.getElementsByName || !doc.getElementsByName( expando ).length; - }); - - if ( support.getById ) { - Expr.find["ID"] = function( id, context ) { - if ( typeof context.getElementById !== strundefined && documentIsHTML ) { - var m = context.getElementById( id ); - return m && m.parentNode ? [m] : []; - } - }; - Expr.filter["ID"] = function( id ) { - var attrId = id.replace( runescape, funescape ); - return function( elem ) { - return elem.getAttribute("id") === attrId; - }; - }; - } else { - delete Expr.find["ID"]; - - Expr.filter["ID"] = function( id ) { - var attrId = id.replace( runescape, funescape ); - return function( elem ) { - var node = typeof elem.getAttributeNode !== strundefined && elem.getAttributeNode("id"); - return node && node.value === attrId; - }; - }; - } - - Expr.find["TAG"] = support.getElementsByTagName ? - function( tag, context ) { - if ( typeof context.getElementsByTagName !== strundefined ) { - return context.getElementsByTagName( tag ); - } - } : - function( tag, context ) { - var elem, - tmp = [], - i = 0, - results = context.getElementsByTagName( tag ); - - if ( tag === "*" ) { - while ( (elem = results[i++]) ) { - if ( elem.nodeType === 1 ) { - tmp.push( elem ); - } - } - - return tmp; - } - return results; - }; - - Expr.find["CLASS"] = support.getElementsByClassName && function( className, context ) { - if ( typeof context.getElementsByClassName !== strundefined && documentIsHTML ) { - return context.getElementsByClassName( className ); - } - }; - - /* QSA/matchesSelector - ---------------------------------------------------------------------- */ - - - rbuggyMatches = []; - - rbuggyQSA = []; - - if ( (support.qsa = rnative.test( doc.querySelectorAll )) ) { - assert(function( div ) { - div.innerHTML = ""; - - if ( div.querySelectorAll("[t^='']").length ) { - rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); - } - - if ( !div.querySelectorAll("[selected]").length ) { - rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); - } - - if ( !div.querySelectorAll(":checked").length ) { - rbuggyQSA.push(":checked"); - } - }); - - assert(function( div ) { - var input = doc.createElement("input"); - input.setAttribute( "type", "hidden" ); - div.appendChild( input ).setAttribute( "name", "D" ); - - if ( div.querySelectorAll("[name=d]").length ) { - rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); - } - - if ( !div.querySelectorAll(":enabled").length ) { - rbuggyQSA.push( ":enabled", ":disabled" ); - } - - div.querySelectorAll("*,:x"); - rbuggyQSA.push(",.*:"); - }); - } - - if ( (support.matchesSelector = rnative.test( (matches = docElem.webkitMatchesSelector || - docElem.mozMatchesSelector || - docElem.oMatchesSelector || - docElem.msMatchesSelector) )) ) { - - assert(function( div ) { - support.disconnectedMatch = matches.call( div, "div" ); - - matches.call( div, "[s!='']:x" ); - rbuggyMatches.push( "!=", pseudos ); - }); - } - - rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join("|") ); - rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join("|") ); - - /* Contains - ---------------------------------------------------------------------- */ - hasCompare = rnative.test( docElem.compareDocumentPosition ); - - contains = hasCompare || rnative.test( docElem.contains ) ? - function( a, b ) { - var adown = a.nodeType === 9 ? a.documentElement : a, - bup = b && b.parentNode; - return a === bup || !!( bup && bup.nodeType === 1 && ( - adown.contains ? - adown.contains( bup ) : - a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 - )); - } : - function( a, b ) { - if ( b ) { - while ( (b = b.parentNode) ) { - if ( b === a ) { - return true; - } - } - } - return false; - }; - - /* Sorting - ---------------------------------------------------------------------- */ - - sortOrder = hasCompare ? - function( a, b ) { - - if ( a === b ) { - hasDuplicate = true; - return 0; - } - - var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; - if ( compare ) { - return compare; - } - - compare = ( a.ownerDocument || a ) === ( b.ownerDocument || b ) ? - a.compareDocumentPosition( b ) : - - 1; - - if ( compare & 1 || - (!support.sortDetached && b.compareDocumentPosition( a ) === compare) ) { - - if ( a === doc || a.ownerDocument === preferredDoc && contains(preferredDoc, a) ) { - return -1; - } - if ( b === doc || b.ownerDocument === preferredDoc && contains(preferredDoc, b) ) { - return 1; - } - - return sortInput ? - ( indexOf.call( sortInput, a ) - indexOf.call( sortInput, b ) ) : - 0; - } - - return compare & 4 ? -1 : 1; - } : - function( a, b ) { - if ( a === b ) { - hasDuplicate = true; - return 0; - } - - var cur, - i = 0, - aup = a.parentNode, - bup = b.parentNode, - ap = [ a ], - bp = [ b ]; - - if ( !aup || !bup ) { - return a === doc ? -1 : - b === doc ? 1 : - aup ? -1 : - bup ? 1 : - sortInput ? - ( indexOf.call( sortInput, a ) - indexOf.call( sortInput, b ) ) : - 0; - - } else if ( aup === bup ) { - return siblingCheck( a, b ); - } - - cur = a; - while ( (cur = cur.parentNode) ) { - ap.unshift( cur ); - } - cur = b; - while ( (cur = cur.parentNode) ) { - bp.unshift( cur ); - } - - while ( ap[i] === bp[i] ) { - i++; - } - - return i ? - siblingCheck( ap[i], bp[i] ) : - - ap[i] === preferredDoc ? -1 : - bp[i] === preferredDoc ? 1 : - 0; - }; - - return doc; -}; - -Sizzle.matches = function( expr, elements ) { - return Sizzle( expr, null, null, elements ); -}; - -Sizzle.matchesSelector = function( elem, expr ) { - if ( ( elem.ownerDocument || elem ) !== document ) { - setDocument( elem ); - } - - expr = expr.replace( rattributeQuotes, "='$1']" ); - - if ( support.matchesSelector && documentIsHTML && - ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && - ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { - - try { - var ret = matches.call( elem, expr ); - - if ( ret || support.disconnectedMatch || - elem.document && elem.document.nodeType !== 11 ) { - return ret; - } - } catch(e) {} - } - - return Sizzle( expr, document, null, [elem] ).length > 0; -}; - -Sizzle.contains = function( context, elem ) { - if ( ( context.ownerDocument || context ) !== document ) { - setDocument( context ); - } - return contains( context, elem ); -}; - -Sizzle.attr = function( elem, name ) { - if ( ( elem.ownerDocument || elem ) !== document ) { - setDocument( elem ); - } - - var fn = Expr.attrHandle[ name.toLowerCase() ], - val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? - fn( elem, name, !documentIsHTML ) : - undefined; - - return val !== undefined ? - val : - support.attributes || !documentIsHTML ? - elem.getAttribute( name ) : - (val = elem.getAttributeNode(name)) && val.specified ? - val.value : - null; -}; - -Sizzle.error = function( msg ) { - throw new Error( "Syntax error, unrecognized expression: " + msg ); -}; - -/** - * Document sorting and removing duplicates - * @param {ArrayLike} results - */ -Sizzle.uniqueSort = function( results ) { - var elem, - duplicates = [], - j = 0, - i = 0; - - hasDuplicate = !support.detectDuplicates; - sortInput = !support.sortStable && results.slice( 0 ); - results.sort( sortOrder ); - - if ( hasDuplicate ) { - while ( (elem = results[i++]) ) { - if ( elem === results[ i ] ) { - j = duplicates.push( i ); - } - } - while ( j-- ) { - results.splice( duplicates[ j ], 1 ); - } - } - - sortInput = null; - - return results; -}; - -/** - * Utility function for retrieving the text value of an array of DOM nodes - * @param {Array|Element} elem - */ -getText = Sizzle.getText = function( elem ) { - var node, - ret = "", - i = 0, - nodeType = elem.nodeType; - - if ( !nodeType ) { - while ( (node = elem[i++]) ) { - ret += getText( node ); - } - } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { - if ( typeof elem.textContent === "string" ) { - return elem.textContent; - } else { - for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { - ret += getText( elem ); - } - } - } else if ( nodeType === 3 || nodeType === 4 ) { - return elem.nodeValue; - } - - return ret; -}; - -Expr = Sizzle.selectors = { - - cacheLength: 50, - - createPseudo: markFunction, - - match: matchExpr, - - attrHandle: {}, - - find: {}, - - relative: { - ">": { dir: "parentNode", first: true }, - " ": { dir: "parentNode" }, - "+": { dir: "previousSibling", first: true }, - "~": { dir: "previousSibling" } - }, - - preFilter: { - "ATTR": function( match ) { - match[1] = match[1].replace( runescape, funescape ); - - match[3] = ( match[4] || match[5] || "" ).replace( runescape, funescape ); - - if ( match[2] === "~=" ) { - match[3] = " " + match[3] + " "; - } - - return match.slice( 0, 4 ); - }, - - "CHILD": function( match ) { - /* matches from matchExpr["CHILD"] - 1 type (only|nth|...) - 2 what (child|of-type) - 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) - 4 xn-component of xn+y argument ([+-]?\d*n|) - 5 sign of xn-component - 6 x of xn-component - 7 sign of y-component - 8 y of y-component - */ - match[1] = match[1].toLowerCase(); - - if ( match[1].slice( 0, 3 ) === "nth" ) { - if ( !match[3] ) { - Sizzle.error( match[0] ); - } - - match[4] = +( match[4] ? match[5] + (match[6] || 1) : 2 * ( match[3] === "even" || match[3] === "odd" ) ); - match[5] = +( ( match[7] + match[8] ) || match[3] === "odd" ); - - } else if ( match[3] ) { - Sizzle.error( match[0] ); - } - - return match; - }, - - "PSEUDO": function( match ) { - var excess, - unquoted = !match[5] && match[2]; - - if ( matchExpr["CHILD"].test( match[0] ) ) { - return null; - } - - if ( match[3] && match[4] !== undefined ) { - match[2] = match[4]; - - } else if ( unquoted && rpseudo.test( unquoted ) && - (excess = tokenize( unquoted, true )) && - (excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length) ) { - - match[0] = match[0].slice( 0, excess ); - match[2] = unquoted.slice( 0, excess ); - } - - return match.slice( 0, 3 ); - } - }, - - filter: { - - "TAG": function( nodeNameSelector ) { - var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); - return nodeNameSelector === "*" ? - function() { return true; } : - function( elem ) { - return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; - }; - }, - - "CLASS": function( className ) { - var pattern = classCache[ className + " " ]; - - return pattern || - (pattern = new RegExp( "(^|" + whitespace + ")" + className + "(" + whitespace + "|$)" )) && - classCache( className, function( elem ) { - return pattern.test( typeof elem.className === "string" && elem.className || typeof elem.getAttribute !== strundefined && elem.getAttribute("class") || "" ); - }); - }, - - "ATTR": function( name, operator, check ) { - return function( elem ) { - var result = Sizzle.attr( elem, name ); - - if ( result == null ) { - return operator === "!="; - } - if ( !operator ) { - return true; - } - - result += ""; - - return operator === "=" ? result === check : - operator === "!=" ? result !== check : - operator === "^=" ? check && result.indexOf( check ) === 0 : - operator === "*=" ? check && result.indexOf( check ) > -1 : - operator === "$=" ? check && result.slice( -check.length ) === check : - operator === "~=" ? ( " " + result + " " ).indexOf( check ) > -1 : - operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : - false; - }; - }, - - "CHILD": function( type, what, argument, first, last ) { - var simple = type.slice( 0, 3 ) !== "nth", - forward = type.slice( -4 ) !== "last", - ofType = what === "of-type"; - - return first === 1 && last === 0 ? - - function( elem ) { - return !!elem.parentNode; - } : - - function( elem, context, xml ) { - var cache, outerCache, node, diff, nodeIndex, start, - dir = simple !== forward ? "nextSibling" : "previousSibling", - parent = elem.parentNode, - name = ofType && elem.nodeName.toLowerCase(), - useCache = !xml && !ofType; - - if ( parent ) { - - if ( simple ) { - while ( dir ) { - node = elem; - while ( (node = node[ dir ]) ) { - if ( ofType ? node.nodeName.toLowerCase() === name : node.nodeType === 1 ) { - return false; - } - } - start = dir = type === "only" && !start && "nextSibling"; - } - return true; - } - - start = [ forward ? parent.firstChild : parent.lastChild ]; - - if ( forward && useCache ) { - outerCache = parent[ expando ] || (parent[ expando ] = {}); - cache = outerCache[ type ] || []; - nodeIndex = cache[0] === dirruns && cache[1]; - diff = cache[0] === dirruns && cache[2]; - node = nodeIndex && parent.childNodes[ nodeIndex ]; - - while ( (node = ++nodeIndex && node && node[ dir ] || - - (diff = nodeIndex = 0) || start.pop()) ) { - - if ( node.nodeType === 1 && ++diff && node === elem ) { - outerCache[ type ] = [ dirruns, nodeIndex, diff ]; - break; - } - } - - } else if ( useCache && (cache = (elem[ expando ] || (elem[ expando ] = {}))[ type ]) && cache[0] === dirruns ) { - diff = cache[1]; - - } else { - while ( (node = ++nodeIndex && node && node[ dir ] || - (diff = nodeIndex = 0) || start.pop()) ) { - - if ( ( ofType ? node.nodeName.toLowerCase() === name : node.nodeType === 1 ) && ++diff ) { - if ( useCache ) { - (node[ expando ] || (node[ expando ] = {}))[ type ] = [ dirruns, diff ]; - } - - if ( node === elem ) { - break; - } - } - } - } - - diff -= last; - return diff === first || ( diff % first === 0 && diff / first >= 0 ); - } - }; - }, - - "PSEUDO": function( pseudo, argument ) { - var args, - fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || - Sizzle.error( "unsupported pseudo: " + pseudo ); - - if ( fn[ expando ] ) { - return fn( argument ); - } - - if ( fn.length > 1 ) { - args = [ pseudo, pseudo, "", argument ]; - return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? - markFunction(function( seed, matches ) { - var idx, - matched = fn( seed, argument ), - i = matched.length; - while ( i-- ) { - idx = indexOf.call( seed, matched[i] ); - seed[ idx ] = !( matches[ idx ] = matched[i] ); - } - }) : - function( elem ) { - return fn( elem, 0, args ); - }; - } - - return fn; - } - }, - - pseudos: { - "not": markFunction(function( selector ) { - var input = [], - results = [], - matcher = compile( selector.replace( rtrim, "$1" ) ); - - return matcher[ expando ] ? - markFunction(function( seed, matches, context, xml ) { - var elem, - unmatched = matcher( seed, null, xml, [] ), - i = seed.length; - - while ( i-- ) { - if ( (elem = unmatched[i]) ) { - seed[i] = !(matches[i] = elem); - } - } - }) : - function( elem, context, xml ) { - input[0] = elem; - matcher( input, null, xml, results ); - return !results.pop(); - }; - }), - - "has": markFunction(function( selector ) { - return function( elem ) { - return Sizzle( selector, elem ).length > 0; - }; - }), - - "contains": markFunction(function( text ) { - return function( elem ) { - return ( elem.textContent || elem.innerText || getText( elem ) ).indexOf( text ) > -1; - }; - }), - - "lang": markFunction( function( lang ) { - if ( !ridentifier.test(lang || "") ) { - Sizzle.error( "unsupported lang: " + lang ); - } - lang = lang.replace( runescape, funescape ).toLowerCase(); - return function( elem ) { - var elemLang; - do { - if ( (elemLang = documentIsHTML ? - elem.lang : - elem.getAttribute("xml:lang") || elem.getAttribute("lang")) ) { - - elemLang = elemLang.toLowerCase(); - return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; - } - } while ( (elem = elem.parentNode) && elem.nodeType === 1 ); - return false; - }; - }), - - "target": function( elem ) { - var hash = window.location && window.location.hash; - return hash && hash.slice( 1 ) === elem.id; - }, - - "root": function( elem ) { - return elem === docElem; - }, - - "focus": function( elem ) { - return elem === document.activeElement && (!document.hasFocus || document.hasFocus()) && !!(elem.type || elem.href || ~elem.tabIndex); - }, - - "enabled": function( elem ) { - return elem.disabled === false; - }, - - "disabled": function( elem ) { - return elem.disabled === true; - }, - - "checked": function( elem ) { - var nodeName = elem.nodeName.toLowerCase(); - return (nodeName === "input" && !!elem.checked) || (nodeName === "option" && !!elem.selected); - }, - - "selected": function( elem ) { - if ( elem.parentNode ) { - elem.parentNode.selectedIndex; - } - - return elem.selected === true; - }, - - "empty": function( elem ) { - for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { - if ( elem.nodeType < 6 ) { - return false; - } - } - return true; - }, - - "parent": function( elem ) { - return !Expr.pseudos["empty"]( elem ); - }, - - "header": function( elem ) { - return rheader.test( elem.nodeName ); - }, - - "input": function( elem ) { - return rinputs.test( elem.nodeName ); - }, - - "button": function( elem ) { - var name = elem.nodeName.toLowerCase(); - return name === "input" && elem.type === "button" || name === "button"; - }, - - "text": function( elem ) { - var attr; - return elem.nodeName.toLowerCase() === "input" && - elem.type === "text" && - - ( (attr = elem.getAttribute("type")) == null || attr.toLowerCase() === "text" ); - }, - - "first": createPositionalPseudo(function() { - return [ 0 ]; - }), - - "last": createPositionalPseudo(function( matchIndexes, length ) { - return [ length - 1 ]; - }), - - "eq": createPositionalPseudo(function( matchIndexes, length, argument ) { - return [ argument < 0 ? argument + length : argument ]; - }), - - "even": createPositionalPseudo(function( matchIndexes, length ) { - var i = 0; - for ( ; i < length; i += 2 ) { - matchIndexes.push( i ); - } - return matchIndexes; - }), - - "odd": createPositionalPseudo(function( matchIndexes, length ) { - var i = 1; - for ( ; i < length; i += 2 ) { - matchIndexes.push( i ); - } - return matchIndexes; - }), - - "lt": createPositionalPseudo(function( matchIndexes, length, argument ) { - var i = argument < 0 ? argument + length : argument; - for ( ; --i >= 0; ) { - matchIndexes.push( i ); - } - return matchIndexes; - }), - - "gt": createPositionalPseudo(function( matchIndexes, length, argument ) { - var i = argument < 0 ? argument + length : argument; - for ( ; ++i < length; ) { - matchIndexes.push( i ); - } - return matchIndexes; - }) - } -}; - -Expr.pseudos["nth"] = Expr.pseudos["eq"]; - -for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { - Expr.pseudos[ i ] = createInputPseudo( i ); -} -for ( i in { submit: true, reset: true } ) { - Expr.pseudos[ i ] = createButtonPseudo( i ); -} - -function setFilters() {} -setFilters.prototype = Expr.filters = Expr.pseudos; -Expr.setFilters = new setFilters(); - -function tokenize( selector, parseOnly ) { - var matched, match, tokens, type, - soFar, groups, preFilters, - cached = tokenCache[ selector + " " ]; - - if ( cached ) { - return parseOnly ? 0 : cached.slice( 0 ); - } - - soFar = selector; - groups = []; - preFilters = Expr.preFilter; - - while ( soFar ) { - - if ( !matched || (match = rcomma.exec( soFar )) ) { - if ( match ) { - soFar = soFar.slice( match[0].length ) || soFar; - } - groups.push( (tokens = []) ); - } - - matched = false; - - if ( (match = rcombinators.exec( soFar )) ) { - matched = match.shift(); - tokens.push({ - value: matched, - type: match[0].replace( rtrim, " " ) - }); - soFar = soFar.slice( matched.length ); - } - - for ( type in Expr.filter ) { - if ( (match = matchExpr[ type ].exec( soFar )) && (!preFilters[ type ] || - (match = preFilters[ type ]( match ))) ) { - matched = match.shift(); - tokens.push({ - value: matched, - type: type, - matches: match - }); - soFar = soFar.slice( matched.length ); - } - } - - if ( !matched ) { - break; - } - } - - return parseOnly ? - soFar.length : - soFar ? - Sizzle.error( selector ) : - tokenCache( selector, groups ).slice( 0 ); -} - -function toSelector( tokens ) { - var i = 0, - len = tokens.length, - selector = ""; - for ( ; i < len; i++ ) { - selector += tokens[i].value; - } - return selector; -} - -function addCombinator( matcher, combinator, base ) { - var dir = combinator.dir, - checkNonElements = base && dir === "parentNode", - doneName = done++; - - return combinator.first ? - function( elem, context, xml ) { - while ( (elem = elem[ dir ]) ) { - if ( elem.nodeType === 1 || checkNonElements ) { - return matcher( elem, context, xml ); - } - } - } : - - function( elem, context, xml ) { - var oldCache, outerCache, - newCache = [ dirruns, doneName ]; - - if ( xml ) { - while ( (elem = elem[ dir ]) ) { - if ( elem.nodeType === 1 || checkNonElements ) { - if ( matcher( elem, context, xml ) ) { - return true; - } - } - } - } else { - while ( (elem = elem[ dir ]) ) { - if ( elem.nodeType === 1 || checkNonElements ) { - outerCache = elem[ expando ] || (elem[ expando ] = {}); - if ( (oldCache = outerCache[ dir ]) && - oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { - - return (newCache[ 2 ] = oldCache[ 2 ]); - } else { - outerCache[ dir ] = newCache; - - if ( (newCache[ 2 ] = matcher( elem, context, xml )) ) { - return true; - } - } - } - } - } - }; -} - -function elementMatcher( matchers ) { - return matchers.length > 1 ? - function( elem, context, xml ) { - var i = matchers.length; - while ( i-- ) { - if ( !matchers[i]( elem, context, xml ) ) { - return false; - } - } - return true; - } : - matchers[0]; -} - -function multipleContexts( selector, contexts, results ) { - var i = 0, - len = contexts.length; - for ( ; i < len; i++ ) { - Sizzle( selector, contexts[i], results ); - } - return results; -} - -function condense( unmatched, map, filter, context, xml ) { - var elem, - newUnmatched = [], - i = 0, - len = unmatched.length, - mapped = map != null; - - for ( ; i < len; i++ ) { - if ( (elem = unmatched[i]) ) { - if ( !filter || filter( elem, context, xml ) ) { - newUnmatched.push( elem ); - if ( mapped ) { - map.push( i ); - } - } - } - } - - return newUnmatched; -} - -function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { - if ( postFilter && !postFilter[ expando ] ) { - postFilter = setMatcher( postFilter ); - } - if ( postFinder && !postFinder[ expando ] ) { - postFinder = setMatcher( postFinder, postSelector ); - } - return markFunction(function( seed, results, context, xml ) { - var temp, i, elem, - preMap = [], - postMap = [], - preexisting = results.length, - - elems = seed || multipleContexts( selector || "*", context.nodeType ? [ context ] : context, [] ), - - matcherIn = preFilter && ( seed || !selector ) ? - condense( elems, preMap, preFilter, context, xml ) : - elems, - - matcherOut = matcher ? - postFinder || ( seed ? preFilter : preexisting || postFilter ) ? - - [] : - - results : - matcherIn; - - if ( matcher ) { - matcher( matcherIn, matcherOut, context, xml ); - } - - if ( postFilter ) { - temp = condense( matcherOut, postMap ); - postFilter( temp, [], context, xml ); - - i = temp.length; - while ( i-- ) { - if ( (elem = temp[i]) ) { - matcherOut[ postMap[i] ] = !(matcherIn[ postMap[i] ] = elem); - } - } - } - - if ( seed ) { - if ( postFinder || preFilter ) { - if ( postFinder ) { - temp = []; - i = matcherOut.length; - while ( i-- ) { - if ( (elem = matcherOut[i]) ) { - temp.push( (matcherIn[i] = elem) ); - } - } - postFinder( null, (matcherOut = []), temp, xml ); - } - - i = matcherOut.length; - while ( i-- ) { - if ( (elem = matcherOut[i]) && - (temp = postFinder ? indexOf.call( seed, elem ) : preMap[i]) > -1 ) { - - seed[temp] = !(results[temp] = elem); - } - } - } - - } else { - matcherOut = condense( - matcherOut === results ? - matcherOut.splice( preexisting, matcherOut.length ) : - matcherOut - ); - if ( postFinder ) { - postFinder( null, results, matcherOut, xml ); - } else { - push.apply( results, matcherOut ); - } - } - }); -} - -function matcherFromTokens( tokens ) { - var checkContext, matcher, j, - len = tokens.length, - leadingRelative = Expr.relative[ tokens[0].type ], - implicitRelative = leadingRelative || Expr.relative[" "], - i = leadingRelative ? 1 : 0, - - matchContext = addCombinator( function( elem ) { - return elem === checkContext; - }, implicitRelative, true ), - matchAnyContext = addCombinator( function( elem ) { - return indexOf.call( checkContext, elem ) > -1; - }, implicitRelative, true ), - matchers = [ function( elem, context, xml ) { - return ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( - (checkContext = context).nodeType ? - matchContext( elem, context, xml ) : - matchAnyContext( elem, context, xml ) ); - } ]; - - for ( ; i < len; i++ ) { - if ( (matcher = Expr.relative[ tokens[i].type ]) ) { - matchers = [ addCombinator(elementMatcher( matchers ), matcher) ]; - } else { - matcher = Expr.filter[ tokens[i].type ].apply( null, tokens[i].matches ); - - if ( matcher[ expando ] ) { - j = ++i; - for ( ; j < len; j++ ) { - if ( Expr.relative[ tokens[j].type ] ) { - break; - } - } - return setMatcher( - i > 1 && elementMatcher( matchers ), - i > 1 && toSelector( - tokens.slice( 0, i - 1 ).concat({ value: tokens[ i - 2 ].type === " " ? "*" : "" }) - ).replace( rtrim, "$1" ), - matcher, - i < j && matcherFromTokens( tokens.slice( i, j ) ), - j < len && matcherFromTokens( (tokens = tokens.slice( j )) ), - j < len && toSelector( tokens ) - ); - } - matchers.push( matcher ); - } - } - - return elementMatcher( matchers ); -} - -function matcherFromGroupMatchers( elementMatchers, setMatchers ) { - var bySet = setMatchers.length > 0, - byElement = elementMatchers.length > 0, - superMatcher = function( seed, context, xml, results, outermost ) { - var elem, j, matcher, - matchedCount = 0, - i = "0", - unmatched = seed && [], - setMatched = [], - contextBackup = outermostContext, - elems = seed || byElement && Expr.find["TAG"]( "*", outermost ), - dirrunsUnique = (dirruns += contextBackup == null ? 1 : Math.random() || 0.1), - len = elems.length; - - if ( outermost ) { - outermostContext = context !== document && context; - } - - for ( ; i !== len && (elem = elems[i]) != null; i++ ) { - if ( byElement && elem ) { - j = 0; - while ( (matcher = elementMatchers[j++]) ) { - if ( matcher( elem, context, xml ) ) { - results.push( elem ); - break; - } - } - if ( outermost ) { - dirruns = dirrunsUnique; - } - } - - if ( bySet ) { - if ( (elem = !matcher && elem) ) { - matchedCount--; - } - - if ( seed ) { - unmatched.push( elem ); - } - } - } - - matchedCount += i; - if ( bySet && i !== matchedCount ) { - j = 0; - while ( (matcher = setMatchers[j++]) ) { - matcher( unmatched, setMatched, context, xml ); - } - - if ( seed ) { - if ( matchedCount > 0 ) { - while ( i-- ) { - if ( !(unmatched[i] || setMatched[i]) ) { - setMatched[i] = pop.call( results ); - } - } - } - - setMatched = condense( setMatched ); - } - - push.apply( results, setMatched ); - - if ( outermost && !seed && setMatched.length > 0 && - ( matchedCount + setMatchers.length ) > 1 ) { - - Sizzle.uniqueSort( results ); - } - } - - if ( outermost ) { - dirruns = dirrunsUnique; - outermostContext = contextBackup; - } - - return unmatched; - }; - - return bySet ? - markFunction( superMatcher ) : - superMatcher; -} - -compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { - var i, - setMatchers = [], - elementMatchers = [], - cached = compilerCache[ selector + " " ]; - - if ( !cached ) { - if ( !match ) { - match = tokenize( selector ); - } - i = match.length; - while ( i-- ) { - cached = matcherFromTokens( match[i] ); - if ( cached[ expando ] ) { - setMatchers.push( cached ); - } else { - elementMatchers.push( cached ); - } - } - - cached = compilerCache( selector, matcherFromGroupMatchers( elementMatchers, setMatchers ) ); - - cached.selector = selector; - } - return cached; -}; - -/** - * A low-level selection function that works with Sizzle's compiled - * selector functions - * @param {String|Function} selector A selector or a pre-compiled - * selector function built with Sizzle.compile - * @param {Element} context - * @param {Array} [results] - * @param {Array} [seed] A set of elements to match against - */ -select = Sizzle.select = function( selector, context, results, seed ) { - var i, tokens, token, type, find, - compiled = typeof selector === "function" && selector, - match = !seed && tokenize( (selector = compiled.selector || selector) ); - - results = results || []; - - if ( match.length === 1 ) { - - tokens = match[0] = match[0].slice( 0 ); - if ( tokens.length > 2 && (token = tokens[0]).type === "ID" && - support.getById && context.nodeType === 9 && documentIsHTML && - Expr.relative[ tokens[1].type ] ) { - - context = ( Expr.find["ID"]( token.matches[0].replace(runescape, funescape), context ) || [] )[0]; - if ( !context ) { - return results; - - } else if ( compiled ) { - context = context.parentNode; - } - - selector = selector.slice( tokens.shift().value.length ); - } - - i = matchExpr["needsContext"].test( selector ) ? 0 : tokens.length; - while ( i-- ) { - token = tokens[i]; - - if ( Expr.relative[ (type = token.type) ] ) { - break; - } - if ( (find = Expr.find[ type ]) ) { - if ( (seed = find( - token.matches[0].replace( runescape, funescape ), - rsibling.test( tokens[0].type ) && testContext( context.parentNode ) || context - )) ) { - - tokens.splice( i, 1 ); - selector = seed.length && toSelector( tokens ); - if ( !selector ) { - push.apply( results, seed ); - return results; - } - - break; - } - } - } - } - - ( compiled || compile( selector, match ) )( - seed, - context, - !documentIsHTML, - results, - rsibling.test( selector ) && testContext( context.parentNode ) || context - ); - return results; -}; - - -support.sortStable = expando.split("").sort( sortOrder ).join("") === expando; - -support.detectDuplicates = !!hasDuplicate; - -setDocument(); - -support.sortDetached = assert(function( div1 ) { - return div1.compareDocumentPosition( document.createElement("div") ) & 1; -}); - -if ( !assert(function( div ) { - div.innerHTML = ""; - return div.firstChild.getAttribute("href") === "#" ; -}) ) { - addHandle( "type|href|height|width", function( elem, name, isXML ) { - if ( !isXML ) { - return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); - } - }); -} - -if ( !support.attributes || !assert(function( div ) { - div.innerHTML = ""; - div.firstChild.setAttribute( "value", "" ); - return div.firstChild.getAttribute( "value" ) === ""; -}) ) { - addHandle( "value", function( elem, name, isXML ) { - if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { - return elem.defaultValue; - } - }); -} - -if ( !assert(function( div ) { - return div.getAttribute("disabled") == null; -}) ) { - addHandle( booleans, function( elem, name, isXML ) { - var val; - if ( !isXML ) { - return elem[ name ] === true ? name.toLowerCase() : - (val = elem.getAttributeNode( name )) && val.specified ? - val.value : - null; - } - }); -} - -if ( typeof define === "function" && define.amd ) { - define(function() { return Sizzle; }); -} else if ( typeof module !== "undefined" && module.exports ) { - module.exports = Sizzle; -} else { - window.Sizzle = Sizzle; -} - -})( window ); - -;(function() { - if (typeof Sizzle !== 'undefined') { - return; - } - - if (typeof define !== 'undefined' && define.amd) { - window.Sizzle = Prototype._actual_sizzle; - window.define = Prototype._original_define; - delete Prototype._actual_sizzle; - delete Prototype._original_define; - } else if (typeof module !== 'undefined' && module.exports) { - window.Sizzle = module.exports; - module.exports = {}; - } -})(); - -;(function(engine) { - var extendElements = Prototype.Selector.extendElements; - - function select(selector, scope) { - return extendElements(engine(selector, scope || document)); - } - - function match(element, selector) { - return engine.matches(selector, [element]).length == 1; - } - - Prototype.Selector.engine = engine; - Prototype.Selector.select = select; - Prototype.Selector.match = match; -})(Sizzle); - -window.Sizzle = Prototype._original_property; -delete Prototype._original_property; - -var Form = { - reset: function(form) { - form = $(form); - form.reset(); - return form; - }, - - serializeElements: function(elements, options) { - if (typeof options != 'object') options = { hash: !!options }; - else if (Object.isUndefined(options.hash)) options.hash = true; - var key, value, submitted = false, submit = options.submit, accumulator, initial; - - if (options.hash) { - initial = {}; - accumulator = function(result, key, value) { - if (key in result) { - if (!Object.isArray(result[key])) result[key] = [result[key]]; - result[key] = result[key].concat(value); - } else result[key] = value; - return result; - }; - } else { - initial = ''; - accumulator = function(result, key, values) { - if (!Object.isArray(values)) {values = [values];} - if (!values.length) {return result;} - var encodedKey = encodeURIComponent(key).gsub(/%20/, '+'); - return result + (result ? "&" : "") + values.map(function (value) { - value = value.gsub(/(\r)?\n/, '\r\n'); - value = encodeURIComponent(value); - value = value.gsub(/%20/, '+'); - return encodedKey + "=" + value; - }).join("&"); - }; - } - - return elements.inject(initial, function(result, element) { - if (!element.disabled && element.name) { - key = element.name; value = $(element).getValue(); - if (value != null && element.type != 'file' && (element.type != 'submit' || (!submitted && - submit !== false && (!submit || key == submit) && (submitted = true)))) { - result = accumulator(result, key, value); - } - } - return result; - }); - } -}; - -Form.Methods = { - serialize: function(form, options) { - return Form.serializeElements(Form.getElements(form), options); - }, - - - getElements: function(form) { - var elements = $(form).getElementsByTagName('*'); - var element, results = [], serializers = Form.Element.Serializers; - - for (var i = 0; element = elements[i]; i++) { - if (serializers[element.tagName.toLowerCase()]) - results.push(Element.extend(element)); - } - return results; - }, - - getInputs: function(form, typeName, name) { - form = $(form); - var inputs = form.getElementsByTagName('input'); - - if (!typeName && !name) return $A(inputs).map(Element.extend); - - for (var i = 0, matchingInputs = [], length = inputs.length; i < length; i++) { - var input = inputs[i]; - if ((typeName && input.type != typeName) || (name && input.name != name)) - continue; - matchingInputs.push(Element.extend(input)); - } - - return matchingInputs; - }, - - disable: function(form) { - form = $(form); - Form.getElements(form).invoke('disable'); - return form; - }, - - enable: function(form) { - form = $(form); - Form.getElements(form).invoke('enable'); - return form; - }, - - findFirstElement: function(form) { - var elements = $(form).getElements().findAll(function(element) { - return 'hidden' != element.type && !element.disabled; - }); - var firstByIndex = elements.findAll(function(element) { - return element.hasAttribute('tabIndex') && element.tabIndex >= 0; - }).sortBy(function(element) { return element.tabIndex }).first(); - - return firstByIndex ? firstByIndex : elements.find(function(element) { - return /^(?:input|select|textarea)$/i.test(element.tagName); - }); - }, - - focusFirstElement: function(form) { - form = $(form); - var element = form.findFirstElement(); - if (element) element.activate(); - return form; - }, - - request: function(form, options) { - form = $(form), options = Object.clone(options || { }); - - var params = options.parameters, action = form.readAttribute('action') || ''; - if (action.blank()) action = window.location.href; - options.parameters = form.serialize(true); - - if (params) { - if (Object.isString(params)) params = params.toQueryParams(); - Object.extend(options.parameters, params); - } - - if (form.hasAttribute('method') && !options.method) - options.method = form.method; - - return new Ajax.Request(action, options); - } -}; - -/*--------------------------------------------------------------------------*/ - - -Form.Element = { - focus: function(element) { - $(element).focus(); - return element; - }, - - select: function(element) { - $(element).select(); - return element; - } -}; - -Form.Element.Methods = { - - serialize: function(element) { - element = $(element); - if (!element.disabled && element.name) { - var value = element.getValue(); - if (value != undefined) { - var pair = { }; - pair[element.name] = value; - return Object.toQueryString(pair); - } - } - return ''; - }, - - getValue: function(element) { - element = $(element); - var method = element.tagName.toLowerCase(); - return Form.Element.Serializers[method](element); - }, - - setValue: function(element, value) { - element = $(element); - var method = element.tagName.toLowerCase(); - Form.Element.Serializers[method](element, value); - return element; - }, - - clear: function(element) { - $(element).value = ''; - return element; - }, - - present: function(element) { - return $(element).value != ''; - }, - - activate: function(element) { - element = $(element); - try { - element.focus(); - if (element.select && (element.tagName.toLowerCase() != 'input' || - !(/^(?:button|reset|submit)$/i.test(element.type)))) - element.select(); - } catch (e) { } - return element; - }, - - disable: function(element) { - element = $(element); - element.disabled = true; - return element; - }, - - enable: function(element) { - element = $(element); - element.disabled = false; - return element; - } -}; - -/*--------------------------------------------------------------------------*/ - -var Field = Form.Element; - -var $F = Form.Element.Methods.getValue; - -/*--------------------------------------------------------------------------*/ - -Form.Element.Serializers = (function() { - function input(element, value) { - switch (element.type.toLowerCase()) { - case 'checkbox': - case 'radio': - return inputSelector(element, value); - default: - return valueSelector(element, value); - } - } - - function inputSelector(element, value) { - if (Object.isUndefined(value)) - return element.checked ? element.value : null; - else element.checked = !!value; - } - - function valueSelector(element, value) { - if (Object.isUndefined(value)) return element.value; - else element.value = value; - } - - function select(element, value) { - if (Object.isUndefined(value)) - return (element.type === 'select-one' ? selectOne : selectMany)(element); - - var opt, currentValue, single = !Object.isArray(value); - for (var i = 0, length = element.length; i < length; i++) { - opt = element.options[i]; - currentValue = this.optionValue(opt); - if (single) { - if (currentValue == value) { - opt.selected = true; - return; - } - } - else opt.selected = value.include(currentValue); - } - } - - function selectOne(element) { - var index = element.selectedIndex; - return index >= 0 ? optionValue(element.options[index]) : null; - } - - function selectMany(element) { - var values, length = element.length; - if (!length) return null; - - for (var i = 0, values = []; i < length; i++) { - var opt = element.options[i]; - if (opt.selected) values.push(optionValue(opt)); - } - return values; - } - - function optionValue(opt) { - return Element.hasAttribute(opt, 'value') ? opt.value : opt.text; - } - - return { - input: input, - inputSelector: inputSelector, - textarea: valueSelector, - select: select, - selectOne: selectOne, - selectMany: selectMany, - optionValue: optionValue, - button: valueSelector - }; -})(); - -/*--------------------------------------------------------------------------*/ - - -Abstract.TimedObserver = Class.create(PeriodicalExecuter, { - initialize: function($super, element, frequency, callback) { - $super(callback, frequency); - this.element = $(element); - this.lastValue = this.getValue(); - }, - - execute: function() { - var value = this.getValue(); - if (Object.isString(this.lastValue) && Object.isString(value) ? - this.lastValue != value : String(this.lastValue) != String(value)) { - this.callback(this.element, value); - this.lastValue = value; - } - } -}); - -Form.Element.Observer = Class.create(Abstract.TimedObserver, { - getValue: function() { - return Form.Element.getValue(this.element); - } -}); - -Form.Observer = Class.create(Abstract.TimedObserver, { - getValue: function() { - return Form.serialize(this.element); - } -}); - -/*--------------------------------------------------------------------------*/ - -Abstract.EventObserver = Class.create({ - initialize: function(element, callback) { - this.element = $(element); - this.callback = callback; - - this.lastValue = this.getValue(); - if (this.element.tagName.toLowerCase() == 'form') - this.registerFormCallbacks(); - else - this.registerCallback(this.element); - }, - - onElementEvent: function() { - var value = this.getValue(); - if (this.lastValue != value) { - this.callback(this.element, value); - this.lastValue = value; - } - }, - - registerFormCallbacks: function() { - Form.getElements(this.element).each(this.registerCallback, this); - }, - - registerCallback: function(element) { - if (element.type) { - switch (element.type.toLowerCase()) { - case 'checkbox': - case 'radio': - Event.observe(element, 'click', this.onElementEvent.bind(this)); - break; - default: - Event.observe(element, 'change', this.onElementEvent.bind(this)); - break; - } - } - } -}); - -Form.Element.EventObserver = Class.create(Abstract.EventObserver, { - getValue: function() { - return Form.Element.getValue(this.element); - } -}); - -Form.EventObserver = Class.create(Abstract.EventObserver, { - getValue: function() { - return Form.serialize(this.element); - } -}); -(function(GLOBAL) { - var DIV = document.createElement('div'); - var docEl = document.documentElement; - var MOUSEENTER_MOUSELEAVE_EVENTS_SUPPORTED = 'onmouseenter' in docEl - && 'onmouseleave' in docEl; - - var Event = { - KEY_BACKSPACE: 8, - KEY_TAB: 9, - KEY_RETURN: 13, - KEY_ESC: 27, - KEY_LEFT: 37, - KEY_UP: 38, - KEY_RIGHT: 39, - KEY_DOWN: 40, - KEY_DELETE: 46, - KEY_HOME: 36, - KEY_END: 35, - KEY_PAGEUP: 33, - KEY_PAGEDOWN: 34, - KEY_INSERT: 45 - }; - - - var isIELegacyEvent = function(event) { return false; }; - - if (window.attachEvent) { - if (window.addEventListener) { - isIELegacyEvent = function(event) { - return !(event instanceof window.Event); - }; - } else { - isIELegacyEvent = function(event) { return true; }; - } - } - - var _isButton; - - function _isButtonForDOMEvents(event, code) { - return event.which ? (event.which === code + 1) : (event.button === code); - } - - var legacyButtonMap = { 0: 1, 1: 4, 2: 2 }; - function _isButtonForLegacyEvents(event, code) { - return event.button === legacyButtonMap[code]; - } - - function _isButtonForWebKit(event, code) { - switch (code) { - case 0: return event.which == 1 && !event.metaKey; - case 1: return event.which == 2 || (event.which == 1 && event.metaKey); - case 2: return event.which == 3; - default: return false; - } - } - - if (window.attachEvent) { - if (!window.addEventListener) { - _isButton = _isButtonForLegacyEvents; - } else { - _isButton = function(event, code) { - return isIELegacyEvent(event) ? _isButtonForLegacyEvents(event, code) : - _isButtonForDOMEvents(event, code); - } - } - } else if (Prototype.Browser.WebKit) { - _isButton = _isButtonForWebKit; - } else { - _isButton = _isButtonForDOMEvents; - } - - function isLeftClick(event) { return _isButton(event, 0) } - - function isMiddleClick(event) { return _isButton(event, 1) } - - function isRightClick(event) { return _isButton(event, 2) } - - function element(event) { - return Element.extend(_element(event)); - } - - function _element(event) { - event = Event.extend(event); - - var node = event.target, type = event.type, - currentTarget = event.currentTarget; - - if (currentTarget && currentTarget.tagName) { - if (type === 'load' || type === 'error' || - (type === 'click' && currentTarget.tagName.toLowerCase() === 'input' - && currentTarget.type === 'radio')) - node = currentTarget; - } - - return node.nodeType == Node.TEXT_NODE ? node.parentNode : node; - } - - function findElement(event, expression) { - var element = _element(event), selector = Prototype.Selector; - if (!expression) return Element.extend(element); - while (element) { - if (Object.isElement(element) && selector.match(element, expression)) - return Element.extend(element); - element = element.parentNode; - } - } - - function pointer(event) { - return { x: pointerX(event), y: pointerY(event) }; - } - - function pointerX(event) { - var docElement = document.documentElement, - body = document.body || { scrollLeft: 0 }; - - return event.pageX || (event.clientX + - (docElement.scrollLeft || body.scrollLeft) - - (docElement.clientLeft || 0)); - } - - function pointerY(event) { - var docElement = document.documentElement, - body = document.body || { scrollTop: 0 }; - - return event.pageY || (event.clientY + - (docElement.scrollTop || body.scrollTop) - - (docElement.clientTop || 0)); - } - - - function stop(event) { - Event.extend(event); - event.preventDefault(); - event.stopPropagation(); - - event.stopped = true; - } - - - Event.Methods = { - isLeftClick: isLeftClick, - isMiddleClick: isMiddleClick, - isRightClick: isRightClick, - - element: element, - findElement: findElement, - - pointer: pointer, - pointerX: pointerX, - pointerY: pointerY, - - stop: stop - }; - - var methods = Object.keys(Event.Methods).inject({ }, function(m, name) { - m[name] = Event.Methods[name].methodize(); - return m; - }); - - if (window.attachEvent) { - function _relatedTarget(event) { - var element; - switch (event.type) { - case 'mouseover': - case 'mouseenter': - element = event.fromElement; - break; - case 'mouseout': - case 'mouseleave': - element = event.toElement; - break; - default: - return null; - } - return Element.extend(element); - } - - var additionalMethods = { - stopPropagation: function() { this.cancelBubble = true }, - preventDefault: function() { this.returnValue = false }, - inspect: function() { return '[object Event]' } - }; - - Event.extend = function(event, element) { - if (!event) return false; - - if (!isIELegacyEvent(event)) return event; - - if (event._extendedByPrototype) return event; - event._extendedByPrototype = Prototype.emptyFunction; - - var pointer = Event.pointer(event); - - Object.extend(event, { - target: event.srcElement || element, - relatedTarget: _relatedTarget(event), - pageX: pointer.x, - pageY: pointer.y - }); - - Object.extend(event, methods); - Object.extend(event, additionalMethods); - - return event; - }; - } else { - Event.extend = Prototype.K; - } - - if (window.addEventListener) { - Event.prototype = window.Event.prototype || document.createEvent('HTMLEvents').__proto__; - Object.extend(Event.prototype, methods); - } - - var EVENT_TRANSLATIONS = { - mouseenter: 'mouseover', - mouseleave: 'mouseout' - }; - - function getDOMEventName(eventName) { - return EVENT_TRANSLATIONS[eventName] || eventName; - } - - if (MOUSEENTER_MOUSELEAVE_EVENTS_SUPPORTED) - getDOMEventName = Prototype.K; - - function getUniqueElementID(element) { - if (element === window) return 0; - - if (typeof element._prototypeUID === 'undefined') - element._prototypeUID = Element.Storage.UID++; - return element._prototypeUID; - } - - function getUniqueElementID_IE(element) { - if (element === window) return 0; - if (element == document) return 1; - return element.uniqueID; - } - - if ('uniqueID' in DIV) - getUniqueElementID = getUniqueElementID_IE; - - function isCustomEvent(eventName) { - return eventName.include(':'); - } - - Event._isCustomEvent = isCustomEvent; - - function getOrCreateRegistryFor(element, uid) { - var CACHE = GLOBAL.Event.cache; - if (Object.isUndefined(uid)) - uid = getUniqueElementID(element); - if (!CACHE[uid]) CACHE[uid] = { element: element }; - return CACHE[uid]; - } - - function destroyRegistryForElement(element, uid) { - if (Object.isUndefined(uid)) - uid = getUniqueElementID(element); - delete GLOBAL.Event.cache[uid]; - } - - - function register(element, eventName, handler) { - var registry = getOrCreateRegistryFor(element); - if (!registry[eventName]) registry[eventName] = []; - var entries = registry[eventName]; - - var i = entries.length; - while (i--) - if (entries[i].handler === handler) return null; - - var uid = getUniqueElementID(element); - var responder = GLOBAL.Event._createResponder(uid, eventName, handler); - var entry = { - responder: responder, - handler: handler - }; - - entries.push(entry); - return entry; - } - - function unregister(element, eventName, handler) { - var registry = getOrCreateRegistryFor(element); - var entries = registry[eventName] || []; - - var i = entries.length, entry; - while (i--) { - if (entries[i].handler === handler) { - entry = entries[i]; - break; - } - } - - if (entry) { - var index = entries.indexOf(entry); - entries.splice(index, 1); - } - - if (entries.length === 0) { - delete registry[eventName]; - if (Object.keys(registry).length === 1 && ('element' in registry)) - destroyRegistryForElement(element); - } - - return entry; - } - - - function observe(element, eventName, handler) { - element = $(element); - var entry = register(element, eventName, handler); - - if (entry === null) return element; - - var responder = entry.responder; - if (isCustomEvent(eventName)) - observeCustomEvent(element, eventName, responder); - else - observeStandardEvent(element, eventName, responder); - - return element; - } - - function observeStandardEvent(element, eventName, responder) { - var actualEventName = getDOMEventName(eventName); - if (element.addEventListener) { - element.addEventListener(actualEventName, responder, false); - } else { - element.attachEvent('on' + actualEventName, responder); - } - } - - function observeCustomEvent(element, eventName, responder) { - if (element.addEventListener) { - element.addEventListener('dataavailable', responder, false); - } else { - element.attachEvent('ondataavailable', responder); - element.attachEvent('onlosecapture', responder); - } - } - - function stopObserving(element, eventName, handler) { - element = $(element); - var handlerGiven = !Object.isUndefined(handler), - eventNameGiven = !Object.isUndefined(eventName); - - if (!eventNameGiven && !handlerGiven) { - stopObservingElement(element); - return element; - } - - if (!handlerGiven) { - stopObservingEventName(element, eventName); - return element; - } - - var entry = unregister(element, eventName, handler); - - if (!entry) return element; - removeEvent(element, eventName, entry.responder); - return element; - } - - function stopObservingStandardEvent(element, eventName, responder) { - var actualEventName = getDOMEventName(eventName); - if (element.removeEventListener) { - element.removeEventListener(actualEventName, responder, false); - } else { - element.detachEvent('on' + actualEventName, responder); - } - } - - function stopObservingCustomEvent(element, eventName, responder) { - if (element.removeEventListener) { - element.removeEventListener('dataavailable', responder, false); - } else { - element.detachEvent('ondataavailable', responder); - element.detachEvent('onlosecapture', responder); - } - } - - - - function stopObservingElement(element) { - var uid = getUniqueElementID(element), registry = GLOBAL.Event.cache[uid]; - if (!registry) return; - - destroyRegistryForElement(element, uid); - - var entries, i; - for (var eventName in registry) { - if (eventName === 'element') continue; - - entries = registry[eventName]; - i = entries.length; - while (i--) - removeEvent(element, eventName, entries[i].responder); - } - } - - function stopObservingEventName(element, eventName) { - var registry = getOrCreateRegistryFor(element); - var entries = registry[eventName]; - if (entries) { - delete registry[eventName]; - } - - entries = entries || []; - - var i = entries.length; - while (i--) - removeEvent(element, eventName, entries[i].responder); - - for (var name in registry) { - if (name === 'element') continue; - return; // There is another registered event - } - - destroyRegistryForElement(element); - } - - - function removeEvent(element, eventName, handler) { - if (isCustomEvent(eventName)) - stopObservingCustomEvent(element, eventName, handler); - else - stopObservingStandardEvent(element, eventName, handler); - } - - - - function getFireTarget(element) { - if (element !== document) return element; - if (document.createEvent && !element.dispatchEvent) - return document.documentElement; - return element; - } - - function fire(element, eventName, memo, bubble) { - element = getFireTarget($(element)); - if (Object.isUndefined(bubble)) bubble = true; - memo = memo || {}; - - var event = fireEvent(element, eventName, memo, bubble); - return Event.extend(event); - } - - function fireEvent_DOM(element, eventName, memo, bubble) { - var event = document.createEvent('HTMLEvents'); - event.initEvent('dataavailable', bubble, true); - - event.eventName = eventName; - event.memo = memo; - - element.dispatchEvent(event); - return event; - } - - function fireEvent_IE(element, eventName, memo, bubble) { - var event = document.createEventObject(); - event.eventType = bubble ? 'ondataavailable' : 'onlosecapture'; - - event.eventName = eventName; - event.memo = memo; - - element.fireEvent(event.eventType, event); - return event; - } - - var fireEvent = document.createEvent ? fireEvent_DOM : fireEvent_IE; - - - - Event.Handler = Class.create({ - initialize: function(element, eventName, selector, callback) { - this.element = $(element); - this.eventName = eventName; - this.selector = selector; - this.callback = callback; - this.handler = this.handleEvent.bind(this); - }, - - - start: function() { - Event.observe(this.element, this.eventName, this.handler); - return this; - }, - - stop: function() { - Event.stopObserving(this.element, this.eventName, this.handler); - return this; - }, - - handleEvent: function(event) { - var element = Event.findElement(event, this.selector); - if (element) this.callback.call(this.element, event, element); - } - }); - - function on(element, eventName, selector, callback) { - element = $(element); - if (Object.isFunction(selector) && Object.isUndefined(callback)) { - callback = selector, selector = null; - } - - return new Event.Handler(element, eventName, selector, callback).start(); - } - - Object.extend(Event, Event.Methods); - - Object.extend(Event, { - fire: fire, - observe: observe, - stopObserving: stopObserving, - on: on - }); - - Element.addMethods({ - fire: fire, - - observe: observe, - - stopObserving: stopObserving, - - on: on - }); - - Object.extend(document, { - fire: fire.methodize(), - - observe: observe.methodize(), - - stopObserving: stopObserving.methodize(), - - on: on.methodize(), - - loaded: false - }); - - if (GLOBAL.Event) Object.extend(window.Event, Event); - else GLOBAL.Event = Event; - - GLOBAL.Event.cache = {}; - - function destroyCache_IE() { - GLOBAL.Event.cache = null; - } - - if (window.attachEvent) - window.attachEvent('onunload', destroyCache_IE); - - DIV = null; - docEl = null; -})(this); - -(function(GLOBAL) { - /* Code for creating leak-free event responders is based on work by - John-David Dalton. */ - - var docEl = document.documentElement; - var MOUSEENTER_MOUSELEAVE_EVENTS_SUPPORTED = 'onmouseenter' in docEl - && 'onmouseleave' in docEl; - - function isSimulatedMouseEnterLeaveEvent(eventName) { - return !MOUSEENTER_MOUSELEAVE_EVENTS_SUPPORTED && - (eventName === 'mouseenter' || eventName === 'mouseleave'); - } - - function createResponder(uid, eventName, handler) { - if (Event._isCustomEvent(eventName)) - return createResponderForCustomEvent(uid, eventName, handler); - if (isSimulatedMouseEnterLeaveEvent(eventName)) - return createMouseEnterLeaveResponder(uid, eventName, handler); - - return function(event) { - if (!Event.cache) return; - - var element = Event.cache[uid].element; - Event.extend(event, element); - handler.call(element, event); - }; - } - - function createResponderForCustomEvent(uid, eventName, handler) { - return function(event) { - var cache = Event.cache[uid]; - var element = cache && cache.element; - - if (Object.isUndefined(event.eventName)) - return false; - - if (event.eventName !== eventName) - return false; - - Event.extend(event, element); - handler.call(element, event); - }; - } - - function createMouseEnterLeaveResponder(uid, eventName, handler) { - return function(event) { - var element = Event.cache[uid].element; - - Event.extend(event, element); - var parent = event.relatedTarget; - - while (parent && parent !== element) { - try { parent = parent.parentNode; } - catch(e) { parent = element; } - } - - if (parent === element) return; - handler.call(element, event); - } - } - - GLOBAL.Event._createResponder = createResponder; - docEl = null; -})(this); - -(function(GLOBAL) { - /* Support for the DOMContentLoaded event is based on work by Dan Webb, - Matthias Miller, Dean Edwards, John Resig, and Diego Perini. */ - - var TIMER; - - function fireContentLoadedEvent() { - if (document.loaded) return; - if (TIMER) window.clearTimeout(TIMER); - document.loaded = true; - document.fire('dom:loaded'); - } - - function checkReadyState() { - if (document.readyState === 'complete') { - document.detachEvent('onreadystatechange', checkReadyState); - fireContentLoadedEvent(); - } - } - - function pollDoScroll() { - try { - document.documentElement.doScroll('left'); - } catch (e) { - TIMER = pollDoScroll.defer(); - return; - } - - fireContentLoadedEvent(); - } - - - if (document.readyState === 'complete') { - fireContentLoadedEvent(); - return; - } - - if (document.addEventListener) { - document.addEventListener('DOMContentLoaded', fireContentLoadedEvent, false); - } else { - document.attachEvent('onreadystatechange', checkReadyState); - if (window == top) TIMER = pollDoScroll.defer(); - } - - Event.observe(window, 'load', fireContentLoadedEvent); -})(this); - - -Element.addMethods(); -/*------------------------------- DEPRECATED -------------------------------*/ - -Hash.toQueryString = Object.toQueryString; - -var Toggle = { display: Element.toggle }; - -Element.addMethods({ - childOf: Element.Methods.descendantOf -}); - -var Insertion = { - Before: function(element, content) { - return Element.insert(element, {before:content}); - }, - - Top: function(element, content) { - return Element.insert(element, {top:content}); - }, - - Bottom: function(element, content) { - return Element.insert(element, {bottom:content}); - }, - - After: function(element, content) { - return Element.insert(element, {after:content}); - } -}; - -var $continue = new Error('"throw $continue" is deprecated, use "return" instead'); - -var Position = { - includeScrollOffsets: false, - - prepare: function() { - this.deltaX = window.pageXOffset - || document.documentElement.scrollLeft - || document.body.scrollLeft - || 0; - this.deltaY = window.pageYOffset - || document.documentElement.scrollTop - || document.body.scrollTop - || 0; - }, - - within: function(element, x, y) { - if (this.includeScrollOffsets) - return this.withinIncludingScrolloffsets(element, x, y); - this.xcomp = x; - this.ycomp = y; - this.offset = Element.cumulativeOffset(element); - - return (y >= this.offset[1] && - y < this.offset[1] + element.offsetHeight && - x >= this.offset[0] && - x < this.offset[0] + element.offsetWidth); - }, - - withinIncludingScrolloffsets: function(element, x, y) { - var offsetcache = Element.cumulativeScrollOffset(element); - - this.xcomp = x + offsetcache[0] - this.deltaX; - this.ycomp = y + offsetcache[1] - this.deltaY; - this.offset = Element.cumulativeOffset(element); - - return (this.ycomp >= this.offset[1] && - this.ycomp < this.offset[1] + element.offsetHeight && - this.xcomp >= this.offset[0] && - this.xcomp < this.offset[0] + element.offsetWidth); - }, - - overlap: function(mode, element) { - if (!mode) return 0; - if (mode == 'vertical') - return ((this.offset[1] + element.offsetHeight) - this.ycomp) / - element.offsetHeight; - if (mode == 'horizontal') - return ((this.offset[0] + element.offsetWidth) - this.xcomp) / - element.offsetWidth; - }, - - - cumulativeOffset: Element.Methods.cumulativeOffset, - - positionedOffset: Element.Methods.positionedOffset, - - absolutize: function(element) { - Position.prepare(); - return Element.absolutize(element); - }, - - relativize: function(element) { - Position.prepare(); - return Element.relativize(element); - }, - - realOffset: Element.Methods.cumulativeScrollOffset, - - offsetParent: Element.Methods.getOffsetParent, - - page: Element.Methods.viewportOffset, - - clone: function(source, target, options) { - options = options || { }; - return Element.clonePosition(target, source, options); - } -}; - -/*--------------------------------------------------------------------------*/ - -if (!document.getElementsByClassName) document.getElementsByClassName = function(instanceMethods){ - function iter(name) { - return name.blank() ? null : "[contains(concat(' ', @class, ' '), ' " + name + " ')]"; - } - - instanceMethods.getElementsByClassName = Prototype.BrowserFeatures.XPath ? - function(element, className) { - className = className.toString().strip(); - var cond = /\s/.test(className) ? $w(className).map(iter).join('') : iter(className); - return cond ? document._getElementsByXPath('.//*' + cond, element) : []; - } : function(element, className) { - className = className.toString().strip(); - var elements = [], classNames = (/\s/.test(className) ? $w(className) : null); - if (!classNames && !className) return elements; - - var nodes = $(element).getElementsByTagName('*'); - className = ' ' + className + ' '; - - for (var i = 0, child, cn; child = nodes[i]; i++) { - if (child.className && (cn = ' ' + child.className + ' ') && (cn.include(className) || - (classNames && classNames.all(function(name) { - return !name.toString().blank() && cn.include(' ' + name + ' '); - })))) - elements.push(Element.extend(child)); - } - return elements; - }; - - return function(className, parentElement) { - return $(parentElement || document.body).getElementsByClassName(className); - }; -}(Element.Methods); - -/*--------------------------------------------------------------------------*/ - -Element.ClassNames = Class.create(); -Element.ClassNames.prototype = { - initialize: function(element) { - this.element = $(element); - }, - - _each: function(iterator, context) { - this.element.className.split(/\s+/).select(function(name) { - return name.length > 0; - })._each(iterator, context); - }, - - set: function(className) { - this.element.className = className; - }, - - add: function(classNameToAdd) { - if (this.include(classNameToAdd)) return; - this.set($A(this).concat(classNameToAdd).join(' ')); - }, - - remove: function(classNameToRemove) { - if (!this.include(classNameToRemove)) return; - this.set($A(this).without(classNameToRemove).join(' ')); - }, - - toString: function() { - return $A(this).join(' '); - } -}; - -Object.extend(Element.ClassNames.prototype, Enumerable); - -/*--------------------------------------------------------------------------*/ - -(function() { - window.Selector = Class.create({ - initialize: function(expression) { - this.expression = expression.strip(); - }, - - findElements: function(rootElement) { - return Prototype.Selector.select(this.expression, rootElement); - }, - - match: function(element) { - return Prototype.Selector.match(element, this.expression); - }, - - toString: function() { - return this.expression; - }, - - inspect: function() { - return "#"; - } - }); - - Object.extend(Selector, { - matchElements: function(elements, expression) { - var match = Prototype.Selector.match, - results = []; - - for (var i = 0, length = elements.length; i < length; i++) { - var element = elements[i]; - if (match(element, expression)) { - results.push(Element.extend(element)); - } - } - return results; - }, - - findElement: function(elements, expression, index) { - index = index || 0; - var matchIndex = 0, element; - for (var i = 0, length = elements.length; i < length; i++) { - element = elements[i]; - if (Prototype.Selector.match(element, expression) && index === matchIndex++) { - return Element.extend(element); - } - } - }, - - findChildElements: function(element, expressions) { - var selector = expressions.toArray().join(', '); - return Prototype.Selector.select(selector, element || document); - } - }); -})(); diff --git a/zookeeper-docs/src/main/resources/markdown/skin/screen.css b/zookeeper-docs/src/main/resources/markdown/skin/screen.css deleted file mode 100644 index 9ce32c292dd..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/skin/screen.css +++ /dev/null @@ -1,531 +0,0 @@ -/* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You under the Apache License, Version 2.0 -* (the "License"); you may not use this file except in compliance with -* the License. You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ -body { margin: 0px 0px 0px 0px; font-family: Verdana, Helvetica, sans-serif; } - -h1 { font-size : 160%; margin: 0px 0px 0px 0px; padding: 0px; } -h2 { font-size : 140%; margin: 1em 0px 0.8em 0px; padding: 0px; font-weight : bold;} -h3 { font-size : 130%; margin: 0.8em 0px 0px 0px; padding: 0px; font-weight : bold; } -.h3 { margin: 22px 0px 3px 0px; } -h4 { font-size : 120%; margin: 0.7em 0px 0px 0px; padding: 0px; font-weight : normal; text-align: left; } -.h4 { margin: 18px 0px 0px 0px; } -h4.faq { font-size : 120%; margin: 18px 0px 0px 0px; padding: 0px; font-weight : bold; text-align: left; } -h5 { font-size : 100%; margin: 14px 0px 0px 0px; padding: 0px; font-weight : normal; text-align: left; } - -/** -* table -*/ -table .title { background-color: #000000; } -.ForrestTable { - color: #ffffff; - background-color: #7099C5; - width: 100%; - font-size : 100%; - empty-cells: show; -} -table caption { - padding-left: 5px; - color: white; - text-align: left; - font-weight: bold; - background-color: #000000; -} -.ForrestTable td { - color: black; - background-color: #f0f0ff; -} -.ForrestTable th { text-align: center; } -/** - * Page Header - */ - -#top { - position: relative; - float: left; - width: 100%; - background: #294563; /* if you want a background in the header, put it here */ -} - -#top .breadtrail { - background: #CFDCED; - color: black; - border-bottom: solid 1px white; - padding: 3px 10px; - font-size: 75%; -} -#top .breadtrail a { color: black; } - -#top .header { - float: left; - width: 100%; - background: url("header_white_line.gif") repeat-x bottom; -} - -#top .grouplogo { - padding: 7px 0 10px 10px; - float: left; - text-align: left; -} -#top .projectlogo { - padding: 7px 0 10px 10px; - float: left; - width: 33%; - text-align: right; -} -#top .projectlogoA1 { - padding: 7px 0 10px 10px; - float: right; -} -html>body #top .searchbox { - bottom: 0px; -} -#top .searchbox { - position: absolute; - right: 10px; - height: 42px; - font-size: 70%; - white-space: nowrap; - bottom: -1px; /* compensate for IE rendering issue */ - border-radius: 5px 5px 0px 0px; -} - -#top .searchbox form { - padding: 5px 10px; - margin: 0; -} -#top .searchbox p { - padding: 0 0 2px 0; - margin: 0; -} -#top .searchbox input { - font-size: 100%; -} - -#tabs { - clear: both; - padding-left: 10px; - margin: 0; - list-style: none; -} - -#tabs li { - float: left; - margin: 0 3px 0 0; - padding: 0; - border-radius: 5px 5px 0px 0px; -} - -/*background: url("tab-left.gif") no-repeat left top;*/ -#tabs li a { - float: left; - display: block; - font-family: verdana, arial, sans-serif; - text-decoration: none; - color: black; - white-space: nowrap; - padding: 5px 15px 4px; - width: .1em; /* IE/Win fix */ -} - -#tabs li a:hover { - - cursor: pointer; - text-decoration:underline; -} - -#tabs > li a { width: auto; } /* Rest of IE/Win fix */ - -/* Commented Backslash Hack hides rule from IE5-Mac \*/ -#tabs a { float: none; } -/* End IE5-Mac hack */ - -#top .header .current { - background-color: #4C6C8F; -} -#top .header .current a { - font-weight: bold; - padding-bottom: 5px; - color: white; -} -#publishedStrip { - padding-right: 10px; - padding-left: 20px; - padding-top: 3px; - padding-bottom:3px; - color: #ffffff; - font-size : 60%; - font-weight: bold; - background-color: #4C6C8F; - text-align:right; -} - -#level2tabs { -margin: 0; -float:left; -position:relative; - -} - - - -#level2tabs a:hover { - - cursor: pointer; - text-decoration:underline; - -} - -#level2tabs a{ - - cursor: pointer; - text-decoration:none; - background-image: url('chapter.gif'); - background-repeat: no-repeat; - background-position: center left; - padding-left: 6px; - margin-left: 6px; -} - -/* -* border-top: solid #4C6C8F 15px; -*/ -#main { - position: relative; - background: white; - clear:both; -} -#main .breadtrail { - clear:both; - position: relative; - background: #CFDCED; - color: black; - border-bottom: solid 1px black; - border-top: solid 1px black; - padding: 0px 180px; - font-size: 75%; - z-index:10; -} - -img.corner { - width: 15px; - height: 15px; - border: none; - display: block !important; -} - -img.cornersmall { - width: 5px; - height: 5px; - border: none; - display: block !important; -} -/** - * Side menu - */ -#menu a { font-weight: normal; text-decoration: none;} -#menu a:visited { font-weight: normal; } -#menu a:active { font-weight: normal; } -#menu a:hover { font-weight: normal; text-decoration:underline;} - -#menuarea { width:10em;} -#menu { - position: relative; - float: left; - width: 160px; - padding-top: 0px; - padding-bottom: 15px; - top:-18px; - left:10px; - z-index: 20; - background-color: #f90; - font-size : 70%; - border-radius: 0px 0px 15px 15px; -} - -.menutitle { - cursor:pointer; - padding: 3px 12px; - margin-left: 10px; - background-image: url('chapter.gif'); - background-repeat: no-repeat; - background-position: center left; - font-weight : bold; -} - -.menutitle.selected { - background-image: url('chapter_open.gif'); -} - -.menutitle:hover{text-decoration:underline;cursor: pointer;} - -#menu .menuitemgroup { - margin: 0px 0px 6px 8px; - padding: 0px; - font-weight : bold; } - -#menu .selectedmenuitemgroup{ - margin: 0px 0px 0px 8px; - padding: 0px; - font-weight : normal; - - } - -#menu .menuitem { - padding: 2px 0px 1px 13px; - background-image: url('page.gif'); - background-repeat: no-repeat; - background-position: center left; - font-weight : normal; - margin-left: 10px; -} - -#menu .selected { - font-style : normal; - margin-right: 10px; - -} -.menuitem .selected { - border-style: solid; - border-width: 1px; -} -#menu .menupageitemgroup { - padding: 3px 0px 4px 6px; - font-style : normal; - border-bottom: 1px solid ; - border-left: 1px solid ; - border-right: 1px solid ; - margin-right: 10px; -} -#menu .menupageitem { - font-style : normal; - font-weight : normal; - border-width: 0px; - font-size : 90%; -} -#menu .searchbox { - text-align: center; -} -#menu .searchbox form { - padding: 3px 3px; - margin: 0; -} -#menu .searchbox input { - font-size: 100%; -} - -#content { - padding: 20px 20px 20px 180px; - margin: 0; - font : small Verdana, Helvetica, sans-serif; - font-size : 80%; -} - -#content ul { - margin: 0; - padding: 0 25px; -} -#content li { - padding: 0 5px; -} -#feedback { - color: black; - background: #CFDCED; - text-align:center; - margin-top: 5px; -} -#feedback #feedbackto { - font-size: 90%; - color: black; -} -#footer { - clear: both; - position: relative; /* IE bugfix (http://www.dracos.co.uk/web/css/ie6floatbug/) */ - width: 100%; - background: #CFDCED; - border-top: solid 1px #4C6C8F; - color: black; -} -#footer .copyright { - position: relative; /* IE bugfix cont'd */ - padding: 5px; - margin: 0; - width: 60%; -} -#footer .lastmodified { - position: relative; /* IE bugfix cont'd */ - float: right; - width: 30%; - padding: 5px; - margin: 0; - text-align: right; -} -#footer a { color: white; } - -#footer #logos { - text-align: left; -} - - -/** - * Misc Styles - */ - -acronym { cursor: help; } -.boxed { background-color: #a5b6c6;} -.underlined_5 {border-bottom: solid 5px #4C6C8F;} -.underlined_10 {border-bottom: solid 10px #4C6C8F;} -/* ==================== snail trail ============================ */ - -.trail { - position: relative; /* IE bugfix cont'd */ - font-size: 70%; - text-align: right; - float: right; - margin: -10px 5px 0px 5px; - padding: 0; -} - -#motd-area { - position:relative; - float:right; - width: 35%; - background-color: #f0f0ff; - border: solid 1px #4C6C8F; - margin: 0px 0px 10px 10px; - padding: 5px; -} - -#minitoc-area { - border-top: solid 1px #4C6C8F; - border-bottom: solid 1px #4C6C8F; - margin: 15px 10% 5px 15px; - /* margin-bottom: 15px; - margin-left: 15px; - margin-right: 10%;*/ - padding-bottom: 7px; - padding-top: 5px; -} -.minitoc { - list-style-image: url('current.gif'); - font-weight: normal; -} - -.abstract{ - text-align:justify; - } - -li p { - margin: 0; - padding: 0; -} - -.pdflink { - position: relative; /* IE bugfix cont'd */ - float: right; - margin: 0px 5px; - padding: 0; -} -.pdflink br { - margin-top: -10px; - padding-left: 1px; -} -.pdflink a { - display: block; - font-size: 70%; - text-align: center; - margin: 0; - padding: 0; -} - -.pdflink img { - display: block; - height: 16px; - width: 16px; -} -.xmllink { - position: relative; /* IE bugfix cont'd */ - float: right; - margin: 0px 5px; - padding: 0; -} -.xmllink br { - margin-top: -10px; - padding-left: 1px; -} -.xmllink a { - display: block; - font-size: 70%; - text-align: center; - margin: 0; - padding: 0; -} - -.xmllink img { - display: block; - height: 16px; - width: 16px; -} -.podlink { - position: relative; /* IE bugfix cont'd */ - float: right; - margin: 0px 5px; - padding: 0; -} -.podlink br { - margin-top: -10px; - padding-left: 1px; -} -.podlink a { - display: block; - font-size: 70%; - text-align: center; - margin: 0; - padding: 0; -} - -.podlink img { - display: block; - height: 16px; - width: 16px; -} - -.printlink { - position: relative; /* IE bugfix cont'd */ - float: right; -} -.printlink br { - margin-top: -10px; - padding-left: 1px; -} -.printlink a { - display: block; - font-size: 70%; - text-align: center; - margin: 0; - padding: 0; -} -.printlink img { - display: block; - height: 16px; - width: 16px; -} - -p.instruction { - display: list-item; - list-style-image: url('../instruction_arrow.png'); - list-style-position: outside; - margin-left: 2em; -} \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md b/zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md deleted file mode 100644 index c87ce053e71..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperAdmin.md +++ /dev/null @@ -1,3078 +0,0 @@ - - -# ZooKeeper Administrator's Guide - -### A Guide to Deployment and Administration - -* [Deployment](#ch_deployment) - * [System Requirements](#sc_systemReq) - * [Supported Platforms](#sc_supportedPlatforms) - * [Required Software](#sc_requiredSoftware) - * [Clustered (Multi-Server) Setup](#sc_zkMulitServerSetup) - * [Single Server and Developer Setup](#sc_singleAndDevSetup) -* [Administration](#ch_administration) - * [Designing a ZooKeeper Deployment](#sc_designing) - * [Cross Machine Requirements](#sc_CrossMachineRequirements) - * [Single Machine Requirements](#Single+Machine+Requirements) - * [Provisioning](#sc_provisioning) - * [Things to Consider: ZooKeeper Strengths and Limitations](#sc_strengthsAndLimitations) - * [Administering](#sc_administering) - * [Maintenance](#sc_maintenance) - * [Ongoing Data Directory Cleanup](#Ongoing+Data+Directory+Cleanup) - * [Debug Log Cleanup (logback)](#Debug+Log+Cleanup+Logback) - * [Supervision](#sc_supervision) - * [Monitoring](#sc_monitoring) - * [Logging](#sc_logging) - * [Troubleshooting](#sc_troubleshooting) - * [Configuration Parameters](#sc_configuration) - * [Minimum Configuration](#sc_minimumConfiguration) - * [Advanced Configuration](#sc_advancedConfiguration) - * [Cluster Options](#sc_clusterOptions) - * [Encryption, Authentication, Authorization Options](#sc_authOptions) - * [TLS Cipher Suites](#sc_tls_cipher_suites) - * [Experimental Options/Features](#Experimental+Options%2FFeatures) - * [Unsafe Options](#Unsafe+Options) - * [Disabling data directory autocreation](#Disabling+data+directory+autocreation) - * [Enabling db existence validation](#sc_db_existence_validation) - * [Performance Tuning Options](#sc_performance_options) - * [AdminServer configuration](#sc_adminserver_config) - * [Communication using the Netty framework](#Communication+using+the+Netty+framework) - * [Quorum TLS](#Quorum+TLS) - * [Upgrading existing non-TLS cluster with no downtime](#Upgrading+existing+nonTLS+cluster) - * [ZooKeeper Commands](#sc_zkCommands) - * [The Four Letter Words](#sc_4lw) - * [The AdminServer](#sc_adminserver) - * [Data File Management](#sc_dataFileManagement) - * [The Data Directory](#The+Data+Directory) - * [The Log Directory](#The+Log+Directory) - * [File Management](#sc_filemanagement) - * [Recovery - TxnLogToolkit](#Recovery+-+TxnLogToolkit) - * [Things to Avoid](#sc_commonProblems) - * [Best Practices](#sc_bestPractices) - - - -## Deployment - -This section contains information about deploying Zookeeper and -covers these topics: - -* [System Requirements](#sc_systemReq) -* [Clustered (Multi-Server) Setup](#sc_zkMulitServerSetup) -* [Single Server and Developer Setup](#sc_singleAndDevSetup) - -The first two sections assume you are interested in installing -ZooKeeper in a production environment such as a datacenter. The final -section covers situations in which you are setting up ZooKeeper on a -limited basis - for evaluation, testing, or development - but not in a -production environment. - - - -### System Requirements - - - -#### Supported Platforms - -ZooKeeper consists of multiple components. Some components are -supported broadly, and other components are supported only on a smaller -set of platforms. - -* **Client** is the Java client - library, used by applications to connect to a ZooKeeper ensemble. -* **Server** is the Java server - that runs on the ZooKeeper ensemble nodes. -* **Native Client** is a client - implemented in C, similar to the Java client, used by applications - to connect to a ZooKeeper ensemble. -* **Contrib** refers to multiple - optional add-on components. - -The following matrix describes the level of support committed for -running each component on different operating system platforms. - -##### Support Matrix - -| Operating System | Client | Server | Native Client | Contrib | -|------------------|--------|--------|---------------|---------| -| GNU/Linux | Development and Production | Development and Production | Development and Production | Development and Production | -| Solaris | Development and Production | Development and Production | Not Supported | Not Supported | -| FreeBSD | Development and Production | Development and Production | Not Supported | Not Supported | -| Windows | Development and Production | Development and Production | Not Supported | Not Supported | -| Mac OS X | Development Only | Development Only | Not Supported | Not Supported | - -For any operating system not explicitly mentioned as supported in -the matrix, components may or may not work. The ZooKeeper community -will fix obvious bugs that are reported for other platforms, but there -is no full support. - - - -#### Required Software - -ZooKeeper runs in Java, release 1.8 or greater -(JDK 8 LTS, JDK 11 LTS, JDK 12 - Java 9 and 10 are not supported). -It runs as an _ensemble_ of ZooKeeper servers. Three -ZooKeeper servers is the minimum recommended size for an -ensemble, and we also recommend that they run on separate -machines. At Yahoo!, ZooKeeper is usually deployed on -dedicated RHEL boxes, with dual-core processors, 2GB of RAM, -and 80GB IDE hard drives. - - - -### Clustered (Multi-Server) Setup - -For reliable ZooKeeper service, you should deploy ZooKeeper in a -cluster known as an _ensemble_. As long as a majority -of the ensemble are up, the service will be available. Because Zookeeper -requires a majority, it is best to use an -odd number of machines. For example, with four machines ZooKeeper can -only handle the failure of a single machine; if two machines fail, the -remaining two machines do not constitute a majority. However, with five -machines ZooKeeper can handle the failure of two machines. - -###### Note ->As mentioned in the -[ZooKeeper Getting Started Guide](zookeeperStarted.html) -, a minimum of three servers are required for a fault tolerant -clustered setup, and it is strongly recommended that you have an -odd number of servers. - ->Usually three servers is more than enough for a production -install, but for maximum reliability during maintenance, you may -wish to install five servers. With three servers, if you perform -maintenance on one of them, you are vulnerable to a failure on one -of the other two servers during that maintenance. If you have five -of them running, you can take one down for maintenance, and know -that you're still OK if one of the other four suddenly fails. - ->Your redundancy considerations should include all aspects of -your environment. If you have three ZooKeeper servers, but their -network cables are all plugged into the same network switch, then -the failure of that switch will take down your entire ensemble. - -Here are the steps to set a server that will be part of an -ensemble. These steps should be performed on every host in the -ensemble: - -1. Install the Java JDK. You can use the native packaging system - for your system, or download the JDK from: - [http://java.sun.com/javase/downloads/index.jsp](http://java.sun.com/javase/downloads/index.jsp) - -2. Set the Java heap size. This is very important to avoid - swapping, which will seriously degrade ZooKeeper performance. To - determine the correct value, use load tests, and make sure you are - well below the usage limit that would cause you to swap. Be - conservative - use a maximum heap size of 3GB for a 4GB - machine. - -3. Install the ZooKeeper Server Package. It can be downloaded - from: - [http://zookeeper.apache.org/releases.html](http://zookeeper.apache.org/releases.html) - -4. Create a configuration file. This file can be called anything. - Use the following settings as a starting point: - - tickTime=2000 - dataDir=/var/lib/zookeeper/ - clientPort=2181 - initLimit=5 - syncLimit=2 - server.1=zoo1:2888:3888 - server.2=zoo2:2888:3888 - server.3=zoo3:2888:3888 - - You can find the meanings of these and other configuration - settings in the section [Configuration Parameters](#sc_configuration). A word - thought about a few here: - Every machine that is part of the ZooKeeper ensemble should know - about every other machine in the ensemble. You accomplish this with - the series of lines of the form **server.id=host:port:port**. - (The parameters **host** and **port** are straightforward, for each server - you need to specify first a Quorum port then a dedicated port for ZooKeeper leader - election). Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#id_multi_address) - for each ZooKeeper server instance (this can increase availability when multiple physical - network interfaces can be used parallel in the cluster). - You attribute the - server id to each machine by creating a file named - *myid*, one for each server, which resides in - that server's data directory, as specified by the configuration file - parameter **dataDir**. - -5. The myid file - consists of a single line containing only the text of that machine's - id. So *myid* of server 1 would contain the text - "1" and nothing else. The id must be unique within the - ensemble and should have a value between 1 and 255. - **IMPORTANT:** if you enable extended features such - as TTL Nodes (see below) the id must be between 1 - and 254 due to internal limitations. - -6. Create an initialization marker file *initialize* - in the same directory as *myid*. This file indicates - that an empty data directory is expected. When present, an empty database - is created and the marker file deleted. When not present, an empty data - directory will mean this peer will not have voting rights and it will not - populate the data directory until it communicates with an active leader. - Intended use is to only create this file when bringing up a new - ensemble. - -7. If your configuration file is set up, you can start a - ZooKeeper server: - - $ java -cp zookeeper.jar:lib/*:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.conf - - QuorumPeerMain starts a ZooKeeper server, - [JMX](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) - management beans are also registered which allows - management through a JMX management console. - The [ZooKeeper JMX - document](zookeeperJMX.html) contains details on managing ZooKeeper with JMX. - See the script _bin/zkServer.sh_, - which is included in the release, for an example - of starting server instances. -8. Test your deployment by connecting to the hosts: - In Java, you can run the following command to execute - simple operations: - - $ bin/zkCli.sh -server 127.0.0.1:2181 - - - -### Single Server and Developer Setup - -If you want to set up ZooKeeper for development purposes, you will -probably want to set up a single server instance of ZooKeeper, and then -install either the Java or C client-side libraries and bindings on your -development machine. - -The steps to setting up a single server instance are the similar -to the above, except the configuration file is simpler. You can find the -complete instructions in the [Installing and -Running ZooKeeper in Single Server Mode](zookeeperStarted.html#sc_InstallingSingleMode) section of the [ZooKeeper Getting Started -Guide](zookeeperStarted.html). - -For information on installing the client side libraries, refer to -the [Bindings](zookeeperProgrammers.html#ch_bindings) -section of the [ZooKeeper -Programmer's Guide](zookeeperProgrammers.html). - - - -## Administration - -This section contains information about running and maintaining -ZooKeeper and covers these topics: - -* [Designing a ZooKeeper Deployment](#sc_designing) -* [Provisioning](#sc_provisioning) -* [Things to Consider: ZooKeeper Strengths and Limitations](#sc_strengthsAndLimitations) -* [Administering](#sc_administering) -* [Maintenance](#sc_maintenance) -* [Supervision](#sc_supervision) -* [Monitoring](#sc_monitoring) -* [Logging](#sc_logging) -* [Troubleshooting](#sc_troubleshooting) -* [Configuration Parameters](#sc_configuration) -* [ZooKeeper Commands](#sc_zkCommands) -* [Data File Management](#sc_dataFileManagement) -* [Things to Avoid](#sc_commonProblems) -* [Best Practices](#sc_bestPractices) - - - -### Designing a ZooKeeper Deployment - -The reliability of ZooKeeper rests on two basic assumptions. - -1. Only a minority of servers in a deployment - will fail. _Failure_ in this context - means a machine crash, or some error in the network that - partitions a server off from the majority. -1. Deployed machines operate correctly. To - operate correctly means to execute code correctly, to have - clocks that work properly, and to have storage and network - components that perform consistently. - -The sections below contain considerations for ZooKeeper -administrators to maximize the probability for these assumptions -to hold true. Some of these are cross-machines considerations, -and others are things you should consider for each and every -machine in your deployment. - - - -#### Cross Machine Requirements - -For the ZooKeeper service to be active, there must be a -majority of non-failing machines that can communicate with -each other. For a ZooKeeper ensemble with N servers, -if N is odd, the ensemble is able to tolerate up to N/2 -server failures without losing any znode data; -if N is even, the ensemble is able to tolerate up to N/2-1 -server failures. - -For example, if we have a ZooKeeper ensemble with 3 servers, -the ensemble is able to tolerate up to 1 (3/2) server failures. -If we have a ZooKeeper ensemble with 5 servers, -the ensemble is able to tolerate up to 2 (5/2) server failures. -If the ZooKeeper ensemble with 6 servers, the ensemble -is also able to tolerate up to 2 (6/2-1) server failures -without losing data and prevent the "brain split" issue. - -ZooKeeper ensemble is usually has odd number of servers. -This is because with the even number of servers, -the capacity of failure tolerance is the same as -the ensemble with one less server -(2 failures for both 5-node ensemble and 6-node ensemble), -but the ensemble has to maintain extra connections and -data transfers for one more server. - -To achieve the highest probability of tolerating a failure -you should try to make machine failures independent. For -example, if most of the machines share the same switch, -failure of that switch could cause a correlated failure and -bring down the service. The same holds true of shared power -circuits, cooling systems, etc. - - - -#### Single Machine Requirements - -If ZooKeeper has to contend with other applications for -access to resources like storage media, CPU, network, or -memory, its performance will suffer markedly. ZooKeeper has -strong durability guarantees, which means it uses storage -media to log changes before the operation responsible for the -change is allowed to complete. You should be aware of this -dependency then, and take great care if you want to ensure -that ZooKeeper operations aren’t held up by your media. Here -are some things you can do to minimize that sort of -degradation: - -* ZooKeeper's transaction log must be on a dedicated - device. (A dedicated partition is not enough.) ZooKeeper - writes the log sequentially, without seeking Sharing your - log device with other processes can cause seeks and - contention, which in turn can cause multi-second - delays. -* Do not put ZooKeeper in a situation that can cause a - swap. In order for ZooKeeper to function with any sort of - timeliness, it simply cannot be allowed to swap. - Therefore, make certain that the maximum heap size given - to ZooKeeper is not bigger than the amount of real memory - available to ZooKeeper. For more on this, see - [Things to Avoid](#sc_commonProblems) - below. - - - -### Provisioning - - - -### Things to Consider: ZooKeeper Strengths and Limitations - - - -### Administering - - - -### Maintenance - -Little long term maintenance is required for a ZooKeeper -cluster however you must be aware of the following: - - - -#### Ongoing Data Directory Cleanup - -The ZooKeeper [Data -Directory](#var_datadir) contains files which are a persistent copy -of the znodes stored by a particular serving ensemble. These -are the snapshot and transactional log files. As changes are -made to the znodes these changes are appended to a -transaction log. Occasionally, when a log grows large, a -snapshot of the current state of all znodes will be written -to the filesystem and a new transaction log file is created -for future transactions. During snapshotting, ZooKeeper may -continue appending incoming transactions to the old log file. -Therefore, some transactions which are newer than a snapshot -may be found in the last transaction log preceding the -snapshot. - -A ZooKeeper server **will not remove -old snapshots and log files** when using the default -configuration (see autopurge below), this is the -responsibility of the operator. Every serving environment is -different and therefore the requirements of managing these -files may differ from install to install (backup for example). - -The PurgeTxnLog utility implements a simple retention -policy that administrators can use. The [API docs](index.html) contains details on -calling conventions (arguments, etc...). - -In the following example the last count snapshots and -their corresponding logs are retained and the others are -deleted. The value of should typically be -greater than 3 (although not required, this provides 3 backups -in the unlikely event a recent log has become corrupted). This -can be run as a cron job on the ZooKeeper server machines to -clean up the logs daily. - - CLASSPATH='lib/*:conf' java org.apache.zookeeper.server.PurgeTxnLog -n - - -Automatic purging of the snapshots and corresponding -transaction logs was introduced in version 3.4.0 and can be -enabled via the following configuration parameters **autopurge.snapRetainCount** and **autopurge.purgeInterval**. For more on -this, see [Advanced Configuration](#sc_advancedConfiguration) -below. - - - -#### Debug Log Cleanup (logback) - -See the section on [logging](#sc_logging) in this document. It is -expected that you will setup a rolling file appender using the -in-built logback feature. The sample configuration file in the -release tar's `conf/logback.xml` provides an example of -this. - - - -### Supervision - -You will want to have a supervisory process that manages -each of your ZooKeeper server processes (JVM). The ZK server is -designed to be "fail fast" meaning that it will shut down -(process exit) if an error occurs that it cannot recover -from. As a ZooKeeper serving cluster is highly reliable, this -means that while the server may go down the cluster as a whole -is still active and serving requests. Additionally, as the -cluster is "self healing" the failed server once restarted will -automatically rejoin the ensemble w/o any manual -interaction. - -Having a supervisory process such as [daemontools](http://cr.yp.to/daemontools.html) or -[SMF](http://en.wikipedia.org/wiki/Service\_Management\_Facility) -(other options for supervisory process are also available, it's -up to you which one you would like to use, these are just two -examples) managing your ZooKeeper server ensures that if the -process does exit abnormally it will automatically be restarted -and will quickly rejoin the cluster. - -It is also recommended to configure the ZooKeeper server process to -terminate and dump its heap if an OutOfMemoryError** occurs. This is achieved -by launching the JVM with the following arguments on Linux and Windows -respectively. The *zkServer.sh* and -*zkServer.cmd* scripts that ship with ZooKeeper set -these options. - - -XX:+HeapDumpOnOutOfMemoryError -XX:OnOutOfMemoryError='kill -9 %p' - - "-XX:+HeapDumpOnOutOfMemoryError" "-XX:OnOutOfMemoryError=cmd /c taskkill /pid %%%%p /t /f" - - - -### Monitoring - -The ZooKeeper service can be monitored in one of three primary ways: - -* the command port through the use of [4 letter words](#sc_zkCommands) -* with [JMX](zookeeperJMX.html) -* using the [`zkServer.sh status` command](zookeeperTools.html#zkServer) - - - -### Logging - -ZooKeeper uses **[SLF4J](http://www.slf4j.org)** -version 1.7 as its logging infrastructure. By default ZooKeeper is shipped with -**[LOGBack](http://logback.qos.ch/)** as the logging backend, but you can use -any other supported logging framework of your choice. - -The ZooKeeper default *logback.xml* -file resides in the *conf* directory. Logback requires that -*logback.xml* either be in the working directory -(the directory from which ZooKeeper is run) or be accessible from the classpath. - -For more information about SLF4J, see -[its manual](http://www.slf4j.org/manual.html). - -For more information about Logback, see -[Logback website](http://logback.qos.ch/). - - - -### Troubleshooting - -* *Server not coming up because of file corruption* : - A server might not be able to read its database and fail to come up because of - some file corruption in the transaction logs of the ZooKeeper server. You will - see some IOException on loading ZooKeeper database. In such a case, - make sure all the other servers in your ensemble are up and working. Use "stat" - command on the command port to see if they are in good health. After you have verified that - all the other servers of the ensemble are up, you can go ahead and clean the database - of the corrupt server. Delete all the files in datadir/version-2 and datalogdir/version-2/. - Restart the server. - - - -### Configuration Parameters - -ZooKeeper's behavior is governed by the ZooKeeper configuration -file. This file is designed so that the exact same file can be used by -all the servers that make up a ZooKeeper server assuming the disk -layouts are the same. If servers use different configuration files, care -must be taken to ensure that the list of servers in all of the different -configuration files match. - -###### Note ->In 3.5.0 and later, some of these parameters should be placed in -a dynamic configuration file. If they are placed in the static -configuration file, ZooKeeper will automatically move them over to the -dynamic configuration file. See [Dynamic Reconfiguration](zookeeperReconfig.html) for more information. - - - -#### Minimum Configuration - -Here are the minimum configuration keywords that must be defined -in the configuration file: - -* *clientPort* : - the port to listen for client connections; that is, the - port that clients attempt to connect to. - -* *secureClientPort* : - the port to listen on for secure client connections using SSL. - **clientPort** specifies - the port for plaintext connections while **secureClientPort** specifies the port for SSL - connections. Specifying both enables mixed-mode while omitting - either will disable that mode. - Note that SSL feature will be enabled when user plugs-in - zookeeper.serverCnxnFactory, zookeeper.clientCnxnSocket as Netty. - -* *observerMasterPort* : - the port to listen for observer connections; that is, the - port that observers attempt to connect to. - if the property is set then the server will host observer connections - when in follower mode in addition to when in leader mode and correspondingly - attempt to connect to any voting peer when in observer mode. - -* *dataDir* : - the location where ZooKeeper will store the in-memory - database snapshots and, unless specified otherwise, the - transaction log of updates to the database. - ###### Note - >Be careful where you put the transaction log. A - dedicated transaction log device is key to consistent good - performance. Putting the log on a busy device will adversely - affect performance. - -* *tickTime* : - the length of a single tick, which is the basic time unit - used by ZooKeeper, as measured in milliseconds. It is used to - regulate heartbeats, and timeouts. For example, the minimum - session timeout will be two ticks. - - - -#### Advanced Configuration - -The configuration settings in the section are optional. You can -use them to further fine tune the behaviour of your ZooKeeper servers. -Some can also be set using Java system properties, generally of the -form _zookeeper.keyword_. The exact system -property, when available, is noted below. - -* *dataLogDir* : - (No Java system property) - This option will direct the machine to write the - transaction log to the **dataLogDir** rather than the **dataDir**. This allows a dedicated log - device to be used, and helps avoid competition between logging - and snapshots. - ###### Note - >Having a dedicated log device has a large impact on - throughput and stable latencies. It is highly recommended dedicating a log device and set **dataLogDir** to point to a directory on - that device, and then make sure to point **dataDir** to a directory - _not_ residing on that device. - -* *globalOutstandingLimit* : - (Java system property: **zookeeper.globalOutstandingLimit.**) - Clients can submit requests faster than ZooKeeper can - process them, especially if there are a lot of clients. To - prevent ZooKeeper from running out of memory due to queued - requests, ZooKeeper will throttle clients so that there are no - more than globalOutstandingLimit outstanding requests across - entire ensemble, equally divided. The default limit is 1,000 - and, for example, with 3 members each of them will have - 1000 / 2 = 500 individual limit. - -* *preAllocSize* : - (Java system property: **zookeeper.preAllocSize**) - To avoid seeks ZooKeeper allocates space in the - transaction log file in blocks of preAllocSize kilobytes. The - default block size is 64M. One reason for changing the size of - the blocks is to reduce the block size if snapshots are taken - more often. (Also, see **snapCount** and **snapSizeLimitInKb**). - -* *snapCount* : - (Java system property: **zookeeper.snapCount**) - ZooKeeper records its transactions using snapshots and - a transaction log (think write-ahead log). The number of - transactions recorded in the transaction log before a snapshot - can be taken (and the transaction log rolled) is determined - by snapCount. In order to prevent all of the machines in the quorum - from taking a snapshot at the same time, each ZooKeeper server - will take a snapshot when the number of transactions in the transaction log - reaches a runtime generated random value in the \[snapCount/2+1, snapCount] - range. The default snapCount is 100,000. - -* *commitLogCount* * : - (Java system property: **zookeeper.commitLogCount**) - Zookeeper maintains an in-memory list of last committed requests for fast synchronization with - followers when the followers are not too behind. This improves sync performance in case when your - snapshots are large (>100,000). The default value is 500 which is the recommended minimum. - -* *snapSizeLimitInKb* : - (Java system property: **zookeeper.snapSizeLimitInKb**) - ZooKeeper records its transactions using snapshots and - a transaction log (think write-ahead log). The total size in bytes allowed - in the set of transactions recorded in the transaction log before a snapshot - can be taken (and the transaction log rolled) is determined - by snapSize. In order to prevent all of the machines in the quorum - from taking a snapshot at the same time, each ZooKeeper server - will take a snapshot when the size in bytes of the set of transactions in the - transaction log reaches a runtime generated random value in the \[snapSize/2+1, snapSize] - range. Each file system has a minimum standard file size and in order - to for valid functioning of this feature, the number chosen must be larger - than that value. The default snapSizeLimitInKb is 4,194,304 (4GB). - A non-positive value will disable the feature. - -* *txnLogSizeLimitInKb* : - (Java system property: **zookeeper.txnLogSizeLimitInKb**) - Zookeeper transaction log file can also be controlled more - directly using txnLogSizeLimitInKb. Larger txn logs can lead to - slower follower syncs when sync is done using transaction log. - This is because leader has to scan through the appropriate log - file on disk to find the transaction to start sync from. - This feature is turned off by default and snapCount and snapSizeLimitInKb are the - only values that limit transaction log size. When enabled - Zookeeper will roll the log when any of the limits is hit. - Please note that actual log size can exceed this value by the size - of the serialized transaction. On the other hand, if this value is - set too close to (or smaller than) **preAllocSize**, - it can cause Zookeeper to roll the log for every transaction. While - this is not a correctness issue, this may cause severely degraded - performance. To avoid this and to get most out of this feature, it is - recommended to set the value to N * **preAllocSize** - where N >= 2. - -* *maxCnxns* : - (Java system property: **zookeeper.maxCnxns**) - Limits the total number of concurrent connections that can be made to a - zookeeper server (per client Port of each server ). This is used to prevent certain - classes of DoS attacks. The default is 0 and setting it to 0 entirely removes - the limit on total number of concurrent connections. Accounting for the - number of connections for serverCnxnFactory and a secureServerCnxnFactory is done - separately, so a peer is allowed to host up to 2*maxCnxns provided they are of appropriate types. - -* *maxClientCnxns* : - (No Java system property) - Limits the number of concurrent connections (at the socket - level) that a single client, identified by IP address, may make - to a single member of the ZooKeeper ensemble. This is used to - prevent certain classes of DoS attacks, including file - descriptor exhaustion. The default is 60. Setting this to 0 - entirely removes the limit on concurrent connections. - -* *clientPortAddress* : - **New in 3.3.0:** the - address (ipv4, ipv6 or hostname) to listen for client - connections; that is, the address that clients attempt - to connect to. This is optional, by default we bind in - such a way that any connection to the **clientPort** for any - address/interface/nic on the server will be - accepted. - -* *minSessionTimeout* : - (No Java system property) - **New in 3.3.0:** the - minimum session timeout in milliseconds that the server - will allow the client to negotiate. Defaults to 2 times - the **tickTime**. - -* *maxSessionTimeout* : - (No Java system property) - **New in 3.3.0:** the - maximum session timeout in milliseconds that the server - will allow the client to negotiate. Defaults to 20 times - the **tickTime**. - -* *fsync.warningthresholdms* : - (Java system property: **zookeeper.fsync.warningthresholdms**) - **New in 3.3.4:** A - warning message will be output to the log whenever an - fsync in the Transactional Log (WAL) takes longer than - this value. The values is specified in milliseconds and - defaults to 1000. This value can only be set as a - system property. - -* *maxResponseCacheSize* : - (Java system property: **zookeeper.maxResponseCacheSize**) - When set to a positive integer, it determines the size - of the cache that stores the serialized form of recently - read records. Helps save the serialization cost on - popular znodes. The metrics **response_packet_cache_hits** - and **response_packet_cache_misses** can be used to tune - this value to a given workload. The feature is turned on - by default with a value of 400, set to 0 or a negative - integer to turn the feature off. - -* *maxGetChildrenResponseCacheSize* : - (Java system property: **zookeeper.maxGetChildrenResponseCacheSize**) - **New in 3.6.0:** - Similar to **maxResponseCacheSize**, but applies to get children - requests. The metrics **response_packet_get_children_cache_hits** - and **response_packet_get_children_cache_misses** can be used to tune - this value to a given workload. The feature is turned on - by default with a value of 400, set to 0 or a negative - integer to turn the feature off. - -* *autopurge.snapRetainCount* : - (No Java system property) - **New in 3.4.0:** - When enabled, ZooKeeper auto purge feature retains - the **autopurge.snapRetainCount** most - recent snapshots and the corresponding transaction logs in the - **dataDir** and **dataLogDir** respectively and deletes the rest. - Defaults to 3. Minimum value is 3. - -* *autopurge.purgeInterval* : - (No Java system property) - **New in 3.4.0:** The - time interval in hours for which the purge task has to - be triggered. Set to a positive integer (1 and above) - to enable the auto purging. Defaults to 0. - **Suffix support added in 3.10.0:** The interval is specified as an integer with an optional suffix to indicate the time unit. - Supported suffixes are: `ms` for milliseconds, `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. - For example, "10m" represents 10 minutes, and "5h" represents 5 hours. - If no suffix is provided, the default unit is hours. - -* *syncEnabled* : - (Java system property: **zookeeper.observer.syncEnabled**) - **New in 3.4.6, 3.5.0:** - The observers now log transaction and write snapshot to disk - by default like the participants. This reduces the recovery time - of the observers on restart. Set to "false" to disable this - feature. Default is "true" - -* *extendedTypesEnabled* : - (Java system property only: **zookeeper.extendedTypesEnabled**) - **New in 3.5.4, 3.6.0:** Define to `true` to enable - extended features such as the creation of [TTL Nodes](zookeeperProgrammers.html#TTL+Nodes). - They are disabled by default. IMPORTANT: when enabled server IDs must - be less than 255 due to internal limitations. - -* *emulate353TTLNodes* : - (Java system property only:**zookeeper.emulate353TTLNodes**). - **New in 3.5.4, 3.6.0:** Due to [ZOOKEEPER-2901] - (https://issues.apache.org/jira/browse/ZOOKEEPER-2901) TTL nodes - created in version 3.5.3 are not supported in 3.5.4/3.6.0. However, a workaround is provided via the - zookeeper.emulate353TTLNodes system property. If you used TTL nodes in ZooKeeper 3.5.3 and need to maintain - compatibility set **zookeeper.emulate353TTLNodes** to `true` in addition to - **zookeeper.extendedTypesEnabled**. NOTE: due to the bug, server IDs - must be 127 or less. Additionally, the maximum support TTL value is `1099511627775` which is smaller - than what was allowed in 3.5.3 (`1152921504606846975`) - -* *watchManagerName* : - (Java system property only: **zookeeper.watchManagerName**) - **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - New watcher manager WatchManagerOptimized is added to optimize the memory overhead in heavy watch use cases. This - config is used to define which watcher manager to be used. Currently, we only support WatchManager and - WatchManagerOptimized. - -* *watcherCleanThreadsNum* : - (Java system property only: **zookeeper.watcherCleanThreadsNum**) - **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, this config is used to decide how - many thread is used in the WatcherCleaner. More thread usually means larger clean up throughput. The - default value is 2, which is good enough even for heavy and continuous session closing/recreating cases. - -* *watcherCleanThreshold* : - (Java system property only: **zookeeper.watcherCleanThreshold**) - **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, the cleanup process is relatively - heavy, batch processing will reduce the cost and improve the performance. This setting is used to decide - the batch size. The default one is 1000, we don't need to change it if there is no memory or clean up - speed issue. - -* *watcherCleanIntervalInSeconds* : - (Java system property only:**zookeeper.watcherCleanIntervalInSeconds**) - **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, the cleanup process is relatively - heavy, batch processing will reduce the cost and improve the performance. Besides watcherCleanThreshold, - this setting is used to clean up the dead watchers after certain time even the dead watchers are not larger - than watcherCleanThreshold, so that we won't leave the dead watchers there for too long. The default setting - is 10 minutes, which usually don't need to be changed. - -* *maxInProcessingDeadWatchers* : - (Java system property only: **zookeeper.maxInProcessingDeadWatchers**) - **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - This is used to control how many backlog can we have in the WatcherCleaner, when it reaches this number, it will - slow down adding the dead watcher to WatcherCleaner, which will in turn slow down adding and closing - watchers, so that we can avoid OOM issue. By default there is no limit, you can set it to values like - watcherCleanThreshold * 1000. - -* *bitHashCacheSize* : - (Java system property only: **zookeeper.bitHashCacheSize**) - **New 3.6.0**: Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) - This is the setting used to decide the HashSet cache size in the BitHashSet implementation. Without HashSet, we - need to use O(N) time to get the elements, N is the bit numbers in elementBits. But we need to - keep the size small to make sure it doesn't cost too much in memory, there is a trade off between memory - and time complexity. The default value is 10, which seems a relatively reasonable cache size. - -* *fastleader.minNotificationInterval* : - (Java system property: **zookeeper.fastleader.minNotificationInterval**) - Lower bound for length of time between two consecutive notification - checks on the leader election. This interval determines how long a - peer waits to check the set of election votes and effects how - quickly an election can resolve. The interval follows a backoff - strategy from the configured minimum (this) and the configured maximum - (fastleader.maxNotificationInterval) for long elections. - -* *fastleader.maxNotificationInterval* : - (Java system property: **zookeeper.fastleader.maxNotificationInterval**) - Upper bound for length of time between two consecutive notification - checks on the leader election. This interval determines how long a - peer waits to check the set of election votes and effects how - quickly an election can resolve. The interval follows a backoff - strategy from the configured minimum (fastleader.minNotificationInterval) - and the configured maximum (this) for long elections. - -* *connectionMaxTokens* : - (Java system property: **zookeeper.connection_throttle_tokens**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the maximum number of tokens in the token-bucket. - When set to 0, throttling is disabled. Default is 0. - -* *connectionTokenFillTime* : - (Java system property: **zookeeper.connection_throttle_fill_time**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the interval in milliseconds when the token bucket is re-filled with - *connectionTokenFillCount* tokens. Default is 1. - -* *connectionTokenFillCount* : - (Java system property: **zookeeper.connection_throttle_fill_count**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the number of tokens to add to the token bucket every - *connectionTokenFillTime* milliseconds. Default is 1. - -* *connectionFreezeTime* : - (Java system property: **zookeeper.connection_throttle_freeze_time**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the interval in milliseconds when the dropping - probability is adjusted. When set to -1, probabilistic dropping is disabled. - Default is -1. - -* *connectionDropIncrease* : - (Java system property: **zookeeper.connection_throttle_drop_increase**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the dropping probability to increase. The throttler - checks every *connectionFreezeTime* milliseconds and if the token bucket is - empty, the dropping probability will be increased by *connectionDropIncrease*. - The default is 0.02. - -* *connectionDropDecrease* : - (Java system property: **zookeeper.connection_throttle_drop_decrease**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. - This parameter defines the dropping probability to decrease. The throttler - checks every *connectionFreezeTime* milliseconds and if the token bucket has - more tokens than a threshold, the dropping probability will be decreased by - *connectionDropDecrease*. The threshold is *connectionMaxTokens* \* - *connectionDecreaseRatio*. The default is 0.002. - -* *connectionDecreaseRatio* : - (Java system property: **zookeeper.connection_throttle_decrease_ratio**) - **New in 3.6.0:** - This is one of the parameters to tune the server-side connection throttler, - which is a token-based rate limiting mechanism with optional probabilistic - dropping. This parameter defines the threshold to decrease the dropping - probability. The default is 0. - -* *zookeeper.connection_throttle_weight_enabled* : - (Java system property only) - **New in 3.6.0:** - Whether to consider connection weights when throttling. Only useful when connection throttle is enabled, that is, connectionMaxTokens is larger than 0. The default is false. - -* *zookeeper.connection_throttle_global_session_weight* : - (Java system property only) - **New in 3.6.0:** - The weight of a global session. It is the number of tokens required for a global session request to get through the connection throttler. It has to be a positive integer no smaller than the weight of a local session. The default is 3. - -* *zookeeper.connection_throttle_local_session_weight* : - (Java system property only) - **New in 3.6.0:** - The weight of a local session. It is the number of tokens required for a local session request to get through the connection throttler. It has to be a positive integer no larger than the weight of a global session or a renew session. The default is 1. - -* *zookeeper.connection_throttle_renew_session_weight* : - (Java system property only) - **New in 3.6.0:** - The weight of renewing a session. It is also the number of tokens required for a reconnect request to get through the throttler. It has to be a positive integer no smaller than the weight of a local session. The default is 2. - - -* *clientPortListenBacklog* : - (No Java system property) - **New in 3.4.14, 3.5.5, 3.6.0:** - The socket backlog length for the ZooKeeper server socket. This controls - the number of requests that will be queued server-side to be processed - by the ZooKeeper server. Connections that exceed this length will receive - a network timeout (30s) which may cause ZooKeeper session expiry issues. - By default, this value is unset (`-1`) which, on Linux, uses a backlog of - `50`. This value must be a positive number. - -* *serverCnxnFactory* : - (Java system property: **zookeeper.serverCnxnFactory**) - Specifies ServerCnxnFactory implementation. - This should be set to `NettyServerCnxnFactory` in order to use TLS based server communication. - Default is `NIOServerCnxnFactory`. - -* *flushDelay* : - (Java system property: **zookeeper.flushDelay**) - Time in milliseconds to delay the flush of the commit log. - Does not affect the limit defined by *maxBatchSize*. - Disabled by default (with value 0). Ensembles with high write rates - may see throughput improved with a value of 10-20 ms. - -* *maxWriteQueuePollTime* : - (Java system property: **zookeeper.maxWriteQueuePollTime**) - If *flushDelay* is enabled, this determines the amount of time in milliseconds - to wait before flushing when no new requests are being queued. - Set to *flushDelay*/3 by default (implicitly disabled by default). - -* *maxBatchSize* : - (Java system property: **zookeeper.maxBatchSize**) - The number of transactions allowed in the server before a flush of the - commit log is triggered. - Does not affect the limit defined by *flushDelay*. - Default is 1000. - -* *enforceQuota* : - (Java system property: **zookeeper.enforceQuota**) - **New in 3.7.0:** - Enforce the quota check. When enabled and the client exceeds the total bytes or children count hard quota under a znode, the server will reject the request and reply the client a `QuotaExceededException` by force. - The default value is: false. Exploring [quota feature](http://zookeeper.apache.org/doc/current/zookeeperQuotas.html) for more details. - -* *requestThrottleLimit* : - (Java system property: **zookeeper.request_throttle_max_requests**) - **New in 3.6.0:** - The total number of outstanding requests allowed before the RequestThrottler starts stalling. When set to 0, throttling is disabled. The default is 0. - -* *requestThrottleStallTime* : - (Java system property: **zookeeper.request_throttle_stall_time**) - **New in 3.6.0:** - The maximum time (in milliseconds) for which a thread may wait to be notified that it may proceed processing a request. The default is 100. - -* *requestThrottleDropStale* : - (Java system property: **request_throttle_drop_stale**) - **New in 3.6.0:** - When enabled, the throttler will drop stale requests rather than issue them to the request pipeline. A stale request is a request sent by a connection that is now closed, and/or a request that will have a request latency higher than the sessionTimeout. The default is true. - -* *requestStaleLatencyCheck* : - (Java system property: **zookeeper.request_stale_latency_check**) - **New in 3.6.0:** - When enabled, a request is considered stale if the request latency is higher than its associated session timeout. Disabled by default. - -* *requestStaleConnectionCheck* : - (Java system property: **zookeeper.request_stale_connection_check**) - **New in 3.6.0:** - When enabled, a request is considered stale if the request's connection has closed. Enabled by default. - -* *zookeeper.request_throttler.shutdownTimeout* : - (Java system property only) - **New in 3.6.0:** - The time (in milliseconds) the RequestThrottler waits for the request queue to drain during shutdown before it shuts down forcefully. The default is 10000. - -* *advancedFlowControlEnabled* : - (Java system property: **zookeeper.netty.advancedFlowControl.enabled**) - Using accurate flow control in netty based on the status of ZooKeeper - pipeline to avoid direct buffer OOM. It will disable the AUTO_READ in - Netty. - -* *enableEagerACLCheck* : - (Java system property only: **zookeeper.enableEagerACLCheck**) - When set to "true", enables eager ACL check on write requests on each local - server before sending the requests to quorum. Default is "false". - -* *maxConcurrentSnapSyncs* : - (Java system property: **zookeeper.leader.maxConcurrentSnapSyncs**) - The maximum number of snap syncs a leader or a follower can serve at the same - time. The default is 10. - -* *maxConcurrentDiffSyncs* : - (Java system property: **zookeeper.leader.maxConcurrentDiffSyncs**) - The maximum number of diff syncs a leader or a follower can serve at the same - time. The default is 100. - -* *digest.enabled* : - (Java system property only: **zookeeper.digest.enabled**) - **New in 3.6.0:** - The digest feature is added to detect the data inconsistency inside - ZooKeeper when loading database from disk, catching up and following - leader, its doing incrementally hash check for the DataTree based on - the adHash paper mentioned in - - https://cseweb.ucsd.edu/~daniele/papers/IncHash.pdf - - The idea is simple, the hash value of DataTree will be updated incrementally - based on the changes to the set of data. When the leader is preparing the txn, - it will pre-calculate the hash of the tree based on the changes happened with - formula: - - current_hash = current_hash + hash(new node data) - hash(old node data) - - If it’s creating a new node, the hash(old node data) will be 0, and if it’s a - delete node op, the hash(new node data) will be 0. - - This hash will be associated with each txn to represent the expected hash value - after applying the txn to the data tree, it will be sent to followers with - original proposals. Learner will compare the actual hash value with the one in - the txn after applying the txn to the data tree, and report mismatch if it’s not - the same. - - These digest value will also be persisted with each txn and snapshot on the disk, - so when servers restarted and load data from disk, it will compare and see if - there is hash mismatch, which will help detect data loss issue on disk. - - For the actual hash function, we’re using CRC internally, it’s not a collisionless - hash function, but it’s more efficient compared to collisionless hash, and the - collision possibility is really really rare and can already meet our needs here. - - This feature is backward and forward compatible, so it can safely roll upgrade, - downgrade, enabled and later disabled without any compatible issue. Here are the - scenarios have been covered and tested: - - 1. When leader runs with new code while follower runs with old one, the digest will - be appended to the end of each txn, follower will only read header and txn data, - digest value in the txn will be ignored. It won't affect the follower reads and - processes the next txn. - 2. When leader runs with old code while follower runs with new one, the digest won't - be sent with txn, when follower tries to read the digest, it will throw EOF which - is caught and handled gracefully with digest value set to null. - 3. When loading old snapshot with new code, it will throw IOException when trying to - read the non-exist digest value, and the exception will be caught and digest will - be set to null, which means we won't compare digest when loading this snapshot, - which is expected to happen during rolling upgrade - 4. When loading new snapshot with old code, it will finish successfully after deserializing - the data tree, the digest value at the end of snapshot file will be ignored - 5. The scenarios of rolling restart with flags change are similar to the 1st and 2nd - scenarios discussed above, if the leader enabled but follower not, digest value will - be ignored, and follower won't compare the digest during runtime; if leader disabled - but follower enabled, follower will get EOF exception which is handled gracefully. - - Note: the current digest calculation excluded nodes under /zookeeper - due to the potential inconsistency in the /zookeeper/quota stat node, - we can include that after that issue is fixed. - - By default, this feature is enabled, set "false" to disable it. - -* *snapshot.compression.method* : - (Java system property: **zookeeper.snapshot.compression.method**) - **New in 3.6.0:** - This property controls whether or not ZooKeeper should compress snapshots - before storing them on disk (see [ZOOKEEPER-3179](https://issues.apache.org/jira/browse/ZOOKEEPER-3179)). - Possible values are: - - "": Disabled (no snapshot compression). This is the default behavior. - - "gz": See [gzip compression](https://en.wikipedia.org/wiki/Gzip). - - "snappy": See [Snappy compression](https://en.wikipedia.org/wiki/Snappy_(compression)). - -* *snapshot.trust.empty* : - (Java system property: **zookeeper.snapshot.trust.empty**) - **New in 3.5.6:** - This property controls whether or not ZooKeeper should treat missing - snapshot files as a fatal state that can't be recovered from. - Set to true to allow ZooKeeper servers recover without snapshot - files. This should only be set during upgrading from old versions of - ZooKeeper (3.4.x, pre 3.5.3) where ZooKeeper might only have transaction - log files but without presence of snapshot files. If the value is set - during upgrade, we recommend setting the value back to false after upgrading - and restart ZooKeeper process so ZooKeeper can continue normal data - consistency check during recovery process. - Default value is false. - -* *audit.enable* : - (Java system property: **zookeeper.audit.enable**) - **New in 3.6.0:** - By default audit logs are disabled. Set to "true" to enable it. Default value is "false". - See the [ZooKeeper audit logs](zookeeperAuditLogs.html) for more information. - -* *audit.impl.class* : - (Java system property: **zookeeper.audit.impl.class**) - **New in 3.6.0:** - Class to implement the audit logger. By default logback based audit logger org.apache.zookeeper.audit - .Slf4jAuditLogger is used. - See the [ZooKeeper audit logs](zookeeperAuditLogs.html) for more information. - -* *largeRequestMaxBytes* : - (Java system property: **zookeeper.largeRequestMaxBytes**) - **New in 3.6.0:** - The maximum number of bytes of all inflight large request. The connection will be closed if a coming large request causes the limit exceeded. The default is 100 * 1024 * 1024. - -* *largeRequestThreshold* : - (Java system property: **zookeeper.largeRequestThreshold**) - **New in 3.6.0:** - The size threshold after which a request is considered a large request. If it is -1, then all requests are considered small, effectively turning off large request throttling. The default is -1. - -* *outstandingHandshake.limit* - (Java system property only: **zookeeper.netty.server.outstandingHandshake.limit**) - The maximum in-flight TLS handshake connections could have in ZooKeeper, - the connections exceed this limit will be rejected before starting handshake. - This setting doesn't limit the max TLS concurrency, but helps avoid herd - effect due to TLS handshake timeout when there are too many in-flight TLS - handshakes. Set it to something like 250 is good enough to avoid herd effect. - -* *netty.server.earlyDropSecureConnectionHandshakes* - (Java system property: **zookeeper.netty.server.earlyDropSecureConnectionHandshakes**) - If the ZooKeeper server is not fully started, drop TCP connections before performing the TLS handshake. - This is useful in order to prevent flooding the server with many concurrent TLS handshakes after a restart. - Please note that if you enable this flag the server won't answer to 'ruok' commands if it is not fully started. - - The behaviour of dropping the connection has been introduced in ZooKeeper 3.7 and it was not possible to disable it. - Since 3.7.1 and 3.8.0 this feature is disabled by default. - -* *throttledOpWaitTime* - (Java system property: **zookeeper.throttled_op_wait_time**) - The time in the RequestThrottler queue longer than which a request will be marked as throttled. - A throttled requests will not be processed other than being fed down the pipeline of the server it belongs - to preserve the order of all requests. - The FinalProcessor will issue an error response (new error code: ZTHROTTLEDOP) for these undigested requests. - The intent is for the clients not to retry them immediately. - When set to 0, no requests will be throttled. The default is 0. - -* *learner.closeSocketAsync* - (Java system property: **zookeeper.learner.closeSocketAsync**) - (Java system property: **learner.closeSocketAsync**)(Added for backward compatibility) - **New in 3.7.0:** - When enabled, a learner will close the quorum socket asynchronously. This is useful for TLS connections where closing a socket might take a long time, block the shutdown process, potentially delay a new leader election, and leave the quorum unavailable. Closing the socket asynchronously avoids blocking the shutdown process despite the long socket closing time and a new leader election can be started while the socket being closed. - The default is false. - -* *leader.closeSocketAsync* - (Java system property: **zookeeper.leader.closeSocketAsync**) - (Java system property: **leader.closeSocketAsync**)(Added for backward compatibility) - **New in 3.7.0:** - When enabled, the leader will close a quorum socket asynchronously. This is useful for TLS connections where closing a socket might take a long time. If disconnecting a follower is initiated in ping() because of a failed SyncLimitCheck then the long socket closing time will block the sending of pings to other followers. Without receiving pings, the other followers will not send session information to the leader, which causes sessions to expire. Setting this flag to true ensures that pings will be sent regularly. - The default is false. - -* *learner.asyncSending* - (Java system property: **zookeeper.learner.asyncSending**) - (Java system property: **learner.asyncSending**)(Added for backward compatibility) - **New in 3.7.0:** - The sending and receiving packets in Learner were done synchronously in a critical section. An untimely network issue could cause the followers to hang (see [ZOOKEEPER-3575](https://issues.apache.org/jira/browse/ZOOKEEPER-3575) and [ZOOKEEPER-4074](https://issues.apache.org/jira/browse/ZOOKEEPER-4074)). The new design moves sending packets in Learner to a separate thread and sends the packets asynchronously. The new design is enabled with this parameter (learner.asyncSending). - The default is false. - -* *forward_learner_requests_to_commit_processor_disabled* - (Java system property: **zookeeper.forward_learner_requests_to_commit_processor_disabled**) - When this property is set, the requests from learners won't be enqueued to - CommitProcessor queue, which will help save the resources and GC time on - leader. - - The default value is false. - -* *serializeLastProcessedZxid.enabled* - (Java system property: **zookeeper.serializeLastProcessedZxid.enabled**) - **New in 3.9.0:** - If enabled, ZooKeeper serializes the lastProcessedZxid when snapshot and deserializes it - when restore. Defaults to true. Needs to be enabled for performing snapshot and restore - via admin server commands, as there is no snapshot file name to extract the lastProcessedZxid. - - This feature is backward and forward compatible. Here are the different scenarios. - - 1. Snapshot triggered by server internally - a. When loading old snapshot with new code, it will throw EOFException when trying to - read the non-exist lastProcessedZxid value, and the exception will be caught. - The lastProcessedZxid will be set using the snapshot file name. - - b. When loading new snapshot with old code, it will finish successfully after deserializing the - digest value, the lastProcessedZxid at the end of snapshot file will be ignored. - The lastProcessedZxid will be set using the snapshot file name. - - 2. Sync up between leader and follower - The lastProcessedZxid will not be serialized by leader and deserialized by follower - in both new and old code. It will be set to the lastProcessedZxid sent from leader - via QuorumPacket. - - 3. Snapshot triggered via admin server APIs - The feature flag need to be enabled for the snapshot command to work. - - - -#### Cluster Options - -The options in this section are designed for use with an ensemble -of servers -- that is, when deploying clusters of servers. - -* *electionAlg* : - (No Java system property) - Election implementation to use. A value of "1" corresponds to the - non-authenticated UDP-based version of fast leader election, "2" - corresponds to the authenticated UDP-based version of fast - leader election, and "3" corresponds to TCP-based version of - fast leader election. Algorithm 3 was made default in 3.2.0 and - prior versions (3.0.0 and 3.1.0) were using algorithm 1 and 2 as well. - ###### Note - >The implementations of leader election 1, and 2 were - **deprecated** in 3.4.0. Since 3.6.0 only FastLeaderElection is available, - in case of upgrade you have to shut down all of your servers and - restart them with electionAlg=3 (or by removing the line from the configuration file). > - -* *maxTimeToWaitForEpoch* : - (Java system property: **zookeeper.leader.maxTimeToWaitForEpoch**) - **New in 3.6.0:** - The maximum time to wait for epoch from voters when activating - leader. If leader received a LOOKING notification from one of - its voters, and it hasn't received epoch packets from majority - within maxTimeToWaitForEpoch, then it will goto LOOKING and - elect leader again. - This can be tuned to reduce the quorum or server unavailable - time, it can be set to be much smaller than initLimit * tickTime. - In cross datacenter environment, it can be set to something - like 2s. - -* *initLimit* : - (No Java system property) - Amount of time, in ticks (see [tickTime](#id_tickTime)), to allow followers to - connect and sync to a leader. Increased this value as needed, if - the amount of data managed by ZooKeeper is large. - -* *connectToLearnerMasterLimit* : - (Java system property: zookeeper.**connectToLearnerMasterLimit**) - Amount of time, in ticks (see [tickTime](#id_tickTime)), to allow followers to - connect to the leader after leader election. Defaults to the value of initLimit. - Use when initLimit is high so connecting to learner master doesn't result in higher timeout. - -* *leaderServes* : - (Java system property: zookeeper.**leaderServes**) - Leader accepts client connections. Default value is "yes". - The leader machine coordinates updates. For higher update - throughput at the slight expense of read throughput the leader - can be configured to not accept clients and focus on - coordination. The default to this option is yes, which means - that a leader will accept client connections. - ###### Note - >Turning on leader selection is highly recommended when - you have more than three ZooKeeper servers in an ensemble. - -* *server.x=[hostname]:nnnnn[:nnnnn] etc* : - (No Java system property) - servers making up the ZooKeeper ensemble. When the server - starts up, it determines which server it is by looking for the - file *myid* in the data directory. That file - contains the server number, in ASCII, and it should match - **x** in **server.x** in the left hand side of this - setting. - The list of servers that make up ZooKeeper servers that is - used by the clients must match the list of ZooKeeper servers - that each ZooKeeper server has. - There are two port numbers **nnnnn**. - The first followers used to connect to the leader, and the second is for - leader election. If you want to test multiple servers on a single machine, then - different ports can be used for each server. - - - - Since ZooKeeper 3.6.0 it is possible to specify **multiple addresses** for each - ZooKeeper server (see [ZOOKEEPER-3188](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3188)). - To enable this feature, you must set the *multiAddress.enabled* configuration property - to *true*. This helps to increase availability and adds network level - resiliency to ZooKeeper. When multiple physical network interfaces are used - for the servers, ZooKeeper is able to bind on all interfaces and runtime switching - to a working interface in case a network error. The different addresses can be specified - in the config using a pipe ('|') character. A valid configuration using multiple addresses looks like: - - server.1=zoo1-net1:2888:3888|zoo1-net2:2889:3889 - server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889 - server.3=zoo3-net1:2888:3888|zoo3-net2:2889:3889 - - - ###### Note - >By enabling this feature, the Quorum protocol (ZooKeeper Server-Server protocol) will change. - The users will not notice this and when anyone starts a ZooKeeper cluster with the new config, - everything will work normally. However, it's not possible to enable this feature and specify - multiple addresses during a rolling upgrade if the old ZooKeeper cluster didn't support the - *multiAddress* feature (and the new Quorum protocol). In case if you need this feature but you - also need to perform a rolling upgrade from a ZooKeeper cluster older than *3.6.0*, then you - first need to do the rolling upgrade without enabling the MultiAddress feature and later make - a separate rolling restart with the new configuration where **multiAddress.enabled** is set - to **true** and multiple addresses are provided. - -* *syncLimit* : - (No Java system property) - Amount of time, in ticks (see [tickTime](#id_tickTime)), to allow followers to sync - with ZooKeeper. If followers fall too far behind a leader, they - will be dropped. - -* *group.x=nnnnn[:nnnnn]* : - (No Java system property) - Enables a hierarchical quorum construction."x" is a group identifier - and the numbers following the "=" sign correspond to server identifiers. - The left-hand side of the assignment is a colon-separated list of server - identifiers. Note that groups must be disjoint and the union of all groups - must be the ZooKeeper ensemble. - You will find an example [here](zookeeperHierarchicalQuorums.html) - -* *weight.x=nnnnn* : - (No Java system property) - Used along with "group", it assigns a weight to a server when - forming quorums. Such a value corresponds to the weight of a server - when voting. There are a few parts of ZooKeeper that require voting - such as leader election and the atomic broadcast protocol. By default - the weight of server is 1. If the configuration defines groups, but not - weights, then a value of 1 will be assigned to all servers. - You will find an example [here](zookeeperHierarchicalQuorums.html) - -* *cnxTimeout* : - (Java system property: zookeeper.**cnxTimeout**) - Sets the timeout value for opening connections for leader election notifications. - Only applicable if you are using electionAlg 3. - ###### Note - >Default value is 5 seconds. - -* *quorumCnxnTimeoutMs* : - (Java system property: zookeeper.**quorumCnxnTimeoutMs**) - Sets the read timeout value for the connections for leader election notifications. - Only applicable if you are using electionAlg 3. - ######Note - >Default value is -1, which will then use the syncLimit * tickTime as the timeout. - -* *standaloneEnabled* : - (No Java system property) - **New in 3.5.0:** - When set to false, a single server can be started in replicated - mode, a lone participant can run with observers, and a cluster - can reconfigure down to one node, and up from one node. The - default is true for backwards compatibility. It can be set - using QuorumPeerConfig's setStandaloneEnabled method or by - adding "standaloneEnabled=false" or "standaloneEnabled=true" - to a server's config file. - -* *reconfigEnabled* : - (No Java system property) - **New in 3.5.3:** - This controls the enabling or disabling of - [Dynamic Reconfiguration](zookeeperReconfig.html) feature. When the feature - is enabled, users can perform reconfigure operations through - the ZooKeeper client API or through ZooKeeper command line tools - assuming users are authorized to perform such operations. - When the feature is disabled, no user, including the super user, - can perform a reconfiguration. Any attempt to reconfigure will return an error. - **"reconfigEnabled"** option can be set as - **"reconfigEnabled=false"** or - **"reconfigEnabled=true"** - to a server's config file, or using QuorumPeerConfig's - setReconfigEnabled method. The default value is false. - If present, the value should be consistent across every server in - the entire ensemble. Setting the value as true on some servers and false - on other servers will cause inconsistent behavior depending on which server - is elected as leader. If the leader has a setting of - **"reconfigEnabled=true"**, then the ensemble - will have reconfig feature enabled. If the leader has a setting of - **"reconfigEnabled=false"**, then the ensemble - will have reconfig feature disabled. It is thus recommended having a consistent - value for **"reconfigEnabled"** across servers - in the ensemble. - -* *4lw.commands.whitelist* : - (Java system property: **zookeeper.4lw.commands.whitelist**) - **New in 3.5.3:** - A list of comma separated [Four Letter Words](#sc_4lw) - commands that user wants to use. A valid Four Letter Words - command must be put in this list else ZooKeeper server will - not enable the command. - By default the whitelist only contains "srvr" command - which zkServer.sh uses. Additionally, if Read Only Mode is enabled by setting - Java system property **readonlymode.enabled**, then the "isro" command is - added to the whitelist. The rest of four-letter word commands are disabled - by default: attempting to use them will gain a response - ".... is not executed because it is not in the whitelist." - Here's an example of the configuration that enables stat, ruok, conf, and isro - command while disabling the rest of Four Letter Words command: - - 4lw.commands.whitelist=stat, ruok, conf, isro - - -If you really need enable all four-letter word commands by default, you can use -the asterisk option so you don't have to include every command one by one in the list. -As an example, this will enable all four-letter word commands: - - - 4lw.commands.whitelist=* - - -* *tcpKeepAlive* : - (Java system property: **zookeeper.tcpKeepAlive**) - **New in 3.5.4:** - Setting this to true sets the TCP keepAlive flag on the - sockets used by quorum members to perform elections. - This will allow for connections between quorum members to - remain up when there is network infrastructure that may - otherwise break them. Some NATs and firewalls may terminate - or lose state for long-running or idle connections. - Enabling this option relies on OS level settings to work - properly, check your operating system's options regarding TCP - keepalive for more information. Defaults to - **false**. - -* *clientTcpKeepAlive* : - (Java system property: **zookeeper.clientTcpKeepAlive**) - **New in 3.6.1:** - Setting this to true sets the TCP keepAlive flag on the - client sockets. Some broken network infrastructure may lose - the FIN packet that is sent from closing client. These never - closed client sockets cause OS resource leak. Enabling this - option terminates these zombie sockets by idle check. - Enabling this option relies on OS level settings to work - properly, check your operating system's options regarding TCP - keepalive for more information. Defaults to **false**. Please - note the distinction between it and **tcpKeepAlive**. It is - applied for the client sockets while **tcpKeepAlive** is for - the sockets used by quorum members. Currently this option is - only available when default `NIOServerCnxnFactory` is used. - -* *electionPortBindRetry* : - (Java system property only: **zookeeper.electionPortBindRetry**) - Property set max retry count when Zookeeper server fails to bind - leader election port. Such errors can be temporary and recoverable, - such as DNS issue described in [ZOOKEEPER-3320](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3320), - or non-retryable, such as port already in use. - In case of transient errors, this property can improve availability - of Zookeeper server and help it to self recover. - Default value 3. In container environment, especially in Kubernetes, - this value should be increased or set to 0(infinite retry) to overcome issues - related to DNS name resolving. - - -* *observer.reconnectDelayMs* : - (Java system property: **zookeeper.observer.reconnectDelayMs**) - When observer loses its connection with the leader, it waits for the - specified value before trying to reconnect with the leader so that - the entire observer fleet won't try to run leader election and reconnect - to the leader at once. - Defaults to 0 ms. - -* *observer.election.DelayMs* : - (Java system property: **zookeeper.observer.election.DelayMs**) - Delay the observer's participation in a leader election upon disconnect - so as to prevent unexpected additional load on the voting peers during - the process. Defaults to 200 ms. - -* *localSessionsEnabled* and *localSessionsUpgradingEnabled* : - **New in 3.5:** - Optional value is true or false. Their default values are false. - Turning on the local session feature by setting *localSessionsEnabled=true*. Turning on - *localSessionsUpgradingEnabled* can upgrade a local session to a global session automatically as required (e.g. creating ephemeral nodes), - which only matters when *localSessionsEnabled* is enabled. - - - -#### Encryption, Authentication, Authorization Options - -The options in this section allow control over -encryption/authentication/authorization performed by the service. - -Beside this page, you can also find useful information about client side configuration in the -[Programmers Guide](zookeeperProgrammers.html#sc_java_client_configuration). -The ZooKeeper Wiki also has useful pages about [ZooKeeper SSL support](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide), -and [SASL authentication for ZooKeeper](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+and+SASL). - -* *DigestAuthenticationProvider.enabled* : - (Java system property: **zookeeper.DigestAuthenticationProvider.enabled**) - **New in 3.7:** - Determines whether the `digest` authentication provider is - enabled. The default value is **true** for backwards - compatibility, but it may be a good idea to disable this provider - if not used, as it can result in misleading entries appearing in - audit logs - (see [ZOOKEEPER-3979](https://issues.apache.org/jira/browse/ZOOKEEPER-3979)) - -* *DigestAuthenticationProvider.superDigest* : - (Java system property: **zookeeper.DigestAuthenticationProvider.superDigest**) - By default this feature is **disabled** - **New in 3.2:** - Enables a ZooKeeper ensemble administrator to access the - znode hierarchy as a "super" user. In particular no ACL - checking occurs for a user authenticated as - super. - org.apache.zookeeper.server.auth.DigestAuthenticationProvider - can be used to generate the superDigest, call it with - one parameter of "super:". Provide the - generated "super:" as the system property value - when starting each server of the ensemble. - When authenticating to a ZooKeeper server (from a - ZooKeeper client) pass a scheme of "digest" and authdata - of "super:". Note that digest auth passes - the authdata in plaintext to the server, it would be - prudent to use this authentication method only on - localhost (not over the network) or over an encrypted - connection. - -* *DigestAuthenticationProvider.digestAlg* : - (Java system property: **zookeeper.DigestAuthenticationProvider.digestAlg**) - **New in 3.7.0:** - Set ACL digest algorithm. The default value is: `SHA1` which will be deprecated in the future for security issues. - Set this property the same value in all the servers. - - - How to support other more algorithms? - - modify the `java.security` configuration file under `$JAVA_HOME/jre/lib/security/java.security` by specifying: - `security.provider.=`. - - ``` - For example: - set zookeeper.DigestAuthenticationProvider.digestAlg=RipeMD160 - security.provider.3=org.bouncycastle.jce.provider.BouncyCastleProvider - ``` - - - copy the jar file to `$JAVA_HOME/jre/lib/ext/`. - - ``` - For example: - copy bcprov-jdk18on-1.60.jar to $JAVA_HOME/jre/lib/ext/ - ``` - - - How to migrate from one digest algorithm to another? - - 1. Regenerate `superDigest` when migrating to new algorithm. - - 2. `SetAcl` for a znode which already had a digest auth of old algorithm. - -* *IPAuthenticationProvider.usexforwardedfor* : - (Java system property: **zookeeper.IPAuthenticationProvider.usexforwardedfor**) - **New in 3.9.3:** - IPAuthenticationProvider uses the client IP address to authenticate the user. By - default it reads the **Host** HTTP header to detect client IP address. In some - proxy configurations the proxy server adds the **X-Forwarded-For** header to - the request in order to provide the IP address of the original client request. - By enabling **usexforwardedfor** ZooKeeper setting, **X-Forwarded-For** will be preferred - over the standard **Host** header. - Default value is **false**. - -* *X509AuthenticationProvider.superUser* : - (Java system property: **zookeeper.X509AuthenticationProvider.superUser**) - The SSL-backed way to enable a ZooKeeper ensemble - administrator to access the znode hierarchy as a "super" user. - When this parameter is set to an X500 principal name, only an - authenticated client with that principal will be able to bypass - ACL checking and have full privileges to all znodes. - -* *zookeeper.superUser* : - (Java system property: **zookeeper.superUser**) - Similar to **zookeeper.X509AuthenticationProvider.superUser** - but is generic for SASL based logins. It stores the name of - a user that can access the znode hierarchy as a "super" user. - You can specify multiple SASL super users using the - **zookeeper.superUser.[suffix]** notation, e.g.: - `zookeeper.superUser.1=...`. - -* *ssl.authProvider* : - (Java system property: **zookeeper.ssl.authProvider**) - Specifies a subclass of **org.apache.zookeeper.auth.X509AuthenticationProvider** - to use for secure client authentication. This is useful in - certificate key infrastructures that do not use JKS. It may be - necessary to extend **javax.net.ssl.X509KeyManager** and **javax.net.ssl.X509TrustManager** - to get the desired behavior from the SSL stack. To configure the - ZooKeeper server to use the custom provider for authentication, - choose a scheme name for the custom AuthenticationProvider and - set the property **zookeeper.authProvider.[scheme]** to the fully-qualified class name of the custom - implementation. This will load the provider into the ProviderRegistry. - Then set this property **zookeeper.ssl.authProvider=[scheme]** and that provider - will be used for secure authentication. - -* *zookeeper.ensembleAuthName* : - (Java system property only: **zookeeper.ensembleAuthName**) - **New in 3.6.0:** - Specify a list of comma-separated valid names/aliases of an ensemble. A client - can provide the ensemble name it intends to connect as the credential for scheme "ensemble". The EnsembleAuthenticationProvider will check the credential against - the list of names/aliases of the ensemble that receives the connection request. - If the credential is not in the list, the connection request will be refused. - This prevents a client accidentally connecting to a wrong ensemble. - -* *sessionRequireClientSASLAuth* : - (Java system property: **zookeeper.sessionRequireClientSASLAuth**) - **New in 3.6.0:** - When set to **true**, ZooKeeper server will only accept connections and requests from clients - that have authenticated with server via SASL. Clients that are not configured with SASL - authentication, or configured with SASL but failed authentication (i.e. with invalid credential) - will not be able to establish a session with server. A typed error code (-124) will be delivered - in such case, both Java and C client will close the session with server thereafter, - without further attempts on retrying to reconnect. - - This configuration is shorthand for **enforce.auth.enabled=true** and **enforce.auth.scheme=sasl** - - By default, this feature is disabled. Users who would like to opt-in can enable the feature - by setting **sessionRequireClientSASLAuth** to **true**. - - This feature overrules the zookeeper.allowSaslFailedClients option, so even if server is - configured to allow clients that fail SASL authentication to login, client will not be able to - establish a session with server if this feature is enabled. - -* *enforce.auth.enabled* : - (Java system property : **zookeeper.enforce.auth.enabled**) - **New in 3.7.0:** - When set to **true**, ZooKeeper server will only accept connections and requests from clients - that have authenticated with server via configured auth scheme. Authentication schemes - can be configured using property enforce.auth.schemes. Clients that are not - configured with the any of the auth scheme configured at server or configured but failed authentication (i.e. with invalid credential) - will not be able to establish a session with server. A typed error code (-124) will be delivered - in such case, both Java and C client will close the session with server thereafter, - without further attempts on retrying to reconnect. - - By default, this feature is disabled. Users who would like to opt-in can enable the feature - by setting **enforce.auth.enabled** to **true**. - - When **enforce.auth.enabled=true** and **enforce.auth.schemes=sasl** then - zookeeper.allowSaslFailedClients configuration is overruled. So even if server is - configured to allow clients that fail SASL authentication to login, client will not be able to - establish a session with server if this feature is enabled with sasl as authentication scheme. - -* *enforce.auth.schemes* : - (Java system property : **zookeeper.enforce.auth.schemes**) - **New in 3.7.0:** - Comma separated list of authentication schemes. Clients must be authenticated with at least one - authentication scheme before doing any zookeeper operations. - This property is used only when **enforce.auth.enabled** is to **true**. - -* *sslQuorum* : - (Java system property: **zookeeper.sslQuorum**) - **New in 3.5.5:** - Enables encrypted quorum communication. Default is `false`. When enabling this feature, please also consider enabling *leader.closeSocketAsync* - and *learner.closeSocketAsync* to avoid issues associated with the potentially long socket closing time when shutting down an SSL connection. - -* *ssl.keyStore.location and ssl.keyStore.password* and *ssl.quorum.keyStore.location* and *ssl.quorum.keyStore.password* : - (Java system properties: **zookeeper.ssl.keyStore.location** and **zookeeper.ssl.keyStore.password** and **zookeeper.ssl.quorum.keyStore.location** and **zookeeper.ssl.quorum.keyStore.password**) - **New in 3.5.5:** - Specifies the file path to a Java keystore containing the local - credentials to be used for client and quorum TLS connections, and the - password to unlock the file. - -* *ssl.keyStore.passwordPath* and *ssl.quorum.keyStore.passwordPath* : - (Java system properties: **zookeeper.ssl.keyStore.passwordPath** and **zookeeper.ssl.quorum.keyStore.passwordPath**) - **New in 3.8.0:** - Specifies the file path that contains the keystore password. Reading the password from a file takes precedence over - the explicit password property. - -* *ssl.keyStore.type* and *ssl.quorum.keyStore.type* : - (Java system properties: **zookeeper.ssl.keyStore.type** and **zookeeper.ssl.quorum.keyStore.type**) - **New in 3.5.5:** - Specifies the file format of client and quorum keystores. Values: JKS, PEM, PKCS12 or null (detect by filename). - Default: null. - **New in 3.5.10, 3.6.3, 3.7.0:** - The format BCFKS was added. - -* *ssl.trustStore.location* and *ssl.trustStore.password* and *ssl.quorum.trustStore.location* and *ssl.quorum.trustStore.password* : - (Java system properties: **zookeeper.ssl.trustStore.location** and **zookeeper.ssl.trustStore.password** and **zookeeper.ssl.quorum.trustStore.location** and **zookeeper.ssl.quorum.trustStore.password**) - **New in 3.5.5:** - Specifies the file path to a Java truststore containing the remote - credentials to be used for client and quorum TLS connections, and the - password to unlock the file. - -* *ssl.trustStore.passwordPath* and *ssl.quorum.trustStore.passwordPath* : - (Java system properties: **zookeeper.ssl.trustStore.passwordPath** and **zookeeper.ssl.quorum.trustStore.passwordPath**) - **New in 3.8.0:** - Specifies the file path that contains the truststore password. Reading the password from a file takes precedence over - the explicit password property. - -* *ssl.trustStore.type* and *ssl.quorum.trustStore.type* : - (Java system properties: **zookeeper.ssl.trustStore.type** and **zookeeper.ssl.quorum.trustStore.type**) - **New in 3.5.5:** - Specifies the file format of client and quorum trustStores. Values: JKS, PEM, PKCS12 or null (detect by filename). - Default: null. - **New in 3.5.10, 3.6.3, 3.7.0:** - The format BCFKS was added. - -* *ssl.protocol* and *ssl.quorum.protocol* : - (Java system properties: **zookeeper.ssl.protocol** and **zookeeper.ssl.quorum.protocol**) - **New in 3.5.5:** - Specifies to protocol to be used in client and quorum TLS negotiation. - Default: TLSv1.3 or TLSv1.2 depending on Java runtime version being used. - -* *ssl.enabledProtocols* and *ssl.quorum.enabledProtocols* : - (Java system properties: **zookeeper.ssl.enabledProtocols** and **zookeeper.ssl.quorum.enabledProtocols**) - **New in 3.5.5:** - Specifies the enabled protocols in client and quorum TLS negotiation. - Default: TLSv1.3, TLSv1.2 if value of `protocol` property is TLSv1.3. TLSv1.2 if `protocol` is TLSv1.2. - -* *ssl.ciphersuites* and *ssl.quorum.ciphersuites* : - (Java system properties: **zookeeper.ssl.ciphersuites** and **zookeeper.ssl.quorum.ciphersuites**) - **New in 3.5.5:** - Specifies the enabled cipher suites to be used in client and quorum TLS negotiation. - Default: JDK defaults since 3.10.0, and hard coded cipher suites for 3.9 and earlier versions. See [TLS Cipher Suites](#sc_tls_cipher_suites). - -* *ssl.context.supplier.class* and *ssl.quorum.context.supplier.class* : - (Java system properties: **zookeeper.ssl.context.supplier.class** and **zookeeper.ssl.quorum.context.supplier.class**) - **New in 3.5.5:** - Specifies the class to be used for creating SSL context in client and quorum SSL communication. - This allows you to use custom SSL context and implement the following scenarios: - 1. Use hardware keystore, loaded in using PKCS11 or something similar. - 2. You don't have access to the software keystore, but can retrieve an already-constructed SSLContext from their container. - Default: null - -* *ssl.hostnameVerification* and *ssl.quorum.hostnameVerification* : - (Java system properties: **zookeeper.ssl.hostnameVerification** and **zookeeper.ssl.quorum.hostnameVerification**) - **New in 3.5.5:** - Specifies whether the hostname verification is enabled in client and quorum TLS negotiation process. - Disabling it only recommended for testing purposes. - Default: true - -* *ssl.clientHostnameVerification* and *ssl.quorum.clientHostnameVerification* : - (Java system properties: **zookeeper.ssl.clientHostnameVerification** and **zookeeper.ssl.quorum.clientHostnameVerification**) - **New in 3.9.4:** - Specifies whether the client's hostname verification is enabled in client and quorum TLS negotiation process. - This option requires the corresponding *hostnameVerification* option to be `true`, or it will be ignored. - Default: true for quorum, false for clients - -* *ssl.allowReverseDnsLookup* and *ssl.quorum.allowReverseDnsLookup* : - (Java system properties: **zookeeper.ssl.allowReverseDnsLookup** and **zookeeper.ssl.quorum.allowReverseDnsLookup**) - **New in 3.9.5:** - Allow reverse DNS lookup in both server- and client hostname verifications if the hostname verification is enabled in - `ZKTrustManager`. Supported in both quorum and client TLS protocols. Not supported in FIPS mode. Reverse DNS lookups are - expensive and unnecessary in most cases. Make sure that certificates are created with all required Subject Alternative - Names (SAN) for successful identity verification. It's recommended to add SAN:IP entries for identity verification - of client certificates. - Default: false - -* *ssl.crl* and *ssl.quorum.crl* : - (Java system properties: **zookeeper.ssl.crl** and **zookeeper.ssl.quorum.crl**) - **New in 3.5.5:** - Specifies whether Certificate Revocation List is enabled in client and quorum TLS protocols. - Default: jvm property "com.sun.net.ssl.checkRevocation" since 3.10.0, false otherwise - -* *ssl.ocsp* and *ssl.quorum.ocsp* : - (Java system properties: **zookeeper.ssl.ocsp** and **zookeeper.ssl.quorum.ocsp**) - **New in 3.5.5:** - Specifies whether Online Certificate Status Protocol is enabled in client and quorum TLS protocols. - **Changed in 3.10.0:** - Before 3.10.0, *ssl.ocsp* and *ssl.quorum.ocsp* implies *ssl.crl* and *ssl.quorum.crl* correspondingly. - After 3.10.0, one has to setup both *ssl.crl* and *ssl.ocsp* (or *ssl.quorum.crl* and *ssl.quorum.ocsp*) - to enable OCSP. This is consistent with jdk's method of [Setting up a Java Client to use Client-Driven OCSP](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ocsp.html#setting-up-a-java-client-to-use-client-driven-ocsp). - Default: jvm security property "ocsp.enable" since 3.10.0, false otherwise - -* *ssl.clientAuth* and *ssl.quorum.clientAuth* : - (Java system properties: **zookeeper.ssl.clientAuth** and **zookeeper.ssl.quorum.clientAuth**) - **Added in 3.5.5, but broken until 3.5.7:** - Specifies options to authenticate ssl connections from clients. Valid values are - - * "none": server will not request client authentication - * "want": server will "request" client authentication - * "need": server will "require" client authentication - - Default: "need" - -* *ssl.handshakeDetectionTimeoutMillis* and *ssl.quorum.handshakeDetectionTimeoutMillis* : - (Java system properties: **zookeeper.ssl.handshakeDetectionTimeoutMillis** and **zookeeper.ssl.quorum.handshakeDetectionTimeoutMillis**) - **New in 3.5.5:** - TBD - -* *ssl.sslProvider* : - (Java system property: **zookeeper.ssl.sslProvider**) - **New in 3.9.0:** - Allows to select SSL provider in the client-server communication when TLS is enabled. Netty-tcnative native library - has been added to ZooKeeper in version 3.9.0 which allows us to use native SSL libraries like OpenSSL on supported - platforms. See the available options in Netty-tcnative documentation. Default value is "JDK". - -* *sslQuorumReloadCertFiles* : - (No Java system property) - **New in 3.5.5, 3.6.0:** - Allows Quorum SSL keyStore and trustStore reloading when the certificates on the filesystem change without having to restart the ZK process. Default: false - -* *client.certReload* : - (Java system property: **zookeeper.client.certReload**) - **New in 3.7.2, 3.8.1, 3.9.0:** - Allows client SSL keyStore and trustStore reloading when the certificates on the filesystem change without having to restart the ZK process. Default: false - -* *client.portUnification*: - (Java system property: **zookeeper.client.portUnification**) - Specifies that the client port should accept SSL connections - (using the same configuration as the secure client port). - Default: false - -* *authProvider*: - (Java system property: **zookeeper.authProvider**) - You can specify multiple authentication provider classes for ZooKeeper. - Usually you use this parameter to specify the SASL authentication provider - like: `authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider` - -* *kerberos.removeHostFromPrincipal* - (Java system property: **zookeeper.kerberos.removeHostFromPrincipal**) - You can instruct ZooKeeper to remove the host from the client principal name during authentication. - (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk@EXAMPLE.COM) - Default: false - -* *kerberos.removeRealmFromPrincipal* - (Java system property: **zookeeper.kerberos.removeRealmFromPrincipal**) - You can instruct ZooKeeper to remove the realm from the client principal name during authentication. - (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk/myhost) - Default: false - -* *kerberos.canonicalizeHostNames* - (Java system property: **zookeeper.kerberos.canonicalizeHostNames**) - **New in 3.7.0:** - Instructs ZooKeeper to canonicalize server host names extracted from *server.x* lines. - This allows using e.g. `CNAME` records to reference servers in configuration files, while still enabling SASL Kerberos authentication between quorum members. - It is essentially the quorum equivalent of the *zookeeper.sasl.client.canonicalize.hostname* property for clients. - The default value is **false** for backwards compatibility. - -* *multiAddress.enabled* : - (Java system property: **zookeeper.multiAddress.enabled**) - **New in 3.6.0:** - Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#id_multi_address) - for each ZooKeeper server instance (this can increase availability when multiple physical - network interfaces can be used parallel in the cluster). Setting this parameter to - **true** will enable this feature. Please note, that you can not enable this feature - during a rolling upgrade if the version of the old ZooKeeper cluster is prior to 3.6.0. - The default value is **false**. - -* *multiAddress.reachabilityCheckTimeoutMs* : - (Java system property: **zookeeper.multiAddress.reachabilityCheckTimeoutMs**) - **New in 3.6.0:** - Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#id_multi_address) - for each ZooKeeper server instance (this can increase availability when multiple physical - network interfaces can be used parallel in the cluster). ZooKeeper will perform ICMP ECHO requests - or try to establish a TCP connection on port 7 (Echo) of the destination host in order to find - the reachable addresses. This happens only if you provide multiple addresses in the configuration. - In this property you can set the timeout in milliseconds for the reachability check. The check happens - in parallel for the different addresses, so the timeout you set here is the maximum time will be taken - by checking the reachability of all addresses. - The default value is **1000**. - - This parameter has no effect, unless you enable the MultiAddress feature by setting *multiAddress.enabled=true*. - -* *fips-mode* : - (Java system property: **zookeeper.fips-mode**) - **New in 3.8.2:** - Enable FIPS compatibility mode in ZooKeeper. If enabled, the following things will be changed in order to comply - with FIPS requirements: - * Custom trust manager (`ZKTrustManager`) that is used for hostname verification will be disabled. As a consequence, - hostname verification is not available in the Quorum protocol, but still can be set in client-server communication. - * DIGEST-MD5 Sasl auth mechanism will be disabled in Quorum and ZooKeeper Sasl clients. Only GSSAPI (Kerberos) - can be used. - - Default: **true** (3.9.0+), **false** (3.8.x) - - - -##### TLS Cipher Suites - -From 3.5.5 to 3.9 a hard coded default cipher list was used, with the ordering -dependent on whether it is run Java 8 or a later version. - -The list on Java 8 includes TLSv1.2 CBC, GCM and TLSv1.3 ciphers in ordering: *TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256* - -The list on Java 9+ includes TLSv1.2 GCM, CBC and TLSv1.3 ciphers in ordering: *TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256* - -Since 3.10 there is no hardcoded list, and the JDK defaults are used. - - - -#### Experimental Options/Features - -New features that are currently considered experimental. - -* *Read Only Mode Server* : - (Java system property: **readonlymode.enabled**) - **New in 3.4.0:** - Setting this value to true enables Read Only Mode server - support (disabled by default). - *localSessionsEnabled* has to be activated to serve clients. - A downgrade of an existing connections is currently not supported. - ROM allows clients sessions which requested ROM support to connect to the - server even when the server might be partitioned from - the quorum. In this mode ROM clients can still read - values from the ZK service, but will be unable to write - values and see changes from other clients. See - ZOOKEEPER-784 for more details. - -* *zookeeper.follower.skipLearnerRequestToNextProcessor* : - (Java system property: **zookeeper.follower.skipLearnerRequestToNextProcessor**) - When our cluster has observers which are connected with ObserverMaster, then turning on this flag might help - you reduce some memory pressure on the Observer Master. If your cluster doesn't have any observers or - they are not connected with ObserverMaster or your Observer's don't make much writes, then using this flag - won't help you. - Currently the change here is guarded behind the flag to help us get more confidence around the memory gains. - In Long run, we might want to remove this flag and set its behavior as the default codepath. - - - -#### Unsafe Options - -The following options can be useful, but be careful when you use -them. The risk of each is explained along with the explanation of what -the variable does. - -* *forceSync* : - (Java system property: **zookeeper.forceSync**) - Requires updates to be synced to media of the transaction - log before finishing processing the update. If this option is - set to no, ZooKeeper will not require updates to be synced to - the media. - -* *jute.maxbuffer* : - (Java system property:**jute.maxbuffer**). - - This option can only be set as a Java system property. - There is no zookeeper prefix on it. It specifies the maximum - size of the data that can be stored in a znode. The unit is: byte. The default is - 0xfffff(1048575) bytes, or just under 1M. - - If this option is changed, the system property must be set on all servers and clients otherwise - problems will arise. - - When *jute.maxbuffer* in the client side is greater than the server side, the client wants to write the data - exceeds *jute.maxbuffer* in the server side, the server side will get **java.io.IOException: Len error** - - When *jute.maxbuffer* in the client side is less than the server side, the client wants to read the data - exceeds *jute.maxbuffer* in the client side, the client side will get **java.io.IOException: Unreasonable length** - or **Packet len is out of range!** - - This is really a sanity check. ZooKeeper is designed to store data on the order of kilobytes in size. - In the production environment, increasing this property to exceed the default value is not recommended for the following reasons: - - Large size znodes cause unwarranted latency spikes, worsen the throughput - - Large size znodes make the synchronization time between leader and followers unpredictable and non-convergent(sometimes timeout), cause the quorum unstable - -* *jute.maxbuffer.extrasize*: - (Java system property: **zookeeper.jute.maxbuffer.extrasize**) - **New in 3.5.7:** - While processing client requests ZooKeeper server adds some additional information into - the requests before persisting it as a transaction. Earlier this additional information size - was fixed to 1024 bytes. For many scenarios, specially scenarios where jute.maxbuffer value - is more than 1 MB and request type is multi, this fixed size was insufficient. - To handle all the scenarios additional information size is increased from 1024 byte - to same as jute.maxbuffer size and also it is made configurable through jute.maxbuffer.extrasize. - Generally this property is not required to be configured as default value is the most optimal value. - -* *skipACL* : - (Java system property: **zookeeper.skipACL**) - Skips ACL checks. This results in a boost in throughput, - but opens up full access to the data tree to everyone. - -* *quorumListenOnAllIPs* : - When set to true the ZooKeeper server will listen - for connections from its peers on all available IP addresses, - and not only the address configured in the server list of the - configuration file. It affects the connections handling the - ZAB protocol and the Fast Leader Election protocol. Default - value is **false**. - -* *multiAddress.reachabilityCheckEnabled* : - (Java system property: **zookeeper.multiAddress.reachabilityCheckEnabled**) - **New in 3.6.0:** - Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#id_multi_address) - for each ZooKeeper server instance (this can increase availability when multiple physical - network interfaces can be used parallel in the cluster). ZooKeeper will perform ICMP ECHO requests - or try to establish a TCP connection on port 7 (Echo) of the destination host in order to find - the reachable addresses. This happens only if you provide multiple addresses in the configuration. - The reachable check can fail if you hit some ICMP rate-limitation, (e.g. on macOS) when you try to - start a large (e.g. 11+) ensemble members cluster on a single machine for testing. - - Default value is **true**. By setting this parameter to 'false' you can disable the reachability checks. - Please note, disabling the reachability check will cause the cluster not to be able to reconfigure - itself properly during network problems, so the disabling is advised only during testing. - - This parameter has no effect, unless you enable the MultiAddress feature by setting *multiAddress.enabled=true*. - - - -#### Disabling data directory autocreation - -**New in 3.5:** The default -behavior of a ZooKeeper server is to automatically create the -data directory (specified in the configuration file) when -started if that directory does not already exist. This can be -inconvenient and even dangerous in some cases. Take the case -where a configuration change is made to a running server, -wherein the **dataDir** parameter -is accidentally changed. When the ZooKeeper server is -restarted it will create this non-existent directory and begin -serving - with an empty znode namespace. This scenario can -result in an effective "split brain" situation (i.e. data in -both the new invalid directory and the original valid data -store). As such is would be good to have an option to turn off -this autocreate behavior. In general for production -environments this should be done, unfortunately however the -default legacy behavior cannot be changed at this point and -therefore this must be done on a case by case basis. This is -left to users and to packagers of ZooKeeper distributions. - -When running **zkServer.sh** autocreate can be disabled -by setting the environment variable **ZOO_DATADIR_AUTOCREATE_DISABLE** to 1. -When running ZooKeeper servers directly from class files this -can be accomplished by setting **zookeeper.datadir.autocreate=false** on -the java command line, i.e. **-Dzookeeper.datadir.autocreate=false** - -When this feature is disabled, and the ZooKeeper server -determines that the required directories do not exist it will -generate an error and refuse to start. - -A new script **zkServer-initialize.sh** is provided to -support this new feature. If autocreate is disabled it is -necessary for the user to first install ZooKeeper, then create -the data directory (and potentially txnlog directory), and -then start the server. Otherwise as mentioned in the previous -paragraph the server will not start. Running **zkServer-initialize.sh** will create the -required directories, and optionally set up the myid file -(optional command line parameter). This script can be used -even if the autocreate feature itself is not used, and will -likely be of use to users as this (setup, including creation -of the myid file) has been an issue for users in the past. -Note that this script ensures the data directories exist only, -it does not create a config file, but rather requires a config -file to be available in order to execute. - - - -#### Enabling db existence validation - -**New in 3.6.0:** The default -behavior of a ZooKeeper server on startup when no data tree -is found is to set zxid to zero and join the quorum as a -voting member. This can be dangerous if some event (e.g. a -rogue 'rm -rf') has removed the data directory while the -server was down since this server may help elect a leader -that is missing transactions. Enabling db existence validation -will change the behavior on startup when no data tree is -found: the server joins the ensemble as a non-voting participant -until it is able to sync with the leader and acquire an up-to-date -version of the ensemble data. To indicate an empty data tree is -expected (ensemble creation), the user should place a file -'initialize' in the same directory as 'myid'. This file will -be detected and deleted by the server on startup. - -Initialization validation can be enabled when running -ZooKeeper servers directly from class files by setting -**zookeeper.db.autocreate=false** -on the java command line, i.e. -**-Dzookeeper.db.autocreate=false**. -Running **zkServer-initialize.sh** -will create the required initialization file. - - - -#### Performance Tuning Options - -**New in 3.5.0:** Several subsystems have been reworked -to improve read throughput. This includes multi-threading of the NIO communication subsystem and -request processing pipeline (Commit Processor). NIO is the default client/server communication -subsystem. Its threading model comprises 1 acceptor thread, 1-N selector threads and 0-M -socket I/O worker threads. In the request processing pipeline the system can be configured -to process multiple read request at once while maintaining the same consistency guarantee -(same-session read-after-write). The Commit Processor threading model comprises 1 main -thread and 0-N worker threads. - -The default values are aimed at maximizing read throughput on a dedicated ZooKeeper machine. -Both subsystems need to have sufficient amount of threads to achieve peak read throughput. - -* *zookeeper.nio.numSelectorThreads* : - (Java system property only: **zookeeper.nio.numSelectorThreads**) - **New in 3.5.0:** - Number of NIO selector threads. At least 1 selector thread required. - It is recommended to use more than one selector for large numbers - of client connections. The default value is sqrt( number of cpu cores / 2 ). - -* *zookeeper.nio.numWorkerThreads* : - (Java system property only: **zookeeper.nio.numWorkerThreads**) - **New in 3.5.0:** - Number of NIO worker threads. If configured with 0 worker threads, the selector threads - do the socket I/O directly. The default value is 2 times the number of cpu cores. - -* *zookeeper.commitProcessor.numWorkerThreads* : - (Java system property only: **zookeeper.commitProcessor.numWorkerThreads**) - **New in 3.5.0:** - Number of Commit Processor worker threads. If configured with 0 worker threads, the main thread - will process the request directly. The default value is the number of cpu cores. - -* *zookeeper.commitProcessor.maxReadBatchSize* : - (Java system property only: **zookeeper.commitProcessor.maxReadBatchSize**) - Max number of reads to process from queuedRequests before switching to processing commits. - If the value < 0 (default), we switch whenever we have a local write, and pending commits. - A high read batch size will delay commit processing, causing stale data to be served. - If reads are known to arrive in fixed size batches then matching that batch size with - the value of this property can smooth queue performance. Since reads are handled in parallel, - one recommendation is to set this property to match *zookeeper.commitProcessor.numWorkerThread* - (default is the number of cpu cores) or lower. - -* *zookeeper.commitProcessor.maxCommitBatchSize* : - (Java system property only: **zookeeper.commitProcessor.maxCommitBatchSize**) - Max number of commits to process before processing reads. We will try to process as many - remote/local commits as we can till we reach this count. A high commit batch size will delay - reads while processing more commits. A low commit batch size will favor reads. - It is recommended to only set this property when an ensemble is serving a workload with a high - commit rate. If writes are known to arrive in a set number of batches then matching that - batch size with the value of this property can smooth queue performance. A generic - approach would be to set this value to equal the ensemble size so that with the processing - of each batch the current server will probabilistically handle a write related to one of - its direct clients. - Default is "1". Negative and zero values are not supported. - -* *znode.container.checkIntervalMs* : - (Java system property only) - **New in 3.6.0:** The - time interval in milliseconds for each check of candidate container - and ttl nodes. Default is "60000". - -* *znode.container.maxPerMinute* : - (Java system property only) - **New in 3.6.0:** The - maximum number of container and ttl nodes that can be deleted per - minute. This prevents herding during container deletion. - Default is "10000". - -* *znode.container.maxNeverUsedIntervalMs* : - (Java system property only) - **New in 3.6.0:** The - maximum interval in milliseconds that a container that has never had - any children is retained. Should be long enough for your client to - create the container, do any needed work and then create children. - Default is "300000"(a.k.a. 5 minutes) since 3.10.0, for earlier versions, - it is "0" which is used to indicate that containers that have never had - any children are never deleted. - - - -#### Debug Observability Configurations - -**New in 3.6.0:** The following options are introduced to make zookeeper easier to debug. - -* *zookeeper.messageTracker.BufferSize* : - (Java system property only) - Controls the maximum number of messages stored in **MessageTracker**. Value should be positive - integers. The default value is 10. **MessageTracker** is introduced in **3.6.0** to record the - last set of messages between a server (follower or observer) and a leader, when a server - disconnects with leader. These set of messages will then be dumped to zookeeper's log file, - and will help reconstruct the state of the servers at the time of the disconnection and - will be useful for debugging purpose. - -* *zookeeper.messageTracker.Enabled* : - (Java system property only) - When set to "true", will enable **MessageTracker** to track and record messages. Default value - is "false". - - - -#### AdminServer configuration - -**New in 3.10.0:** [AdminServer](#sc_adminserver) will use the following existing properties: - -* *ssl.quorum.ciphersuites* : - (Java system property: **zookeeper.ssl.quorum.ciphersuites**) - The enabled cipher suites to be used in TLS negotiation for AdminServer. - Default: Jetty default. - -* *ssl.quorum.enabledProtocols* : - (Java system property: **zookeeper.ssl.quorum.enabledProtocols**) - The enabled protocols to be used in TLS negotiation for AdminServer. - Default: Jetty default. - -**New in 3.9.0:** The following -options are used to configure the [AdminServer](#sc_adminserver). - -* *admin.rateLimiterIntervalInMS* : - (Java system property: **zookeeper.admin.rateLimiterIntervalInMS**) - The time interval for rate limiting admin command to protect the server. - Defaults to 5 mins. - -* *admin.snapshot.enabled* : - (Java system property: **zookeeper.admin.snapshot.enabled**) - The flag for enabling the snapshot command. Defaults to true. - - -* *admin.restore.enabled* : - (Java system property: **zookeeper.admin.restore.enabled**) - The flag for enabling the restore command. Defaults to true. - - -* *admin.needClientAuth* : - (Java system property: **zookeeper.admin.needClientAuth**) - The flag to control whether client auth is needed. Using x509 auth requires true. - Defaults to false. - -**New in 3.7.1:** The following -options are used to configure the [AdminServer](#sc_adminserver). - -* *admin.forceHttps* : - (Java system property: **zookeeper.admin.forceHttps**) - Force AdminServer to use SSL, thus allowing only HTTPS traffic. - Defaults to disabled. - Overwrites **admin.portUnification** settings. - -**New in 3.6.0:** The following -options are used to configure the [AdminServer](#sc_adminserver). - -* *admin.portUnification* : - (Java system property: **zookeeper.admin.portUnification**) - Enable the admin port to accept both HTTP and HTTPS traffic. - Defaults to disabled. - -**New in 3.5.0:** The following -options are used to configure the [AdminServer](#sc_adminserver). - -* *admin.enableServer* : - (Java system property: **zookeeper.admin.enableServer**) - Set to "false" to disable the AdminServer. By default the - AdminServer is enabled. - -* *admin.serverAddress* : - (Java system property: **zookeeper.admin.serverAddress**) - The address the embedded Jetty server listens on. Defaults to 0.0.0.0. - -* *admin.serverPort* : - (Java system property: **zookeeper.admin.serverPort**) - The port the embedded Jetty server listens on. Defaults to 8080. - -* *admin.idleTimeout* : - (Java system property: **zookeeper.admin.idleTimeout**) - Set the maximum idle time in milliseconds that a connection can wait - before sending or receiving data. Defaults to 30000 ms. - -* *admin.commandURL* : - (Java system property: **zookeeper.admin.commandURL**) - The URL for listing and issuing commands relative to the - root URL. Defaults to "/commands". - -### Metrics Providers - -**New in 3.6.0:** The following options are used to configure metrics. - - By default ZooKeeper server exposes useful metrics using the [AdminServer](#sc_adminserver). - and [Four Letter Words](#sc_4lw) interface. - - Since 3.6.0 you can configure a different Metrics Provider, that exports metrics - to your favourite system. - - Since 3.6.0 ZooKeeper binary package bundles an integration with [Prometheus.io](https://prometheus.io) - -* *metricsProvider.className* : - Set to "org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider" to - enable Prometheus.io exporter. - -* *metricsProvider.httpHost* : - **New in 3.8.0:** Prometheus.io exporter will start a Jetty server and listen this address, default is "0.0.0.0" - -* *metricsProvider.httpPort* : - Prometheus.io exporter will start a Jetty server and bind to this port. - Prometheus end point will be `http://hostname:httpPort/metrics`. - If omitted no HTTP port will be opened. - * Note: Either HTTP or HTTPS port has to be specified or both. - -* *metricsProvider.httpsPort* : - **New in 3.10.0:** - Prometheus.io exporter will start a Jetty server and bind to this port. - Prometheus end point will be `https://hostname:httpsPort/metrics`. - If omitted no HTTPS port will be opened. - * Note: Either HTTP or HTTPS port has to be specified or both. - -* *metricsProvider.exportJvmInfo* : - If this property is set to **true** Prometheus.io will export useful metrics about the JVM. - The default is true. - -* *metricsProvider.numWorkerThreads* : - **New in 3.7.1:** - Number of worker threads for reporting Prometheus summary metrics. - Default value is 1. - If the number is less than 1, the main thread will be used. - -* *metricsProvider.maxQueueSize* : - **New in 3.7.1:** - The max queue size for Prometheus summary metrics reporting task. - Default value is 10000. - -* *metricsProvider.workerShutdownTimeoutMs* : - **New in 3.7.1:** - The timeout in ms for Prometheus worker threads shutdown. - Default value is 1000ms. - -* *metricsProvider.ssl.keyStore.location* and *metricsProvider.ssl.keyStore.password*: - **New in 3.10.0:** - Specifies the file path to a Java keystore containing the local - credentials to be used for PrometheusMetricsProvider TLS connections and the - password to unlock the file. - -* *metricsProvider.ssl.keyStore.type*: - **New in 3.10.0:** - Specifies the file format of the PrometheusMetricsProvider keystore. Values: JKS, PEM, PKCS12 or null (detect by filename). - Default: null. - -* *metricsProvider.ssl.trustStore.location* and *metricsProvider.ssl.trustStore.password*: - **New in 3.10.0:** - Specifies the file path to a Java truststore containing the remote - credentials to be used for PrometheusMetricsProvider TLS connections and the - password to unlock the file. - -* *metricsProvider.ssl.trustStore.type*: - **New in 3.10.0:** - Specifies the file format of the PrometheusMetricsProvider truststore. Values: JKS, PEM, PKCS12 or null (detect by filename). - Default: null. - -* *metricsProvider.ssl.need.client.auth*: - **New in 3.10.0:** - Specifies options to authenticate SSL connections from clients. - When set to true, PrometheusMetricsProvider will "require" client authentication. - Default: true - -* *metricsProvider.ssl.want.client.auth*: - **New in 3.10.0:** - Specifies options to authenticate SSL connections from clients. - When set to true, PrometheusMetricsProvider will "request" client authentication. - Default: true - -* *metricsProvider.ssl.ciphersuites* : - **New in 3.10.0:** - The enabled cipher suites to be used in TLS negotiation for PrometheusMetricsProvider. - Default value is Jetty default. - -* *metricsProvider.ssl.enabledProtocols* : - **New in 3.10.0:** - The enabled protocols to be used in TLS negotiation for PrometheusMetricsProvider. - Default value is Jetty default. - - - -### Communication using the Netty framework - -[Netty](http://netty.io) -is an NIO based client/server communication framework, it -simplifies (over NIO being used directly) many of the -complexities of network level communication for java -applications. Additionally the Netty framework has built -in support for encryption (SSL) and authentication -(certificates). These are optional features and can be -turned on or off individually. - -In versions 3.5+, a ZooKeeper server can use Netty -instead of NIO (default option) by setting the environment -variable **zookeeper.serverCnxnFactory** -to **org.apache.zookeeper.server.NettyServerCnxnFactory**; -for the client, set **zookeeper.clientCnxnSocket** -to **org.apache.zookeeper.ClientCnxnSocketNetty**. - - - -#### Quorum TLS - -*New in 3.5.5* - -Based on the Netty Framework ZooKeeper ensembles can be set up -to use TLS encryption in their communication channels. This section -describes how to set up encryption on the quorum communication. - -Please note that Quorum TLS encapsulates securing both leader election -and quorum communication protocols. - -1. Create SSL keystore JKS to store local credentials - -One keystore should be created for each ZK instance. - -In this example we generate a self-signed certificate and store it -together with the private key in `keystore.jks`. This is suitable for -testing purposes, but you probably need an official certificate to sign -your keys in a production environment. - -Please note that the alias (`-alias`) and the distinguished name (`-dname`) -must match the hostname of the machine that is associated with, otherwise -hostname verification won't work. - -``` -keytool -genkeypair -alias $(hostname -f) -keyalg RSA -keysize 2048 -dname "cn=$(hostname -f)" -keypass password -keystore keystore.jks -storepass password -``` - -2. Extract the signed public key (certificate) from keystore - -*This step might only necessary for self-signed certificates.* - -``` -keytool -exportcert -alias $(hostname -f) -keystore keystore.jks -file $(hostname -f).cer -rfc -``` - -3. Create SSL truststore JKS containing certificates of all ZooKeeper instances - -The same truststore (storing all accepted certs) should be shared on -participants of the ensemble. You need to use different aliases to store -multiple certificates in the same truststore. Name of the aliases doesn't matter. - -``` -keytool -importcert -alias [host1..3] -file [host1..3].cer -keystore truststore.jks -storepass password -``` - -4. You need to use `NettyServerCnxnFactory` as serverCnxnFactory, because SSL is not supported by NIO. -Add the following configuration settings to your `zoo.cfg` config file: - -``` -sslQuorum=true -serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory -ssl.quorum.keyStore.location=/path/to/keystore.jks -ssl.quorum.keyStore.password=password -ssl.quorum.trustStore.location=/path/to/truststore.jks -ssl.quorum.trustStore.password=password -``` - -5. Verify in the logs that your ensemble is running on TLS: - -``` -INFO [main:QuorumPeer@1789] - Using TLS encrypted quorum communication -INFO [main:QuorumPeer@1797] - Port unification disabled -... -INFO [QuorumPeerListener:QuorumCnxManager$Listener@877] - Creating TLS-only quorum server socket -``` - - - -#### Upgrading existing non-TLS cluster with no downtime - -*New in 3.5.5* - -Here are the steps needed to upgrade an already running ZooKeeper ensemble -to TLS without downtime by taking advantage of port unification functionality. - -1. Create the necessary keystores and truststores for all ZK participants as described in the previous section - -2. Add the following config settings and restart the first node - -``` -sslQuorum=false -portUnification=true -serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory -ssl.quorum.keyStore.location=/path/to/keystore.jks -ssl.quorum.keyStore.password=password -ssl.quorum.trustStore.location=/path/to/truststore.jks -ssl.quorum.trustStore.password=password -``` - -Note that TLS is not yet enabled, but we turn on port unification. - -3. Repeat step #2 on the remaining nodes. Verify that you see the following entries in the logs: - -``` -INFO [main:QuorumPeer@1791] - Using insecure (non-TLS) quorum communication -INFO [main:QuorumPeer@1797] - Port unification enabled -... -INFO [QuorumPeerListener:QuorumCnxManager$Listener@874] - Creating TLS-enabled quorum server socket -``` - -You should also double-check after each node restart that the quorum become healthy again. - -4. Enable Quorum TLS on each node and do rolling restart: - -``` -sslQuorum=true -portUnification=true -``` - -5. Once you verified that your entire ensemble is running on TLS, you could disable port unification -and do another rolling restart - -``` -sslQuorum=true -portUnification=false -``` - - - - -### ZooKeeper Commands - - - -#### The Four Letter Words - -ZooKeeper responds to a small set of commands. Each command is -composed of four letters. You issue the commands to ZooKeeper via telnet -or nc, at the client port. - -Three of the more interesting commands: "stat" gives some -general information about the server and connected clients, -while "srvr" and "cons" give extended details on server and -connections respectively. - -**New in 3.5.3:** -Four Letter Words need to be explicitly white listed before using. -Please refer to **4lw.commands.whitelist** -described in [cluster configuration section](#sc_clusterOptions) for details. -Moving forward, Four Letter Words will be deprecated, please use -[AdminServer](#sc_adminserver) instead. - -* *conf* : - **New in 3.3.0:** Print - details about serving configuration. - -* *cons* : - **New in 3.3.0:** List - full connection/session details for all clients connected - to this server. Includes information on numbers of packets - received/sent, session id, operation latencies, last - operation performed, etc... - -* *crst* : - **New in 3.3.0:** Reset - connection/session statistics for all connections. - -* *dump* : - Lists the outstanding sessions and ephemeral nodes. - -* *envi* : - Print details about serving environment - -* *ruok* : - Tests if the server is running in a non-error state. - When the whitelist enables ruok, the server will respond with `imok` - if it is running, otherwise it will not respond at all. - When ruok is disabled, the server responds with: - "ruok is not executed because it is not in the whitelist." - A response of "imok" does not necessarily indicate that the - server has joined the quorum, just that the server process is active - and bound to the specified client port. Use "stat" for details on - state wrt quorum and client connection information. - -* *srst* : - Reset server statistics. - -* *srvr* : - **New in 3.3.0:** Lists - full details for the server. - -* *stat* : - Lists brief details for the server and connected - clients. - -* *wchs* : - **New in 3.3.0:** Lists - brief information on watches for the server. - -* *wchc* : - **New in 3.3.0:** Lists - detailed information on watches for the server, by - session. This outputs a list of sessions(connections) - with associated watches (paths). Note, depending on the - number of watches this operation may be expensive (ie - impact server performance), use it carefully. - -* *dirs* : - **New in 3.5.1:** - Shows the total size of snapshot and log files in bytes - -* *wchp* : - **New in 3.3.0:** Lists - detailed information on watches for the server, by path. - This outputs a list of paths (znodes) with associated - sessions. Note, depending on the number of watches this - operation may be expensive (ie impact server performance), - use it carefully. - -* *mntr* : - **New in 3.4.0:** Outputs a list - of variables that could be used for monitoring the health of the cluster. - - - $ echo mntr | nc localhost 2185 - zk_version 3.4.0 - zk_avg_latency 0.7561 - be account to four decimal places - zk_max_latency 0 - zk_min_latency 0 - zk_packets_received 70 - zk_packets_sent 69 - zk_outstanding_requests 0 - zk_server_state leader - zk_znode_count 4 - zk_watch_count 0 - zk_ephemerals_count 0 - zk_approximate_data_size 27 - zk_learners 4 - only exposed by the Leader - zk_synced_followers 4 - only exposed by the Leader - zk_pending_syncs 0 - only exposed by the Leader - zk_open_file_descriptor_count 23 - only available on Unix platforms - zk_max_file_descriptor_count 1024 - only available on Unix platforms - - -The output is compatible with java properties format and the content -may change over time (new keys added). Your scripts should expect changes. -ATTENTION: Some of the keys are platform specific and some of the keys are only exported by the Leader. -The output contains multiple lines with the following format: - - - key \t value - - -* *isro* : - **New in 3.4.0:** Tests if - server is running in read-only mode. The server will respond with - "ro" if in read-only mode or "rw" if not in read-only mode. - -* *hash* : - **New in 3.6.0:** - Return the latest history of the tree digest associated with zxid. - -* *gtmk* : - Gets the current trace mask as a 64-bit signed long value in - decimal format. See `stmk` for an explanation of - the possible values. - -* *stmk* : - Sets the current trace mask. The trace mask is 64 bits, - where each bit enables or disables a specific category of trace - logging on the server. Logback must be configured to enable - `TRACE` level first in order to see trace logging - messages. The bits of the trace mask correspond to the following - trace logging categories. - - | Trace Mask Bit Values | | - |-----------------------|---------------------| - | 0b0000000000 | Unused, reserved for future use. | - | 0b0000000010 | Logs client requests, excluding ping requests. | - | 0b0000000100 | Unused, reserved for future use. | - | 0b0000001000 | Logs client ping requests. | - | 0b0000010000 | Logs packets received from the quorum peer that is the current leader, excluding ping requests. | - | 0b0000100000 | Logs addition, removal and validation of client sessions. | - | 0b0001000000 | Logs delivery of watch events to client sessions. | - | 0b0010000000 | Logs ping packets received from the quorum peer that is the current leader. | - | 0b0100000000 | Unused, reserved for future use. | - | 0b1000000000 | Unused, reserved for future use. | - - All remaining bits in the 64-bit value are unused and - reserved for future use. Multiple trace logging categories are - specified by calculating the bitwise OR of the documented values. - The default trace mask is 0b0100110010. Thus, by default, trace - logging includes client requests, packets received from the - leader and sessions. - To set a different trace mask, send a request containing the - `stmk` four-letter word followed by the trace - mask represented as a 64-bit signed long value. This example uses - the Perl `pack` function to construct a trace - mask that enables all trace logging categories described above and - convert it to a 64-bit signed long value with big-endian byte - order. The result is appended to `stmk` and sent - to the server using netcat. The server responds with the new - trace mask in decimal format. - - - $ perl -e "print 'stmk', pack('q>', 0b0011111010)" | nc localhost 2181 - 250 - - -Here's an example of the **ruok** -command: - - - $ echo ruok | nc 127.0.0.1 5111 - imok - - - - -#### The AdminServer - -**New in 3.5.0:** The AdminServer is -an embedded Jetty server that provides an HTTP interface to the four-letter -word commands. By default, the server is started on port 8080, -and commands are issued by going to the URL "/commands/\[command name]", -e.g., http://localhost:8080/commands/stat. The command response is -returned as JSON. Unlike the original protocol, commands are not -restricted to four-letter names, and commands can have multiple names; -for instance, "stmk" can also be referred to as "set_trace_mask". To -view a list of all available commands, point a browser to the URL -/commands (e.g., http://localhost:8080/commands). See the [AdminServer configuration options](#sc_adminserver_config) -for how to change the port and URLs. - -The AdminServer is enabled by default, but can be disabled by either: - -* Setting the zookeeper.admin.enableServer system - property to false. -* Removing Jetty from the classpath. (This option is - useful if you would like to override ZooKeeper's jetty - dependency.) - -Note that the TCP four-letter word interface is still available if -the AdminServer is disabled. - -##### Configuring AdminServer for SSL/TLS -- Generating the **keystore.jks** and **truststore.jks** which can be found in the [Quorum TLS](http://zookeeper.apache.org/doc/current/zookeeperAdmin.html#Quorum+TLS). -- Add the following configuration settings to the `zoo.cfg` config file: - -``` -admin.portUnification=true -ssl.quorum.keyStore.location=/path/to/keystore.jks -ssl.quorum.keyStore.password=password -ssl.quorum.trustStore.location=/path/to/truststore.jks -ssl.quorum.trustStore.password=password -``` -- Verify that the following entries in the logs can be seen: - -``` -2019-08-03 15:44:55,213 [myid:] - INFO [main:JettyAdminServer@123] - Successfully loaded private key from /data/software/cert/keystore.jks -2019-08-03 15:44:55,213 [myid:] - INFO [main:JettyAdminServer@124] - Successfully loaded certificate authority from /data/software/cert/truststore.jks - -2019-08-03 15:44:55,403 [myid:] - INFO [main:JettyAdminServer@170] - Started AdminServer on address 0.0.0.0, port 8080 and command URL /commands -``` - -###### Restrict TLS protocols and cipher suites for SSL/TLS negotiation in AdminServer - -From 3.10.0 AdminServer uses the following already existing properties: - -* **ssl.quorum.enabledProtocols** to specify the enabled protocols, -* **ssl.quorum.ciphersuites** to specify the enabled cipher suites. - -Add the following configuration settings to the `zoo.cfg` config file: - -``` -ssl.quorum.enabledProtocols=TLSv1.2,TLSv1.3 -ssl.quorum.ciphersuites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 -``` - -To verify raise the log level of JettyAdminServer to DEBUG and check that the following entries can be seen in the logs: - -``` -2026-03-11 11:38:01,102 [myid:] - DEBUG [main:o.a.z.s.a.JettyAdminServer@159] - Setting enabled protocols: 'TLSv1.2,TLSv1.3' -2026-03-11 11:38:01,102 [myid:] - DEBUG [main:o.a.z.s.a.JettyAdminServer@166] - Setting enabled cipherSuites: 'TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384' -``` - -Available commands include: - -* *connection_stat_reset/crst*: - Reset all client connection statistics. - No new fields returned. - -* *configuration/conf/config* : - Print basic details about serving configuration, e.g. - client port, absolute path to data directory. - -* *connections/cons* : - Information on client connections to server. - Note, depending on the number of client connections this operation may be expensive - (i.e. impact server performance). - Returns "connections", a list of connection info objects. - -* *hash*: - Txn digests in the historical digest list. - One is recorded every 128 transactions. - Returns "digests", a list to transaction digest objects. - -* *dirs* : - Information on logfile directory and snapshot directory - size in bytes. - Returns "datadir_size" and "logdir_size". - -* *dump* : - Information on session expirations and ephemerals. - Note, depending on the number of global sessions and ephemerals - this operation may be expensive (i.e. impact server performance). - Returns "expiry_time_to_session_ids" and "session_id_to_ephemeral_paths" as maps. - -* *environment/env/envi* : - All defined environment variables. - Returns each as its own field. - -* *get_trace_mask/gtmk* : - The current trace mask. Read-only version of *set_trace_mask*. - See the description of the four letter command *stmk* for - more details. - Returns "tracemask". - -* *initial_configuration/icfg* : - Print the text of the configuration file used to start the peer. - Returns "initial_configuration". - -* *is_read_only/isro* : - A true/false if this server is in read-only mode. - Returns "read_only". - -* *last_snapshot/lsnp* : - Information of the last snapshot that zookeeper server has finished saving to disk. - If called during the initial time period between the server starting up - and the server finishing saving its first snapshot, the command returns the - information of the snapshot read when starting up the server. - Returns "zxid" and "timestamp", the latter using a time unit of seconds. - -* *leader/lead* : - If the ensemble is configured in quorum mode then emits the current leader - status of the peer and the current leader location. - Returns "is_leader", "leader_id", and "leader_ip". - -* *monitor/mntr* : - Emits a wide variety of useful info for monitoring. - Includes performance stats, information about internal queues, and - summaries of the data tree (among other things). - Returns each as its own field. - -* *observer_connection_stat_reset/orst* : - Reset all observer connection statistics. Companion command to *observers*. - No new fields returned. - -* *restore/rest* : - Restore database from snapshot input stream on the current server. - Returns the following data in response payload: - "last_zxid": String - Note: this API is rate-limited (once every 5 mins by default) to protect the server - from being over-loaded. - -* *ruok* : - No-op command, check if the server is running. - A response does not necessarily indicate that the - server has joined the quorum, just that the admin server - is active and bound to the specified port. - No new fields returned. - -* *set_trace_mask/stmk* : - Sets the trace mask (as such, it requires a parameter). - Write version of *get_trace_mask*. - See the description of the four letter command *stmk* for - more details. - Returns "tracemask". - -* *server_stats/srvr* : - Server information. - Returns multiple fields giving a brief overview of server state. - -* *shed_connections/shed* : - Attempts to shed approximately the specified percentage of connections. - Requires "percentage": (int) - Returns "connections_shed" (int) and "percentage_requested" (int) - -* *snapshot/snap* : - Takes a snapshot of the current server in the datadir and stream out data. - Optional query parameter: - "streaming": Boolean (defaults to true if the parameter is not present) - Returns the following via Http headers: - "last_zxid": String - "snapshot_size": String - Note: this API is rate-limited (once every 5 mins by default) to protect the server - from being over-loaded. - -* *stats/stat* : - Same as *server_stats* but also returns the "connections" field (see *connections* - for details). - Note, depending on the number of client connections this operation may be expensive - (i.e. impact server performance). - -* *stat_reset/srst* : - Resets server statistics. This is a subset of the information returned - by *server_stats* and *stats*. - No new fields returned. - -* *observers/obsr* : - Information on observer connections to server. - Always available on a Leader, available on a Follower if its - acting as a learner master. - Returns "synced_observers" (int) and "observers" (list of per-observer properties). - -* *system_properties/sysp* : - All defined system properties. - Returns each as its own field. - -* *voting_view* : - Provides the current voting members in the ensemble. - Returns "current_config" as a map. - -* *watches/wchc* : - Watch information aggregated by session. - Note, depending on the number of watches this operation may be expensive - (i.e. impact server performance). - Returns "session_id_to_watched_paths" as a map. - -* *watches_by_path/wchp* : - Watch information aggregated by path. - Note, depending on the number of watches this operation may be expensive - (i.e. impact server performance). - Returns "path_to_session_ids" as a map. - -* *watch_summary/wchs* : - Summarized watch information. - Returns "num_total_watches", "num_paths", and "num_connections". - -* *zabstate* : - The current phase of Zab protocol that peer is running and whether it is a - voting member. - Peers can be in one of these phases: ELECTION, DISCOVERY, SYNCHRONIZATION, BROADCAST. - Returns fields "voting" and "zabstate". - - - - -### Data File Management - -ZooKeeper stores its data in a data directory and its transaction -log in a transaction log directory. By default these two directories are -the same. The server can (and should) be configured to store the -transaction log files in a separate directory than the data files. -Throughput increases and latency decreases when transaction logs reside -on a dedicated log devices. - - - -#### The Data Directory - -This directory has two or three files in it: - -* *myid* - contains a single integer in - human readable ASCII text that represents the server id. -* *initialize* - presence indicates lack of - data tree is expected. Cleaned up once data tree is created. -* *snapshot.* - holds the fuzzy - snapshot of a data tree. - -Each ZooKeeper server has a unique id. This id is used in two -places: the *myid* file and the configuration file. -The *myid* file identifies the server that -corresponds to the given data directory. The configuration file lists -the contact information for each server identified by its server id. -When a ZooKeeper server instance starts, it reads its id from the -*myid* file and then, using that id, reads from the -configuration file, looking up the port on which it should -listen. - -The *snapshot* files stored in the data -directory are fuzzy snapshots in the sense that during the time the -ZooKeeper server is taking the snapshot, updates are occurring to the -data tree. The suffix of the *snapshot* file names -is the _zxid_, the ZooKeeper transaction id, of the -last committed transaction at the start of the snapshot. Thus, the -snapshot includes a subset of the updates to the data tree that -occurred while the snapshot was in process. The snapshot, then, may -not correspond to any data tree that actually existed, and for this -reason we refer to it as a fuzzy snapshot. Still, ZooKeeper can -recover using this snapshot because it takes advantage of the -idempotent nature of its updates. By replaying the transaction log -against fuzzy snapshots ZooKeeper gets the state of the system at the -end of the log. - - - -#### The Log Directory - -The Log Directory contains the ZooKeeper transaction logs. -Before any update takes place, ZooKeeper ensures that the transaction -that represents the update is written to non-volatile storage. A new -log file is started when the number of transactions written to the -current log file reaches a (variable) threshold. The threshold is -computed using the same parameter which influences the frequency of -snapshotting (see snapCount and snapSizeLimitInKb above). The log file's -suffix is the first zxid written to that log. - - - -#### File Management - -The format of snapshot and log files does not change between -standalone ZooKeeper servers and different configurations of -replicated ZooKeeper servers. Therefore, you can pull these files from -a running replicated ZooKeeper server to a development machine with a -stand-alone ZooKeeper server for troubleshooting. - -Using older log and snapshot files, you can look at the previous -state of ZooKeeper servers and even restore that state. - -The ZooKeeper server creates snapshot and log files, but -never deletes them. The retention policy of the data and log -files is implemented outside of the ZooKeeper server. The -server itself only needs the latest complete fuzzy snapshot, all log -files following it, and the last log file preceding it. The latter -requirement is necessary to include updates which happened after this -snapshot was started but went into the existing log file at that time. -This is possible because snapshotting and rolling over of logs -proceed somewhat independently in ZooKeeper. See the -[maintenance](#sc_maintenance) section in -this document for more details on setting a retention policy -and maintenance of ZooKeeper storage. - -###### Note ->The data stored in these files is not encrypted. In the case of -storing sensitive data in ZooKeeper, necessary measures need to be -taken to prevent unauthorized access. Such measures are external to -ZooKeeper (e.g., control access to the files) and depend on the -individual settings in which it is being deployed. - - - -#### Recovery - TxnLogToolkit -More details can be found in [this](http://zookeeper.apache.org/doc/current/zookeeperTools.html#zkTxnLogToolkit) - - - -### Things to Avoid - -Here are some common problems you can avoid by configuring -ZooKeeper correctly: - -* *inconsistent lists of servers* : - The list of ZooKeeper servers used by the clients must match - the list of ZooKeeper servers that each ZooKeeper server has. - Things work okay if the client list is a subset of the real list, - but things will really act strange if clients have a list of - ZooKeeper servers that are in different ZooKeeper clusters. Also, - the server lists in each Zookeeper server configuration file - should be consistent with one another. - -* *incorrect placement of transaction log* : - The most performance critical part of ZooKeeper is the - transaction log. ZooKeeper syncs transactions to media before it - returns a response. A dedicated transaction log device is key to - consistent good performance. Putting the log on a busy device will - adversely affect performance. If you only have one storage device, - increase the snapCount so that snapshot files are generated less often; - it does not eliminate the problem, but it makes more resources available - for the transaction log. - -* *incorrect Java heap size* : - You should take special care to set your Java max heap size - correctly. In particular, you should not create a situation in - which ZooKeeper swaps to disk. The disk is death to ZooKeeper. - Everything is ordered, so if processing one request swaps the - disk, all other queued requests will probably do the same. the - disk. DON'T SWAP. - Be conservative in your estimates: if you have 4G of RAM, do - not set the Java max heap size to 6G or even 4G. For example, it - is more likely you would use a 3G heap for a 4G machine, as the - operating system and the cache also need memory. The best and only - recommend practice for estimating the heap size your system needs - is to run load tests, and then make sure you are well below the - usage limit that would cause the system to swap. - -* *Publicly accessible deployment* : - A ZooKeeper ensemble is expected to operate in a trusted computing environment. - It is thus recommended deploying ZooKeeper behind a firewall. - - - -### Best Practices - -For best results, take note of the following list of good -Zookeeper practices: - -For multi-tenant installations see the [section](zookeeperProgrammers.html#ch_zkSessions) -detailing ZooKeeper "chroot" support, this can be very useful -when deploying many applications/services interfacing to a -single ZooKeeper cluster. diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperAuditLogs.md b/zookeeper-docs/src/main/resources/markdown/zookeeperAuditLogs.md deleted file mode 100644 index b3954ad676d..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperAuditLogs.md +++ /dev/null @@ -1,140 +0,0 @@ - - -# ZooKeeper Audit Logging - -* [ZooKeeper Audit Logs](#ch_auditLogs) -* [ZooKeeper Audit Log Configuration](#ch_reconfig_format) -* [Who is taken as user in audit logs?](#ch_zkAuditUser) - - -## ZooKeeper Audit Logs - -Apache ZooKeeper supports audit logs from version 3.6.0. By default audit logs are disabled. To enable audit logs - configure audit.enable=true in conf/zoo.cfg. Audit logs are not logged on all the ZooKeeper servers, but logged only on the servers where client is connected as depicted in below figure. - -![Audit Logs](images/zkAuditLogs.jpg) - - -The audit log captures detailed information for the operations that are selected to be audited. The audit information is written as a set of key=value pairs for the following keys - -| Key | Value | -| ----- | ----- | -|session | client session id | -|user | comma separated list of users who are associate with a client session. For more on this, see [Who is taken as user in audit logs](#ch_zkAuditUser). -|ip | client IP address -|operation | any one of the selected operations for audit. Possible values are(serverStart, serverStop, create, delete, setData, setAcl, multiOperation, reconfig, ephemeralZNodeDeleteOnSessionClose) -|znode | path of the znode -|znode type | type of znode in case of creation operation -|acl | String representation of znode ACL like cdrwa(create, delete,read, write, admin). This is logged only for setAcl operation -|result | result of the operation. Possible values are (success/failure/invoked). Result "invoked" is used for serverStop operation because stop is logged before ensuring that server actually stopped. - -Below are sample audit logs for all operations, where client is connected from 192.168.1.2, client principal is zkcli@HADOOP.COM, server principal is zookeeper/192.168.1.3@HADOOP.COM - - user=zookeeper/192.168.1.3 operation=serverStart result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/a znode_type=persistent result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/a znode_type=persistent result=failure - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/a result=failure - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/a result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=failure - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/b znode_type=persistent result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/b result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/b result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=multiOperation result=failure - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/a result=failure - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/a result=success - session=0x19344730001 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/ephemral znode_type=ephemral result=success - session=0x19344730001 user=zookeeper/192.168.1.3 operation=ephemeralZNodeDeletionOnSessionCloseOrExpire znode=/ephemral result=success - session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=reconfig znode=/zookeeper/config result=success - user=zookeeper/192.168.1.3 operation=serverStop result=invoked - - - -## ZooKeeper Audit Log Configuration - -By default audit logs are disabled. To enable audit logs configure `audit.enable=true` in _conf/zoo.cfg_. -Audit logging is done using logback. Following is the default logback configuration for audit logs in `conf/logback.xml` - - - - -Change above configuration to customize the auditlog file, number of backups, max file size, custom audit logger etc. - - - -## Who is taken as user in audit logs? - -By default there are only four authentication provider: - -* IPAuthenticationProvider -* SASLAuthenticationProvider -* X509AuthenticationProvider -* DigestAuthenticationProvider - -User is decided based on the configured authentication provider: - -* When IPAuthenticationProvider is configured then authenticated IP is taken as user -* When SASLAuthenticationProvider is configured then client principal is taken as user -* When X509AuthenticationProvider is configured then client certificate is taken as user -* When DigestAuthenticationProvider is configured then authenticated user is user - -Custom authentication provider can override org.apache.zookeeper.server.auth.AuthenticationProvider.getUserName(String id) - to provide user name. If authentication provider is not overriding this method then whatever is stored in - org.apache.zookeeper.data.Id.id is taken as user. - Generally only user name is stored in this field but it is up to the custom authentication provider what they store in it. - For audit logging value of org.apache.zookeeper.data.Id.id would be taken as user. - -In ZooKeeper Server not all the operations are done by clients but some operations are done by the server itself. For example when client closes the session, ephemeral znodes are deleted by the Server. These deletion are not done by clients directly but it is done the server itself these are called system operations. For these system operations the user associated with the ZooKeeper server are taken as user while audit logging these operations. For example if in ZooKeeper server principal is zookeeper/hadoop.hadoop.com@HADOOP.COM then this becomes the system user and all the system operations will be logged with this user name. - - user=zookeeper/hadoop.hadoop.com@HADOOP.COM operation=serverStart result=success - - -If there is no user associate with ZooKeeper server then the user who started the ZooKeeper server is taken as the user. For example if server started by root then root is taken as the system user - - user=root operation=serverStart result=success - - -Single client can attach multiple authentication schemes to a session, in this case all authenticated schemes will taken taken as user and will be presented as comma separated list. For example if a client is authenticate with principal zkcli@HADOOP.COM and ip 127.0.0.1 then create znode audit log will be as: - - session=0x10c0bcb0000 user=zkcli@HADOOP.COM,127.0.0.1 ip=127.0.0.1 operation=create znode=/a result=success - - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperCLI.md b/zookeeper-docs/src/main/resources/markdown/zookeeperCLI.md deleted file mode 100644 index aeccf1dcfce..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperCLI.md +++ /dev/null @@ -1,574 +0,0 @@ - - -# ZooKeeper-cli: the ZooKeeper command line interface - -## Pre-requisites -Enter into the ZooKeeper-cli - -```bash -# connect to the localhost with the default port:2181 -bin/zkCli.sh -# connect to the remote host with timeout:3s -bin/zkCli.sh -timeout 3000 -server remoteIP:2181 -# connect to the remote host with -waitforconnection option to wait for connection success before executing commands -bin/zkCli.sh -waitforconnection -timeout 3000 -server remoteIP:2181 -# connect with a custom client configuration properties file -bin/zkCli.sh -client-configuration /path/to/client.properties -``` -## help -Showing helps about ZooKeeper commands - -```bash -[zkshell: 1] help -# a sample one -[zkshell: 2] h -ZooKeeper -server host:port cmd args - addauth scheme auth - close - config [-c] [-w] [-s] - connect host:port - create [-s] [-e] [-c] [-t ttl] path [data] [acl] - delete [-v version] path - deleteall path - delquota [-n|-b|-N|-B] path - exit - get [-s] [-w] path - getAcl [-s] path - getAllChildrenNumber path - getEphemerals path - history - listquota path - ls [-s] [-w] [-R] path - printwatches on|off - quit - reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*] - redo cmdno - removewatches path [-c|-d|-a] [-l] - set [-s] [-v version] path data - setAcl [-s] [-v version] [-R] path acl - setquota -n|-b|-N|-B val path - stat [-w] path - sync path - version -``` - -## addauth -Add a authorized user for ACL - -```bash -[zkshell: 9] getAcl /acl_digest_test - Insufficient permission : /acl_digest_test -[zkshell: 10] addauth digest user1:12345 -[zkshell: 11] getAcl /acl_digest_test - 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= - : cdrwa -# add a super user -# Notice:set zookeeper.DigestAuthenticationProvider -# e.g. zookeeper.DigestAuthenticationProvider.superDigest=zookeeper:qW/HnTfCSoQpB5G8LgkwT3IbiFc= -[zkshell: 12] addauth digest zookeeper:admin -``` - -## close -Close this client/session. - -```bash -[zkshell: 0] close - 2019-03-09 06:42:22,178 [myid:] - INFO [main-EventThread:ClientCnxn$EventThread@528] - EventThread shut down for session: 0x10007ab7c550006 - 2019-03-09 06:42:22,179 [myid:] - INFO [main:ZooKeeper@1346] - Session: 0x10007ab7c550006 closed -``` - -## config -Showing the config of quorum membership - -```bash -[zkshell: 17] config - server.1=[2001:db8:1:0:0:242:ac11:2]:2888:3888:participant - server.2=[2001:db8:1:0:0:242:ac11:2]:12888:13888:participant - server.3=[2001:db8:1:0:0:242:ac11:2]:22888:23888:participant - version=0 -``` -## connect -Connect a ZooKeeper server. - -```bash -[zkshell: 4] connect - 2019-03-09 06:43:33,179 [myid:localhost:2181] - INFO [main-SendThread(localhost:2181):ClientCnxn$SendThread@986] - Socket connection established, initiating session, client: /127.0.0.1:35144, server: localhost/127.0.0.1:2181 - 2019-03-09 06:43:33,189 [myid:localhost:2181] - INFO [main-SendThread(localhost:2181):ClientCnxn$SendThread@1421] - Session establishment complete on server localhost/127.0.0.1:2181, sessionid = 0x10007ab7c550007, negotiated timeout = 30000 - connect "localhost:2181,localhost:2182,localhost:2183" - -# connect a remote server -[zkshell: 5] connect remoteIP:2181 -``` -## create -Create a znode. - -```bash -# create a persistent_node -[zkshell: 7] create /persistent_node - Created /persistent_node - -# create a ephemeral node -[zkshell: 8] create -e /ephemeral_node mydata - Created /ephemeral_node - -# create the persistent-sequential node -[zkshell: 9] create -s /persistent_sequential_node mydata - Created /persistent_sequential_node0000000176 - -# create the ephemeral-sequential_node -[zkshell: 10] create -s -e /ephemeral_sequential_node mydata - Created /ephemeral_sequential_node0000000174 - -# create a node with the schema -[zkshell: 11] create /zk-node-create-schema mydata digest:user1:+owfoSBn/am19roBPzR1/MfCblE=:crwad - Created /zk-node-create-schema -[zkshell: 12] addauth digest user1:12345 -[zkshell: 13] getAcl /zk-node-create-schema - 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= - : cdrwa - -# create the container node.When the last child of a container is deleted,the container becomes to be deleted -[zkshell: 14] create -c /container_node mydata - Created /container_node -[zkshell: 15] create -c /container_node/child_1 mydata - Created /container_node/child_1 -[zkshell: 16] create -c /container_node/child_2 mydata - Created /container_node/child_2 -[zkshell: 17] delete /container_node/child_1 -[zkshell: 18] delete /container_node/child_2 -[zkshell: 19] get /container_node - org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /container_node - -# create the ttl node. -# set zookeeper.extendedTypesEnabled=true -# Otherwise:KeeperErrorCode = Unimplemented for /ttl_node -[zkshell: 20] create -t 3000 /ttl_node mydata - Created /ttl_node -# after 3s later -[zkshell: 21] get /ttl_node - org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /ttl_node -``` -## delete -Delete a node with a specific path - -```bash -[zkshell: 2] delete /config/topics/test -[zkshell: 3] ls /config/topics/test - Node does not exist: /config/topics/test -``` - -## deleteall -Delete all nodes under a specific path - -```bash -zkshell: 1] ls /config - [changes, clients, topics] -[zkshell: 2] deleteall /config -[zkshell: 3] ls /config - Node does not exist: /config -``` - -## delquota -Delete the quota under a path - -```bash -[zkshell: 1] delquota /quota_test -[zkshell: 2] listquota /quota_test - absolute path is /zookeeper/quota/quota_test/zookeeper_limits - quota for /quota_test does not exist. -[zkshell: 3] delquota -n /c1 -[zkshell: 4] delquota -N /c2 -[zkshell: 5] delquota -b /c3 -[zkshell: 6] delquota -B /c4 - -``` -## get -Get the data of the specific path - -```bash -[zkshell: 10] get /latest_producer_id_block - {"version":1,"broker":0,"block_start":"0","block_end":"999"} - -# -s to show the stat -[zkshell: 11] get -s /latest_producer_id_block - {"version":1,"broker":0,"block_start":"0","block_end":"999"} - cZxid = 0x90000009a - ctime = Sat Jul 28 08:14:09 UTC 2018 - mZxid = 0x9000000a2 - mtime = Sat Jul 28 08:14:12 UTC 2018 - pZxid = 0x90000009a - cversion = 0 - dataVersion = 1 - aclVersion = 0 - ephemeralOwner = 0x0 - dataLength = 60 - numChildren = 0 - -# -w to set a watch on the data change, Notice: turn on the printwatches -[zkshell: 12] get -w /latest_producer_id_block - {"version":1,"broker":0,"block_start":"0","block_end":"999"} -[zkshell: 13] set /latest_producer_id_block mydata - WATCHER:: - WatchedEvent state:SyncConnected type:NodeDataChanged path:/latest_producer_id_block -``` - -## getAcl -Get the ACL permission of one path - -```bash -[zkshell: 4] create /acl_test mydata ip:127.0.0.1:crwda - Created /acl_test -[zkshell: 5] getAcl /acl_test - 'ip,'127.0.0.1 - : cdrwa - [zkshell: 6] getAcl /testwatch - 'world,'anyone - : cdrwa -``` -## getAllChildrenNumber -Get all numbers of children nodes under a specific path - -```bash -[zkshell: 1] getAllChildrenNumber / - 73779 -[zkshell: 2] getAllChildrenNumber /ZooKeeper - 2 -[zkshell: 3] getAllChildrenNumber /ZooKeeper/quota - 0 -``` -## getEphemerals -Get all the ephemeral nodes created by this session - -```bash -[zkshell: 1] create -e /test-get-ephemerals "ephemeral node" - Created /test-get-ephemerals -[zkshell: 2] getEphemerals - [/test-get-ephemerals] -[zkshell: 3] getEphemerals / - [/test-get-ephemerals] -[zkshell: 4] create -e /test-get-ephemerals-1 "ephemeral node" - Created /test-get-ephemerals-1 -[zkshell: 5] getEphemerals /test-get-ephemerals - test-get-ephemerals test-get-ephemerals-1 -[zkshell: 6] getEphemerals /test-get-ephemerals - [/test-get-ephemerals-1, /test-get-ephemerals] -[zkshell: 7] getEphemerals /test-get-ephemerals-1 - [/test-get-ephemerals-1] -``` - -## history -Showing the history about the recent 11 commands that you have executed - -```bash -[zkshell: 7] history - 0 - close - 1 - close - 2 - ls / - 3 - ls / - 4 - connect - 5 - ls / - 6 - ll - 7 - history -``` - -## listquota -Listing the quota of one path - -```bash -[zkshell: 1] listquota /c1 - absolute path is /zookeeper/quota/c1/zookeeper_limits - Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2 - Output stat for /c1 count=4,bytes=0 -``` - -## ls -Listing the child nodes of one path - -```bash -[zkshell: 36] ls /quota_test - [child_1, child_2, child_3] - -# -s to show the stat -[zkshell: 37] ls -s /quota_test - [child_1, child_2, child_3] - cZxid = 0x110000002d - ctime = Thu Mar 07 11:19:07 UTC 2019 - mZxid = 0x110000002d - mtime = Thu Mar 07 11:19:07 UTC 2019 - pZxid = 0x1100000033 - cversion = 3 - dataVersion = 0 - aclVersion = 0 - ephemeralOwner = 0x0 - dataLength = 0 - numChildren = 3 - -# -R to show the child nodes recursely -[zkshell: 38] ls -R /quota_test - /quota_test - /quota_test/child_1 - /quota_test/child_2 - /quota_test/child_3 - -# -w to set a watch on the child change,Notice: turn on the printwatches -[zkshell: 39] ls -w /brokers - [ids, seqid, topics] -[zkshell: 40] delete /brokers/ids - WATCHER:: - WatchedEvent state:SyncConnected type:NodeChildrenChanged path:/brokers -``` - -## printwatches -A switch to turn on/off whether printing watches or not. - -```bash -[zkshell: 0] printwatches - printwatches is on -[zkshell: 1] printwatches off -[zkshell: 2] printwatches - printwatches is off -[zkshell: 3] printwatches on -[zkshell: 4] printwatches - printwatches is on -``` - -## quit (or exit) -The `quit` or `exit` command can be used to quit the CLI windows. - -```bash -[zkshell: 1] quit -``` - -## reconfig -Change the membership of the ensemble during the runtime. - -Before using this cli,read the details in the [Dynamic Reconfiguration](zookeeperReconfig.html) about the reconfig feature,especially the "Security" part. - -Pre-requisites: - -1. set reconfigEnabled=true in the zoo.cfg - -2. add a super user or skipAcl,otherwise will get “Insufficient permission”. e.g. addauth digest zookeeper:admin - -```bash -# Change follower 2 to an observer and change its port from 2182 to 12182 -# Add observer 5 to the ensemble -# Remove Observer 4 from the ensemble -[zkshell: 1] reconfig --add 2=localhost:2781:2786:observer;12182 --add 5=localhost:2781:2786:observer;2185 -remove 4 - Committed new configuration: - server.1=localhost:2780:2785:participant;0.0.0.0:2181 - server.2=localhost:2781:2786:observer;0.0.0.0:12182 - server.3=localhost:2782:2787:participant;0.0.0.0:2183 - server.5=localhost:2784:2789:observer;0.0.0.0:2185 - version=1c00000002 - -# -members to appoint the membership -[zkshell: 2] reconfig -members server.1=localhost:2780:2785:participant;0.0.0.0:2181,server.2=localhost:2781:2786:observer;0.0.0.0:12182,server.3=localhost:2782:2787:participant;0.0.0.0:12183 - Committed new configuration: - server.1=localhost:2780:2785:participant;0.0.0.0:2181 - server.2=localhost:2781:2786:observer;0.0.0.0:12182 - server.3=localhost:2782:2787:participant;0.0.0.0:12183 - version=f9fe0000000c - -# Change the current config to the one in the myNewConfig.txt -# But only if current config version is 2100000010 -[zkshell: 3] reconfig -file /data/software/zookeeper/zookeeper-test/conf/myNewConfig.txt -v 2100000010 - Committed new configuration: - server.1=localhost:2780:2785:participant;0.0.0.0:2181 - server.2=localhost:2781:2786:observer;0.0.0.0:12182 - server.3=localhost:2782:2787:participant;0.0.0.0:2183 - server.5=localhost:2784:2789:observer;0.0.0.0:2185 - version=220000000c -``` - -## redo -Redo the cmd with the index from history. - -```bash -[zkshell: 4] history - 0 - ls / - 1 - get /consumers - 2 - get /hbase - 3 - ls /hbase - 4 - history -[zkshell: 5] redo 3 - [backup-masters, draining, flush-table-proc, hbaseid, master-maintenance, meta-region-server, namespace, online-snapshot, replication, rs, running, splitWAL, switch, table, table-lock] -``` - -## removewatches -Remove the watches under a node. - -```bash -[zkshell: 1] get -w /brokers - null -[zkshell: 2] removewatches /brokers - WATCHER:: - WatchedEvent state:SyncConnected type:DataWatchRemoved path:/brokers - -``` - -## set -Set/update the data on a path. - -```bash -[zkshell: 50] set /brokers myNewData - -# -s to show the stat of this node. -[zkshell: 51] set -s /quota_test mydata_for_quota_test - cZxid = 0x110000002d - ctime = Thu Mar 07 11:19:07 UTC 2019 - mZxid = 0x1100000038 - mtime = Thu Mar 07 11:42:41 UTC 2019 - pZxid = 0x1100000033 - cversion = 3 - dataVersion = 2 - aclVersion = 0 - ephemeralOwner = 0x0 - dataLength = 21 - numChildren = 3 - -# -v to set the data with CAS,the version can be found from dataVersion using stat. -[zkshell: 52] set -v 0 /brokers myNewData -[zkshell: 53] set -v 0 /brokers myNewData - version No is not valid : /brokers -``` - -## setAcl -Set the Acl permission for one node. - -```bash -[zkshell: 28] addauth digest user1:12345 -[zkshell: 30] setAcl /acl_auth_test auth:user1:12345:crwad -[zkshell: 31] getAcl /acl_auth_test - 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= - : cdrwa - -# -R to set Acl recursely -[zkshell: 32] ls /acl_auth_test - [child_1, child_2] -[zkshell: 33] getAcl /acl_auth_test/child_2 - 'world,'anyone - : cdrwa -[zkshell: 34] setAcl -R /acl_auth_test auth:user1:12345:crwad -[zkshell: 35] getAcl /acl_auth_test/child_2 - 'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= - : cdrwa - -# -v set Acl with the acl version which can be found from the aclVersion using the stat -[zkshell: 36] stat /acl_auth_test - cZxid = 0xf9fc0000001c - ctime = Tue Mar 26 16:50:58 CST 2019 - mZxid = 0xf9fc0000001c - mtime = Tue Mar 26 16:50:58 CST 2019 - pZxid = 0xf9fc0000001f - cversion = 2 - dataVersion = 0 - aclVersion = 3 - ephemeralOwner = 0x0 - dataLength = 0 - numChildren = 2 -[zkshell: 37] setAcl -v 3 /acl_auth_test auth:user1:12345:crwad -``` - -## setquota -Set the quota in one path. - -```bash -# -n to limit the number of child nodes(included itself) -[zkshell: 18] setquota -n 2 /quota_test -[zkshell: 19] create /quota_test/child_1 - Created /quota_test/child_1 -[zkshell: 20] create /quota_test/child_2 - Created /quota_test/child_2 -[zkshell: 21] create /quota_test/child_3 - Created /quota_test/child_3 -# Notice:don't have a hard constraint,just log the warning info - 2019-03-07 11:22:36,680 [myid:1] - WARN [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=3 limit=2 - 2019-03-07 11:22:41,861 [myid:1] - WARN [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=4 limit=2 - -# -b to limit the bytes(data length) of one path -[zkshell: 22] setquota -b 5 /brokers -[zkshell: 23] set /brokers "I_love_zookeeper" -# Notice:don't have a hard constraint,just log the warning info - WARN [CommitProcWorkThread-7:DataTree@379] - Quota exceeded: /brokers bytes=4206 limit=5 - -# -N count Hard quota -[zkshell: 3] create /c1 -Created /c1 -[zkshell: 4] setquota -N 2 /c1 -[zkshell: 5] listquota /c1 -absolute path is /zookeeper/quota/c1/zookeeper_limits -Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2 -Output stat for /c1 count=2,bytes=0 -[zkshell: 6] create /c1/ch-3 -Count Quota has exceeded : /c1/ch-3 - -# -B byte Hard quota -[zkshell: 3] create /c2 -[zkshell: 4] setquota -B 4 /c2 -[zkshell: 5] set /c2 "foo" -[zkshell: 6] set /c2 "foo-bar" -Bytes Quota has exceeded : /c2 -[zkshell: 7] get /c2 -foo -``` - -## stat -Showing the stat/metadata of one node. - -```bash -[zkshell: 1] stat /hbase - cZxid = 0x4000013d9 - ctime = Wed Jun 27 20:13:07 CST 2018 - mZxid = 0x4000013d9 - mtime = Wed Jun 27 20:13:07 CST 2018 - pZxid = 0x500000001 - cversion = 17 - dataVersion = 0 - aclVersion = 0 - ephemeralOwner = 0x0 - dataLength = 0 - numChildren = 15 -``` - -## sync -Sync the data of one node between leader and followers(Asynchronous sync) - -```bash -[zkshell: 14] sync / -[zkshell: 15] Sync is OK -``` - -## version -Show the version of the ZooKeeper client/CLI - -```bash -[zkshell: 1] version -ZooKeeper CLI version: 3.6.0-SNAPSHOT-29f9b2c1c0e832081f94d59a6b88709c5f1bb3ca, built on 05/30/2019 09:26 GMT -``` - -## whoami -Gives all authentication information added into the current session. - - [zkshell: 1] whoami - Auth scheme: User - ip: 127.0.0.1 - [zkshell: 2] addauth digest user1:12345 - [zkshell: 3] whoami - Auth scheme: User - ip: 127.0.0.1 - digest: user1 \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperHierarchicalQuorums.md b/zookeeper-docs/src/main/resources/markdown/zookeeperHierarchicalQuorums.md deleted file mode 100644 index e11f34f2b59..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperHierarchicalQuorums.md +++ /dev/null @@ -1,47 +0,0 @@ - - -# Introduction to hierarchical quorums - -This document gives an example of how to use hierarchical quorums. The basic idea is -very simple. First, we split servers into groups, and add a line for each group listing -the servers that form this group. Next we have to assign a weight to each server. - -The following example shows how to configure a system with three groups of three servers -each, and we assign a weight of 1 to each server: - - - group.1=1:2:3 - group.2=4:5:6 - group.3=7:8:9 - - weight.1=1 - weight.2=1 - weight.3=1 - weight.4=1 - weight.5=1 - weight.6=1 - weight.7=1 - weight.8=1 - weight.9=1 - - -When running the system, we are able to form a quorum once we have a majority of votes from -a majority of non-zero-weight groups. Groups that have zero weight are discarded and not -considered when forming quorums. Looking at the example, we are able to form a quorum once -we have votes from at least two servers from each of two different groups. - - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md b/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md deleted file mode 100644 index 171f33ddb4c..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperInternals.md +++ /dev/null @@ -1,382 +0,0 @@ - - -# ZooKeeper Internals - -* [Introduction](#ch_Introduction) -* [Atomic Broadcast](#sc_atomicBroadcast) - * [Guarantees, Properties, and Definitions](#sc_guaranteesPropertiesDefinitions) - * [Leader Activation](#sc_leaderElection) - * [Active Messaging](#sc_activeMessaging) - * [Summary](#sc_summary) - * [Comparisons](#sc_comparisons) -* [Consistency Guarantees](#sc_consistency) -* [Quorums](#sc_quorum) -* [Logging](#sc_logging) - * [Developer Guidelines](#sc_developerGuidelines) - * [Logging at the Right Level](#sc_rightLevel) - * [Use of Standard slf4j Idioms](#sc_slf4jIdioms) - - - -## Introduction - -This document contains information on the inner workings of ZooKeeper. -It discusses the following topics: - -* [Atomic Broadcast](#sc_atomicBroadcast) -* [Consistency Guarantees](#sc_consistency) -* [Quorums](#sc_quorum) -* [Logging](#sc_logging) - - - -## Atomic Broadcast - -At the heart of ZooKeeper is an atomic messaging system that keeps all of the servers in sync. - - - -### Guarantees, Properties, and Definitions - -The specific guarantees provided by the messaging system used by ZooKeeper are the following: - -* *_Reliable delivery_* : - If a message `m`, is delivered - by one server, message `m` will be eventually delivered by all servers. - -* *_Total order_* : - If a message `a` is - delivered before message `b` by one server, message `a` will be delivered before `b` by all - servers. - -* *_Causal order_* : - If a message `b` is sent after a message `a` has been delivered by the sender of `b`, - message `a` must be ordered before `b`. If a sender sends `c` after sending `b`, `c` must be ordered after `b`. - -The ZooKeeper messaging system also needs to be efficient, reliable, and easy to -implement and maintain. We make heavy use of messaging, so we need the system to -be able to handle thousands of requests per second. Although we can require at -least k+1 correct servers to send new messages, we must be able to recover from -correlated failures such as power outages. When we implemented the system we had -little time and few engineering resources, so we needed a protocol that is -accessible to engineers and is easy to implement. We found that our protocol -satisfied all of these goals. - -Our protocol assumes that we can construct point-to-point FIFO channels between -the servers. While similar services usually assume message delivery that can -lose or reorder messages, our assumption of FIFO channels is very practical -given that we use TCP for communication. Specifically we rely on the following property of TCP: - -* *_Ordered delivery_* : - Data is delivered in the same order it is sent and a message `m` is - delivered only after all messages sent before `m` have been delivered. - (The corollary to this is that if message `m` is lost all messages after `m` will be lost.) - -* *_No message after close_* : - Once a FIFO channel is closed, no messages will be received from it. - -FLP proved that consensus cannot be achieved in asynchronous distributed systems -if failures are possible. To ensure that we achieve consensus in the presence of failures -we use timeouts. However, we rely on time for liveness not for correctness. So, -if timeouts stop working (e.g., skewed clocks) the messaging system may -hang, but it will not violate its guarantees. - -When describing the ZooKeeper messaging protocol we will talk of packets, -proposals, and messages: - -* *_Packet_* : - a sequence of bytes sent through a FIFO channel. - -* *_Proposal_* : - a unit of agreement. Proposals are agreed upon by exchanging packets - with a quorum of ZooKeeper servers. Most proposals contain messages, however the - NEW_LEADER proposal is an example of a proposal that does not contain to a message. - -* *_Message_* : - a sequence of bytes to be atomically broadcast to all ZooKeeper - servers. A message put into a proposal and agreed upon before it is delivered. - -As stated above, ZooKeeper guarantees a total order of messages, and it also -guarantees a total order of proposals. ZooKeeper exposes the total ordering using -a ZooKeeper transaction id (_zxid_). All proposals will be stamped with a zxid when -it is proposed and exactly reflects the total ordering. Proposals are sent to all -ZooKeeper servers and committed when a quorum of them acknowledge the proposal. -If a proposal contains a message, the message will be delivered when the proposal -is committed. Acknowledgement means the server has recorded the proposal to persistent storage. -Our quorums have the requirement that any pair of quorum must have at least one server -in common. We ensure this by requiring that all quorums have size (_n/2+1_) where -n is the number of servers that make up a ZooKeeper service. - -The zxid has two parts: the epoch and a counter. In our implementation the zxid -is a 64-bit number. We use the high order 32-bits for the epoch and the low order -32-bits for the counter. Because zxid consists of two parts, zxid can be represented both as a -number and as a pair of integers, (_epoch, count_). The epoch number represents a -change in leadership. Each time a new leader comes into power it will have its -own epoch number. We have a simple algorithm to assign a unique zxid to a proposal: -the leader simply increments the zxid to obtain a unique zxid for each proposal. _Leadership activation will ensure that only one leader uses a given epoch, so our -simple algorithm guarantees that every proposal will have a unique id._ - -ZooKeeper messaging consists of two phases: - -* *_Leader activation_* : - In this phase a leader establishes the correct state of the system - and gets ready to start making proposals. - -* *_Active messaging_* : - In this phase a leader accepts messages to propose and coordinates message delivery. - -ZooKeeper is a holistic protocol. We do not focus on individual proposals, rather -look at the stream of proposals as a whole. Our strict ordering allows us to do this -efficiently and greatly simplifies our protocol. Leadership activation embodies -this holistic concept. A leader becomes active only when a quorum of followers -(The leader counts as a follower as well. You can always vote for yourself ) has synced -up with the leader, they have the same state. This state consists of all of the -proposals that the leader believes have been committed and the proposal to follow -the leader, the NEW_LEADER proposal. (Hopefully you are thinking to -yourself, _Does the set of proposals that the leader believes has been committed -include all the proposals that really have been committed?_ The answer is _yes_. -Below, we make clear why.) - - - -### Leader Activation - -Leader activation includes leader election (`FastLeaderElection`). -ZooKeeper messaging doesn't care about the exact method of electing a leader as long as the following holds: - -* The leader has seen the highest zxid of all the followers. -* A quorum of servers have committed to following the leader. - -Of these two requirements only the first, the highest zxid among the followers -needs to hold for correct operation. The second requirement, a quorum of followers, -just needs to hold with high probability. We are going to recheck the second requirement, -so if a failure happens during or after the leader election and quorum is lost, -we will recover by abandoning leader activation and running another election. - -After leader election a single server will be designated as a leader and start -waiting for followers to connect. The rest of the servers will try to connect to -the leader. The leader will sync up with the followers by sending any proposals they -are missing, or if a follower is missing too many proposals, it will send a full -snapshot of the state to the follower. - -There is a corner case in which a follower that has proposals, `U`, not seen -by a leader arrives. Proposals are seen in order, so the proposals of `U` will have a zxids -higher than zxids seen by the leader. The follower must have arrived after the -leader election, otherwise the follower would have been elected leader given that -it has seen a higher zxid. Since committed proposals must be seen by a quorum of -servers, and a quorum of servers that elected the leader did not see `U`, the proposals -of `U` have not been committed, so they can be discarded. When the follower connects -to the leader, the leader will tell the follower to discard `U`. - -A new leader establishes a zxid to start using for new proposals by getting the -epoch, e, of the highest zxid it has seen and setting the next zxid to use to be -(e+1, 0), after the leader syncs with a follower, it will propose a NEW_LEADER -proposal. Once the NEW_LEADER proposal has been committed, the leader will activate -and start receiving and issuing proposals. - -It all sounds complicated but here are the basic rules of operation during leader -activation: - -* A follower will ACK the NEW_LEADER proposal after it has synced with the leader. -* A follower will only ACK a NEW_LEADER proposal with a given zxid from a single server. -* A new leader will COMMIT the NEW_LEADER proposal when a quorum of followers has ACKed it. -* A follower will commit any state it received from the leader when the NEW_LEADER proposal is COMMIT. -* A new leader will not accept new proposals until the NEW_LEADER proposal has been COMMITTED. - -If leader election terminates erroneously, we don't have a problem since the -NEW_LEADER proposal will not be committed since the leader will not have quorum. -When this happens, the leader and any remaining followers will timeout and go back -to leader election. - - - -### Active Messaging - -Leader Activation does all the heavy lifting. Once the leader is coronated he can -start blasting out proposals. As long as he remains the leader no other leader can -emerge since no other leader will be able to get a quorum of followers. If a new -leader does emerge, -it means that the leader has lost quorum, and the new leader will clean up any -mess left over during her leadership activation. - -ZooKeeper messaging operates similar to a classic two-phase commit. - -![Two phase commit](images/2pc.jpg) - -All communication channels are FIFO, so everything is done in order. Specifically -the following operating constraints are observed: - -* The leader sends proposals to all followers using - the same order. Moreover, this order follows the order in which requests have been - received. Because we use FIFO channels this means that followers also receive proposals in order. -* Followers process messages in the order they are received. This - means that messages will be ACKed in order and the leader will receive ACKs from - followers in order, due to the FIFO channels. It also means that if message `m` - has been written to non-volatile storage, all messages that were proposed before - `m` have been written to non-volatile storage. -* The leader will issue a COMMIT to all followers as soon as a - quorum of followers have ACKed a message. Since messages are ACKed in order, - COMMITs will be sent by the leader as received by the followers in order. -* COMMITs are processed in order. Followers deliver a proposal - message when that proposal is committed. - - - -### Summary - -So there you go. Why does it work? Specifically, why does a set of proposals -believed by a new leader always contain any proposal that has actually been committed? -First, all proposals have a unique zxid, so unlike other protocols, we never have -to worry about two different values being proposed for the same zxid; followers -(a leader is also a follower) see and record proposals in order; proposals are -committed in order; there is only one active leader at a time since followers only -follow a single leader at a time; a new leader has seen all committed proposals -from the previous epoch since it has seen the highest zxid from a quorum of servers; -any uncommitted proposals from a previous epoch seen by a new leader will be committed -by that leader before it becomes active. - - - -### Comparisons - -Isn't this just Multi-Paxos? No, Multi-Paxos requires some way of assuring that -there is only a single coordinator. We do not count on such assurances. Instead -we use the leader activation to recover from leadership change or old leaders -believing they are still active. - -Isn't this just Paxos? Your active messaging phase looks just like phase 2 of Paxos? -Actually, to us active messaging looks just like 2 phase commit without the need to -handle aborts. Active messaging is different from both in the sense that it has -cross proposal ordering requirements. If we do not maintain strict FIFO ordering of -all packets, it all falls apart. Also, our leader activation phase is different from -both of them. In particular, our use of epochs allows us to skip blocks of uncommitted -proposals and to not worry about duplicate proposals for a given zxid. - - - - -## Consistency Guarantees - -The [consistency](https://jepsen.io/consistency) guarantees of ZooKeeper lie between sequential consistency and linearizability. In this section, we explain the exact consistency guarantees that ZooKeeper provides. - -Write operations in ZooKeeper are *linearizable*. In other words, each `write` will appear to take effect atomically at some point between when the client issues the request and receives the corresponding response. This means that the writes performed by all the clients in ZooKeeper can be totally ordered in such a way that respects the real-time ordering of these writes. However, merely stating that write operations are linearizable is meaningless unless we also talk about read operations. - -Read operations in ZooKeeper are *not linearizable* since they can return potentially stale data. This is because a `read` in ZooKeeper is not a quorum operation and a server will respond immediately to a client that is performing a `read`. ZooKeeper does this because it prioritizes performance over consistency for the read use case. However, reads in ZooKeeper are *sequentially consistent*, because `read` operations will appear to take effect in some sequential order that furthermore respects the order of each client's operations. A common pattern to work around this is to issue a `sync` before issuing a `read`. This too does **not** strictly guarantee up-to-date data because `sync` is [not currently a quorum operation](https://issues.apache.org/jira/browse/ZOOKEEPER-1675). To illustrate, consider a scenario where two servers simultaneously think they are the leader, something that could occur if the TCP connection timeout is smaller than `syncLimit * tickTime`. Note that this is [unlikely](https://www.amazon.com/ZooKeeper-Distributed-Coordination-Flavio-Junqueira/dp/1449361307) to occur in practice, but should be kept in mind nevertheless when discussing strict theoretical guarantees. Under this scenario, it is possible that the `sync` is served by the “leader” with stale data, thereby allowing the following `read` to be stale as well. The stronger guarantee of linearizability is provided if an actual quorum operation (e.g., a `write`) is performed before a `read`. - -Overall, the consistency guarantees of ZooKeeper are formally captured by the notion of [ordered sequential consistency](http://webee.technion.ac.il/people/idish/ftp/OSC-IPL17.pdf) or `OSC(U)` to be exact, which lies between sequential consistency and linearizability. - - - -## Quorums - -Atomic broadcast and leader election use the notion of quorum to guarantee a consistent -view of the system. By default, ZooKeeper uses majority quorums, which means that every -voting that happens in one of these protocols requires a majority to vote on. One example is -acknowledging a leader proposal: the leader can only commit once it receives an -acknowledgement from a quorum of servers. - -If we extract the properties that we really need from our use of majorities, we have that we only -need to guarantee that groups of processes used to validate an operation by voting (e.g., acknowledging -a leader proposal) pairwise intersect in at least one server. Using majorities guarantees such a property. -However, there are other ways of constructing quorums different from majorities. For example, we can assign -weights to the votes of servers, and say that the votes of some servers are more important. To obtain a quorum, -we get enough votes so that the sum of weights of all votes is larger than half of the total sum of all weights. - -A different construction that uses weights and is useful in wide-area deployments (co-locations) is a hierarchical -one. With this construction, we split the servers into disjoint groups and assign weights to processes. To form -a quorum, we have to get a hold of enough servers from a majority of groups G, such that for each group g in G, -the sum of votes from g is larger than half of the sum of weights in g. Interestingly, this construction enables -smaller quorums. If we have, for example, 9 servers, we split them into 3 groups, and assign a weight of 1 to each -server, then we are able to form quorums of size 4. Note that two subsets of processes composed each of a majority -of servers from each of a majority of groups necessarily have a non-empty intersection. It is reasonable to expect -that a majority of co-locations will have a majority of servers available with high probability. - -With ZooKeeper, we provide a user with the ability of configuring servers to use majority quorums, weights, or a -hierarchy of groups. - - - -## Logging - -Zookeeper uses [slf4j](http://www.slf4j.org/index.html) as an abstraction layer for logging. -[Logback](https://logback.qos.ch/) is chosen the logging backend since ZooKeeper version 3.8.0. -For better embedding support, it is planned in the future to leave the decision of choosing the final logging implementation to the end user. -Therefore, always use the slf4j api to write log statements in the code, but configure logback for how to log at runtime. -Note that slf4j has no FATAL level, former messages at FATAL level have been moved to ERROR level. -For information on configuring logback for -ZooKeeper, see the [Logging](zookeeperAdmin.html#sc_logging) section -of the [ZooKeeper Administrator's Guide.](zookeeperAdmin.html) - - - -### Developer Guidelines - -Please follow the [slf4j manual](http://www.slf4j.org/manual.html) when creating log statements within code. -Also read the [FAQ on performance](http://www.slf4j.org/faq.html#logging\_performance), when creating log statements. Patch reviewers will look for the following: - - - -#### Logging at the Right Level - -There are several levels of logging in slf4j. - -It's important to pick the right one. In order of higher to lower severity: - -1. ERROR level designates error events that might still allow the application to continue running. -1. WARN level designates potentially harmful situations. -1. INFO level designates informational messages that highlight the progress of the application at coarse-grained level. -1. DEBUG Level designates fine-grained informational events that are most useful to debug an application. -1. TRACE Level designates finer-grained informational events than the DEBUG. - -ZooKeeper is typically run in production such that log messages of INFO level -severity and higher (more severe) are output to the log. - - - -#### Use of Standard slf4j Idioms - -_Static Message Logging_ - - LOG.debug("process completed successfully!"); - -However when creating parameterized messages are required, use formatting anchors. - - LOG.debug("got {} messages in {} minutes",new Object[]{count,time}); - -_Naming_ - -Loggers should be named after the class in which they are used. - - public class Foo { - private static final Logger LOG = LoggerFactory.getLogger(Foo.class); - .... - public Foo() { - LOG.info("constructing Foo"); - -_Exception handling_ - - try { - // code - } catch (XYZException e) { - // do this - LOG.error("Something bad happened", e); - // don't do this (generally) - // LOG.error(e); - // why? because "don't do" case hides the stack trace - - // continue process here as you need... recover or (re)throw - } diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperJMX.md b/zookeeper-docs/src/main/resources/markdown/zookeeperJMX.md deleted file mode 100644 index 99b366f2265..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperJMX.md +++ /dev/null @@ -1,130 +0,0 @@ - - -# ZooKeeper JMX - -* [JMX](#ch_jmx) -* [Starting ZooKeeper with JMX enabled](#ch_starting) -* [Run a JMX console](#ch_console) -* [ZooKeeper MBean Reference](#ch_reference) - - - -## JMX - -Apache ZooKeeper has extensive support for JMX, allowing you -to view and manage a ZooKeeper serving ensemble. - -This document assumes that you have basic knowledge of -JMX. See [Sun JMX Technology](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) page to get started with JMX. - -See the [JMX Management Guide](http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html) for details on setting up local and -remote management of VM instances. By default the included -_zkServer.sh_ supports only local management - -review the linked document to enable support for remote management -(beyond the scope of this document). - - - -## Starting ZooKeeper with JMX enabled - -The class -_org.apache.zookeeper.server.quorum.QuorumPeerMain_ -will start a JMX manageable ZooKeeper server. This class -registers the proper MBeans during initialization to support JMX -monitoring and management of the -instance. See _bin/zkServer.sh_ for one -example of starting ZooKeeper using QuorumPeerMain. - - - -## Run a JMX console - -There are a number of JMX consoles available which can connect -to the running server. For this example we will use Sun's -_jconsole_. - -The Java JDK ships with a simple JMX console -named [jconsole](http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html) -which can be used to connect to ZooKeeper and inspect a running -server. Once you've started ZooKeeper using QuorumPeerMain -start _jconsole_, which typically resides in -_JDK_HOME/bin/jconsole_ - -When the "new connection" window is displayed either connect -to local process (if jconsole started on the same host as Server) or -use the remote process connection. - -By default the "overview" tab for the VM is displayed (this -is a great way to get insight into the VM btw). Select -the "MBeans" tab. - -You should now see _org.apache.ZooKeeperService_ -on the left hand side. Expand this item and depending on how you've -started the server you will be able to monitor and manage various -service related features. - -#### Logback MBeans registration _(new in 3.8.0)_ - -Logback is the default logging backend of ZooKeeper since version 3.8.0. -It can be configured to register JMX MBeans by adding `` to _logback.xml_. More -information can be found on Logback's [website](https://logback.qos.ch/manual/jmxConfig.html). - -#### Log4j MBeans _(deprecated)_ - -Also note that ZooKeeper will register log4j MBeans as -well if log4j1 is configured as the logging backend of SLF4j. -In the same section along the left hand side you will see -"log4j". Expand that to manage log4j through JMX. Of particular -interest is the ability to dynamically change the logging levels -used by editing the appender and root thresholds. Log4j MBean -registration can be disabled by passing -_-Dzookeeper.jmx.log4j.disable=true_ to the JVM -when starting ZooKeeper. In addition, we can specify the name of -the MBean with the _-Dzookeeper.jmx.log4j.mbean=log4j:hierarchy=default_ -option, in case we need to upgrade an integrated system -using the old MBean name (`log4j:hierarchy = default`). - - - -## ZooKeeper MBean Reference - -This table details JMX for a server participating in a -replicated ZooKeeper ensemble (ie not standalone). This is the -typical case for a production environment. - -### MBeans, their names and description - -| MBean | MBean Object Name | Description | -|-----------|-------------------|-------------------------------------------------| -| Quorum | ReplicatedServer_id<#> | Represents the Quorum, or Ensemble - parent of all cluster members. Note that the object name includes the "myid" of the server (name suffix) that your JMX agent has connected to. | -| LocalPeer/RemotePeer | replica.<#> | Represents a local or remote peer (ie server participating in the ensemble). Note that the object name includes the "myid" of the server (name suffix). | -| LeaderElection | LeaderElection | Represents a ZooKeeper cluster leader election which is in progress. Provides information about the election, such as when it started. | -| Leader | Leader | Indicates that the parent replica is the leader and provides attributes/operations for that server. Note that Leader is a subclass of ZooKeeperServer, so it provides all of the information normally associated with a ZooKeeperServer node. | -| Follower | Follower | Indicates that the parent replica is a follower and provides attributes/operations for that server. Note that Follower is a subclass of ZooKeeperServer, so it provides all of the information normally associated with a ZooKeeperServer node. | -| DataTree | InMemoryDataTree | Statistics on the in memory znode database, also operations to access finer (and more computationally intensive) statistics on the data (such as ephemeral count). InMemoryDataTrees are children of ZooKeeperServer nodes. | -| ServerCnxn | | Statistics on each client connection, also operations on those connections (such as termination). Note the object name is the session id of the connection in hex form. | - -This table details JMX for a standalone server. Typically -standalone is only used in development situations. - -### MBeans, their names and description - -| MBean | MBean Object Name | Description | -|-------|-------------------|------------------------| -| ZooKeeperServer | StandaloneServer_port<#> | Statistics on the running server, also operations to reset these attributes. Note that the object name includes the client port of the server (name suffix). | -| DataTree | InMemoryDataTree | Statistics on the in memory znode database, also operations to access finer (and more computationally intensive) statistics on the data (such as ephemeral count). | -| ServerCnxn | < session_id > | Statistics on each client connection, also operations on those connections (such as termination). Note the object name is the session id of the connection in hex form. | diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperMonitor.md b/zookeeper-docs/src/main/resources/markdown/zookeeperMonitor.md deleted file mode 100644 index 705b5eb049a..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperMonitor.md +++ /dev/null @@ -1,287 +0,0 @@ - - -# ZooKeeper Monitor Guide - -* [New Metrics System](#Metrics-System) - * [Metrics](#Metrics) - * [Prometheus](#Prometheus) - * [Alerting with Prometheus](#Alerting) - * [Grafana](#Grafana) - * [InfluxDB](#influxdb) - -* [JMX](#JMX) - -* [Four letter words](#four-letter-words) - - - -## New Metrics System -The feature:`New Metrics System` has been available since 3.6.0 which provides the abundant metrics -to help users monitor the ZooKeeper on the topic: znode, network, disk, quorum, leader election, -client, security, failures, watch/session, requestProcessor, and so forth. - - - -### Metrics -All the metrics are included in the `ServerMetrics.java`. - - - - -### Pre-requisites: -- Enable the `Prometheus MetricsProvider` by setting the following in `zoo.cfg`: - ```conf - metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider - ``` - -- The port for Prometheus metrics can be configured using: - ```conf - metricsProvider.httpPort=7000 # Default port is 7000 - ``` - -#### Enabling HTTPS for Prometheus Metrics: - -ZooKeeper also supports SSL for Prometheus metrics, which provides secure data transmission. To enable this, configure an HTTPS port and set up SSL certificates as follows: - -- Define the HTTPS port: - ```conf - metricsProvider.httpsPort=4443 - ``` - -- Configure the SSL key store (holds the server’s private key and certificates): - ```conf - metricsProvider.ssl.keyStore.location=/path/to/keystore.jks - metricsProvider.ssl.keyStore.password=your_keystore_password - metricsProvider.ssl.keyStore.type=jks # Default is JKS - ``` - -- Configure the SSL trust store (used to verify client certificates): - ```conf - metricsProvider.ssl.trustStore.location=/path/to/truststore.jks - metricsProvider.ssl.trustStore.password=your_truststore_password - metricsProvider.ssl.trustStore.type=jks # Default is JKS - ``` - -- **Note**: You can enable both HTTP and HTTPS simultaneously by defining both ports: - ```conf - metricsProvider.httpPort=7000 - metricsProvider.httpsPort=4443 - ``` - -#### Configure TLS protocols and cipher suites for SSL/TLS negotiation in Prometheus Metrics: - -It is also possible to restrict TLS versions and cipher suites for PrometheusMetricsProvider. -Add the following configuration settings to the `zoo.cfg` config file: - -``` -metricsProvider.ssl.enabledProtocols=TLSv1.2,TLSv1.3 -metricsProvider.ssl.ciphersuites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 -``` - -To verify raise the log level of PrometheusMetricsProvider to DEBUG and check that the following entries can be seen in the logs: - -``` -2026-03-11 15:46:36,997 [myid:] - INFO [main:o.a.z.m.p.PrometheusMetricsProvider@245] - Setting enabled protocols: 'TLSv1.2,TLSv1.3' -2026-03-11 15:46:36,997 [myid:] - INFO [main:o.a.z.m.p.PrometheusMetricsProvider@251] - Setting enabled cipherSuites: 'TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384' -``` - -### Prometheus -- Running a [Prometheus](https://prometheus.io/) monitoring service is the easiest way to ingest and record ZooKeeper's metrics. - -- Install Prometheus: - Go to the official website download [page](https://prometheus.io/download/), download the latest release. - -- Set Prometheus's scraper to target the ZooKeeper cluster endpoints: - - ```bash - cat > /tmp/test-zk.yaml <> /tmp/test-zk.log 2>&1 & - ``` - -- Now Prometheus will scrape zk metrics every 10 seconds. - - - -### Alerting with Prometheus -- We recommend that you read [Prometheus Official Alerting Page](https://prometheus.io/docs/practices/alerting/) to explore - some principles of alerting - -- We recommend that you use [Prometheus Alertmanager](https://www.prometheus.io/docs/alerting/latest/alertmanager/) which can - help users to receive alerting email or instant message(by webhook) in a more convenient way - -- We provide an alerting example where these metrics should be taken a special attention. Note: this is for your reference only, - and you need to adjust them according to your actual situation and resource environment - - - use ./promtool check rules rules/zk.yml to check the correctness of the config file - cat rules/zk.yml - - groups: - - name: zk-alert-example - rules: - - alert: ZooKeeper server is down - expr: up == 0 - for: 1m - labels: - severity: critical - annotations: - summary: "Instance {{ $labels.instance }} ZooKeeper server is down" - description: "{{ $labels.instance }} of job {{$labels.job}} ZooKeeper server is down: [{{ $value }}]." - - - alert: create too many znodes - expr: znode_count > 1000000 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} create too many znodes" - description: "{{ $labels.instance }} of job {{$labels.job}} create too many znodes: [{{ $value }}]." - - - alert: create too many connections - expr: num_alive_connections > 50 # suppose we use the default maxClientCnxns: 60 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} create too many connections" - description: "{{ $labels.instance }} of job {{$labels.job}} create too many connections: [{{ $value }}]." - - - alert: znode total occupied memory is too big - expr: approximate_data_size /1024 /1024 > 1 * 1024 # more than 1024 MB(1 GB) - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} znode total occupied memory is too big" - description: "{{ $labels.instance }} of job {{$labels.job}} znode total occupied memory is too big: [{{ $value }}] MB." - - - alert: set too many watch - expr: watch_count > 10000 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} set too many watch" - description: "{{ $labels.instance }} of job {{$labels.job}} set too many watch: [{{ $value }}]." - - - alert: a leader election happens - expr: increase(election_time_count[5m]) > 0 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} a leader election happens" - description: "{{ $labels.instance }} of job {{$labels.job}} a leader election happens: [{{ $value }}]." - - - alert: open too many files - expr: open_file_descriptor_count > 300 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} open too many files" - description: "{{ $labels.instance }} of job {{$labels.job}} open too many files: [{{ $value }}]." - - - alert: fsync time is too long - expr: rate(fsynctime_sum[1m]) > 100 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} fsync time is too long" - description: "{{ $labels.instance }} of job {{$labels.job}} fsync time is too long: [{{ $value }}]." - - - alert: take snapshot time is too long - expr: rate(snapshottime_sum[5m]) > 100 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} take snapshot time is too long" - description: "{{ $labels.instance }} of job {{$labels.job}} take snapshot time is too long: [{{ $value }}]." - - - alert: avg latency is too high - expr: avg_latency > 100 - for: 1m - labels: - severity: warning - annotations: - summary: "Instance {{ $labels.instance }} avg latency is too high" - description: "{{ $labels.instance }} of job {{$labels.job}} avg latency is too high: [{{ $value }}]." - - - alert: JvmMemoryFillingUp - expr: jvm_memory_bytes_used / jvm_memory_bytes_max{area="heap"} > 0.8 - for: 5m - labels: - severity: warning - annotations: - summary: "JVM memory filling up (instance {{ $labels.instance }})" - description: "JVM memory is filling up (> 80%)\n labels: {{ $labels }} value = {{ $value }}\n" - - - - -### Grafana -- Grafana has built-in Prometheus support; just add a Prometheus data source: - - ```bash - Name: test-zk - Type: Prometheus - Url: http://localhost:9090 - Access: proxy - ``` -- Then download and import the default ZooKeeper dashboard [template](https://grafana.com/grafana/dashboards/10465) and customize. -- Users can ask for Grafana dashboard account if having any good improvements by writing a email to **dev@zookeeper.apache.org**. - - - -### InfluxDB - -InfluxDB is an open source time series data that is often used to store metrics -from Zookeeper. You can [download](https://portal.influxdata.com/downloads/) the -open source version or create a [free](https://cloud2.influxdata.com/signup) -account on InfluxDB Cloud. In either case, configure the [Apache Zookeeper -Telegraf plugin](https://www.influxdata.com/integration/apache-zookeeper/) to -start collecting and storing metrics from your Zookeeper clusters into your -InfluxDB instance. There is also an [Apache Zookeeper InfluxDB -template](https://www.influxdata.com/influxdb-templates/zookeeper-monitor/) that -includes the Telegraf configurations and a dashboard to get you set up right -away. - - -## JMX -More details can be found in [here](http://zookeeper.apache.org/doc/current/zookeeperJMX.html) - - -## Four letter words -More details can be found in [here](http://zookeeper.apache.org/doc/current/zookeeperAdmin.html#sc_zkCommands) diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperObservers.md b/zookeeper-docs/src/main/resources/markdown/zookeeperObservers.md deleted file mode 100644 index a41e703d9d8..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperObservers.md +++ /dev/null @@ -1,138 +0,0 @@ - - -# ZooKeeper Observers - -* [Observers: Scaling ZooKeeper Without Hurting Write Performance](#ch_Introduction) -* [How to use Observers](#sc_UsingObservers) -* [Example use cases](#ch_UseCases) - - - -## Observers: Scaling ZooKeeper Without Hurting Write Performance - -Although ZooKeeper performs very well by having clients connect directly -to voting members of the ensemble, this architecture makes it hard to -scale out to huge numbers of clients. The problem is that as we add more -voting members, the write performance drops. This is due to the fact that -a write operation requires the agreement of (in general) at least half the -nodes in an ensemble and therefore the cost of a vote can increase -significantly as more voters are added. - -We have introduced a new type of ZooKeeper node called -an _Observer_ which helps address this problem and -further improves ZooKeeper's scalability. Observers are non-voting members -of an ensemble which only hear the results of votes, not the agreement -protocol that leads up to them. Other than this simple distinction, -Observers function exactly the same as Followers - clients may connect to -them and send read and write requests to them. Observers forward these -requests to the Leader like Followers do, but they then simply wait to -hear the result of the vote. Because of this, we can increase the number -of Observers as much as we like without harming the performance of votes. - -Observers have other advantages. Because they do not vote, they are not a -critical part of the ZooKeeper ensemble. Therefore they can fail, or be -disconnected from the cluster, without harming the availability of the -ZooKeeper service. The benefit to the user is that Observers may connect -over less reliable network links than Followers. In fact, Observers may be -used to talk to a ZooKeeper server from another data center. Clients of -the Observer will see fast reads, as all reads are served locally, and -writes result in minimal network traffic as the number of messages -required in the absence of the vote protocol is smaller. - - - -## How to use Observers - -Setting up a ZooKeeper ensemble that uses Observers is very simple, -and requires just two changes to your config files. Firstly, in the config -file of every node that is to be an Observer, you must place this line: - - peerType=observer - -This line tells ZooKeeper that the server is to be an Observer. Secondly, -in every server config file, you must add :observer to the server -definition line of each Observer. For example: - - server.1:localhost:2181:3181:observer - -This tells every other server that server.1 is an Observer, and that they -should not expect it to vote. This is all the configuration you need to do -to add an Observer to your ZooKeeper cluster. Now you can connect to it as -though it were an ordinary Follower. Try it out, by running: - - $ bin/zkCli.sh -server localhost:2181 - -where localhost:2181 is the hostname and port number of the Observer as -specified in every config file. You should see a command line prompt -through which you can issue commands like _ls_ to query -the ZooKeeper service. - - - -## How to use Observer Masters - -Observers function simple as non-voting members of the ensemble, sharing -the Learner interface with Followers and holding only a slightly different -internal pipeline. Both maintain connections along the quorum port with the -Leader by which they learn of all new proposals on the ensemble. - -By default, Observers connect to the Leader of the quorum along its -quorum port and this is how they learn of all new proposals on the -ensemble. There are benefits to allowing Observers to connect to the -Followers instead as a means of plugging into the commit stream in place -of connecting to the Leader. It shifts the burden of supporting Observers -off the Leader and allow it to focus on coordinating the commit of writes. -This means better performance when the Leader is under high load, -particularly high network load such as can happen after a leader election -when many Learners need to sync. It reduces the total network connections -maintained on the Leader when there are a high number of observers. -Activating Followers to support Observers allow the overall number of -Observers to scale into the hundreds. On the other end, Observer -availability is improved since it will take shorter time for a high -number of Observers to finish syncing and start serving client traffic. - -This feature can be activated by letting all members of the ensemble know -which port will be used by the Followers to listen for Observer -connections. The following entry, when added to the server config file, -will instruct Observers to connect to peers (Leaders and Followers) on -port 2191 and instruct Followers to create an ObserverMaster thread to -listen and serve on that port. - - observerMasterPort=2191 - - -## Example use cases - -Two example use cases for Observers are listed below. In fact, wherever -you wish to scale the number of clients of your ZooKeeper ensemble, or -where you wish to insulate the critical part of an ensemble from the load -of dealing with client requests, Observers are a good architectural -choice. - -* As a datacenter bridge: Forming a ZK ensemble between two - datacenters is a problematic endeavour as the high variance in latency - between the datacenters could lead to false positive failure detection - and partitioning. However if the ensemble runs entirely in one - datacenter, and the second datacenter runs only Observers, partitions - aren't problematic as the ensemble remains connected. Clients of the - Observers may still see and issue proposals. -* As a link to a message bus: Some companies have expressed an - interest in using ZK as a component of a persistent reliable message - bus. Observers would give a natural integration point for this work: a - plug-in mechanism could be used to attach the stream of proposals an - Observer sees to a publish-subscribe system, again without loading the - core ensemble. diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperOracleQuorums.md b/zookeeper-docs/src/main/resources/markdown/zookeeperOracleQuorums.md deleted file mode 100644 index 0f72d6ee5cf..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperOracleQuorums.md +++ /dev/null @@ -1,202 +0,0 @@ - - -# Introduction to Oracle Quorum -The introduction to Oracle Quorum increases the availability of a cluster of 2 ZooKeeper instances with a failure detector as known as the Oracle. - The Oracle is designed to grant the permission to the instance which is the only remaining instance -in a 2-instance configuration when the other instance is identified as faulty by the fail detector, the Oracle. - -## The implementation of the Oracle -Every instance shall access to a file which contains either 0 or 1 to indicate whether this instance is authorized by the Oracle. -However, this design can be changed since the fail detector algorithms vary from each other. Therefore, ones can override the method of _askOracle()_ in _QuorumOracleMaj_ to adapt the preferred way of deciphering the message from the Oracle. - -## The deployment contexts -The Oracle is designed to increase the availability of a cluster of 2 ZooKeeper instances; thus, the size of the voting member is **2**. -In other words, the Oracle solves the consensus problem of a possibility of faulty instance in a two-instance ensemble. - -In the case that the size of the voting members exceeds 2, the expected way to make the Oracle work correctly is to reconfigure the size of the cluster when a faulty machine is identified. -For example, with a configuration of 5 instances, when a faulty machine breaks the connection with the Leader, it is expected to have a _reconfig_ client request to the cluster, which makes the cluster to re-form as the configuration of 4 instances. -Therefore, once the size of the voting member equals to 2, the configuration falls into the problem domain which the Oracle is designed to address. - -## How to deploy the Oracle in _zoo.cfg_ -Regardless of the size of the cluster, the _oraclePath_ must be configured at the time of the initialization, which is like other static parameters. -The below shows the correct way to specify and enable the Oracle. - - oraclePath=/to/some/file - -#### An example of zoo.cfg: - - dataDir=/data - dataLogDir=/datalog - tickTime=2000 - initLimit=5 - syncLimit=2 - autopurge.snapRetainCount=3 - autopurge.purgeInterval=0 - maxClientCnxns=60 - standaloneEnabled=true - admin.enableServer=true - oraclePath=/chassis/mastership - server.1=0.0.0.0:2888:3888;2181 - server.2=hw1:2888:3888;2181 - -The QuorumOracleMaj is designed to read the result of a failure detector, which is written on a text file, the oracle file. -The configuration in the zoo.cfg like the following: - - oraclePath=/to/some/file - -Suppose you have the result of the failure detector written on /some/path/result.txt, and then the correct configuration is the following: - - oraclePath=/some/path/result.txt - -So, what is the correct content of the provided file? An example file can be created with the following command from the terminal: - - $echo 1 > /some/path/result.txt - -Any equivalent files are suitable for the current implementation of QuorumOracleMaj. -The number of oracle files should be equal to the number of ZooKeeper instances configured to enable the Oracle. -In other words, each ZooKeeper instance should have its oracle file, and the files shall not be shared; otherwise, the issues in the next section will arise. - -## What differs after the deployment of the Oracle enabled -The _QuorumPeerConfig_ will create an instance of _QuorumOracleMaj_ instead of the default QuorumVerifier, _QuorumMaj_ when it reads the _zoo.cfg_ contains _oraclePath_. -QuorumOracleMaj inheritances from QuorumMaj, and differs from its superclass by overriding the method of _containsQuorum()_. -QuorumOracleMaj is designed to execute its version of _containsQuorum_ when the Leader loses all of its followers, and fails to maintain the quorum. -In other cases, _QuorumOracleMaj_ shall execute as _QuorumMaj_. - -## What we should pay attention to the Oracle -We consider an asynchronous distributed system which consists of **2** ZooKeeper instances and an Oracle. - -### Liveness Issue: -When we consider the oracle satisfies the following property introduced by [CT]: - - Strong Completeness: There is a time after which every process that crashes is permanently suspected by every correct processes - -The liveness of the system is ensured by the Oracle. -However, when the introduced oracle fails to maintain this property, the lost of the liveness is expected as the following example, - -Suppose we have a Leader and a Follower, which are running in the broadcasting state, -The system will lose its liveness when: - - 1. The Leader fails, but the Oracle does not detect the faulty Leader, which means the Oracle will not authorize the Follower to become a new Leader. - 2. When a Follower fails, but the Oracle does not detect the faulty follower, which means the Oracle will authorize the Leader to move system forward. - -### Safety Issue: -#### Lost of Progress -The progress can lost when multiple failures occurs in the system at different time as the following example, - -Suppose we have a Leader(Ben) and a Follower(John) in the broadcasting state, - - At T1 with zxid(0x1_1): L-Ben fails, and the F-John takes over the system under the authorization from the Oracle. - At T2 with zxid(0x2_1): The F-John becomes a new Leader, L-John, and starts a new epoch. - At T3 with zxid(0x2_A): L-John fails - At T4 with zxid(0x2_A): Ben recovers up and starts its leader election. - At T5 with zxid(0x3_1): Ben becomes the new leader, L-Ben, under the authorization from the Oracle. - -In this case, the system loses its progress after the L-Ben failed. - - -However, the lost of progress can be prevented by making the Oracle is capable of referring the latest zxid. -When the Oracle could refer to the latest zxid, - - At T5 with zxid(0x2_A): Ben will not end his leader election because the Oracle would not authorize although John is down. - -Nevertheless, we exchange the liveness for the safety. -#### Split Brain Issue -We consider the Oracle satisfies the following desired property introduced by [CT], - - Accuracy: There is a time after which some correct processes is never suspected by any processes - -Nevertheless, the decisions which the Oracle gives out should be mutual exclusive. - -In other words, - -Suppose we have a Leader(Ben) and a Follower(John) in the broadcasting state, - - - At any time, the Oracle will not authorize both Ben and John even though the failure detectors think each other is faulty. - Or - - At any time, for any two values in any two Oracle files respectively, the values are not both equal to 1. - -The split brain is expected when the Oracle fails to maintain this property during the leader election phase of - - 1. Start of the system - 2. A failed instance recovers from failures. - -## Examples of Concepts for Implementation of a Failure Detector -One should consider that the failure detector's outcome is to authorize the querying ZooKeeper instance whether it has the right to move the system forward without waiting for the faulty instance, which is identified by the failure detector. - -### An Implementation of Hardware -Suppose two dedicated pieces of hardware, hw1 and hw2, can host ZooKeeper instances, zk1 and zk2, respectively, and form a cluster. -A hardware device is attached to both of the hardware, and it is capable of determining whether the hardware is power on or not. -So, when hw1 is not power on, the zk1 is undoubtedly faulty. -Therefore, the hardware device updates the oracle file on hw2 to 1, which indicates that zk1 is faulty and authorizes zk2 to move the system forwards. - -### An Implementation of Software -Suppose two dedicated pieces of hardware, hw1 and hw2, can host ZooKeeper instances, zk1 and zk2, respectively, and form a cluster. -One can have two more services, o1 and o2, on hw1 and hw2, respectively. The job of o1 and o2 are detecting the other hardware is alive or not. -For example, o1 can constantly ping hw2 to determine if hw2 is power on or not. -When o1 cannot ping hw2, o1 identifies that hw2 is faulty and then update the oracle file of zk1 to 1, which indicates that zk2 is faulty and authorizes zk1 to move the system forwards. - -### Use USB devices as Oracle to Maintain Progress -In macOS,10.15.7 (19H2), the external storage devices are mounted under `/Volumes`. -Thus, we can insert a USB device which contains the required information as the oracle. -When the device is connected, the oracle authorizes the leader to move system forward, which also means the other instance fails. -There are **SIX** steps to reproduce this stimulation. - -* Firstly, insert a USB device named `Oracle`, and then we can expect that `/Volumes/Oracle` is accessible. -* Secondly, we create a file contains `1` under `/Volumes/Oracle` named `mastership`. -Now we can access `/Volumes/Oracle/mastership`, and so does the zookeeper instances to see whether it has the right to move the system forward. -The file can easily be generated by the following command: - - - $echo 1 > mastership - -* Thirdly, you shall have a `zoo.cfg` like the example below: - - - dataDir=/data - dataLogDir=/datalog - tickTime=2000 - initLimit=5 - syncLimit=2 - autopurge.snapRetainCount=3 - autopurge.purgeInterval=0 - maxClientCnxns=60 - standaloneEnabled=true - admin.enableServer=true - oraclePath=/Volumes/Oracle/mastership - server.1=0.0.0.0:2888:3888;2181 - server.2=hw1:2888:3888;2181 - -_(NOTE) The split brain issues will not occur because there is only a SINGLE USB device in this stimulation._ -_Additionally, `mastership` should not be shared by multiple instances._ -_Thus, only one ZooKeeper instance is configured with Oracle._ -_For more, please refer to Section Safety Issue._ - -* Fourthly, start the cluster, and it is expected it forms a quorum normally. -* Fifthly, terminate the instance either without attaching to a USB device or `mastership` contains 0. -There are two scenarios to expect: - 1. A leader failure occurs, and the remained instance finishes the leader election on its own due to the oracle. - 2. The quorum is still maintained due to the oracle. - -* Lastly, when the USB device is removed, `/Volumes/Oracle/mastership` becomes unavailable. -Therefore, according to the current implementation, whenever the Leader queries the oracle, the oracle throws an exception and return `FALSE`. -Repeat the fifth step, and then it is expected that either the system cannot recover from a leader failure ,or the leader loses the quorum. -In either case, the service is interrupted. - -With these steps, we can show and practice how the oracle works with two-instance systems with ease. - -##REFERENCE -[CT] Tushar Deepak Chandra and Sam Toueg. 1991. Unreliable failure detectors for asynchronous systems (preliminary version). In Proceedings of the tenth annual ACM symposium on Principles of distributed computing (PODC '91). Association for Computing Machinery, New York, NY, USA, 325–340. DOI:https://doi.org/10.1145/112600.112627 \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperProgrammers.md b/zookeeper-docs/src/main/resources/markdown/zookeeperProgrammers.md deleted file mode 100644 index a9b7fd711c7..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperProgrammers.md +++ /dev/null @@ -1,1668 +0,0 @@ - - -# ZooKeeper Programmer's Guide - -### Developing Distributed Applications that use ZooKeeper - -* [Introduction](#_introduction) -* [The ZooKeeper Data Model](#ch_zkDataModel) - * [ZNodes](#sc_zkDataModel_znodes) - * [Watches](#sc_zkDataMode_watches) - * [Data Access](#Data+Access) - * [Ephemeral Nodes](#Ephemeral+Nodes) - * [Sequence Nodes -- Unique Naming](#Sequence+Nodes+--+Unique+Naming) - * [Container Nodes](#Container+Nodes) - * [TTL Nodes](#TTL+Nodes) - * [Time in ZooKeeper](#sc_timeInZk) - * [ZooKeeper Stat Structure](#sc_zkStatStructure) -* [ZooKeeper Sessions](#ch_zkSessions) -* [ZooKeeper Watches](#ch_zkWatches) - * [Semantics of Watches](#sc_WatchSemantics) - * [Persistent, Recursive Watches](#sc_WatchPersistentRecursive) - * [Remove Watches](#sc_WatchRemoval) - * [What ZooKeeper Guarantees about Watches](#sc_WatchGuarantees) - * [Things to Remember about Watches](#sc_WatchRememberThese) -* [ZooKeeper access control using ACLs](#sc_ZooKeeperAccessControl) - * [ACL Permissions](#sc_ACLPermissions) - * [Builtin ACL Schemes](#sc_BuiltinACLSchemes) - * [ZooKeeper C client API](#ZooKeeper+C+client+API) -* [Pluggable ZooKeeper authentication](#sc_ZooKeeperPluggableAuthentication) -* [Consistency Guarantees](#ch_zkGuarantees) -* [Bindings](#ch_bindings) - * [Java Binding](#Java+Binding) - * [Client Configuration Parameters](#sc_java_client_configuration) - * [C Binding](#C+Binding) - * [Installation](#Installation) - * [Building Your Own C Client](#Building+Your+Own+C+Client) -* [Building Blocks: A Guide to ZooKeeper Operations](#ch_guideToZkOperations) - * [Handling Errors](#sc_errorsZk) - * [Connecting to ZooKeeper](#sc_connectingToZk) -* [Gotchas: Common Problems and Troubleshooting](#ch_gotchas) - - - -## Introduction - -This document is a guide for developers wishing to create -distributed applications that take advantage of ZooKeeper's coordination -services. It contains conceptual and practical information. - -The first four sections of this guide present a higher level -discussions of various ZooKeeper concepts. These are necessary both for an -understanding of how ZooKeeper works as well how to work with it. It does -not contain source code, but it does assume a familiarity with the -problems associated with distributed computing. The sections in this first -group are: - -* [The ZooKeeper Data Model](#ch_zkDataModel) -* [ZooKeeper Sessions](#ch_zkSessions) -* [ZooKeeper Watches](#ch_zkWatches) -* [Consistency Guarantees](#ch_zkGuarantees) - -The next four sections provide practical programming -information. These are: - -* [Building Blocks: A Guide to ZooKeeper Operations](#ch_guideToZkOperations) -* [Bindings](#ch_bindings) -* [Gotchas: Common Problems and Troubleshooting](#ch_gotchas) - -The book concludes with an [appendix](#apx_linksToOtherInfo) containing links to other -useful, ZooKeeper-related information. - -Most of the information in this document is written to be accessible as -stand-alone reference material. However, before starting your first -ZooKeeper application, you should probably at least read the chapters on -the [ZooKeeper Data Model](#ch_zkDataModel) and [ZooKeeper Basic Operations](#ch_guideToZkOperations). - - - -## The ZooKeeper Data Model - -ZooKeeper has a hierarchal namespace, much like a distributed file -system. The only difference is that each node in the namespace can have -data associated with it as well as children. It is like having a file -system that allows a file to also be a directory. Paths to nodes are -always expressed as canonical, absolute, slash-separated paths; there are -no relative reference. Any unicode character can be used in a path subject -to the following constraints: - -* The null character (\\u0000) cannot be part of a path name. (This - causes problems with the C binding.) -* The following characters can't be used because they don't - display well, or render in confusing ways: \\u0001 - \\u001F and \\u007F - - \\u009F. -* The following characters are not allowed: \\ud800 - uF8FF, - \\uFFF0 - uFFFF. -* The "." character can be used as part of another name, but "." - and ".." cannot alone be used to indicate a node along a path, - because ZooKeeper doesn't use relative paths. The following would be - invalid: "/a/b/./c" or "/a/b/../c". -* The token "zookeeper" is reserved. - - - -### ZNodes - -Every node in a ZooKeeper tree is referred to as a -_znode_. Znodes maintain a stat structure that -includes version numbers for data changes, acl changes. The stat -structure also has timestamps. The version number, together with the -timestamp, allows ZooKeeper to validate the cache and to coordinate -updates. Each time a znode's data changes, the version number increases. -For instance, whenever a client retrieves data, it also receives the -version of the data. And when a client performs an update or a delete, -it must supply the version of the data of the znode it is changing. If -the version it supplies doesn't match the actual version of the data, -the update will fail. (This behavior can be overridden. - -######Note - ->In distributed application engineering, the word -_node_ can refer to a generic host machine, a -server, a member of an ensemble, a client process, etc. In the ZooKeeper -documentation, _znodes_ refer to the data nodes. -_Servers_ refers to machines that make up the -ZooKeeper service; _quorum peers_ refer to the -servers that make up an ensemble; client refers to any host or process -which uses a ZooKeeper service. - -Znodes are the main entity that a programmer access. They have -several characteristics that are worth mentioning here. - - - -#### Watches - -Clients can set watches on znodes. Changes to that znode trigger -the watch and then clear the watch. When a watch triggers, ZooKeeper -sends the client a notification. More information about watches can be -found in the section -[ZooKeeper Watches](#ch_zkWatches). - - - -#### Data Access - -The data stored at each znode in a namespace is read and written -atomically. Reads get all the data bytes associated with a znode and a -write replaces all the data. Each node has an Access Control List -(ACL) that restricts who can do what. - -ZooKeeper was not designed to be a general database or large -object store. Instead, it manages coordination data. This data can -come in the form of configuration, status information, rendezvous, etc. -A common property of the various forms of coordination data is that -they are relatively small: measured in kilobytes. -The ZooKeeper client and the server implementations have sanity checks -to ensure that znodes have less than 1M of data, but the data should -be much less than that on average. Operating on relatively large data -sizes will cause some operations to take much more time than others and -will affect the latencies of some operations because of the extra time -needed to move more data over the network and onto storage media. If -large data storage is needed, the usual pattern of dealing with such -data is to store it on a bulk storage system, such as NFS or HDFS, and -store pointers to the storage locations in ZooKeeper. - - - -#### Ephemeral Nodes - -ZooKeeper also has the notion of ephemeral nodes. These znodes -exists as long as the session that created the znode is active. When -the session ends the znode is deleted. Because of this behavior -ephemeral znodes are not allowed to have children. The list of ephemerals -for the session can be retrieved using **getEphemerals()** api. - -##### getEphemerals() -Retrieves the list of ephemeral nodes created by the session for the -given path. If the path is empty, it will list all the ephemeral nodes -for the session. -**Use Case** - A sample use case might be, if the list of ephemeral -nodes for the session needs to be collected for duplicate data entry check -and the nodes are created in a sequential manner so you do not know the name -for duplicate check. In that case, getEphemerals() api could be used to -get the list of nodes for the session. This might be a typical use case -for service discovery. - - - -#### Sequence Nodes -- Unique Naming - -When creating a znode you can also request that -ZooKeeper append a monotonically increasing counter to the end -of path. This counter is unique to the parent znode. The -counter has a format of %010d -- that is 10 digits with 0 -(zero) padding (the counter is formatted in this way to -simplify sorting), i.e. "0000000001". See -[Queue -Recipe](recipes.html#sc_recipes_Queues) for an example use of this feature. Note: the -counter used to store the next sequence number is a signed int -(4bytes) maintained by the parent node, the counter will -overflow when incremented beyond 2147483647 (resulting in a -name "-2147483648"). - - - -#### Container Nodes - -**Added in 3.5.3** - -ZooKeeper has the notion of container znodes. Container znodes are -special purpose znodes useful for recipes such as leader, lock, etc. -When the last child of a container is deleted, the container becomes -a candidate to be deleted by the server at some point in the future. - -Given this property, you should be prepared to get -KeeperException.NoNodeException when creating children inside of -container znodes. i.e. when creating child znodes inside of container znodes -always check for KeeperException.NoNodeException and recreate the container -znode when it occurs. - - - -#### TTL Nodes - -**Added in 3.5.3** - -When creating PERSISTENT or PERSISTENT_SEQUENTIAL znodes, -you can optionally set a TTL in milliseconds for the znode. If the znode -is not modified within the TTL and has no children it will become a candidate -to be deleted by the server at some point in the future. - -Note: TTL Nodes must be enabled via System property as they -are disabled by default. See the [Administrator's Guide](zookeeperAdmin.html#sc_configuration) for -details. If you attempt to create TTL Nodes without the -proper System property set the server will throw -KeeperException.UnimplementedException. - - - -### Time in ZooKeeper - -ZooKeeper tracks time multiple ways: - -* **Zxid** - Every change to the ZooKeeper state receives a stamp in the - form of a _zxid_ (ZooKeeper Transaction Id). - This exposes the total ordering of all changes to ZooKeeper. Each - change will have a unique zxid and if zxid1 is smaller than zxid2 - then zxid1 happened before zxid2. -* **Version numbers** - Every change to a node will cause an increase to one of the - version numbers of that node. The three version numbers are version - (number of changes to the data of a znode), cversion (number of - changes to the children of a znode), and aversion (number of changes - to the ACL of a znode). -* **Ticks** - When using multi-server ZooKeeper, servers use ticks to define - timing of events such as status uploads, session timeouts, - connection timeouts between peers, etc. The tick time is only - indirectly exposed through the minimum session timeout (2 times the - tick time); if a client requests a session timeout less than the - minimum session timeout, the server will tell the client that the - session timeout is actually the minimum session timeout. -* **Real time** - ZooKeeper doesn't use real time, or clock time, at all except - to put timestamps into the stat structure on znode creation and - znode modification. - - - -### ZooKeeper Stat Structure - -The Stat structure for each znode in ZooKeeper is made up of the -following fields: - -* **czxid** - The zxid of the change that caused this znode to be - created. -* **mzxid** - The zxid of the change that last modified this znode. -* **pzxid** - The zxid of the change that last modified children of this znode. -* **ctime** - The time in milliseconds from epoch when this znode was - created. -* **mtime** - The time in milliseconds from epoch when this znode was last - modified. -* **version** - The number of changes to the data of this znode. -* **cversion** - The number of changes to the children of this znode. -* **aversion** - The number of changes to the ACL of this znode. -* **ephemeralOwner** - The session id of the owner of this znode if the znode is an - ephemeral node. If it is not an ephemeral node, it will be - zero. -* **dataLength** - The length of the data field of this znode. -* **numChildren** - The number of children of this znode. - - - -## ZooKeeper Sessions - -A ZooKeeper client establishes a session with the ZooKeeper -service by creating a handle to the service using a language -binding. Once created, the handle starts off in the CONNECTING state -and the client library tries to connect to one of the servers that -make up the ZooKeeper service at which point it switches to the -CONNECTED state. During normal operation the client handle will be in one of these -two states. If an unrecoverable error occurs, such as session -expiration or authentication failure, or if the application explicitly -closes the handle, the handle will move to the CLOSED state. -The following figure shows the possible state transitions of a -ZooKeeper client: - -![State transitions](images/state_dia.jpg) - -To create a client session the application code must provide -a connection string containing a comma separated list of host:port pairs, -each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or -"127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper -client library will pick an arbitrary server and try to connect to -it. If this connection fails, or if the client becomes -disconnected from the server for any reason, the client will -automatically try the next server in the list, until a connection -is (re-)established. - -**Added in 3.2.0**: An -optional "chroot" suffix may also be appended to the connection -string. This will run the client commands while interpreting all -paths relative to this root (similar to the unix chroot -command). If used the example would look like: -"127.0.0.1:4545/app/a" or -"127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the -client would be rooted at "/app/a" and all paths would be relative -to this root - ie getting/setting/etc... "/foo/bar" would result -in operations being run on "/app/a/foo/bar" (from the server -perspective). This feature is particularly useful in multi-tenant -environments where each user of a particular ZooKeeper service -could be rooted differently. This makes re-use much simpler as -each user can code his/her application as if it were rooted at -"/", while actual location (say /app/a) could be determined at -deployment time. - -When a client gets a handle to the ZooKeeper service, -ZooKeeper creates a ZooKeeper session, represented as a 64-bit -number, that it assigns to the client. If the client connects to a -different ZooKeeper server, it will send the session id as a part -of the connection handshake. As a security measure, the server -creates a password for the session id that any ZooKeeper server -can validate.The password is sent to the client with the session -id when the client establishes the session. The client sends this -password with the session id whenever it reestablishes the session -with a new server. - -One of the parameters to the ZooKeeper client library call -to create a ZooKeeper session is the session timeout in -milliseconds. The client sends a requested timeout, the server -responds with the timeout that it can give the client. The current -implementation requires that the timeout be a minimum of 2 times -the tickTime (as set in the server configuration) and a maximum of -20 times the tickTime. The ZooKeeper client API allows access to -the negotiated timeout. - -When a client (session) becomes partitioned from the ZK -serving cluster it will begin searching the list of servers that -were specified during session creation. Eventually, when -connectivity between the client and at least one of the servers is -re-established, the session will either again transition to the -"connected" state (if reconnected within the session timeout -value) or it will transition to the "expired" state (if -reconnected after the session timeout). It is not advisable to -create a new session object (a new ZooKeeper.class or zookeeper -handle in the c binding) for disconnection. The ZK client library -will handle reconnect for you. In particular we have heuristics -built into the client library to handle things like "herd effect", -etc... Only create a new session when you are notified of session -expiration (mandatory). - -Session expiration is managed by the ZooKeeper cluster -itself, not by the client. When the ZK client establishes a -session with the cluster it provides a "timeout" value detailed -above. This value is used by the cluster to determine when the -client's session expires. Expirations happens when the cluster -does not hear from the client within the specified session timeout -period (i.e. no heartbeat). At session expiration the cluster will -delete any/all ephemeral nodes owned by that session and -immediately notify any/all connected clients of the change (anyone -watching those znodes). At this point the client of the expired -session is still disconnected from the cluster, it will not be -notified of the session expiration until/unless it is able to -re-establish a connection to the cluster. The client will stay in -disconnected state until the TCP connection is re-established with -the cluster, at which point the watcher of the expired session -will receive the "session expired" notification. - -Example state transitions for an expired session as seen by -the expired session's watcher: - -1. 'connected' : session is established and client - is communicating with cluster (client/server communication is - operating properly) -1. .... client is partitioned from the - cluster -1. 'disconnected' : client has lost connectivity - with the cluster -1. .... time elapses, after 'timeout' period the - cluster expires the session, nothing is seen by client as it is - disconnected from cluster -1. .... time elapses, the client regains network - level connectivity with the cluster -1. 'expired' : eventually the client reconnects to - the cluster, it is then notified of the - expiration - -Another parameter to the ZooKeeper session establishment -call is the default watcher. Watchers are notified when any state -change occurs in the client. For example if the client loses -connectivity to the server the client will be notified, or if the -client's session expires, etc... This watcher should consider the -initial state to be disconnected (i.e. before any state changes -events are sent to the watcher by the client lib). In the case of -a new connection, the first event sent to the watcher is typically -the session connection event. - -The session is kept alive by requests sent by the client. If -the session is idle for a period of time that would timeout the -session, the client will send a PING request to keep the session -alive. This PING request not only allows the ZooKeeper server to -know that the client is still active, but it also allows the -client to verify that its connection to the ZooKeeper server is -still active. The timing of the PING is conservative enough to -ensure reasonable time to detect a dead connection and reconnect -to a new server. - -Once a connection to the server is successfully established -(connected) there are basically two cases where the client lib generates -connectionloss (the result code in c binding, exception in Java -- see -the API documentation for binding specific details) when either a synchronous or -asynchronous operation is performed and one of the following holds: - -1. The application calls an operation on a session that is no - longer alive/valid -1. The ZooKeeper client disconnects from a server when there - are pending operations to that server, i.e., there is a pending asynchronous call. - -**Added in 3.2.0 -- SessionMovedException**. There is an internal -exception that is generally not seen by clients called the SessionMovedException. -This exception occurs because a request was received on a connection for a session -which has been reestablished on a different server. The normal cause of this error is -a client that sends a request to a server, but the network packet gets delayed, so -the client times out and connects to a new server. When the delayed packet arrives at -the first server, the old server detects that the session has moved, and closes the -client connection. Clients normally do not see this error since they do not read -from those old connections. (Old connections are usually closed.) One situation in which this -condition can be seen is when two clients try to reestablish the same connection using -a saved session id and password. One of the clients will reestablish the connection -and the second client will be disconnected (causing the pair to attempt to re-establish -its connection/session indefinitely). - -**Updating the list of servers**. We allow a client to -update the connection string by providing a new comma separated list of host:port pairs, -each corresponding to a ZooKeeper server. The function invokes a probabilistic load-balancing -algorithm which may cause the client to disconnect from its current host with the goal -to achieve expected uniform number of connections per server in the new list. -In case the current host to which the client is connected is not in the new list -this call will always cause the connection to be dropped. Otherwise, the decision -is based on whether the number of servers has increased or decreased and by how much. - -For example, if the previous connection string contained 3 hosts and now the list contains -these 3 hosts and 2 more hosts, 40% of clients connected to each of the 3 hosts will -move to one of the new hosts in order to balance the load. The algorithm will cause the client -to drop its connection to the current host to which it is connected with probability 0.4 and in this -case cause the client to connect to one of the 2 new hosts, chosen at random. - -Another example -- suppose we have 5 hosts and now update the list to remove 2 of the hosts, -the clients connected to the 3 remaining hosts will stay connected, whereas all clients connected -to the 2 removed hosts will need to move to one of the 3 hosts, chosen at random. If the connection -is dropped, the client moves to a special mode where he chooses a new server to connect to using the -probabilistic algorithm, and not just round robin. - -In the first example, each client decides to disconnect with probability 0.4 but once the decision is -made, it will try to connect to a random new server and only if it cannot connect to any of the new -servers will it try to connect to the old ones. After finding a server, or trying all servers in the -new list and failing to connect, the client moves back to the normal mode of operation where it picks -an arbitrary server from the connectString and attempts to connect to it. If that fails, it will continue -trying different random servers in round robin. (see above the algorithm used to initially choose a server) - -**Local session**. Added in 3.5.0, mainly implemented by [ZOOKEEPER-1147](https://issues.apache.org/jira/browse/ZOOKEEPER-1147). - -- Background: The creation and closing of sessions are costly in ZooKeeper because they need quorum confirmations, - they become the bottleneck of a ZooKeeper ensemble when it needs to handle thousands of client connections. -So after 3.5.0, we introduce a new type of session: local session which doesn't have a full functionality of a normal(global) session, this feature -will be available by turning on *localSessionsEnabled*. - -when *localSessionsUpgradingEnabled* is disable: - -- Local sessions cannot create ephemeral nodes - -- Once a local session is lost, users cannot re-establish it using the session-id/password, the session and its watches are gone for good. - Note: Losing the tcp connection does not necessarily imply that the session is lost. If the connection can be reestablished with the same zk server - before the session timeout then the client can continue (it simply cannot move to another server). - -- When a local session connects, the session info is only maintained on the zookeeper server that it is connected to. The leader is not aware of the creation of such a session and -there is no state written to disk. - -- The pings, expiration and other session state maintenance are handled by the server which current session is connected to. - -when *localSessionsUpgradingEnabled* is enable: - -- A local session can be upgraded to the global session automatically. - -- When a new session is created it is saved locally in a wrapped *LocalSessionTracker*. It can subsequently be upgraded -to a global session as required (e.g. create ephemeral nodes). If an upgrade is requested the session is removed from local - collections while keeping the same session ID. - -- Currently, Only the operation: *create ephemeral node* needs a session upgrade from local to global. -The reason is that the creation of ephemeral node depends heavily on a global session. If local session can create ephemeral -node without upgrading to global session, it will cause the data inconsistency between different nodes. -The leader also needs to know about the lifespan of a session in order to clean up ephemeral nodes on close/expiry. -This requires a global session as the local session is tied to its particular server. - -- A session can be both a local and global session during upgrade, but the operation of upgrade cannot be called concurrently by two thread. - -- *ZooKeeperServer*(Standalone) uses *SessionTrackerImpl*; *LeaderZookeeper* uses *LeaderSessionTracker* which holds - *SessionTrackerImpl*(global) and *LocalSessionTracker*(if enable); *FollowerZooKeeperServer* and *ObserverZooKeeperServer* - use *LearnerSessionTracker* which holds *LocalSessionTracker*. - The UML Graph of Classes about session: - - ``` - +----------------+ +--------------------+ +---------------------+ - | | --> | | ----> | LocalSessionTracker | - | SessionTracker | | SessionTrackerImpl | +---------------------+ - | | | | +-----------------------+ - | | | | +-------------------------> | LeaderSessionTracker | - +----------------+ +--------------------+ | +-----------------------+ - | | - | | - | | - | +---------------------------+ - +---------> | | - | UpgradeableSessionTracker | - | | - | | ------------------------+ - +---------------------------+ | - | - | - v - +-----------------------+ - | LearnerSessionTracker | - +-----------------------+ - ``` - -- Q&A - - *What's the reason for having the config option to disable local session upgrade?* - - In a large deployment which wants to handle a very large number of clients, we know that clients connecting via the observers - which is supposed to be local session only. So this is more like a safeguard against someone accidentally creates lots of ephemeral nodes and global sessions. - - - *When is the session created?* - - In the current implementation, it will try to create a local session when processing *ConnectRequest* and when - *createSession* request reaches *FinalRequestProcessor*. - - - *What happens if the create for session is sent at server A and the client disconnects to some other server B - which ends up sending it again and then disconnects and connects back to server A?* - - When a client reconnects to B, its sessionId won’t exist in B’s local session tracker. So B will send validation packet. - If CreateSession issued by A is committed before validation packet arrive the client will be able to connect. - Otherwise, the client will get session expired because the quorum hasn’t know about this session yet. - If the client also tries to connect back to A again, the session is already removed from local session tracker. - So A will need to send a validation packet to the leader. The outcome should be the same as B depending on the timing of the request. - - - -## ZooKeeper Watches - -All of the read operations in ZooKeeper - **getData()**, **getChildren()**, and **exists()** - have the option of setting a watch as a -side effect. Here is ZooKeeper's definition of a watch: a watch event is -one-time trigger, sent to the client that set the watch, which occurs when -the data for which the watch was set changes. There are three key points -to consider in this definition of a watch: - -* **One-time trigger** - One watch event will be sent to the client when the data has changed. - For example, if a client does a getData("/znode1", true) and later the - data for /znode1 is changed or deleted, the client will get a watch - event for /znode1. If /znode1 changes again, no watch event will be - sent unless the client has done another read that sets a new - watch. -* **Sent to the client** - This implies that an event is on the way to the client, but may - not reach the client before the successful return code to the change - operation reaches the client that initiated the change. Watches are - sent asynchronously to watchers. ZooKeeper provides an ordering - guarantee: a client will never see a change for which it has set a - watch until it first sees the watch event. Network delays or other - factors may cause different clients to see watches and return codes - from updates at different times. The key point is that everything seen - by the different clients will have a consistent order. -* **The data for which the watch was - set** - This refers to the different ways a node can change. It - helps to think of ZooKeeper as maintaining two lists of - watches: data watches and child watches. getData() and - exists() set data watches. getChildren() sets child - watches. Alternatively, it may help to think of watches being - set according to the kind of data returned. getData() and - exists() return information about the data of the node, - whereas getChildren() returns a list of children. Thus, - setData() will trigger data watches for the znode being set - (assuming the set is successful). A successful create() will - trigger a data watch for the znode being created and a child - watch for the parent znode. A successful delete() will trigger - both a data watch and a child watch (since there can be no - more children) for a znode being deleted as well as a child - watch for the parent znode. - -Watches are maintained locally at the ZooKeeper server to which the -client is connected. This allows watches to be lightweight to set, -maintain, and dispatch. When a client connects to a new server, the watch -will be triggered for any session events. Watches will not be received -while disconnected from a server. When a client reconnects, any previously -registered watches will be reregistered and triggered if needed. In -general this all occurs transparently. There is one case where a watch -may be missed: a watch for the existence of a znode not yet created will -be missed if the znode is created and deleted while disconnected. - -**New in 3.6.0:** Clients can also set -permanent, recursive watches on a znode that are not removed when triggered -and that trigger for changes on the registered znode as well as any children -znodes recursively. - - - -### Semantics of Watches - -We can set watches with the three calls that read the state of -ZooKeeper: exists, getData, and getChildren. The following list details -the events that a watch can trigger and the calls that enable them: - -* **Created event:** - Enabled with a call to exists. -* **Deleted event:** - Enabled with a call to exists, getData, and getChildren. -* **Changed event:** - Enabled with a call to exists and getData. -* **Child event:** - Enabled with a call to getChildren. - - - -### Persistent, Recursive Watches - -**New in 3.6.0:** There is now a variation on the standard -watch described above whereby you can set a watch that does not get removed when triggered. -Additionally, these watches trigger the event types *NodeCreated*, *NodeDeleted*, and *NodeDataChanged* -and, optionally, recursively for all znodes starting at the znode that the watch is registered for. Note -that *NodeChildrenChanged* events are not triggered for persistent recursive watches as it would be redundant. - -Persistent watches are set using the method *addWatch()*. The triggering semantics and guarantees -(other than one-time triggering) are the same as standard watches. The only exception regarding events is that -recursive persistent watchers never trigger child changed events as they are redundant. -Persistent watches are removed using *removeWatches()* with watcher type *WatcherType.Any*. - - - -### Remove Watches - -We can remove the watches registered on a znode with a call to -removeWatches. Also, a ZooKeeper client can remove watches locally even -if there is no server connection by setting the local flag to true. The -following list details the events which will be triggered after the -successful watch removal. - -* **Child Remove event:** - Watcher which was added with a call to getChildren. -* **Data Remove event:** - Watcher which was added with a call to exists or getData. -* **Persistent Remove event:** - Watcher which was added with a call to add a persistent watch. - - - -### What ZooKeeper Guarantees about Watches - -With regard to watches, ZooKeeper maintains these -guarantees: - -* Watches are ordered with respect to other events, other - watches, and asynchronous replies. The ZooKeeper client libraries - ensures that everything is dispatched in order. - -* A client will see a watch event for a znode it is watching - before seeing the new data that corresponds to that znode. - -* The order of watch events from ZooKeeper corresponds to the - order of the updates as seen by the ZooKeeper service. - - - -### Things to Remember about Watches - -* Standard watches are one time triggers; if you get a watch event and - you want to get notified of future changes, you must set another - watch. - -* Because standard watches are one time triggers and there is latency - between getting the event and sending a new request to get a watch - you cannot reliably see every change that happens to a node in - ZooKeeper. Be prepared to handle the case where the znode changes - multiple times between getting the event and setting the watch - again. (You may not care, but at least realize it may - happen.) - -* A watch object, or function/context pair, will only be - triggered once for a given notification. For example, if the same - watch object is registered for an exists and a getData call for the - same file and that file is then deleted, the watch object would - only be invoked once with the deletion notification for the file. - -* When you disconnect from a server (for example, when the - server fails), you will not get any watches until the connection - is reestablished. For this reason session events are sent to all - outstanding watch handlers. Use session events to go into a safe - mode: you will not be receiving events while disconnected, so your - process should act conservatively in that mode. - - - -## ZooKeeper access control using ACLs - -ZooKeeper uses ACLs to control access to its znodes (the -data nodes of a ZooKeeper data tree). The ACL implementation is -quite similar to UNIX file access permissions: it employs -permission bits to allow/disallow various operations against a -node and the scope to which the bits apply. Unlike standard UNIX -permissions, a ZooKeeper node is not limited by the three standard -scopes for user (owner of the file), group, and world -(other). ZooKeeper does not have a notion of an owner of a -znode. Instead, an ACL specifies sets of ids and permissions that -are associated with those ids. - -Note also that an ACL pertains only to a specific znode. In -particular it does not apply to children. For example, if -_/app_ is only readable by ip:172.16.16.1 and -_/app/status_ is world readable, anyone will -be able to read _/app/status_; ACLs are not -recursive. - -ZooKeeper supports pluggable authentication schemes. Ids are -specified using the form _scheme:expression_, -where _scheme_ is the authentication scheme -that the id corresponds to. The set of valid expressions are defined -by the scheme. For example, _ip:172.16.16.1_ is -an id for a host with the address _172.16.16.1_ -using the _ip_ scheme, whereas _digest:bob:password_ -is an id for the user with the name of _bob_ using -the _digest_ scheme. - -When a client connects to ZooKeeper and authenticates -itself, ZooKeeper associates all the ids that correspond to a -client with the clients connection. These ids are checked against -the ACLs of znodes when a client tries to access a node. ACLs are -made up of pairs of _(scheme:expression, -perms)_. The format of -the _expression_ is specific to the scheme. For -example, the pair _(ip:19.22.0.0/16, READ)_ -gives the _READ_ permission to any clients with -an IP address that starts with 19.22. - - - -### ACL Permissions - -ZooKeeper supports the following permissions: - -* **CREATE**: you can create a child node -* **READ**: you can get data from a node and list its children. -* **WRITE**: you can set data for a node -* **DELETE**: you can delete a child node -* **ADMIN**: you can set permissions - -The _CREATE_ -and _DELETE_ permissions have been broken out -of the _WRITE_ permission for finer grained -access controls. The cases for _CREATE_ -and _DELETE_ are the following: - -You want A to be able to do a set on a ZooKeeper node, but -not be able to _CREATE_ -or _DELETE_ children. - -_CREATE_ -without _DELETE_: clients create requests by -creating ZooKeeper nodes in a parent directory. You want all -clients to be able to add, but only request processor can -delete. (This is kind of like the APPEND permission for -files.) - -Also, the _ADMIN_ permission is there -since ZooKeeper doesn’t have a notion of file owner. In some -sense the _ADMIN_ permission designates the -entity as the owner. ZooKeeper doesn’t support the LOOKUP -permission (execute permission bit on directories to allow you -to LOOKUP even though you can't list the directory). Everyone -implicitly has LOOKUP permission. This allows you to stat a -node, but nothing more. (The problem is, if you want to call -zoo_exists() on a node that doesn't exist, there is no -permission to check.) - -_ADMIN_ permission also has a special role in terms of ACLs: -in order to retrieve ACLs of a znode user has to have _READ_ or _ADMIN_ - permission, but without _ADMIN_ permission, digest hash values will be -masked out. - -As of versions **3.9.2 / 3.8.4 / 3.7.3** the exists() call will now verify ACLs -on nodes that exist and the client must have READ permission otherwise -'Insufficient permission' error will be raised. - - - -#### Builtin ACL Schemes - -ZooKeeper has the following built in schemes: - -* **world** has a - single id, _anyone_, that represents - anyone. -* **auth** is a special - scheme which ignores any provided expression and instead uses the current user, - credentials, and scheme. Any expression (whether _user_ like with SASL - authentication or _user:password_ like with DIGEST authentication) provided is ignored - by the ZooKeeper server when persisting the ACL. However, the expression must still be - provided in the ACL because the ACL must match the form _scheme:expression:perms_. - This scheme is provided as a convenience as it is a common use-case for - a user to create a znode and then restrict access to that znode to only that user. - If there is no authenticated user, setting an ACL with the auth scheme will fail. -* **digest** uses - a _username:password_ string to generate - MD5 hash which is then used as an ACL ID - identity. Authentication is done by sending - the _username:password_ in clear text. When - used in the ACL the expression will be - the _username:base64_ - encoded _SHA1_ - password _digest_. -* **ip** uses the - client host IP as an ACL ID identity. The ACL expression is of - the form _addr/bits_ where the most - significant _bits_ - of _addr_ are matched against the most - significant _bits_ of the client host - IP. -* **x509** uses the client - X500 Principal as an ACL ID identity. The ACL expression is the exact - X500 Principal name of a client. When using the secure port, clients - are automatically authenticated and their auth info for the x509 scheme - is set. - - - -#### ZooKeeper C client API - -The following constants are provided by the ZooKeeper C -library: - -* _const_ _int_ ZOO_PERM_READ; //can read node’s value and list its children -* _const_ _int_ ZOO_PERM_WRITE;// can set the node’s value -* _const_ _int_ ZOO_PERM_CREATE; //can create children -* _const_ _int_ ZOO_PERM_DELETE;// can delete children -* _const_ _int_ ZOO_PERM_ADMIN; //can execute set_acl() -* _const_ _int_ ZOO_PERM_ALL;// all of the above flags OR’d together - -The following are the standard ACL IDs: - -* _struct_ Id ZOO_ANYONE_ID_UNSAFE; //(‘world’,’anyone’) -* _struct_ Id ZOO_AUTH_IDS;// (‘auth’,’’) - -ZOO_AUTH_IDS empty identity string should be interpreted as “the identity of the creator”. - -ZooKeeper client comes with three standard ACLs: - -* _struct_ ACL_vector ZOO_OPEN_ACL_UNSAFE; //(ZOO_PERM_ALL,ZOO_ANYONE_ID_UNSAFE) -* _struct_ ACL_vector ZOO_READ_ACL_UNSAFE;// (ZOO_PERM_READ, ZOO_ANYONE_ID_UNSAFE) -* _struct_ ACL_vector ZOO_CREATOR_ALL_ACL; //(ZOO_PERM_ALL,ZOO_AUTH_IDS) - -The ZOO_OPEN_ACL_UNSAFE is completely open free for all -ACL: any application can execute any operation on the node and -can create, list and delete its children. The -ZOO_READ_ACL_UNSAFE is read-only access for any -application. CREATE_ALL_ACL grants all permissions to the -creator of the node. The creator must have been authenticated by -the server (for example, using “_digest_” -scheme) before it can create nodes with this ACL. - -The following ZooKeeper operations deal with ACLs: - -* _int_ _zoo_add_auth_ - (zhandle_t \*zh,_const_ _char_* - scheme,_const_ _char_* - cert, _int_ certLen, void_completion_t - completion, _const_ _void_ - \*data); - -The application uses the zoo_add_auth function to -authenticate itself to the server. The function can be called -multiple times if the application wants to authenticate using -different schemes and/or identities. - -* _int_ _zoo_create_ - (zhandle_t \*zh, _const_ _char_ - \*path, _const_ _char_ - \*value,_int_ - valuelen, _const_ _struct_ - ACL_vector \*acl, _int_ - flags,_char_ - \*realpath, _int_ - max_realpath_len); - -zoo_create(...) operation creates a new node. The acl -parameter is a list of ACLs associated with the node. The parent -node must have the CREATE permission bit set. - -* _int_ _zoo_get_acl_ - (zhandle_t \*zh, _const_ _char_ - \*path,_struct_ ACL_vector - \*acl, _struct_ Stat \*stat); - -This operation returns a node’s ACL info. The node must have READ or ADMIN -permission set. Without ADMIN permission, the digest hash values will be masked out. - -* _int_ _zoo_set_acl_ - (zhandle_t \*zh, _const_ _char_ - \*path, _int_ - version,_const_ _struct_ - ACL_vector \*acl); - -This function replaces node’s ACL list with a new one. The -node must have the ADMIN permission set. - -Here is a sample code that makes use of the above APIs to -authenticate itself using the “_foo_” scheme -and create an ephemeral node “/xyz” with create-only -permissions. - -######Note ->This is a very simple example which is intended to show -how to interact with ZooKeeper ACLs -specifically. See *.../trunk/zookeeper-client/zookeeper-client-c/src/cli.c* -for an example of a C client implementation - - - - #include - #include - - #include "zookeeper.h" - - static zhandle_t *zh; - - /** - * In this example this method gets the cert for your - * environment -- you must provide - */ - char *foo_get_cert_once(char* id) { return 0; } - - /** Watcher function -- empty for this example, not something you should - * do in real code */ - void watcher(zhandle_t *zzh, int type, int state, const char *path, - void *watcherCtx) {} - - int main(int argc, char argv) { - char buffer[512]; - char p[2048]; - char *cert=0; - char appId[64]; - - strcpy(appId, "example.foo_test"); - cert = foo_get_cert_once(appId); - if(cert!=0) { - fprintf(stderr, - "Certificate for appid [%s] is [%s]\n",appId,cert); - strncpy(p,cert, sizeof(p)-1); - free(cert); - } else { - fprintf(stderr, "Certificate for appid [%s] not found\n",appId); - strcpy(p, "dummy"); - } - - zoo_set_debug_level(ZOO_LOG_LEVEL_DEBUG); - - zh = zookeeper_init("localhost:3181", watcher, 10000, 0, 0, 0); - if (!zh) { - return errno; - } - if(zoo_add_auth(zh,"foo",p,strlen(p),0,0)!=ZOK) - return 2; - - struct ACL CREATE_ONLY_ACL[] = {{ZOO_PERM_CREATE, ZOO_AUTH_IDS}}; - struct ACL_vector CREATE_ONLY = {1, CREATE_ONLY_ACL}; - int rc = zoo_create(zh,"/xyz","value", 5, &CREATE_ONLY, ZOO_EPHEMERAL, - buffer, sizeof(buffer)-1); - - /** this operation will fail with a ZNOAUTH error */ - int buflen= sizeof(buffer); - struct Stat stat; - rc = zoo_get(zh, "/xyz", 0, buffer, &buflen, &stat); - if (rc) { - fprintf(stderr, "Error %d for %s\n", rc, __LINE__); - } - - zookeeper_close(zh); - return 0; - } - - - - -## Pluggable ZooKeeper authentication - -ZooKeeper runs in a variety of different environments with -various different authentication schemes, so it has a completely -pluggable authentication framework. Even the builtin authentication -schemes use the pluggable authentication framework. - -To understand how the authentication framework works, first you must -understand the two main authentication operations. The framework -first must authenticate the client. This is usually done as soon as -the client connects to a server and consists of validating information -sent from or gathered about a client and associating it with the connection. -The second operation handled by the framework is finding the entries in an -ACL that correspond to client. ACL entries are <_idspec, -permissions_> pairs. The _idspec_ may be -a simple string match against the authentication information associated -with the connection or it may be a expression that is evaluated against that -information. It is up to the implementation of the authentication plugin -to do the match. Here is the interface that an authentication plugin must -implement: - - - public interface AuthenticationProvider { - String getScheme(); - KeeperException.Code handleAuthentication(ServerCnxn cnxn, byte authData[]); - boolean isValid(String id); - boolean matches(String id, String aclExpr); - boolean isAuthenticated(); - } - - -The first method _getScheme_ returns the string -that identifies the plugin. Because we support multiple methods of authentication, -an authentication credential or an _idspec_ will always be -prefixed with _scheme:_. The ZooKeeper server uses the scheme -returned by the authentication plugin to determine which ids the scheme -applies to. - -_handleAuthentication_ is called when a client -sends authentication information to be associated with a connection. The -client specifies the scheme to which the information corresponds. The -ZooKeeper server passes the information to the authentication plugin whose -_getScheme_ matches the scheme passed by the client. The -implementor of _handleAuthentication_ will usually return -an error if it determines that the information is bad, or it will associate information -with the connection using _cnxn.getAuthInfo().add(new Id(getScheme(), data))_. - -The authentication plugin is involved in both setting and using ACLs. When an -ACL is set for a znode, the ZooKeeper server will pass the id part of the entry to -the _isValid(String id)_ method. It is up to the plugin to verify -that the id has a correct form. For example, _ip:172.16.0.0/16_ -is a valid id, but _ip:host.com_ is not. If the new ACL includes -an "auth" entry, _isAuthenticated_ is used to see if the -authentication information for this scheme that is associated with the connection -should be added to the ACL. Some schemes -should not be included in auth. For example, the IP address of the client is not -considered as an id that should be added to the ACL if auth is specified. - -ZooKeeper invokes _matches(String id, String aclExpr)_ when checking an ACL. It -needs to match authentication information of the client against the relevant ACL -entries. To find the entries which apply to the client, the ZooKeeper server will -find the scheme of each entry and if there is authentication information -from that client for that scheme, _matches(String id, String aclExpr)_ -will be called with _id_ set to the authentication information -that was previously added to the connection by _handleAuthentication_ and -_aclExpr_ set to the id of the ACL entry. The authentication plugin -uses its own logic and matching scheme to determine if _id_ is included -in _aclExpr_. - -There are two built in authentication plugins: _ip_ and -_digest_. Additional plugins can adding using system properties. At -startup the ZooKeeper server will look for system properties that start with -"zookeeper.authProvider." and interpret the value of those properties as the class name -of an authentication plugin. These properties can be set using the -_-Dzookeeper.authProvider.X=com.f.MyAuth_ or adding entries such as -the following in the server configuration file: - - - authProvider.1=com.f.MyAuth - authProvider.2=com.f.MyAuth2 - - -Care should be taking to ensure that the suffix on the property is unique. If there are -duplicates such as _-Dzookeeper.authProvider.X=com.f.MyAuth -Dzookeeper.authProvider.X=com.f.MyAuth2_, -only one will be used. Also all servers must have the same plugins defined, otherwise clients using -the authentication schemes provided by the plugins will have problems connecting to some servers. - -**Added in 3.6.0**: An alternate abstraction is available for pluggable -authentication. It provides additional arguments. - - - public abstract class ServerAuthenticationProvider implements AuthenticationProvider { - public abstract KeeperException.Code handleAuthentication(ServerObjs serverObjs, byte authData[]); - public abstract boolean matches(ServerObjs serverObjs, MatchValues matchValues); - } - - -Instead of implementing AuthenticationProvider you extend ServerAuthenticationProvider. Your handleAuthentication() -and matches() methods will then receive the additional parameters (via ServerObjs and MatchValues). - -* **ZooKeeperServer** - The ZooKeeperServer instance -* **ServerCnxn** - The current connection -* **path** - The ZNode path being operated on (or null if not used) -* **perm** - The operation value or 0 -* **setAcls** - When the setAcl() method is being operated on, the list of ACLs that are being set - - - -## Consistency Guarantees - -ZooKeeper is a high performance, scalable service. Both reads and -write operations are designed to be fast, though reads are faster than -writes. The reason for this is that in the case of reads, ZooKeeper can -serve older data, which in turn is due to ZooKeeper's consistency -guarantees: - -* *Sequential Consistency* : - Updates from a client will be applied in the order that they - were sent. - -* *Atomicity* : - Updates either succeed or fail -- there are no partial - results. - -* *Single System Image* : - A client will see the same view of the service regardless of - the server that it connects to. i.e., a client will never see an - older view of the system even if the client fails over to a - different server with the same session. - -* *Reliability* : - Once an update has been applied, it will persist from that - time forward until a client overwrites the update. This guarantee - has two corollaries: - 1. If a client gets a successful return code, the update will - have been applied. On some failures (communication errors, - timeouts, etc) the client will not know if the update has - applied or not. We take steps to minimize the failures, but the - guarantee is only present with successful return codes. - (This is called the _monotonicity condition_ in Paxos.) - 1. Any updates that are seen by the client, through a read - request or successful update, will never be rolled back when - recovering from server failures. - -* *Timeliness* : - The clients view of the system is guaranteed to be up-to-date - within a certain time bound (on the order of tens of seconds). - Either system changes will be seen by a client within this bound, or - the client will detect a service outage. - -Using these consistency guarantees it is easy to build higher level -functions such as leader election, barriers, queues, and read/write -revocable locks solely at the ZooKeeper client (no additions needed to -ZooKeeper). See [Recipes and Solutions](recipes.html) -for more details. - -######Note - ->Sometimes developers mistakenly assume one other guarantee that -ZooKeeper does _not_ in fact make. This is: -> * Simultaneously Consistent Cross-Client Views* : - ZooKeeper does not guarantee that at every instance in - time, two different clients will have identical views of - ZooKeeper data. Due to factors like network delays, one client - may perform an update before another client gets notified of the - change. Consider the scenario of two clients, A and B. If client - A sets the value of a znode /a from 0 to 1, then tells client B - to read /a, client B may read the old value of 0, depending on - which server it is connected to. If it - is important that Client A and Client B read the same value, - Client B should call the **sync()** method from the ZooKeeper API - method before it performs its read. - So, ZooKeeper by itself doesn't guarantee that changes occur - synchronously across all servers, but ZooKeeper - primitives can be used to construct higher level functions that - provide useful client synchronization. (For more information, - see the [ZooKeeper Recipes](recipes.html). - - - -## Bindings - -The ZooKeeper client libraries come in two languages: Java and C. -The following sections describe these. - - - -### Java Binding - -There are two packages that make up the ZooKeeper Java binding: -**org.apache.zookeeper** and **org.apache.zookeeper.data**. The rest of the -packages that make up ZooKeeper are used internally or are part of the -server implementation. The **org.apache.zookeeper.data** package is made up of -generated classes that are used simply as containers. - -The main class used by a ZooKeeper Java client is the **ZooKeeper** class. Its two constructors differ only -by an optional session id and password. ZooKeeper supports session -recovery across instances of a process. A Java program may save its -session id and password to stable storage, restart, and recover the -session that was used by the earlier instance of the program. - -When a ZooKeeper object is created, two threads are created as -well: an IO thread and an event thread. All IO happens on the IO thread -(using Java NIO). All event callbacks happen on the event thread. -Session maintenance such as reconnecting to ZooKeeper servers and -maintaining heartbeat is done on the IO thread. Responses for -synchronous methods are also processed in the IO thread. All responses -to asynchronous methods and watch events are processed on the event -thread. There are a few things to notice that result from this -design: - -* All completions for asynchronous calls and watcher callbacks - will be made in order, one at a time. The caller can do any - processing they wish, but no other callbacks will be processed - during that time. -* Callbacks do not block the processing of the IO thread or the - processing of the synchronous calls. -* Synchronous calls may not return in the correct order. For - example, assume a client does the following processing: issues an - asynchronous read of node **/a** with - _watch_ set to true, and then in the completion - callback of the read it does a synchronous read of **/a**. (Maybe not good practice, but not illegal - either, and it makes for a simple example.) - Note that if there is a change to **/a** between the asynchronous read and the - synchronous read, the client library will receive the watch event - saying **/a** changed before the - response for the synchronous read, but because of the completion - callback blocking the event queue, the synchronous read will - return with the new value of **/a** - before the watch event is processed. - -Finally, the rules associated with shutdown are straightforward: -once a ZooKeeper object is closed or receives a fatal event -(SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid. -On a close, the two threads shut down and any further access on zookeeper -handle is undefined behavior and should be avoided. - - - -#### Client Configuration Parameters - -The following list contains configuration properties for the Java client. You can set any -of these properties using Java system properties. For server properties, please check the -[Server configuration section of the Admin Guide](zookeeperAdmin.html#sc_configuration). -The ZooKeeper Wiki also has useful pages about -[ZooKeeper SSL support](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide), -and [SASL authentication for ZooKeeper](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+and+SASL). - - -* *zookeeper.sasl.client* : - Set the value to **false** to disable - SASL authentication. Default is **true**. - -* *zookeeper.sasl.clientconfig* : - Specifies the context key in the JAAS login file. Default is "Client". - -* *zookeeper.server.principal* : - Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper - server, when Kerberos authentication is enabled. If this configuration is provided, then - the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: - zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm - Note: this config parameter is working only for ZooKeeper 3.5.7+, 3.6.0+ - -* *zookeeper.sasl.client.username* : - Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. - The format of a typical Kerberos V5 principal is primary/instance@REALM. - zookeeper.sasl.client.username specifies the primary part of the server principal. Default - is "zookeeper". Instance part is derived from the server IP. Finally server's principal is - username/IP@realm, where username is the value of zookeeper.sasl.client.username, IP is - the server IP, and realm is the value of zookeeper.server.realm. - -* *zookeeper.sasl.client.canonicalize.hostname* : - Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to - determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided - as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting - the fully qualified domain name belonging to the address. You can disable this 'canonicalization' - by setting: zookeeper.sasl.client.canonicalize.hostname=false - -* *zookeeper.sasl.client.allowReverseDnsLookup* : - **New in 3.9.5:** - Controls whether reverse DNS lookup is enabled when constructing the server principal for the SASL client. - Default: false - -* *zookeeper.server.realm* : - Realm part of the server principal. By default it is the client principal realm. - -* *zookeeper.disableAutoWatchReset* : - This switch controls whether automatic watch resetting is enabled. Clients automatically - reset watches during session reconnect by default, this option allows the client to turn off - this behavior by setting zookeeper.disableAutoWatchReset to **true**. - -* *zookeeper.client.secure* : - **New in 3.5.5:** - If you want to connect to the server secure client port, you need to set this property to - **true** - on the client. This will connect to server using SSL with specified credentials. Note that - it requires the Netty client. - -* *zookeeper.clientCnxnSocket* : - Specifies which ClientCnxnSocket to be used. Possible values are - **org.apache.zookeeper.ClientCnxnSocketNIO** - and - **org.apache.zookeeper.ClientCnxnSocketNetty** - . Default is - **org.apache.zookeeper.ClientCnxnSocketNIO** - . If you want to connect to server's secure client port, you need to set this property to - **org.apache.zookeeper.ClientCnxnSocketNetty** - on client. - -* *zookeeper.ssl.keyStore.location and zookeeper.ssl.keyStore.password* : - **New in 3.5.5:** - Specifies the file path to a JKS containing the local credentials to be used for SSL connections, - and the password to unlock the file. - -* *zookeeper.ssl.keyStore.passwordPath* : - **New in 3.8.0:** - Specifies the file path which contains the keystore password - -* *zookeeper.ssl.trustStore.location and zookeeper.ssl.trustStore.password* : - **New in 3.5.5:** - Specifies the file path to a JKS containing the remote credentials to be used for SSL connections, - and the password to unlock the file. - -* *zookeeper.ssl.trustStore.passwordPath* : - **New in 3.8.0:** - Specifies the file path which contains the truststore password - -* *zookeeper.ssl.keyStore.type* and *zookeeper.ssl.trustStore.type*: - **New in 3.5.5:** - Specifies the file format of keys/trust store files used to establish TLS connection to the ZooKeeper server. - Values: JKS, PEM, PKCS12 or null (detect by filename). Default: null. - **New in 3.6.3, 3.7.0:** - The format BCFKS was added. - -* *jute.maxbuffer* : - In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, - or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send - data on the order of kilobytes. If incoming data length is more than this value, an IOException - is raised. This value of client side should keep same with the server side(Setting **System.setProperty("jute.maxbuffer", "xxxx")** in the client side will work), - otherwise problems will arise. - -* *zookeeper.kinit* : - Specifies path to kinit binary. Default is "/usr/bin/kinit". - -* *zookeeper.shuffleDnsResponse* : - **New in 3.10.0:** - Specifies whether ZooKeeper client should randomly pick an IP address from the DNS lookup query result when resolving - server addresses or not. This is a feature flag in order to keep the old behavior of the default DNS resolver in - `StaticHostProvider`, because we disabled it by default. The reason behind that is shuffling the response of DNS queries - shadows JVM network property `java.net.preferIPv6Addresses` (default: false). This property controls whether JVM's built-in - resolver should prioritize v4 (false value) or v6 (true value) addresses when putting together the list of IP addresses - in the result. In other words the above Java system property was completely ineffective in the case of ZooKeeper server host - resolution protocol and this must have been fixed. In a dual stack environment one might want to prefer one stack over - the other which, in case of Java processes, should be controlled by JVM network properties and ZooKeeper must honor - these settings. Since the old behavior has been with us since day zero, we introduced this feature flag in case you - need it. Such case could be when you have a buggy DNS server which responds IP addresses always in the same order and - you want to randomize that. - Default: false - -* *zookeeper.hostProvider.dnsSrvRefreshIntervalSeconds* : - **New in 3.10.0:** - Specifies the refresh interval in seconds for DNS SRV record lookups when using DnsSrvHostProvider. - A value of 0 disables periodic refresh. - Default: 60 seconds - - - -### C Binding - -The C binding has a single-threaded and multi-threaded library. -The multi-threaded library is easiest to use and is most similar to the -Java API. This library will create an IO thread and an event dispatch -thread for handling connection maintenance and callbacks. The -single-threaded library allows ZooKeeper to be used in event driven -applications by exposing the event loop used in the multi-threaded -library. - -The package includes two shared libraries: zookeeper_st and -zookeeper_mt. The former only provides the asynchronous APIs and -callbacks for integrating into the application's event loop. The only -reason this library exists is to support the platforms were a -_pthread_ library is not available or is unstable -(i.e. FreeBSD 4.x). In all other cases, application developers should -link with zookeeper_mt, as it includes support for both Sync and Async -API. - - - -#### Installation - -If you're building the client from a check-out from the Apache -repository, follow the steps outlined below. If you're building from a -project source package downloaded from apache, skip to step **3**. - -1. Run `mvn compile` in zookeeper-jute directory (*.../trunk/zookeeper-jute*). - This will create a directory named "generated" under - *.../trunk/zookeeper-client/zookeeper-client-c*. -1. Change directory to the*.../trunk/zookeeper-client/zookeeper-client-c* - and run `autoreconf -if` to bootstrap **autoconf**, **automake** and **libtool**. Make sure you have **autoconf version 2.59** or greater installed. - Skip to step**4**. -1. If you are building from a project source package, - unzip/untar the source tarball and cd to the* - zookeeper-x.x.x/zookeeper-client/zookeeper-client-c* directory. -1. Run `./configure ` to - generate the makefile. Here are some of options the **configure** utility supports that can be - useful in this step: - * `--enable-debug` - Enables optimization and enables debug info compiler - options. (Disabled by default.) - * `--without-syncapi` - Disables Sync API support; zookeeper_mt library won't be - built. (Enabled by default.) - * `--disable-static` - Do not build static libraries. (Enabled by - default.) - * `--disable-shared` - Do not build shared libraries. (Enabled by - default.) -######Note ->See INSTALL for general information about running **configure**. -1. Run `make` or `make - install` to build the libraries and install them. -1. To generate doxygen documentation for the ZooKeeper API, run - `make doxygen-doc`. All documentation will be - placed in a new subfolder named docs. By default, this command - only generates HTML. For information on other document formats, - run `./configure --help` - - - -#### Building Your Own C Client - -In order to be able to use the ZooKeeper C API in your application -you have to remember to - -1. Include ZooKeeper header: `#include ` -1. If you are building a multithreaded client, compile with - `-DTHREADED` compiler flag to enable the multi-threaded version of - the library, and then link against the - _zookeeper_mt_ library. If you are building a - single-threaded client, do not compile with `-DTHREADED`, and be - sure to link against the_zookeeper_st_library. - -######Note ->See *.../trunk/zookeeper-client/zookeeper-client-c/src/cli.c* -for an example of a C client implementation - - - -## Building Blocks: A Guide to ZooKeeper Operations - -This section surveys all the operations a developer can perform -against a ZooKeeper server. It is lower level information than the earlier -concepts chapters in this manual, but higher level than the ZooKeeper API -Reference. It covers these topics: - -* [Connecting to ZooKeeper](#sc_connectingToZk) - - - -### Handling Errors - -Both the Java and C client bindings may report errors. The Java client binding does so by throwing KeeperException, calling code() on the exception will return the specific error code. The C client binding returns an error code as defined in the enum ZOO_ERRORS. API callbacks indicate result code for both language bindings. See the API documentation (javadoc for Java, doxygen for C) for full details on the possible errors and their meaning. - - - -### Connecting to ZooKeeper - -Before we begin, you will have to set up a running Zookeeper server so that we can start developing the client. For C client bindings, we will be using the multithreaded library(zookeeper_mt) with a simple example written in C. To establish a connection with Zookeeper server, we make use of C API - _zookeeper_init_ with the following signature: - - int zookeeper_init(const char *host, watcher_fn fn, int recv_timeout, const clientid_t *clientid, void *context, int flags); - -* **host* : - Connection string to zookeeper server in the format of host:port. If there are multiple servers, use comma as separator after specifying the host:port pairs. Eg: "127.0.0.1:2181,127.0.0.1:3001,127.0.0.1:3002" - -* *fn* : - Watcher function to process events when a notification is triggered. - -* *recv_timeout* : - Session expiration time in milliseconds. - -* **clientid* : - We can specify 0 for a new session. If a session has already establish previously, we could provide that client ID and it would reconnect to that previous session. - -* **context* : - Context object that can be associated with the zkhandle_t handler. If it is not used, we can set it to 0. - -* *flags* : - In an initiation, we can leave it for 0. - -We will demonstrate client that outputs "Connected to Zookeeper" after successful connection or an error message otherwise. Let's call the following code _zkClient.cc_ : - - - #include - #include - #include - using namespace std; - - // Keeping track of the connection state - static int connected = 0; - static int expired = 0; - - // *zkHandler handles the connection with Zookeeper - static zhandle_t *zkHandler; - - // watcher function would process events - void watcher(zhandle_t *zkH, int type, int state, const char *path, void *watcherCtx) - { - if (type == ZOO_SESSION_EVENT) { - - // state refers to states of zookeeper connection. - // To keep it simple, we would demonstrate these 3: ZOO_EXPIRED_SESSION_STATE, ZOO_CONNECTED_STATE, ZOO_NOTCONNECTED_STATE - // If you are using ACL, you should be aware of an authentication failure state - ZOO_AUTH_FAILED_STATE - if (state == ZOO_CONNECTED_STATE) { - connected = 1; - } else if (state == ZOO_NOTCONNECTED_STATE ) { - connected = 0; - } else if (state == ZOO_EXPIRED_SESSION_STATE) { - expired = 1; - connected = 0; - zookeeper_close(zkH); - } - } - } - - int main(){ - zoo_set_debug_level(ZOO_LOG_LEVEL_DEBUG); - - // zookeeper_init returns the handler upon a successful connection, null otherwise - zkHandler = zookeeper_init("localhost:2181", watcher, 10000, 0, 0, 0); - - if (!zkHandler) { - return errno; - }else{ - printf("Connection established with Zookeeper. \n"); - } - - // Close Zookeeper connection - zookeeper_close(zkHandler); - - return 0; - } - - -Compile the code with the multithreaded library mentioned before. - -`> g++ -Iinclude/ zkClient.cpp -lzookeeper_mt -o Client` - -Run the client. - -`> ./Client` - -From the output, you should see "Connected to Zookeeper" along with Zookeeper's DEBUG messages if the connection is successful. - - - -## Gotchas: Common Problems and Troubleshooting - -So now you know ZooKeeper. It's fast, simple, your application -works, but wait ... something's wrong. Here are some pitfalls that -ZooKeeper users fall into: - -1. If you are using watches, you must look for the connected watch - event. When a ZooKeeper client disconnects from a server, you will - not receive notification of changes until reconnected. If you are - watching for a znode to come into existence, you will miss the event - if the znode is created and deleted while you are disconnected. -1. You must test ZooKeeper server failures. The ZooKeeper service - can survive failures as long as a majority of servers are active. The - question to ask is: can your application handle it? In the real world - a client's connection to ZooKeeper can break. (ZooKeeper server - failures and network partitions are common reasons for connection - loss.) The ZooKeeper client library takes care of recovering your - connection and letting you know what happened, but you must make sure - that you recover your state and any outstanding requests that failed. - Find out if you got it right in the test lab, not in production - test - with a ZooKeeper service made up of a several of servers and subject - them to reboots. -1. The list of ZooKeeper servers used by the client must match the - list of ZooKeeper servers that each ZooKeeper server has. Things can - work, although not optimally, if the client list is a subset of the - real list of ZooKeeper servers, but not if the client lists ZooKeeper - servers not in the ZooKeeper cluster. -1. Be careful where you put that transaction log. The most - performance-critical part of ZooKeeper is the transaction log. - ZooKeeper must sync transactions to media before it returns a - response. A dedicated transaction log device is key to consistent good - performance. Putting the log on a busy device will adversely effect - performance. If you only have one storage device, put trace files on - NFS and increase the snapshotCount; it doesn't eliminate the problem, - but it can mitigate it. -1. Set your Java max heap size correctly. It is very important to - _avoid swapping._ Going to disk unnecessarily will - almost certainly degrade your performance unacceptably. Remember, in - ZooKeeper, everything is ordered, so if one request hits the disk, all - other queued requests hit the disk. - To avoid swapping, try to set the heapsize to the amount of - physical memory you have, minus the amount needed by the OS and cache. - The best way to determine an optimal heap size for your configurations - is to _run load tests_. If for some reason you - can't, be conservative in your estimates and choose a number well - below the limit that would cause your machine to swap. For example, on - a 4G machine, a 3G heap is a conservative estimate to start - with. - -## Links to Other Information - -Outside the formal documentation, there're several other sources of -information for ZooKeeper developers. - -* *[API Reference](https://zookeeper.apache.org/doc/current/apidocs/zookeeper-server/index.html)* : - The complete reference to the ZooKeeper API - -* *[ZooKeeper Talk at the Hadoop Summit 2008](https://www.youtube.com/watch?v=rXI9xiesUV8)* : - A video introduction to ZooKeeper, by Benjamin Reed of Yahoo! - Research - -* *[Barrier and Queue Tutorial](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Tutorial)* : - The excellent Java tutorial by Flavio Junqueira, implementing - simple barriers and producer-consumer queues using ZooKeeper. - -* *[ZooKeeper - A Reliable, Scalable Distributed Coordination System](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeperArticles)* : - An article by Todd Hoff (07/15/2008) - -* *[ZooKeeper Recipes](recipes.html)* : - Pseudo-level discussion of the implementation of various - synchronization solutions with ZooKeeper: Event Handles, Queues, - Locks, and Two-phase Commits. - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperQuotas.md b/zookeeper-docs/src/main/resources/markdown/zookeeperQuotas.md deleted file mode 100644 index 72864c37e4f..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperQuotas.md +++ /dev/null @@ -1,85 +0,0 @@ - - -# ZooKeeper Quota's Guide - -### A Guide to Deployment and Administration - -* [Quotas](#zookeeper_quotas) - * [Setting Quotas](#Setting+Quotas) - * [Listing Quotas](#Listing+Quotas) - * [Deleting Quotas](#Deleting+Quotas) - - - -## Quotas - -ZooKeeper has both namespace and bytes quotas. You can use the ZooKeeperMain class to setup quotas. -ZooKeeper prints _WARN_ messages if users exceed the quota assigned to them. The messages -are printed in the log of the ZooKeeper. - -Notice: What the `namespace` quota means is the count quota which limits the number of children -under the path(included itself). - - $ bin/zkCli.sh -server host:port** - -The above command gives you a command line option of using quotas. - - - -### Setting Quotas - -- You can use `setquota` to set a quota on a ZooKeeper node. It has an option of setting quota with -`-n` (for namespace/count) and `-b` (for bytes/data length). - -- The ZooKeeper quota is stored in ZooKeeper itself in **/zookeeper/quota**. To disable other people from -changing the quotas, users can set the ACL for **/zookeeper/quota** ,so that only admins are able to read and write to it. - -- If the quota doesn't exist in the specified path,create the quota, otherwise update the quota. - -- The Scope of the quota users set is all the nodes under the path specified (included itself). - -- In order to simplify the calculation of quota in the current directory/hierarchy structure, a complete tree path(from root to leaf node) -can be set only one quota. In the situation when setting a quota in a path which its parent or child node already has a quota. `setquota` will -reject and tell the specified parent or child path, users can adjust allocations of quotas(delete/move-up/move-down the quota) -according to specific circumstances. - -- Combined with the Chroot, the quota will have a better isolation effectiveness between different applications.For example: - - ```bash - # Chroot is: - 192.168.0.1:2181,192.168.0.2:2181,192.168.0.3:2181/apps/app1 - setquota -n 100000 /apps/app1 - ``` - -- Users cannot set the quota on the path under **/zookeeper/quota** - -- The quota supports the soft and hard quota. The soft quota just logs the warning info when exceeding the quota, but the hard quota -also throws a `QuotaExceededException`. When setting soft and hard quota on the same path, the hard quota has the priority. - - - -### Listing Quotas - -You can use _listquota_ to list a quota on a ZooKeeper node. - - - -### Deleting Quotas - -You can use _delquota_ to delete quota on a ZooKeeper node. - - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperReconfig.md b/zookeeper-docs/src/main/resources/markdown/zookeeperReconfig.md deleted file mode 100644 index 8b3e3dad799..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperReconfig.md +++ /dev/null @@ -1,908 +0,0 @@ - - -# ZooKeeper Dynamic Reconfiguration - -* [Overview](#ch_reconfig_intro) -* [Changes to Configuration Format](#ch_reconfig_format) - * [Specifying the client port](#sc_reconfig_clientport) - * [Specifying multiple server addresses](#sc_multiaddress) - * [The standaloneEnabled flag](#sc_reconfig_standaloneEnabled) - * [The reconfigEnabled flag](#sc_reconfig_reconfigEnabled) - * [Dynamic configuration file](#sc_reconfig_file) - * [Backward compatibility](#sc_reconfig_backward) -* [Upgrading to 3.5.0](#ch_reconfig_upgrade) -* [Dynamic Reconfiguration of the ZooKeeper Ensemble](#ch_reconfig_dyn) - * [API](#ch_reconfig_api) - * [Security](#sc_reconfig_access_control) - * [Retrieving the current dynamic configuration](#sc_reconfig_retrieving) - * [Modifying the current dynamic configuration](#sc_reconfig_modifying) - * [General](#sc_reconfig_general) - * [Incremental mode](#sc_reconfig_incremental) - * [Non-incremental mode](#sc_reconfig_nonincremental) - * [Conditional reconfig](#sc_reconfig_conditional) - * [Error conditions](#sc_reconfig_errors) - * [Additional comments](#sc_reconfig_additional) -* [Rebalancing Client Connections](#ch_reconfig_rebalancing) - - - -## Overview - -Prior to the 3.5.0 release, the membership and all other configuration -parameters of Zookeeper were static - loaded during boot and immutable at -runtime. Operators resorted to ''rolling restarts'' - a manually intensive -and error-prone method of changing the configuration that has caused data -loss and inconsistency in production. - -Starting with 3.5.0, “rolling restarts” are no longer needed! -ZooKeeper comes with full support for automated configuration changes: the -set of Zookeeper servers, their roles (participant / observer), all ports, -and even the quorum system can be changed dynamically, without service -interruption and while maintaining data consistency. Reconfigurations are -performed immediately, just like other operations in ZooKeeper. Multiple -changes can be done using a single reconfiguration command. The dynamic -reconfiguration functionality does not limit operation concurrency, does -not require client operations to be stopped during reconfigurations, has a -very simple interface for administrators and no added complexity to other -client operations. - -New client-side features allow clients to find out about configuration -changes and to update the connection string (list of servers and their -client ports) stored in their ZooKeeper handle. A probabilistic algorithm -is used to rebalance clients across the new configuration servers while -keeping the extent of client migrations proportional to the change in -ensemble membership. - -This document provides the administrator manual for reconfiguration. -For a detailed description of the reconfiguration algorithms, performance -measurements, and more, please see our paper: - -* *Shraer, A., Reed, B., Malkhi, D., Junqueira, F. Dynamic -Reconfiguration of Primary/Backup Clusters. In _USENIX Annual -Technical Conference (ATC)_(2012), 425-437* : - Links: [paper (pdf)](https://www.usenix.org/system/files/conference/atc12/atc12-final74.pdf), [slides (pdf)](https://www.usenix.org/sites/default/files/conference/protected-files/shraer\_atc12\_slides.pdf), [video](https://www.usenix.org/conference/atc12/technical-sessions/presentation/shraer), [hadoop summit slides](http://www.slideshare.net/Hadoop\_Summit/dynamic-reconfiguration-of-zookeeper) - -**Note:** Starting with 3.5.3, the dynamic reconfiguration -feature is disabled by default, and has to be explicitly turned on via -[reconfigEnabled](zookeeperAdmin.html#sc_advancedConfiguration) configuration option. - - - -## Changes to Configuration Format - - - -### Specifying the client port - -A client port of a server is the port on which the server accepts plaintext (non-TLS) client connection requests -and secure client port is the port on which the server accepts TLS client connection requests. - -Starting with 3.5.0 the -_clientPort_ and _clientPortAddress_ configuration parameters should no longer be used in zoo.cfg. - -Starting with 3.10.0 the -_secureClientPort_ and _secureClientPortAddress_ configuration parameters should no longer be used in zoo.cfg. - -Instead, this information is now part of the server keyword specification, which -becomes as follows: - - server. = ::[:role];[[:]][;[:]] - -- [New in ZK 3.10.0] The client port specification is optional and is to the right of the - first semicolon. The secure client port specification is also optional and is to the right - of the second semicolon. However, both the client port and secure client port specification - cannot be omitted, at least one of them should be present. If the user intends to omit client - port specification and provide only secure client port specification (TLS-only server), a second - semicolon should still be specified to indicate an empty client port specification (see last - example below). In either spec, the port address is optional, and if not specified it defaults - to "0.0.0.0". -- As usual, role is also optional, it can be _participant_ or _observer_ (_participant_ by default). - -Examples of legal server statements: - - server.5 = 125.23.63.23:1234:1235;1236 (non-TLS server) - server.5 = 125.23.63.23:1234:1235;1236;1237 (non-TLS + TLS server) - server.5 = 125.23.63.23:1234:1235;;1237 (TLS-only server) - server.5 = 125.23.63.23:1234:1235:participant;1236 (non-TLS server) - server.5 = 125.23.63.23:1234:1235:observer;1236 (non-TLS server) - server.5 = 125.23.63.23:1234:1235;125.23.63.24:1236 (non-TLS server) - server.5 = 125.23.63.23:1234:1235:participant;125.23.63.23:1236 (non-TLS server) - server.5 = 125.23.63.23:1234:1235:participant;125.23.63.23:1236;125.23.63.23:1237 (non-TLS + TLS server) - server.5 = 125.23.63.23:1234:1235:participant;;125.23.63.23:1237 (TLS-only server) - - - - -### Specifying multiple server addresses - -Since ZooKeeper 3.6.0 it is possible to specify multiple addresses for each -ZooKeeper server (see [ZOOKEEPER-3188](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3188)). -This helps to increase availability and adds network level -resiliency to ZooKeeper. When multiple physical network interfaces are used -for the servers, ZooKeeper is able to bind on all interfaces and runtime switching -to a working interface in case a network error. The different addresses can be -specified in the config using a pipe ('|') character. - -Examples for a valid configurations using multiple addresses: - - server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889;2188 - server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889|zoo2-net3:2890:3890;2188 - server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889;zoo2-net1:2188 - server.2=zoo2-net1:2888:3888:observer|zoo2-net2:2889:3889:observer;2188 - - - -### The _standaloneEnabled_ flag - -Prior to 3.5.0, one could run ZooKeeper in Standalone mode or in a -Distributed mode. These are separate implementation stacks, and -switching between them during run time is not possible. By default (for -backward compatibility) _standaloneEnabled_ is set to -_true_. The consequence of using this default is that -if started with a single server the ensemble will not be allowed to -grow, and if started with more than one server it will not be allowed to -shrink to contain fewer than two participants. - -Setting the flag to _false_ instructs the system -to run the Distributed software stack even if there is only a single -participant in the ensemble. To achieve this the (static) configuration -file should contain: - - standaloneEnabled=false** - -With this setting it is possible to start a ZooKeeper ensemble -containing a single participant and to dynamically grow it by adding -more servers. Similarly, it is possible to shrink an ensemble so that -just a single participant remains, by removing servers. - -Since running the Distributed mode allows more flexibility, we -recommend setting the flag to _false_. We expect that -the legacy Standalone mode will be deprecated in the future. - - - -### The _reconfigEnabled_ flag - -Starting with 3.5.0 and prior to 3.5.3, there is no way to disable -dynamic reconfiguration feature. We would like to offer the option of -disabling reconfiguration feature because with reconfiguration enabled, -we have a security concern that a malicious actor can make arbitrary changes -to the configuration of a ZooKeeper ensemble, including adding a compromised -server to the ensemble. We prefer to leave to the discretion of the user to -decide whether to enable it or not and make sure that the appropriate security -measure are in place. So in 3.5.3 the [reconfigEnabled](zookeeperAdmin.html#sc_advancedConfiguration) configuration option is introduced -such that the reconfiguration feature can be completely disabled and any attempts -to reconfigure a cluster through reconfig API with or without authentication -will fail by default, unless **reconfigEnabled** is set to -**true**. - -To set the option to true, the configuration file (zoo.cfg) should contain: - - reconfigEnabled=true - - - -### Dynamic configuration file - -Starting with 3.5.0 we're distinguishing between dynamic -configuration parameters, which can be changed during runtime, and -static configuration parameters, which are read from a configuration -file when a server boots and don't change during its execution. For now, -the following configuration keywords are considered part of the dynamic -configuration: _server_, _group_ -and _weight_. - -Dynamic configuration parameters are stored in a separate file on -the server (which we call the dynamic configuration file). This file is -linked from the static config file using the new -_dynamicConfigFile_ keyword. - -**Example** - -#### zoo_replicated1.cfg - - - tickTime=2000 - dataDir=/zookeeper/data/zookeeper1 - initLimit=5 - syncLimit=2 - dynamicConfigFile=/zookeeper/conf/zoo_replicated1.cfg.dynamic - - -#### zoo_replicated1.cfg.dynamic - - - server.1=125.23.63.23:2780:2783:participant;2791 - server.2=125.23.63.24:2781:2784:participant;2792 - server.3=125.23.63.25:2782:2785:participant;2793 - - -When the ensemble configuration changes, the static configuration -parameters remain the same. The dynamic parameters are pushed by -ZooKeeper and overwrite the dynamic configuration files on all servers. -Thus, the dynamic configuration files on the different servers are -usually identical (they can only differ momentarily when a -reconfiguration is in progress, or if a new configuration hasn't -propagated yet to some of the servers). Once created, the dynamic -configuration file should not be manually altered. Changed are only made -through the new reconfiguration commands outlined below. Note that -changing the config of an offline cluster could result in an -inconsistency with respect to configuration information stored in the -ZooKeeper log (and the special configuration znode, populated from the -log) and is therefore highly discouraged. - -**Example 2** - -Users may prefer to initially specify a single configuration file. -The following is thus also legal: - -#### zoo_replicated1.cfg - - - tickTime=2000 - dataDir=/zookeeper/data/zookeeper1 - initLimit=5 - syncLimit=2 - clientPort= - - -The configuration files on each server will be automatically split -into dynamic and static files, if they are not already in this format. -So the configuration file above will be automatically transformed into -the two files in Example 1. Note that the clientPort and -clientPortAddress lines (if specified) will be automatically removed -during this process, if they are redundant (as in the example above). -The original static configuration file is backed up (in a .bak -file). - - - -### Backward compatibility - -We still support the old configuration format. For example, the -following configuration file is acceptable (but not recommended): - -#### zoo_replicated1.cfg - - tickTime=2000 - dataDir=/zookeeper/data/zookeeper1 - initLimit=5 - syncLimit=2 - clientPort=2791 - server.1=125.23.63.23:2780:2783:participant - server.2=125.23.63.24:2781:2784:participant - server.3=125.23.63.25:2782:2785:participant - - -During boot, a dynamic configuration file is created and contains -the dynamic part of the configuration as explained earlier. In this -case, however, the line "clientPort=2791" will remain in the static -configuration file of server 1 since it is not redundant -- it was not -specified as part of the "server.1=..." using the format explained in -the section [Changes to Configuration Format](#ch_reconfig_format). If a reconfiguration -is invoked that sets the client port of server 1, we remove -"clientPort=2791" from the static configuration file (the dynamic file -now contain this information as part of the specification of server -1). - - - -## Upgrading to 3.5.0 - -Upgrading a running ZooKeeper ensemble to 3.5.0 should be done only -after upgrading your ensemble to the 3.4.6 release. Note that this is only -necessary for rolling upgrades (if you're fine with shutting down the -system completely, you don't have to go through 3.4.6). If you attempt a -rolling upgrade without going through 3.4.6 (for example from 3.4.5), you -may get the following error: - - 2013-01-30 11:32:10,663 [myid:2] - INFO [localhost/127.0.0.1:2784:QuorumCnxManager$Listener@498] - Received connection request /127.0.0.1:60876 - 2013-01-30 11:32:10,663 [myid:2] - WARN [localhost/127.0.0.1:2784:QuorumCnxManager@349] - Invalid server id: -65536 - -During a rolling upgrade, each server is taken down in turn and -rebooted with the new 3.5.0 binaries. Before starting the server with -3.5.0 binaries, we highly recommend updating the configuration file so -that all server statements "server.x=..." contain client ports (see the -section [Specifying the client port](#sc_reconfig_clientport)). As explained earlier -you may leave the configuration in a single file, as well as leave the -clientPort/clientPortAddress statements (although if you specify client -ports in the new format, these statements are now redundant). - - - -## Dynamic Reconfiguration of the ZooKeeper Ensemble - -The ZooKeeper Java and C API were extended with getConfig and reconfig -commands that facilitate reconfiguration. Both commands have a synchronous -(blocking) variant and an asynchronous one. We demonstrate these commands -here using the Java CLI, but note that you can similarly use the C CLI or -invoke the commands directly from a program just like any other ZooKeeper -command. - - - -### API - -There are two sets of APIs for both Java and C client. - -* ***Reconfiguration API*** : - Reconfiguration API is used to reconfigure the ZooKeeper cluster. - Starting with 3.5.3, reconfiguration Java APIs are moved into ZooKeeperAdmin class - from ZooKeeper class, and use of this API requires ACL setup and user - authentication (see [Security](#sc_reconfig_access_control) for more information.). - -* ***Get Configuration API*** : - Get configuration APIs are used to retrieve ZooKeeper cluster configuration information - stored in /zookeeper/config znode. Use of this API does not require specific setup or authentication, - because /zookeeper/config is readable to any users. - - - -### Security - -Prior to **3.5.3**, there is no enforced security mechanism -over reconfig so any ZooKeeper clients that can connect to ZooKeeper server ensemble -will have the ability to change the state of a ZooKeeper cluster via reconfig. -It is thus possible for a malicious client to add compromised server to an ensemble, -e.g., add a compromised server, or remove legitimate servers. -Cases like these could be security vulnerabilities on a case by case basis. - -To address this security concern, we introduced access control over reconfig -starting from **3.5.3** such that only a specific set of users -can use reconfig commands or APIs, and these users need be configured explicitly. In addition, -the setup of ZooKeeper cluster must enable authentication so ZooKeeper clients can be authenticated. - -We also provide an escape hatch for users who operate and interact with a ZooKeeper ensemble in a secured -environment (i.e. behind company firewall). For those users who want to use reconfiguration feature but -don't want the overhead of configuring an explicit list of authorized user for reconfig access checks, -they can set ["skipACL"](zookeeperAdmin.html#sc_authOptions) to "yes" which will -skip ACL check and allow any user to reconfigure cluster. - -Overall, ZooKeeper provides flexible configuration options for the reconfigure feature -that allow a user to choose based on user's security requirement. -We leave to the discretion of the user to decide appropriate security measure are in place. - -* ***Access Control*** : - The dynamic configuration is stored in a special znode - ZooDefs.CONFIG_NODE = /zookeeper/config. This node by default is read only - for all users, except super user and users that's explicitly configured for write - access. - Clients that need to use reconfig commands or reconfig API should be configured as users - that have write access to CONFIG_NODE. By default, only the super user has full control including - write access to CONFIG_NODE. Additional users can be granted write access through superuser - by setting an ACL that has write permission associated with specified user. - A few examples of how to setup ACLs and use reconfiguration API with authentication can be found in - ReconfigExceptionTest.java and TestReconfigServer.cc. - -* ***Authentication*** : - Authentication of users is orthogonal to the access control and is delegated to - existing authentication mechanism supported by ZooKeeper's pluggable authentication schemes. - See [ZooKeeper and SASL](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Zookeeper+and+SASL) for more details on this topic. - -* ***Disable ACL check*** : - ZooKeeper supports ["skipACL"](zookeeperAdmin.html#sc_authOptions) option such that ACL - check will be completely skipped, if skipACL is set to "yes". In such cases any unauthenticated - users can use reconfig API. - - - -### Retrieving the current dynamic configuration - -The dynamic configuration is stored in a special znode -ZooDefs.CONFIG_NODE = /zookeeper/config. The new -`config` CLI command reads this znode (currently it is -simply a wrapper to `get /zookeeper/config`). As with -normal reads, to retrieve the latest committed value you should do a -`sync` first. - - [zk: 127.0.0.1:2791(CONNECTED) 3] config - server.1=localhost:2780:2783:participant;localhost:2791 - server.2=localhost:2781:2784:participant;localhost:2792 - server.3=localhost:2782:2785:participant;localhost:2793 - -Notice the last line of the output. This is the configuration -version. The version equals to the zxid of the reconfiguration command -which created this configuration. The version of the first established -configuration equals to the zxid of the NEWLEADER message sent by the -first successfully established leader. When a configuration is written -to a dynamic configuration file, the version automatically becomes part -of the filename and the static configuration file is updated with the -path to the new dynamic configuration file. Configuration files -corresponding to earlier versions are retained for backup -purposes. - -During boot time the version (if it exists) is extracted from the -filename. The version should never be altered manually by users or the -system administrator. It is used by the system to know which -configuration is most up-to-date. Manipulating it manually can result in -data loss and inconsistency. - -Just like a `get` command, the -`config` CLI command accepts the _-w_ -flag for setting a watch on the znode, and _-s_ flag for -displaying the Stats of the znode. It additionally accepts a new flag -_-c_ which outputs only the version and the client -connection string corresponding to the current configuration. For -example, for the configuration above we would get: - - [zk: 127.0.0.1:2791(CONNECTED) 17] config -c - 400000003 localhost:2791,localhost:2793,localhost:2792 - -Note that when using the API directly, this command is called -`getConfig`. - -As any read command it returns the configuration known to the -follower to which your client is connected, which may be slightly -out-of-date. One can use the `sync` command for -stronger guarantees. For example using the Java API: - - zk.sync(ZooDefs.CONFIG_NODE, void_callback, context); - zk.getConfig(watcher, callback, context); - -Note: in 3.5.0 it doesn't really matter which path is passed to the -`sync()` command as all the server's state is brought -up to date with the leader (so one could use a different path instead of -ZooDefs.CONFIG_NODE). However, this may change in the future. - - - -### Modifying the current dynamic configuration - -Modifying the configuration is done through the -`reconfig` command. There are two modes of -reconfiguration: incremental and non-incremental (bulk). The -non-incremental simply specifies the new dynamic configuration of the -system. The incremental specifies changes to the current configuration. -The `reconfig` command returns the new -configuration. - -A few examples are in: *ReconfigTest.java*, -*ReconfigRecoveryTest.java* and -*TestReconfigServer.cc*. - - - -#### General - -**Removing servers:** Any server can -be removed, including the leader (although removing the leader will -result in a short unavailability, see Figures 6 and 8 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters)). The server will not be shut-down automatically. -Instead, it becomes a "non-voting follower". This is somewhat similar -to an observer in that its votes don't count towards the Quorum of -votes necessary to commit operations. However, unlike a non-voting -follower, an observer doesn't actually see any operation proposals and -does not ACK them. Thus a non-voting follower has a more significant -negative effect on system throughput compared to an observer. -Non-voting follower mode should only be used as a temporary mode, -before shutting the server down, or adding it as a follower or as an -observer to the ensemble. We do not shut the server down automatically -for two main reasons. The first reason is that we do not want all the -clients connected to this server to be immediately disconnected, -causing a flood of connection requests to other servers. Instead, it -is better if each client decides when to migrate independently. The -second reason is that removing a server may sometimes (rarely) be -necessary in order to change it from "observer" to "participant" (this -is explained in the section [Additional comments](#sc_reconfig_additional)). - -Note that the new configuration should have some minimal number of -participants in order to be considered legal. If the proposed change -would leave the cluster with less than 2 participants and standalone -mode is enabled (standaloneEnabled=true, see the section [The _standaloneEnabled_ flag](#sc_reconfig_standaloneEnabled)), the reconfig will not be -processed (BadArgumentsException). If standalone mode is disabled -(standaloneEnabled=false) then it's legal to remain with 1 or more -participants. - -**Adding servers:** Before a -reconfiguration is invoked, the administrator must make sure that a -quorum (majority) of participants from the new configuration are -already connected and synced with the current leader. To achieve this -we need to connect a new joining server to the leader before it is -officially part of the ensemble. This is done by starting the joining -server using an initial list of servers which is technically not a -legal configuration of the system but (a) contains the joiner, and (b) -gives sufficient information to the joiner in order for it to find and -connect to the current leader. We list a few different options of -doing this safely. - -1. Initial configuration of joiners is comprised of servers in - the last committed configuration and one or more joiners, where - **joiners are listed as observers.** - For example, if servers D and E are added at the same time to (A, - B, C) and server C is being removed, the initial configuration of - D could be (A, B, C, D) or (A, B, C, D, E), where D and E are - listed as observers. Similarly, the configuration of E could be - (A, B, C, E) or (A, B, C, D, E), where D and E are listed as - observers. **Note that listing the joiners as - observers will not actually make them observers - it will only - prevent them from accidentally forming a quorum with other - joiners.** Instead, they will contact the servers in the - current configuration and adopt the last committed configuration - (A, B, C), where the joiners are absent. Configuration files of - joiners are backed up and replaced automatically as this happens. - After connecting to the current leader, joiners become non-voting - followers until the system is reconfigured and they are added to - the ensemble (as participant or observer, as appropriate). -1. Initial configuration of each joiner is comprised of servers - in the last committed configuration + **the - joiner itself, listed as a participant.** For example, to - add a new server D to a configuration consisting of servers (A, B, - C), the administrator can start D using an initial configuration - file consisting of servers (A, B, C, D). If both D and E are added - at the same time to (A, B, C), the initial configuration of D - could be (A, B, C, D) and the configuration of E could be (A, B, - C, E). Similarly, if D is added and C is removed at the same time, - the initial configuration of D could be (A, B, C, D). Never list - more than one joiner as participant in the initial configuration - (see warning below). -1. Whether listing the joiner as an observer or as participant, - it is also fine not to list all the current configuration servers, - as long as the current leader is in the list. For example, when - adding D we could start D with a configuration file consisting of - just (A, D) if A is the current leader. however this is more - fragile since if A fails before D officially joins the ensemble, D - doesn’t know anyone else and therefore the administrator will have - to intervene and restart D with another server list. - -######Note ->##### Warning - ->Never specify more than one joining server in the same initial -configuration as participants. Currently, the joining servers don’t -know that they are joining an existing ensemble; if multiple joiners -are listed as participants they may form an independent quorum -creating a split-brain situation such as processing operations -independently from your main ensemble. It is OK to list multiple -joiners as observers in an initial config. - -If the configuration of existing servers changes or they become unavailable -before the joiner succeeds to connect and learn about configuration changes, the -joiner may need to be restarted with an updated configuration file in order to be -able to connect. - -Finally, note that once connected to the leader, a joiner adopts -the last committed configuration, in which it is absent (the initial -config of the joiner is backed up before being rewritten). If the -joiner restarts in this state, it will not be able to boot since it is -absent from its configuration file. In order to start it you’ll once -again have to specify an initial configuration. - -**Modifying server parameters:** One -can modify any of the ports of a server, or its role -(participant/observer) by adding it to the ensemble with different -parameters. This works in both the incremental and the bulk -reconfiguration modes. It is not necessary to remove the server and -then add it back; just specify the new parameters as if the server is -not yet in the system. The server will detect the configuration change -and perform the necessary adjustments. See an example in the section -[Incremental mode](#sc_reconfig_incremental) and an exception to this -rule in the section [Additional comments](#sc_reconfig_additional). - -It is also possible to change the Quorum System used by the -ensemble (for example, change the Majority Quorum System to a -Hierarchical Quorum System on the fly). This, however, is only allowed -using the bulk (non-incremental) reconfiguration mode. In general, -incremental reconfiguration only works with the Majority Quorum -System. Bulk reconfiguration works with both Hierarchical and Majority -Quorum Systems. - -**Performance Impact:** There is -practically no performance impact when removing a follower, since it -is not being automatically shut down (the effect of removal is that -the server's votes are no longer being counted). When adding a server, -there is no leader change and no noticeable performance disruption. -For details and graphs please see Figures 6, 7 and 8 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters). - -The most significant disruption will happen when a leader change -is caused, in one of the following cases: - -1. Leader is removed from the ensemble. -1. Leader's role is changed from participant to observer. -1. The port used by the leader to send transactions to others - (quorum port) is modified. - -In these cases we perform a leader hand-off where the old leader -nominates a new leader. The resulting unavailability is usually -shorter than when a leader crashes since detecting leader failure is -unnecessary and electing a new leader can usually be avoided during a -hand-off (see Figures 6 and 8 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters)). - -When the client port of a server is modified, it does not drop -existing client connections. New connections to the server will have -to use the new client port. - -**Progress guarantees:** Up to the -invocation of the reconfig operation, a quorum of the old -configuration is required to be available and connected for ZooKeeper -to be able to make progress. Once reconfig is invoked, a quorum of -both the old and of the new configurations must be available. The -final transition happens once (a) the new configuration is activated, -and (b) all operations scheduled before the new configuration is -activated by the leader are committed. Once (a) and (b) happen, only a -quorum of the new configuration is required. Note, however, that -neither (a) nor (b) are visible to a client. Specifically, when a -reconfiguration operation commits, it only means that an activation -message was sent out by the leader. It does not necessarily mean that -a quorum of the new configuration got this message (which is required -in order to activate it) or that (b) has happened. If one wants to -make sure that both (a) and (b) has already occurred (for example, in -order to know that it is safe to shut down old servers that were -removed), one can simply invoke an update -(`set-data`, or some other quorum operation, but not -a `sync`) and wait for it to commit. An alternative -way to achieve this was to introduce another round to the -reconfiguration protocol (which, for simplicity and compatibility with -Zab, we decided to avoid). - - - -#### Incremental mode - -The incremental mode allows adding and removing servers to the -current configuration. Multiple changes are allowed. For -example: - - > reconfig -remove 3 -add - server.5=125.23.63.23:1234:1235;1236 - -Both the add and the remove options get a list of comma separated -arguments (no spaces): - - > reconfig -remove 3,4 -add - server.5=localhost:2111:2112;2113,6=localhost:2114:2115:observer;2116 - -The format of the server statement is exactly the same as -described in the section [Specifying the client port](#sc_reconfig_clientport) and -includes the client port. Notice that here instead of "server.5=" you -can just say "5=". In the example above, if server 5 is already in the -system, but has different ports or is not an observer, it is updated -and once the configuration commits becomes an observer and starts -using these new ports. This is an easy way to turn participants into -observers and vice versa or change any of their ports, without -rebooting the server. - -ZooKeeper supports two types of Quorum Systems – the simple -Majority system (where the leader commits operations after receiving -ACKs from a majority of voters) and a more complex Hierarchical -system, where votes of different servers have different weights and -servers are divided into voting groups. Currently, incremental -reconfiguration is allowed only if the last proposed configuration -known to the leader uses a Majority Quorum System -(BadArgumentsException is thrown otherwise). - -Incremental mode - examples using the Java API: - - List leavingServers = new ArrayList(); - leavingServers.add("1"); - leavingServers.add("2"); - byte[] config = zk.reconfig(null, leavingServers, null, -1, new Stat()); - - List leavingServers = new ArrayList(); - List joiningServers = new ArrayList(); - leavingServers.add("1"); - joiningServers.add("server.4=localhost:1234:1235;1236"); - byte[] config = zk.reconfig(joiningServers, leavingServers, null, -1, new Stat()); - - String configStr = new String(config); - System.out.println(configStr); - -There is also an asynchronous API, and an API accepting comma -separated Strings instead of List. See -src/java/main/org/apache/zookeeper/ZooKeeper.java. - - - -#### Non-incremental mode - -The second mode of reconfiguration is non-incremental, whereby a -client gives a complete specification of the new dynamic system -configuration. The new configuration can either be given in place or -read from a file: - - > reconfig -file newconfig.cfg - -//newconfig.cfg is a dynamic config file, see [Dynamic configuration file](#sc_reconfig_file) - - > reconfig -members - server.1=125.23.63.23:2780:2783:participant;2791,server.2=125.23.63.24:2781:2784:participant;2792,server.3=125.23.63.25:2782:2785:participant;2793}} - -The new configuration may use a different Quorum System. For -example, you may specify a Hierarchical Quorum System even if the -current ensemble uses a Majority Quorum System. - -Bulk mode - example using the Java API: - - List newMembers = new ArrayList(); - newMembers.add("server.1=1111:1234:1235;1236"); - newMembers.add("server.2=1112:1237:1238;1239"); - newMembers.add("server.3=1114:1240:1241:observer;1242"); - - byte[] config = zk.reconfig(null, null, newMembers, -1, new Stat()); - - String configStr = new String(config); - System.out.println(configStr); - -There is also an asynchronous API, and an API accepting comma -separated String containing the new members instead of -List. See -src/java/main/org/apache/zookeeper/ZooKeeper.java. - - - -#### Conditional reconfig - -Sometimes (especially in non-incremental mode) a new proposed -configuration depends on what the client "believes" to be the current -configuration, and should be applied only to that configuration. -Specifically, the `reconfig` succeeds only if the -last configuration at the leader has the specified version. - - > reconfig -file -v - -In the previously listed Java examples, instead of -1 one could -specify a configuration version to condition the -reconfiguration. - - - -#### Error conditions - -In addition to normal ZooKeeper error conditions, a -reconfiguration may fail for the following reasons: - -1. another reconfig is currently in progress - (ReconfigInProgress) -1. the proposed change would leave the cluster with less than 2 - participants, in case standalone mode is enabled, or, if - standalone mode is disabled then its legal to remain with 1 or - more participants (BadArgumentsException) -1. no quorum of the new configuration was connected and - up-to-date with the leader when the reconfiguration processing - began (NewConfigNoQuorum) -1. `-v x` was specified, but the version -`y` of the latest configuration is not -`x` (BadVersionException) -1. an incremental reconfiguration was requested but the last - configuration at the leader uses a Quorum System which is - different from the Majority system (BadArgumentsException) -1. syntax error (BadArgumentsException) -1. I/O exception when reading the configuration from a file - (BadArgumentsException) - -Most of these are illustrated by test-cases in -*ReconfigFailureCases.java*. - - - -#### Additional comments - -**Liveness:** To better understand -the difference between incremental and non-incremental -reconfiguration, suppose that client C1 adds server D to the system -while a different client C2 adds server E. With the non-incremental -mode, each client would first invoke `config` to find -out the current configuration, and then locally create a new list of -servers by adding its own suggested server. The new configuration can -then be submitted using the non-incremental -`reconfig` command. After both reconfigurations -complete, only one of E or D will be added (not both), depending on -which client's request arrives second to the leader, overwriting the -previous configuration. The other client can repeat the process until -its change takes effect. This method guarantees system-wide progress -(i.e., for one of the clients), but does not ensure that every client -succeeds. To have more control C2 may request to only execute the -reconfiguration in case the version of the current configuration -hasn't changed, as explained in the section [Conditional reconfig](#sc_reconfig_conditional). In this way it may avoid blindly -overwriting the configuration of C1 if C1's configuration reached the -leader first. - -With incremental reconfiguration, both changes will take effect as -they are simply applied by the leader one after the other to the -current configuration, whatever that is (assuming that the second -reconfig request reaches the leader after it sends a commit message -for the first reconfig request -- currently the leader will refuse to -propose a reconfiguration if another one is already pending). Since -both clients are guaranteed to make progress, this method guarantees -stronger liveness. In practice, multiple concurrent reconfigurations -are probably rare. Non-incremental reconfiguration is currently the -only way to dynamically change the Quorum System. Incremental -configuration is currently only allowed with the Majority Quorum -System. - -**Changing an observer into a -follower:** Clearly, changing a server that participates in -voting into an observer may fail if error (2) occurs, i.e., if fewer -than the minimal allowed number of participants would remain. However, -converting an observer into a participant may sometimes fail for a -more subtle reason: Suppose, for example, that the current -configuration is (A, B, C, D), where A is the leader, B and C are -followers and D is an observer. In addition, suppose that B has -crashed. If a reconfiguration is submitted where D is said to become a -follower, it will fail with error (3) since in this configuration, a -majority of voters in the new configuration (any 3 voters), must be -connected and up-to-date with the leader. An observer cannot -acknowledge the history prefix sent during reconfiguration, and -therefore it does not count towards these 3 required servers and the -reconfiguration will be aborted. In case this happens, a client can -achieve the same task by two reconfig commands: first invoke a -reconfig to remove D from the configuration and then invoke a second -command to add it back as a participant (follower). During the -intermediate state D is a non-voting follower and can ACK the state -transfer performed during the second reconfig command. - - - -## Rebalancing Client Connections - -When a ZooKeeper cluster is started, if each client is given the same -connection string (list of servers), the client will randomly choose a -server in the list to connect to, which makes the expected number of -client connections per server the same for each of the servers. We -implemented a method that preserves this property when the set of servers -changes through reconfiguration. See Sections 4 and 5.1 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters). - -In order for the method to work, all clients must subscribe to -configuration changes (by setting a watch on /zookeeper/config either -directly or through the `getConfig` API command). When -the watch is triggered, the client should read the new configuration by -invoking `sync` and `getConfig` and if -the configuration is indeed new invoke the -`updateServerList` API command. To avoid mass client -migration at the same time, it is better to have each client sleep a -random short period of time before invoking -`updateServerList`. - -A few examples can be found in: -*StaticHostProviderTest.java* and -*TestReconfig.cc* - -Example (this is not a recipe, but a simplified example just to -explain the general idea): - - public void process(WatchedEvent event) { - synchronized (this) { - if (event.getType() == EventType.None) { - connected = (event.getState() == KeeperState.SyncConnected); - notifyAll(); - } else if (event.getPath()!=null && event.getPath().equals(ZooDefs.CONFIG_NODE)) { - // in prod code never block the event thread! - zk.sync(ZooDefs.CONFIG_NODE, this, null); - zk.getConfig(this, this, null); - } - } - } - - public void processResult(int rc, String path, Object ctx, byte[] data, Stat stat) { - if (path!=null && path.equals(ZooDefs.CONFIG_NODE)) { - String config[] = ConfigUtils.getClientConfigStr(new String(data)).split(" "); // similar to config -c - long version = Long.parseLong(config[0], 16); - if (this.configVersion == null){ - this.configVersion = version; - } else if (version > this.configVersion) { - hostList = config[1]; - try { - // the following command is not blocking but may cause the client to close the socket and - // migrate to a different server. In practice it's better to wait a short period of time, chosen - // randomly, so that different clients migrate at different times - zk.updateServerList(hostList); - } catch (IOException e) { - System.err.println("Error updating server list"); - e.printStackTrace(); - } - this.configVersion = version; - } - } - } diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperSnapshotAndRestore.md b/zookeeper-docs/src/main/resources/markdown/zookeeperSnapshotAndRestore.md deleted file mode 100644 index 576f18fdadd..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperSnapshotAndRestore.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# ZooKeeper Snapshot and Restore Guide - -Zookeeper is designed to withstand machine failures. A Zookeeper cluster can automatically recover -from temporary failures such as machine reboot. It can also tolerate up to (N-1)/2 permanent -failures for a cluster of N members due to hardware failures or disk corruption, etc. When a member -permanently fails, it loses access to the cluster. If the cluster permanently loses more than -(N-1)/2 members, it disastrously fails and loses quorum. Once the quorum is lost, the cluster -cannot reach consensus and therefore cannot continue to accept updates. - -To recover from such disastrous failures, Zookeeper provides snapshot and restore functionalities to -restore a cluster from a snapshot. - -1. Snapshot and restore operate on the connected server via Admin Server APIs -1. Snapshot and restore are rate limited to protect the server from being overloaded -1. Snapshot and restore require authentication and authorization on the root path with ALL permission. -The supported auth schemas are digest, x509 and IP. - -* [Snapshot](#zookeeper_snapshot) -* [Restore](#zookeeper_restore) - - - -## Snapshot -Recovering a cluster needs a snapshot from a ZooKeeper cluster. Users can periodically take -snapshots from a live server which has the highest zxid and stream out data to a local -or external storage/file system (e.g., S3). - - ```bash - # The snapshot command takes snapshot from the server it connects to and rate limited to once every 5 mins by default - curl -H 'Authorization: digest root:root_passwd' http://hostname:adminPort/commands/snapshot?streaming=true --output snapshotFileName - ``` - - -## Restore - -Restoring a cluster needs a single snapshot as input stream. Restore can be used for recovering a -cluster for quorum lost or building a brand-new cluster with seed data. - -All members should restore using the same snapshot. The following are the recommended steps: - -- Blocking traffic on the client port or client secure port before restore starts -- Take a snapshot of the latest database state using the snapshot admin server command if applicable -- For each server - - Moving the files in dataDir and dataLogDir to different location to prevent the restored database - from being overwritten when server restarts after restore - - Restore the server using restore admin server command -- Unblocking traffic on the client port or client secure port after restore completes - - ```bash - # The restore command takes a snapshot as input stream and restore the db of the server it connects. It is rate limited to once every 5 mins by default - curl -H 'Content-Type:application/octet-stream' -H 'Authorization: digest root:root_passwd' -POST http://hostname:adminPort/commands/restore --data-binary "@snapshotFileName" - ``` diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperStarted.md b/zookeeper-docs/src/main/resources/markdown/zookeeperStarted.md deleted file mode 100644 index a33e83c33b4..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperStarted.md +++ /dev/null @@ -1,373 +0,0 @@ - - -# ZooKeeper Getting Started Guide - -* [Getting Started: Coordinating Distributed Applications with ZooKeeper](#getting-started-coordinating-distributed-applications-with-zooKeeper) - * [Pre-requisites](#sc_Prerequisites) - * [Download](#sc_Download) - * [Standalone Operation](#sc_InstallingSingleMode) - * [Managing ZooKeeper Storage](#sc_FileManagement) - * [Connecting to ZooKeeper](#sc_ConnectingToZooKeeper) - * [Programming to ZooKeeper](#sc_ProgrammingToZooKeeper) - * [Running Replicated ZooKeeper](#sc_RunningReplicatedZooKeeper) - * [Other Optimizations](#other-optimizations) - - - -## Getting Started: Coordinating Distributed Applications with ZooKeeper - -This document contains information to get you started quickly with -ZooKeeper. It is aimed primarily at developers hoping to try it out, and -contains simple installation instructions for a single ZooKeeper server, a -few commands to verify that it is running, and a simple programming -example. Finally, as a convenience, there are a few sections regarding -more complicated installations, for example running replicated -deployments, and optimizing the transaction log. However for the complete -instructions for commercial deployments, please refer to the [ZooKeeper -Administrator's Guide](zookeeperAdmin.html). - - - -### Pre-requisites - -See [System Requirements](zookeeperAdmin.html#sc_systemReq) in the Admin guide. - - - -### Download - -To get a ZooKeeper distribution, download a recent -[stable](http://zookeeper.apache.org/releases.html) release from one of the Apache Download -Mirrors. - - - -### Standalone Operation - -Setting up a ZooKeeper server in standalone mode is -straightforward. The server is contained in a single JAR file, -so installation consists of creating a configuration. - -Once you've downloaded a stable ZooKeeper release unpack -it and cd to the root - -To start ZooKeeper you need a configuration file. Here is a sample, -create it in **conf/zoo.cfg**: - - - tickTime=2000 - dataDir=/var/lib/zookeeper - clientPort=2181 - - -This file can be called anything, but for the sake of this -discussion call -it **conf/zoo.cfg**. Change the -value of **dataDir** to specify an -existing (empty to start with) directory. Here are the meanings -for each of the fields: - -* ***tickTime*** : - the basic time unit in milliseconds used by ZooKeeper. It is - used to do heartbeats and the minimum session timeout will be - twice the tickTime. - -* ***dataDir*** : - the location to store the in-memory database snapshots and, - unless specified otherwise, the transaction log of updates to the - database. - -* ***clientPort*** : - the port to listen for client connections - -Now that you created the configuration file, you can start -ZooKeeper: - - - bin/zkServer.sh start - - -ZooKeeper logs messages using _logback_ -- more detail -available in the -[Logging](zookeeperProgrammers.html#Logging) -section of the Programmer's Guide. You will see log messages -coming to the console (default) and/or a log file depending on -the logback configuration. - -The steps outlined here run ZooKeeper in standalone mode. There is -no replication, so if ZooKeeper process fails, the service will go down. -This is fine for most development situations, but to run ZooKeeper in -replicated mode, please see [Running Replicated -ZooKeeper](#sc_RunningReplicatedZooKeeper). - - - -### Managing ZooKeeper Storage - -For long running production systems ZooKeeper storage must -be managed externally (dataDir and logs). See the section on -[maintenance](zookeeperAdmin.html#sc_maintenance) for -more details. - - - -### Connecting to ZooKeeper - - - $ bin/zkCli.sh -server 127.0.0.1:2181 - - -This lets you perform simple, file-like operations. - -Once you have connected, you should see something like: - - - Connecting to localhost:2181 - ... - Welcome to ZooKeeper! - JLine support is enabled - [zkshell: 0] - -From the shell, type `help` to get a listing of commands that can be executed from the client, as in: - - - [zkshell: 0] help - ZooKeeper -server host:port cmd args - addauth scheme auth - close - config [-c] [-w] [-s] - connect host:port - create [-s] [-e] [-c] [-t ttl] path [data] [acl] - delete [-v version] path - deleteall path - delquota [-n|-b] path - get [-s] [-w] path - getAcl [-s] path - getAllChildrenNumber path - getEphemerals path - history - listquota path - ls [-s] [-w] [-R] path - printwatches on|off - quit - reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*] - redo cmdno - removewatches path [-c|-d|-a] [-l] - set [-s] [-v version] path data - setAcl [-s] [-v version] [-R] path acl - setquota -n|-b val path - stat [-w] path - sync path - - -From here, you can try a few simple commands to get a feel for this simple command line interface. First, start by issuing the list command, as -in `ls`, yielding: - - - [zkshell: 8] ls / - [zookeeper] - - -Next, create a new znode by running `create /zk_test my_data`. This creates a new znode and associates the string "my_data" with the node. -You should see: - - - [zkshell: 9] create /zk_test my_data - Created /zk_test - - -Issue another `ls /` command to see what the directory looks like: - - - [zkshell: 11] ls / - [zookeeper, zk_test] - - -Notice that the zk_test directory has now been created. - -Next, verify that the data was associated with the znode by running the `get` command, as in: - - - [zkshell: 12] get /zk_test - my_data - cZxid = 5 - ctime = Fri Jun 05 13:57:06 PDT 2009 - mZxid = 5 - mtime = Fri Jun 05 13:57:06 PDT 2009 - pZxid = 5 - cversion = 0 - dataVersion = 0 - aclVersion = 0 - ephemeralOwner = 0 - dataLength = 7 - numChildren = 0 - - -We can change the data associated with zk_test by issuing the `set` command, as in: - - - [zkshell: 14] set /zk_test junk - cZxid = 5 - ctime = Fri Jun 05 13:57:06 PDT 2009 - mZxid = 6 - mtime = Fri Jun 05 14:01:52 PDT 2009 - pZxid = 5 - cversion = 0 - dataVersion = 1 - aclVersion = 0 - ephemeralOwner = 0 - dataLength = 4 - numChildren = 0 - [zkshell: 15] get /zk_test - junk - cZxid = 5 - ctime = Fri Jun 05 13:57:06 PDT 2009 - mZxid = 6 - mtime = Fri Jun 05 14:01:52 PDT 2009 - pZxid = 5 - cversion = 0 - dataVersion = 1 - aclVersion = 0 - ephemeralOwner = 0 - dataLength = 4 - numChildren = 0 - - -(Notice we did a `get` after setting the data and it did, indeed, change. - -Finally, let's `delete` the node by issuing: - - - [zkshell: 16] delete /zk_test - [zkshell: 17] ls / - [zookeeper] - [zkshell: 18] - - -That's it for now. To explore more, see the [Zookeeper CLI](zookeeperCLI.html). - - - -### Programming to ZooKeeper - -ZooKeeper has a Java bindings and C bindings. They are -functionally equivalent. The C bindings exist in two variants: single -threaded and multi-threaded. These differ only in how the messaging loop -is done. For more information, see the [Programming -Examples in the ZooKeeper Programmer's Guide](zookeeperProgrammers.html#ch_programStructureWithExample) for -sample code using the different APIs. - - - -### Running Replicated ZooKeeper - -Running ZooKeeper in standalone mode is convenient for evaluation, -some development, and testing. But in production, you should run -ZooKeeper in replicated mode. A replicated group of servers in the same -application is called a _quorum_, and in replicated -mode, all servers in the quorum have copies of the same configuration -file. - -######Note ->For replicated mode, a minimum of three servers are required, -and it is strongly recommended that you have an odd number of -servers. If you only have two servers, then you are in a -situation where if one of them fails, there are not enough -machines to form a majority quorum. Two servers are inherently -**less** stable than a single server, because there are two single -points of failure. - -The required -**conf/zoo.cfg** -file for replicated mode is similar to the one used in standalone -mode, but with a few differences. Here is an example: - - tickTime=2000 - dataDir=/var/lib/zookeeper - clientPort=2181 - initLimit=5 - syncLimit=2 - server.1=zoo1:2888:3888 - server.2=zoo2:2888:3888 - server.3=zoo3:2888:3888 - -The new entry, **initLimit** is -timeouts ZooKeeper uses to limit the length of time the ZooKeeper -servers in quorum have to connect to a leader. The entry **syncLimit** limits how far out of date a server can -be from a leader. - -With both of these timeouts, you specify the unit of time using -**tickTime**. In this example, the timeout -for initLimit is 5 ticks at 2000 milliseconds a tick, or 10 -seconds. - -The entries of the form _server.X_ list the -servers that make up the ZooKeeper service. When the server starts up, -it knows which server it is by looking for the file -_myid_ in the data directory. That file has the -contains the server number, in ASCII. - -Finally, note the two port numbers after each server -name: " 2888" and "3888". Peers use the former port to connect -to other peers. Such a connection is necessary so that peers -can communicate, for example, to agree upon the order of -updates. More specifically, a ZooKeeper server uses this port -to connect followers to the leader. When a new leader arises, a -follower opens a TCP connection to the leader using this -port. Because the default leader election also uses TCP, we -currently require another port for leader election. This is the -second port in the server entry. - -######Note ->If you want to test multiple servers on a single -machine, specify the servername -as _localhost_ with unique quorum & -leader election ports (i.e. 2888:3888, 2889:3889, 2890:3890 in -the example above) for each server.X in that server's config -file. Of course separate _dataDir_s and -distinct _clientPort_s are also necessary -(in the above replicated example, running on a -single _localhost_, you would still have -three config files). - ->Please be aware that setting up multiple servers on a single -machine will not create any redundancy. If something were to -happen which caused the machine to die, all of the zookeeper -servers would be offline. Full redundancy requires that each -server have its own machine. It must be a completely separate -physical server. Multiple virtual machines on the same physical -host are still vulnerable to the complete failure of that host. - ->If you have multiple network interfaces in your ZooKeeper machines, -you can also instruct ZooKeeper to bind on all of your interfaces and -automatically switch to a healthy interface in case of a network failure. -For details, see the [Configuration Parameters](zookeeperAdmin.html#id_multi_address). - - - -### Other Optimizations - -There are a couple of other configuration parameters that can -greatly increase performance: - -* To get low latencies on updates it is important to - have a dedicated transaction log directory. By default - transaction logs are put in the same directory as the data - snapshots and _myid_ file. The dataLogDir - parameters indicates a different directory to use for the - transaction logs. - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperTools.md b/zookeeper-docs/src/main/resources/markdown/zookeeperTools.md deleted file mode 100644 index d4abe385467..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperTools.md +++ /dev/null @@ -1,698 +0,0 @@ - - -# A series of tools for ZooKeeper - -* [Scripts](#Scripts) - * [zkServer.sh](#zkServer) - * [zkCli.sh](#zkCli) - * [zkEnv.sh](#zkEnv) - * [zkCleanup.sh](#zkCleanup) - * [zkTxnLogToolkit.sh](#zkTxnLogToolkit) - * [zkSnapShotToolkit.sh](#zkSnapShotToolkit) - * [zkSnapshotRecursiveSummaryToolkit.sh](#zkSnapshotRecursiveSummaryToolkit) - * [zkSnapshotComparer.sh](#zkSnapshotComparer) - -* [Benchmark](#Benchmark) - * [YCSB](#YCSB) - * [zk-smoketest](#zk-smoketest) - -* [Testing](#Testing) - * [Fault Injection Framework](#fault-injection) - * [Byteman](#Byteman) - * [Jepsen Test](#jepsen-test) - - - -## Scripts - - - -### zkServer.sh -A command for the operations for the ZooKeeper server. - -```bash -Usage: ./zkServer.sh {start|start-foreground|stop|version|restart|status|upgrade|print-cmd} -# start the server -./zkServer.sh start - -# start the server in the foreground for debugging -./zkServer.sh start-foreground - -# stop the server -./zkServer.sh stop - -# restart the server -./zkServer.sh restart - -# show the status,mode,role of the server -./zkServer.sh status -JMX enabled by default -Using config: /data/software/zookeeper/conf/zoo.cfg -Mode: standalone - -# Deprecated -./zkServer.sh upgrade - -# print the parameters of the start-up -./zkServer.sh print-cmd - -# show the version of the ZooKeeper server -./zkServer.sh version -Apache ZooKeeper, version 3.6.0-SNAPSHOT 06/11/2019 05:39 GMT - -``` - -The `status` command establishes a client connection to the server to execute diagnostic commands. -When the ZooKeeper cluster is started in client SSL only mode (by omitting the clientPort -from the zoo.cfg), then additional SSL related configuration has to be provided before using -the `./zkServer.sh status` command to find out if the ZooKeeper server is running. An example: - - CLIENT_JVMFLAGS="-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty -Dzookeeper.ssl.trustStore.location=/tmp/clienttrust.jks -Dzookeeper.ssl.trustStore.password=password -Dzookeeper.ssl.keyStore.location=/tmp/client.jks -Dzookeeper.ssl.keyStore.password=password -Dzookeeper.client.secure=true" ./zkServer.sh status - - - - -### zkCli.sh -Look at the [ZooKeeperCLI](zookeeperCLI.html) - - - -### zkEnv.sh -The environment setting for the ZooKeeper server - -```bash -# the setting of log property -ZOO_LOG_DIR: the directory to store the logs -``` - - - -### zkCleanup.sh -Clean up the old snapshots and transaction logs. - -```bash -Usage: - * args dataLogDir [snapDir] -n count - * dataLogDir -- path to the txn log directory - * snapDir -- path to the snapshot directory - * count -- the number of old snaps/logs you want to keep, value should be greater than or equal to 3 -# Keep the latest 5 logs and snapshots -./zkCleanup.sh -n 5 -``` - - - -### zkTxnLogToolkit.sh -TxnLogToolkit is a command line tool shipped with ZooKeeper which -is capable of recovering transaction log entries with broken CRC. - -Running it without any command line parameters or with the `-h,--help` argument, it outputs the following help page: - - $ bin/zkTxnLogToolkit.sh - usage: TxnLogToolkit [-dhrv] txn_log_file_name - -d,--dump Dump mode. Dump all entries of the log file. (this is the default) - -h,--help Print help message - -r,--recover Recovery mode. Re-calculate CRC for broken entries. - -v,--verbose Be verbose in recovery mode: print all entries, not just fixed ones. - -y,--yes Non-interactive mode: repair all CRC errors without asking - -The default behaviour is safe: it dumps the entries of the given -transaction log file to the screen: (same as using `-d,--dump` parameter) - - $ bin/zkTxnLogToolkit.sh log.100000001 - ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 - 4/5/18 2:15:58 PM CEST session 0x16295bafcc40000 cxid 0x0 zxid 0x100000001 createSession 30000 - CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null - 4/5/18 2:16:12 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x100000003 createSession 30000 - 4/5/18 2:17:34 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x200000001 closeSession null - 4/5/18 2:17:34 PM CEST session 0x16295bd23720000 cxid 0x0 zxid 0x200000002 createSession 30000 - 4/5/18 2:18:02 PM CEST session 0x16295bd23720000 cxid 0x2 zxid 0x200000003 create '/andor,#626262,v{s{31,s{'world,'anyone}}},F,1 - EOF reached after 6 txns. - -There's a CRC error in the 2nd entry of the above transaction log file. In **dump** -mode, the toolkit only prints this information to the screen without touching the original file. In -**recovery** mode (`-r,--recover` flag) the original file still remains -untouched and all transactions will be copied over to a new txn log file with ".fixed" suffix. It recalculates -CRC values and copies the calculated value, if it doesn't match the original txn entry. -By default, the tool works interactively: it asks for confirmation whenever CRC error encountered. - - $ bin/zkTxnLogToolkit.sh -r log.100000001 - ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 - CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null - Would you like to fix it (Yes/No/Abort) ? - -Answering **Yes** means the newly calculated CRC value will be outputted -to the new file. **No** means that the original CRC value will be copied over. -**Abort** will abort the entire operation and exits. -(In this case the ".fixed" will not be deleted and left in a half-complete state: contains only entries which -have already been processed or only the header if the operation was aborted at the first entry.) - - $ bin/zkTxnLogToolkit.sh -r log.100000001 - ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 - CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null - Would you like to fix it (Yes/No/Abort) ? y - EOF reached after 6 txns. - Recovery file log.100000001.fixed has been written with 1 fixed CRC error(s) - -The default behaviour of recovery is to be silent: only entries with CRC error get printed to the screen. -One can turn on verbose mode with the `-v,--verbose` parameter to see all records. -Interactive mode can be turned off with the `-y,--yes` parameter. In this case all CRC errors will be fixed -in the new transaction file. - - - -### zkSnapShotToolkit.sh -Dump a snapshot file to stdout, showing the detailed information of the each zk-node. - -```bash -# help -./zkSnapShotToolkit.sh -/usr/bin/java -USAGE: SnapshotFormatter [-d|-json] snapshot_file - -d dump the data for each znode - -json dump znode info in json format - -# show the each zk-node info without data content -./zkSnapShotToolkit.sh /data/zkdata/version-2/snapshot.fa01000186d -/zk-latencies_4/session_946 - cZxid = 0x00000f0003110b - ctime = Wed Sep 19 21:58:22 CST 2018 - mZxid = 0x00000f0003110b - mtime = Wed Sep 19 21:58:22 CST 2018 - pZxid = 0x00000f0003110b - cversion = 0 - dataVersion = 0 - aclVersion = 0 - ephemeralOwner = 0x00000000000000 - dataLength = 100 - -# [-d] show the each zk-node info with data content -./zkSnapShotToolkit.sh -d /data/zkdata/version-2/snapshot.fa01000186d -/zk-latencies2/session_26229 - cZxid = 0x00000900007ba0 - ctime = Wed Aug 15 20:13:52 CST 2018 - mZxid = 0x00000900007ba0 - mtime = Wed Aug 15 20:13:52 CST 2018 - pZxid = 0x00000900007ba0 - cversion = 0 - dataVersion = 0 - aclVersion = 0 - ephemeralOwner = 0x00000000000000 - data = eHh4eHh4eHh4eHh4eA== - -# [-json] show the each zk-node info with json format -./zkSnapShotToolkit.sh -json /data/zkdata/version-2/snapshot.fa01000186d -[[1,0,{"progname":"SnapshotFormatter.java","progver":"0.01","timestamp":1559788148637},[{"name":"\/","asize":0,"dsize":0,"dev":0,"ino":1001},[{"name":"zookeeper","asize":0,"dsize":0,"dev":0,"ino":1002},{"name":"config","asize":0,"dsize":0,"dev":0,"ino":1003},[{"name":"quota","asize":0,"dsize":0,"dev":0,"ino":1004},[{"name":"test","asize":0,"dsize":0,"dev":0,"ino":1005},{"name":"zookeeper_limits","asize":52,"dsize":52,"dev":0,"ino":1006},{"name":"zookeeper_stats","asize":15,"dsize":15,"dev":0,"ino":1007}]]],{"name":"test","asize":0,"dsize":0,"dev":0,"ino":1008}]] -``` - - -### zkSnapshotRecursiveSummaryToolkit.sh -Recursively collect and display child count and data size for a selected node. - - $./zkSnapshotRecursiveSummaryToolkit.sh - USAGE: - - SnapshotRecursiveSummary - - snapshot_file: path to the zookeeper snapshot - starting_node: the path in the zookeeper tree where the traversal should begin - max_depth: defines the depth where the tool still writes to the output. 0 means there is no depth limit, every non-leaf node's stats will be displayed, 1 means it will only contain the starting node's and it's children's stats, 2 ads another level and so on. This ONLY affects the level of details displayed, NOT the calculation. - -```bash -# recursively collect and display child count and data for the root node and 2 levels below it -./zkSnapshotRecursiveSummaryToolkit.sh /data/zkdata/version-2/snapshot.fa01000186d / 2 - -/ - children: 1250511 - data: 1952186580 --- /zookeeper --- children: 1 --- data: 0 --- /solr --- children: 1773 --- data: 8419162 ----- /solr/configs ----- children: 1640 ----- data: 8407643 ----- /solr/overseer ----- children: 6 ----- data: 0 ----- /solr/live_nodes ----- children: 3 ----- data: 0 -``` - - - -### zkSnapshotComparer.sh -SnapshotComparer is a tool that loads and compares two snapshots with configurable threshold and various filters, and outputs information about the delta. - -The delta includes specific znode paths added, updated, deleted comparing one snapshot to another. - -It's useful in use cases that involve snapshot analysis, such as offline data consistency checking, and data trending analysis (e.g. what's growing under which zNode path during when). - -This tool only outputs information about permanent nodes, ignoring both sessions and ephemeral nodes. - -It provides two tuning parameters to help filter out noise: -1. `--nodes` Threshold number of children added/removed; -2. `--bytes` Threshold number of bytes added/removed. - -#### Locate Snapshots -Snapshots can be found in [Zookeeper Data Directory](zookeeperAdmin.html#The+Data+Directory) which configured in [conf/zoo.cfg](zookeeperStarted.html#sc_InstallingSingleMode) when set up Zookeeper server. - -#### Supported Snapshot Formats -This tool supports uncompressed snapshot format, and compressed snapshot file formats: `snappy` and `gz`. Snapshots with different formats can be compared using this tool directly without decompression. - -#### Running the Tool -Running the tool with no command line argument or an unrecognized argument, it outputs the following help page: - -``` -usage: java -cp org.apache.zookeeper.server.SnapshotComparer - -b,--bytes (Required) The node data delta size threshold, in bytes, for printing the node. - -d,--debug Use debug output. - -i,--interactive Enter interactive mode. - -l,--left (Required) The left snapshot file. - -n,--nodes (Required) The descendant node delta size threshold, in nodes, for printing the node. - -r,--right (Required) The right snapshot file. -``` -Example Command: - -``` -./bin/zkSnapshotComparer.sh -l /zookeeper-data/backup/snapshot.d.snappy -r /zookeeper-data/backup/snapshot.44 -b 2 -n 1 -``` - -Example Output: -``` -... -Deserialized snapshot in snapshot.44 in 0.002741 seconds -Processed data tree in 0.000361 seconds -Node count: 10 -Total size: 0 -Max depth: 4 -Count of nodes at depth 0: 1 -Count of nodes at depth 1: 2 -Count of nodes at depth 2: 4 -Count of nodes at depth 3: 3 - -Node count: 22 -Total size: 2903 -Max depth: 5 -Count of nodes at depth 0: 1 -Count of nodes at depth 1: 2 -Count of nodes at depth 2: 4 -Count of nodes at depth 3: 7 -Count of nodes at depth 4: 8 - -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for depth 0 -Node found in both trees. Delta: 2903 bytes, 12 descendants -Analysis for depth 1 -Node /zk_test found in both trees. Delta: 2903 bytes, 12 descendants -Analysis for depth 2 -Node /zk_test/gz found in both trees. Delta: 730 bytes, 3 descendants -Node /zk_test/snappy found in both trees. Delta: 2173 bytes, 9 descendants -Analysis for depth 3 -Node /zk_test/gz/12345 found in both trees. Delta: 9 bytes, 1 descendants -Node /zk_test/gz/a found only in right tree. Descendant size: 721. Descendant count: 0 -Node /zk_test/snappy/anotherTest found in both trees. Delta: 1738 bytes, 2 descendants -Node /zk_test/snappy/test_1 found only in right tree. Descendant size: 344. Descendant count: 3 -Node /zk_test/snappy/test_2 found only in right tree. Descendant size: 91. Descendant count: 2 -Analysis for depth 4 -Node /zk_test/gz/12345/abcdef found only in right tree. Descendant size: 9. Descendant count: 0 -Node /zk_test/snappy/anotherTest/abc found only in right tree. Descendant size: 1738. Descendant count: 0 -Node /zk_test/snappy/test_1/a found only in right tree. Descendant size: 93. Descendant count: 0 -Node /zk_test/snappy/test_1/b found only in right tree. Descendant size: 251. Descendant count: 0 -Node /zk_test/snappy/test_2/xyz found only in right tree. Descendant size: 33. Descendant count: 0 -Node /zk_test/snappy/test_2/y found only in right tree. Descendant size: 58. Descendant count: 0 -All layers compared. -``` - -#### Interactive Mode -Use "-i" or "--interactive" to enter interactive mode: -``` -./bin/zkSnapshotComparer.sh -l /zookeeper-data/backup/snapshot.d.snappy -r /zookeeper-data/backup/snapshot.44 -b 2 -n 1 -i -``` - -There are three options to proceed: -``` -- Press enter to move to print current depth layer; -- Type a number to jump to and print all nodes at a given depth; -- Enter an ABSOLUTE path to print the immediate subtree of a node. Path must start with '/'. -``` - -Note: As indicated by the interactive messages, the tool only shows analysis on the result that filtered by tuning parameters bytes threshold and nodes threshold. - -Press enter to print current depth layer: - -``` -Current depth is 0 -Press enter to move to print current depth layer; -... -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for depth 0 -Node found in both trees. Delta: 2903 bytes, 12 descendants -``` - -Type a number to jump to and print all nodes at a given depth: - -(Jump forward) - -``` -Current depth is 1 -... -Type a number to jump to and print all nodes at a given depth; -... -3 -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for depth 3 -Node /zk_test/gz/12345 found in both trees. Delta: 9 bytes, 1 descendants -Node /zk_test/gz/a found only in right tree. Descendant size: 721. Descendant count: 0 -Filtered node /zk_test/gz/anotherOne of left size 0, right size 0 -Filtered right node /zk_test/gz/b of size 0 -Node /zk_test/snappy/anotherTest found in both trees. Delta: 1738 bytes, 2 descendants -Node /zk_test/snappy/test_1 found only in right tree. Descendant size: 344. Descendant count: 3 -Node /zk_test/snappy/test_2 found only in right tree. Descendant size: 91. Descendant count: 2 -``` - -(Jump back) - -``` -Current depth is 3 -... -Type a number to jump to and print all nodes at a given depth; -... -0 -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for depth 0 -Node found in both trees. Delta: 2903 bytes, 12 descendants -``` - -Out of range depth is handled: - -``` -Current depth is 1 -... -Type a number to jump to and print all nodes at a given depth; -... -10 -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Depth must be in range [0, 4] -``` - -Enter an ABSOLUTE path to print the immediate subtree of a node: - -``` -Current depth is 3 -... -Enter an ABSOLUTE path to print the immediate subtree of a node. -/zk_test -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for node /zk_test -Node /zk_test/gz found in both trees. Delta: 730 bytes, 3 descendants -Node /zk_test/snappy found in both trees. Delta: 2173 bytes, 9 descendants -``` - -Invalid path is handled: - -``` -Current depth is 3 -... -Enter an ABSOLUTE path to print the immediate subtree of a node. -/non-exist-path -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for node /non-exist-path -Path /non-exist-path is neither found in left tree nor right tree. -``` - -Invalid input is handled: -``` -Current depth is 1 -- Press enter to move to print current depth layer; -- Type a number to jump to and print all nodes at a given depth; -- Enter an ABSOLUTE path to print the immediate subtree of a node. Path must start with '/'. -12223999999999999999999999999999999999999 -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Input 12223999999999999999999999999999999999999 is not valid. Depth must be in range [0, 4]. Path must be an absolute path which starts with '/'. -``` - -Exit interactive mode automatically when all layers are compared: - -``` -Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. -Analysis for depth 4 -Node /zk_test/gz/12345/abcdef found only in right tree. Descendant size: 9. Descendant count: 0 -Node /zk_test/snappy/anotherTest/abc found only in right tree. Descendant size: 1738. Descendant count: 0 -Filtered right node /zk_test/snappy/anotherTest/abcd of size 0 -Node /zk_test/snappy/test_1/a found only in right tree. Descendant size: 93. Descendant count: 0 -Node /zk_test/snappy/test_1/b found only in right tree. Descendant size: 251. Descendant count: 0 -Filtered right node /zk_test/snappy/test_1/c of size 0 -Node /zk_test/snappy/test_2/xyz found only in right tree. Descendant size: 33. Descendant count: 0 -Node /zk_test/snappy/test_2/y found only in right tree. Descendant size: 58. Descendant count: 0 -All layers compared. -``` - -Or use `^c` to exit interactive mode anytime. - - - - -## Benchmark - - - -### YCSB - -#### Quick Start - -This section describes how to run YCSB on ZooKeeper. - -#### 1. Start ZooKeeper Server(s) - -#### 2. Install Java and Maven - -#### 3. Set Up YCSB - -Git clone YCSB and compile: - - git clone http://github.com/brianfrankcooper/YCSB.git - # more details in the landing page for instructions on downloading YCSB(https://github.com/brianfrankcooper/YCSB#getting-started). - cd YCSB - mvn -pl site.ycsb:zookeeper-binding -am clean package -DskipTests - -#### 4. Provide ZooKeeper Connection Parameters - -Set connectString, sessionTimeout, watchFlag in the workload you plan to run. - -- `zookeeper.connectString` -- `zookeeper.sessionTimeout` -- `zookeeper.watchFlag` - * A parameter for enabling ZooKeeper's watch, optional values:true or false.the default value is false. - * This parameter cannot test the watch performance, but for testing what effect will take on the read/write requests when enabling the watch. - - ```bash - ./bin/ycsb run zookeeper -s -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p zookeeper.watchFlag=true - ``` - -Or, you can set configs with the shell command, EG: - - # create a /benchmark namespace for sake of cleaning up the workspace after test. - # e.g the CLI:create /benchmark - ./bin/ycsb run zookeeper -s -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p zookeeper.sessionTimeout=30000 - -#### 5. Load data and run tests - -Load the data: - - # -p recordcount,the count of records/paths you want to insert - ./bin/ycsb load zookeeper -s -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p recordcount=10000 > outputLoad.txt - -Run the workload test: - - # YCSB workloadb is the most suitable workload for read-heavy workload for the ZooKeeper in the real world. - - # -p fieldlength, test the length of value/data-content took effect on performance - ./bin/ycsb run zookeeper -s -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p fieldlength=1000 - - # -p fieldcount - ./bin/ycsb run zookeeper -s -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p fieldcount=20 - - # -p hdrhistogram.percentiles,show the hdrhistogram benchmark result - ./bin/ycsb run zookeeper -threads 1 -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p hdrhistogram.percentiles=10,25,50,75,90,95,99,99.9 -p histogram.buckets=500 - - # -threads: multi-clients test, increase the **maxClientCnxns** in the zoo.cfg to handle more connections. - ./bin/ycsb run zookeeper -threads 10 -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark - - # show the timeseries benchmark result - ./bin/ycsb run zookeeper -threads 1 -P workloads/workloadb -p zookeeper.connectString=127.0.0.1:2181/benchmark -p measurementtype=timeseries -p timeseries.granularity=50 - - # cluster test - ./bin/ycsb run zookeeper -P workloads/workloadb -p zookeeper.connectString=192.168.10.43:2181,192.168.10.45:2181,192.168.10.27:2181/benchmark - - # test leader's read/write performance by setting zookeeper.connectString to leader's(192.168.10.43:2181) - ./bin/ycsb run zookeeper -P workloads/workloadb -p zookeeper.connectString=192.168.10.43:2181/benchmark - - # test for large znode(by default: jute.maxbuffer is 1048575 bytes/1 MB ). Notice:jute.maxbuffer should also be set the same value in all the zk servers. - ./bin/ycsb run zookeeper -jvm-args="-Djute.maxbuffer=4194304" -s -P workloads/workloadc -p zookeeper.connectString=127.0.0.1:2181/benchmark - - # Cleaning up the workspace after finishing the benchmark. - # e.g the CLI:deleteall /benchmark - - - - -### zk-smoketest - -**zk-smoketest** provides a simple smoketest client for a ZooKeeper ensemble. Useful for verifying new, updated, -existing installations. More details are [here](https://github.com/phunt/zk-smoketest). - - - - -## Testing - - - -### Fault Injection Framework - - - -#### Byteman - -- **Byteman** is a tool which makes it easy to trace, monitor and test the behaviour of Java application and JDK runtime code. -It injects Java code into your application methods or into Java runtime methods without the need for you to recompile, repackage or even redeploy your application. -Injection can be performed at JVM startup or after startup while the application is still running. -- Visit the official [website](https://byteman.jboss.org/) to download the latest release -- A brief tutorial can be found [here](https://developer.jboss.org/wiki/ABytemanTutorial) - - ```bash - Preparations: - # attach the byteman to 3 zk servers during runtime - # 55001,55002,55003 is byteman binding port; 714,740,758 is the zk server pid - ./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55001 714 - ./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55002 740 - ./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55003 758 - - # load the fault injection script - ./bmsubmit.sh -p 55002 -l my_zk_fault_injection.btm - # unload the fault injection script - ./bmsubmit.sh -p 55002 -u my_zk_fault_injectionr.btm - ``` - -Look at the below examples to customize your byteman fault injection script - -Example 1: This script makes leader's zxid roll over, to force re-election. - -```bash -cat zk_leader_zxid_roll_over.btm - -RULE trace zk_leader_zxid_roll_over -CLASS org.apache.zookeeper.server.quorum.Leader -METHOD propose -IF true -DO - traceln("*** Leader zxid has rolled over, forcing re-election ***"); - $1.zxid = 4294967295L -ENDRULE -``` - -Example 2: This script makes the leader drop the ping packet to a specific follower. -The leader will close the **LearnerHandler** with that follower, and the follower will enter the state:LOOKING -then re-enter the quorum with the state:FOLLOWING - -```bash -cat zk_leader_drop_ping_packet.btm - -RULE trace zk_leader_drop_ping_packet -CLASS org.apache.zookeeper.server.quorum.LearnerHandler -METHOD ping -AT ENTRY -IF $0.sid == 2 -DO - traceln("*** Leader drops ping packet to sid: 2 ***"); - return; -ENDRULE -``` - -Example 3: This script makes one follower drop ACK packet which has no big effect in the broadcast phrase, since after receiving -the majority of ACKs from the followers, the leader can commit that proposal - -```bash -cat zk_leader_drop_ping_packet.btm - -RULE trace zk.follower_drop_ack_packet -CLASS org.apache.zookeeper.server.quorum.SendAckRequestProcessor -METHOD processRequest -AT ENTRY -IF true -DO - traceln("*** Follower drops ACK packet ***"); - return; -ENDRULE -``` - - - - -### Jepsen Test -A framework for distributed systems verification, with fault injection. -Jepsen has been used to verify everything from eventually-consistent commutative databases to linearizable coordination systems to distributed task schedulers. -more details can be found in [jepsen-io](https://github.com/jepsen-io/jepsen) - -Running the [Dockerized Jepsen](https://github.com/jepsen-io/jepsen/blob/master/docker/README.md) is the simplest way to use the Jepsen. - -Installation: - -```bash -git clone git@github.com:jepsen-io/jepsen.git -cd docker -# maybe a long time for the first init. -./up.sh -# docker ps to check one control node and five db nodes are up -docker ps - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 8265f1d3f89c docker_control "/bin/sh -c /init.sh" 9 hours ago Up 4 hours 0.0.0.0:32769->8080/tcp jepsen-control - 8a646102da44 docker_n5 "/run.sh" 9 hours ago Up 3 hours 22/tcp jepsen-n5 - 385454d7e520 docker_n1 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n1 - a62d6a9d5f8e docker_n2 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n2 - 1485e89d0d9a docker_n3 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n3 - 27ae01e1a0c5 docker_node "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-node - 53c444b00ebd docker_n4 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n4 -``` - -Running & Test - -```bash -# Enter into the container:jepsen-control -docker exec -it jepsen-control bash -# Test -cd zookeeper && lein run test --concurrency 10 -# See something like the following to assert that ZooKeeper has passed the Jepsen test -INFO [2019-04-01 11:25:23,719] jepsen worker 8 - jepsen.util 8 :ok :read 2 -INFO [2019-04-01 11:25:23,722] jepsen worker 3 - jepsen.util 3 :invoke :cas [0 4] -INFO [2019-04-01 11:25:23,760] jepsen worker 3 - jepsen.util 3 :fail :cas [0 4] -INFO [2019-04-01 11:25:23,791] jepsen worker 1 - jepsen.util 1 :invoke :read nil -INFO [2019-04-01 11:25:23,794] jepsen worker 1 - jepsen.util 1 :ok :read 2 -INFO [2019-04-01 11:25:24,038] jepsen worker 0 - jepsen.util 0 :invoke :write 4 -INFO [2019-04-01 11:25:24,073] jepsen worker 0 - jepsen.util 0 :ok :write 4 -............................................................................... -Everything looks good! ヽ(‘ー`)ノ - -``` - -Reference: -read [this blog](https://aphyr.com/posts/291-call-me-maybe-zookeeper) to learn more about the Jepsen test for the Zookeeper. diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperTutorial.md b/zookeeper-docs/src/main/resources/markdown/zookeeperTutorial.md deleted file mode 100644 index 366c0a9f081..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperTutorial.md +++ /dev/null @@ -1,666 +0,0 @@ - - -# Programming with ZooKeeper - A basic tutorial - -* [Introduction](#ch_Introduction) -* [Barriers](#sc_barriers) -* [Producer-Consumer Queues](#sc_producerConsumerQueues) -* [Complete example](#Complete+example) - * [Queue test](#Queue+test) - * [Barrier test](#Barrier+test) - * [Source Listing](#sc_sourceListing) - - - -## Introduction - -In this tutorial, we show simple implementations of barriers and -producer-consumer queues using ZooKeeper. We call the respective classes Barrier and Queue. -These examples assume that you have at least one ZooKeeper server running. - -Both primitives use the following common excerpt of code: - - static ZooKeeper zk = null; - static Integer mutex; - - String root; - - SyncPrimitive(String address) { - if(zk == null){ - try { - System.out.println("Starting ZK:"); - zk = new ZooKeeper(address, 3000, this); - mutex = new Integer(-1); - System.out.println("Finished starting ZK: " + zk); - } catch (IOException e) { - System.out.println(e.toString()); - zk = null; - } - } - } - - synchronized public void process(WatchedEvent event) { - synchronized (mutex) { - mutex.notify(); - } - } - - - -Both classes extend SyncPrimitive. In this way, we execute steps that are -common to all primitives in the constructor of SyncPrimitive. To keep the examples -simple, we create a ZooKeeper object the first time we instantiate either a barrier -object or a queue object, and we declare a static variable that is a reference -to this object. The subsequent instances of Barrier and Queue check whether a -ZooKeeper object exists. Alternatively, we could have the application creating a -ZooKeeper object and passing it to the constructor of Barrier and Queue. - -We use the process() method to process notifications triggered due to watches. -In the following discussion, we present code that sets watches. A watch is internal -structure that enables ZooKeeper to notify a client of a change to a node. For example, -if a client is waiting for other clients to leave a barrier, then it can set a watch and -wait for modifications to a particular node, which can indicate that it is the end of the wait. -This point becomes clear once we go over the examples. - - - -## Barriers - -A barrier is a primitive that enables a group of processes to synchronize the -beginning and the end of a computation. The general idea of this implementation -is to have a barrier node that serves the purpose of being a parent for individual -process nodes. Suppose that we call the barrier node "/b1". Each process "p" then -creates a node "/b1/p". Once enough processes have created their corresponding -nodes, joined processes can start the computation. - -In this example, each process instantiates a Barrier object, and its constructor takes as parameters: - -* the address of a ZooKeeper server (e.g., "zoo1.foo.com:2181") -* the path of the barrier node on ZooKeeper (e.g., "/b1") -* the size of the group of processes - -The constructor of Barrier passes the address of the Zookeeper server to the -constructor of the parent class. The parent class creates a ZooKeeper instance if -one does not exist. The constructor of Barrier then creates a -barrier node on ZooKeeper, which is the parent node of all process nodes, and -we call root (**Note:** This is not the ZooKeeper root "/"). - - /** - * Barrier constructor - * - * @param address - * @param root - * @param size - */ - Barrier(String address, String root, int size) { - super(address); - this.root = root; - this.size = size; - // Create barrier node - if (zk != null) { - try { - Stat s = zk.exists(root, false); - if (s == null) { - zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT); - } - } catch (KeeperException e) { - System.out - .println("Keeper exception when instantiating queue: " - + e.toString()); - } catch (InterruptedException e) { - System.out.println("Interrupted exception"); - } - } - - // My node name - try { - name = new String(InetAddress.getLocalHost().getCanonicalHostName().toString()); - } catch (UnknownHostException e) { - System.out.println(e.toString()); - } - } - - -To enter the barrier, a process calls enter(). The process creates a node under -the root to represent it, using its host name to form the node name. It then wait -until enough processes have entered the barrier. A process does it by checking -the number of children the root node has with "getChildren()", and waiting for -notifications in the case it does not have enough. To receive a notification when -there is a change to the root node, a process has to set a watch, and does it -through the call to "getChildren()". In the code, we have that "getChildren()" -has two parameters. The first one states the node to read from, and the second is -a boolean flag that enables the process to set a watch. In the code the flag is true. - - /** - * Join barrier - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - - boolean enter() throws KeeperException, InterruptedException{ - zk.create(root + "/" + name, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.EPHEMERAL); - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - - if (list.size() < size) { - mutex.wait(); - } else { - return true; - } - } - } - } - - -Note that enter() throws both KeeperException and InterruptedException, so it is -the responsibility of the application to catch and handle such exceptions. - -Once the computation is finished, a process calls leave() to leave the barrier. -First it deletes its corresponding node, and then it gets the children of the root -node. If there is at least one child, then it waits for a notification (obs: note -that the second parameter of the call to getChildren() is true, meaning that -ZooKeeper has to set a watch on the root node). Upon reception of a notification, -it checks once more whether the root node has any children. - - /** - * Wait until all reach barrier - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - - boolean leave() throws KeeperException, InterruptedException { - zk.delete(root + "/" + name, 0); - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - if (list.size() > 0) { - mutex.wait(); - } else { - return true; - } - } - } - } - - - - -## Producer-Consumer Queues - -A producer-consumer queue is a distributed data structure that groups of processes -use to generate and consume items. Producer processes create new elements and add -them to the queue. Consumer processes remove elements from the list, and process them. -In this implementation, the elements are simple integers. The queue is represented -by a root node, and to add an element to the queue, a producer process creates a new node, -a child of the root node. - -The following excerpt of code corresponds to the constructor of the object. As -with Barrier objects, it first calls the constructor of the parent class, SyncPrimitive, -that creates a ZooKeeper object if one doesn't exist. It then verifies if the root -node of the queue exists, and creates if it doesn't. - - /** - * Constructor of producer-consumer queue - * - * @param address - * @param name - */ - Queue(String address, String name) { - super(address); - this.root = name; - // Create ZK node name - if (zk != null) { - try { - Stat s = zk.exists(root, false); - if (s == null) { - zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT); - } - } catch (KeeperException e) { - System.out - .println("Keeper exception when instantiating queue: " - + e.toString()); - } catch (InterruptedException e) { - System.out.println("Interrupted exception"); - } - } - } - - -A producer process calls "produce()" to add an element to the queue, and passes -an integer as an argument. To add an element to the queue, the method creates a -new node using "create()", and uses the SEQUENCE flag to instruct ZooKeeper to -append the value of the sequencer counter associated to the root node. In this way, -we impose a total order on the elements of the queue, thus guaranteeing that the -oldest element of the queue is the next one consumed. - - /** - * Add element to the queue. - * - * @param i - * @return - */ - - boolean produce(int i) throws KeeperException, InterruptedException{ - ByteBuffer b = ByteBuffer.allocate(4); - byte[] value; - - // Add child with value i - b.putInt(i); - value = b.array(); - zk.create(root + "/element", value, Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT_SEQUENTIAL); - - return true; - } - - -To consume an element, a consumer process obtains the children of the root node, -reads the node with smallest counter value, and returns the element. Note that -if there is a conflict, then one of the two contending processes won't be able to -delete the node and the delete operation will throw an exception. - -A call to getChildren() returns the list of children in lexicographic order. -As lexicographic order does not necessarily follow the numerical order of the counter -values, we need to decide which element is the smallest. To decide which one has -the smallest counter value, we traverse the list, and remove the prefix "element" -from each one. - - /** - * Remove first element from the queue. - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - int consume() throws KeeperException, InterruptedException{ - int retvalue = -1; - Stat stat = null; - - // Get the first element available - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - if (list.size() == 0) { - System.out.println("Going to wait"); - mutex.wait(); - } else { - Integer min = new Integer(list.get(0).substring(7)); - for(String s : list){ - Integer tempValue = new Integer(s.substring(7)); - //System.out.println("Temporary value: " + tempValue); - if(tempValue < min) min = tempValue; - } - System.out.println("Temporary value: " + root + "/element" + min); - byte[] b = zk.getData(root + "/element" + min, - false, stat); - zk.delete(root + "/element" + min, 0); - ByteBuffer buffer = ByteBuffer.wrap(b); - retvalue = buffer.getInt(); - - return retvalue; - } - } - } - } - } - - - - -## Complete example - -In the following section you can find a complete command line application to demonstrate the above mentioned -recipes. Use the following command to run it. - - ZOOBINDIR="[path_to_distro]/bin" - . "$ZOOBINDIR"/zkEnv.sh - java SyncPrimitive [Test Type] [ZK server] [No of elements] [Client type] - - - -### Queue test - -Start a producer to create 100 elements - - java SyncPrimitive qTest localhost 100 p - - -Start a consumer to consume 100 elements - - java SyncPrimitive qTest localhost 100 c - - - -### Barrier test - -Start a barrier with 2 participants (start as many times as many participants you'd like to enter) - - java SyncPrimitive bTest localhost 2 - - - -### Source Listing - -#### SyncPrimitive.Java - - import java.io.IOException; - import java.net.InetAddress; - import java.net.UnknownHostException; - import java.nio.ByteBuffer; - import java.util.List; - import java.util.Random; - - import org.apache.zookeeper.CreateMode; - import org.apache.zookeeper.KeeperException; - import org.apache.zookeeper.WatchedEvent; - import org.apache.zookeeper.Watcher; - import org.apache.zookeeper.ZooKeeper; - import org.apache.zookeeper.ZooDefs.Ids; - import org.apache.zookeeper.data.Stat; - - public class SyncPrimitive implements Watcher { - - static ZooKeeper zk = null; - static Integer mutex; - String root; - - SyncPrimitive(String address) { - if(zk == null){ - try { - System.out.println("Starting ZK:"); - zk = new ZooKeeper(address, 3000, this); - mutex = new Integer(-1); - System.out.println("Finished starting ZK: " + zk); - } catch (IOException e) { - System.out.println(e.toString()); - zk = null; - } - } - //else mutex = new Integer(-1); - } - - synchronized public void process(WatchedEvent event) { - synchronized (mutex) { - //System.out.println("Process: " + event.getType()); - mutex.notify(); - } - } - - /** - * Barrier - */ - static public class Barrier extends SyncPrimitive { - int size; - String name; - - /** - * Barrier constructor - * - * @param address - * @param root - * @param size - */ - Barrier(String address, String root, int size) { - super(address); - this.root = root; - this.size = size; - - // Create barrier node - if (zk != null) { - try { - Stat s = zk.exists(root, false); - if (s == null) { - zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT); - } - } catch (KeeperException e) { - System.out - .println("Keeper exception when instantiating queue: " - + e.toString()); - } catch (InterruptedException e) { - System.out.println("Interrupted exception"); - } - } - - // My node name - try { - name = new String(InetAddress.getLocalHost().getCanonicalHostName().toString()); - } catch (UnknownHostException e) { - System.out.println(e.toString()); - } - - } - - /** - * Join barrier - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - - boolean enter() throws KeeperException, InterruptedException{ - zk.create(root + "/" + name, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.EPHEMERAL); - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - - if (list.size() < size) { - mutex.wait(); - } else { - return true; - } - } - } - } - - /** - * Wait until all reach barrier - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - boolean leave() throws KeeperException, InterruptedException{ - zk.delete(root + "/" + name, 0); - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - if (list.size() > 0) { - mutex.wait(); - } else { - return true; - } - } - } - } - } - - /** - * Producer-Consumer queue - */ - static public class Queue extends SyncPrimitive { - - /** - * Constructor of producer-consumer queue - * - * @param address - * @param name - */ - Queue(String address, String name) { - super(address); - this.root = name; - // Create ZK node name - if (zk != null) { - try { - Stat s = zk.exists(root, false); - if (s == null) { - zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT); - } - } catch (KeeperException e) { - System.out - .println("Keeper exception when instantiating queue: " - + e.toString()); - } catch (InterruptedException e) { - System.out.println("Interrupted exception"); - } - } - } - - /** - * Add element to the queue. - * - * @param i - * @return - */ - - boolean produce(int i) throws KeeperException, InterruptedException{ - ByteBuffer b = ByteBuffer.allocate(4); - byte[] value; - - // Add child with value i - b.putInt(i); - value = b.array(); - zk.create(root + "/element", value, Ids.OPEN_ACL_UNSAFE, - CreateMode.PERSISTENT_SEQUENTIAL); - - return true; - } - - /** - * Remove first element from the queue. - * - * @return - * @throws KeeperException - * @throws InterruptedException - */ - int consume() throws KeeperException, InterruptedException{ - int retvalue = -1; - Stat stat = null; - - // Get the first element available - while (true) { - synchronized (mutex) { - List list = zk.getChildren(root, true); - if (list.size() == 0) { - System.out.println("Going to wait"); - mutex.wait(); - } else { - Integer min = new Integer(list.get(0).substring(7)); - String minNode = list.get(0); - for(String s : list){ - Integer tempValue = new Integer(s.substring(7)); - //System.out.println("Temporary value: " + tempValue); - if(tempValue < min) { - min = tempValue; - minNode = s; - } - } - System.out.println("Temporary value: " + root + "/" + minNode); - byte[] b = zk.getData(root + "/" + minNode, - false, stat); - zk.delete(root + "/" + minNode, 0); - ByteBuffer buffer = ByteBuffer.wrap(b); - retvalue = buffer.getInt(); - - return retvalue; - } - } - } - } - } - - public static void main(String args[]) { - if (args[0].equals("qTest")) - queueTest(args); - else - barrierTest(args); - } - - public static void queueTest(String args[]) { - Queue q = new Queue(args[1], "/app1"); - - System.out.println("Input: " + args[1]); - int i; - Integer max = new Integer(args[2]); - - if (args[3].equals("p")) { - System.out.println("Producer"); - for (i = 0; i < max; i++) - try{ - q.produce(10 + i); - } catch (KeeperException e){ - - } catch (InterruptedException e){ - - } - } else { - System.out.println("Consumer"); - - for (i = 0; i < max; i++) { - try{ - int r = q.consume(); - System.out.println("Item: " + r); - } catch (KeeperException e){ - i--; - } catch (InterruptedException e){ - } - } - } - } - - public static void barrierTest(String args[]) { - Barrier b = new Barrier(args[1], "/b1", new Integer(args[2])); - try{ - boolean flag = b.enter(); - System.out.println("Entered barrier: " + args[2]); - if(!flag) System.out.println("Error when entering the barrier"); - } catch (KeeperException e){ - } catch (InterruptedException e){ - } - - // Generate random integer - Random rand = new Random(); - int r = rand.nextInt(100); - // Loop for rand iterations - for (int i = 0; i < r; i++) { - try { - Thread.sleep(100); - } catch (InterruptedException e) { - } - } - try{ - b.leave(); - } catch (KeeperException e){ - - } catch (InterruptedException e){ - - } - System.out.println("Left barrier"); - } - } - diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperUseCases.md b/zookeeper-docs/src/main/resources/markdown/zookeeperUseCases.md deleted file mode 100644 index 98045444457..00000000000 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperUseCases.md +++ /dev/null @@ -1,385 +0,0 @@ - - -# ZooKeeper Use Cases - -- Applications and organizations using ZooKeeper include (alphabetically) [1]. -- If your use case wants to be listed here. Please do not hesitate, submit a pull request or write an email to **dev@zookeeper.apache.org**, - and then, your use case will be included. -- If this documentation has violated your intellectual property rights or you and your company's privacy, write an email to **dev@zookeeper.apache.org**, - we will handle them in a timely manner. - - -## Free Software Projects - -### [AdroitLogic UltraESB](http://adroitlogic.org/) - - Uses ZooKeeper to implement node coordination, in clustering support. This allows the management of the complete cluster, - or any specific node - from any other node connected via JMX. A Cluster wide command framework developed on top of the - ZooKeeper coordination allows commands that fail on some nodes to be retried etc. We also support the automated graceful - round-robin-restart of a complete cluster of nodes using the same framework [1]. - -### [Akka](http://akka.io/) - - Akka is the platform for the next generation event-driven, scalable and fault-tolerant architectures on the JVM. - Or: Akka is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven applications on the JVM [1]. - -### [Eclipse Communication Framework](http://www.eclipse.org/ecf) - - The Eclipse ECF project provides an implementation of its Abstract Discovery services using Zookeeper. ECF itself - is used in many projects providing base functionality for communication, all based on OSGi [1]. - -### [Eclipse Gyrex](http://www.eclipse.org/gyrex) - - The Eclipse Gyrex project provides a platform for building your own Java OSGi based clouds. - - ZooKeeper is used as the core cloud component for node membership and management, coordination of jobs executing among workers, - a lock service and a simple queue service and a lot more [1]. - -### [GoldenOrb](http://www.goldenorbos.org/) - - massive-scale Graph analysis [1]. - -### [Juju](https://juju.ubuntu.com/) - - Service deployment and orchestration framework, formerly called Ensemble [1]. - -### [Katta](http://katta.sourceforge.net/) - - Katta serves distributed Lucene indexes in a grid environment. - - Zookeeper is used for node, master and index management in the grid [1]. - -### [KeptCollections](https://github.com/anthonyu/KeptCollections) - - KeptCollections is a library of drop-in replacements for the data structures in the Java Collections framework. - - KeptCollections uses Apache ZooKeeper as a backing store, thus making its data structures distributed and scalable [1]. - -### [Neo4j](https://neo4j.com/) - - Neo4j is a Graph Database. It's a disk based, ACID compliant transactional storage engine for big graphs and fast graph traversals, - using external indices like Lucene/Solr for global searches. - - We use ZooKeeper in the Neo4j High Availability components for write-master election, - read slave coordination and other cool stuff. ZooKeeper is a great and focused project - we like! [1]. - -### [Norbert](http://sna-projects.com/norbert) - - Partitioned routing and cluster management [1]. - -### [spring-cloud-zookeeper](https://spring.io/projects/spring-cloud-zookeeper) - - Spring Cloud Zookeeper provides Apache Zookeeper integrations for Spring Boot apps through autoconfiguration - and binding to the Spring Environment and other Spring programming model idioms. With a few simple annotations - you can quickly enable and configure the common patterns inside your application and build large distributed systems with Zookeeper. - The patterns provided include Service Discovery and Distributed Configuration [38]. - -### [spring-statemachine](https://projects.spring.io/spring-statemachine/) - - Spring Statemachine is a framework for application developers to use state machine concepts with Spring applications. - - Spring Statemachine can provide this feature:Distributed state machine based on a Zookeeper [31,32]. - -### [spring-xd](https://projects.spring.io/spring-xd/) - - Spring XD is a unified, distributed, and extensible system for data ingestion, real time analytics, batch processing, and data export. - The project’s goal is to simplify the development of big data applications. - - ZooKeeper - Provides all runtime information for the XD cluster. Tracks running containers, in which containers modules - and jobs are deployed, stream definitions, deployment manifests, and the like [30,31]. - -### [Talend ESB](http://www.talend.com/products-application-integration/application-integration-esb-se.php) - - Talend ESB is a versatile and flexible, enterprise service bus. - - It uses ZooKeeper as endpoint repository of both REST and SOAP Web services. - By using ZooKeeper Talend ESB is able to provide failover and load balancing capabilities in a very light-weight manner [1]. - -### [redis_failover](https://github.com/ryanlecompte/redis_failover) - - Redis Failover is a ZooKeeper-based automatic master/slave failover solution for Ruby [1]. - - -## Apache Projects - -### [Apache Accumulo](https://accumulo.apache.org/) - - Accumulo is a distributed key/value store that provides expressive, cell-level access labels. - - Apache ZooKeeper plays a central role within the Accumulo architecture. Its quorum consistency model supports an overall - Accumulo architecture with no single points of failure. Beyond that, Accumulo leverages ZooKeeper to store and communication - configuration information for users and tables, as well as operational states of processes and tablets [2]. - -### [Apache Atlas](http://atlas.apache.org) - - Atlas is a scalable and extensible set of core foundational governance services – enabling enterprises to effectively and efficiently meet - their compliance requirements within Hadoop and allows integration with the whole enterprise data ecosystem. - - Atlas uses Zookeeper for coordination to provide redundancy and high availability of HBase,Kafka [31,35]. - -### [Apache BookKeeper](https://bookkeeper.apache.org/) - - A scalable, fault-tolerant, and low-latency storage service optimized for real-time workloads. - - BookKeeper requires a metadata storage service to store information related to ledgers and available bookies. BookKeeper currently uses - ZooKeeper for this and other tasks [3]. - -### [Apache CXF DOSGi](http://cxf.apache.org/distributed-osgi.html) - - Apache CXF is an open source services framework. CXF helps you build and develop services using frontend programming - APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, - or CORBA and work over a variety of transports such as HTTP, JMS or JBI. - - The Distributed OSGi implementation at Apache CXF uses ZooKeeper for its Discovery functionality [4]. - -### [Apache Drill](http://drill.apache.org/) - - Schema-free SQL Query Engine for Hadoop, NoSQL and Cloud Storage - - ZooKeeper maintains ephemeral cluster membership information. The Drillbits use ZooKeeper to find other Drillbits in the cluster, - and the client uses ZooKeeper to find Drillbits to submit a query [28]. - -### [Apache Druid](https://druid.apache.org/) - - Apache Druid is a high performance real-time analytics database. - - Apache Druid uses Apache ZooKeeper (ZK) for management of current cluster state. The operations that happen over ZK are [27]: - - Coordinator leader election - - Segment "publishing" protocol from Historical and Realtime - - Segment load/drop protocol between Coordinator and Historical - - Overlord leader election - - Overlord and MiddleManager task management - -### [Apache Dubbo](http://dubbo.apache.org) - - Apache Dubbo is a high-performance, java based open source RPC framework. - - Zookeeper is used for service registration discovery and configuration management in Dubbo [6]. - -### [Apache Flink](https://flink.apache.org/) - - Apache Flink is a framework and distributed processing engine for stateful computations over unbounded and bounded data streams. - Flink has been designed to run in all common cluster environments, perform computations at in-memory speed and at any scale. - - To enable JobManager High Availability you have to set the high-availability mode to zookeeper, configure a ZooKeeper quorum and set up a masters file with all JobManagers hosts and their web UI ports. - Flink leverages ZooKeeper for distributed coordination between all running JobManager instances. ZooKeeper is a separate service from Flink, - which provides highly reliable distributed coordination via leader election and light-weight consistent state storage [23]. - -### [Apache Flume](https://flume.apache.org/) - - Flume is a distributed, reliable, and available service for efficiently collecting, aggregating, and moving large amounts - of log data. It has a simple and flexible architecture based on streaming data flows. It is robust and fault tolerant - with tunable reliability mechanisms and many failover and recovery mechanisms. It uses a simple extensible data model - that allows for online analytic application. - - Flume supports Agent configurations via Zookeeper. This is an experimental feature [5]. - -### [Apache Fluo](https://fluo.apache.org/) - - Apache Fluo is a distributed processing system that lets users make incremental updates to large data sets. - - Apache Fluo is built on Apache Accumulo which uses Apache Zookeeper for consensus [31,37]. - -### [Apache Griffin](https://griffin.apache.org/) - - Big Data Quality Solution For Batch and Streaming. - - Griffin uses Zookeeper for coordination to provide redundancy and high availability of Kafka [31,36]. - -### [Apache Hadoop](http://hadoop.apache.org/) - - The Apache Hadoop software library is a framework that allows for the distributed processing of large data sets across - clusters of computers using simple programming models. It is designed to scale up from single servers to thousands of machines, - each offering local computation and storage. Rather than rely on hardware to deliver high-availability, - the library itself is designed to detect and handle failures at the application layer, so delivering a highly-available service on top of a cluster of computers, each of which may be prone to failures. - - The implementation of automatic HDFS failover relies on ZooKeeper for the following things: - - **Failure detection** - each of the NameNode machines in the cluster maintains a persistent session in ZooKeeper. - If the machine crashes, the ZooKeeper session will expire, notifying the other NameNode that a failover should be triggered. - - **Active NameNode election** - ZooKeeper provides a simple mechanism to exclusively elect a node as active. If the current active NameNode crashes, - another node may take a special exclusive lock in ZooKeeper indicating that it should become the next active. - - The ZKFailoverController (ZKFC) is a new component which is a ZooKeeper client which also monitors and manages the state of the NameNode. - Each of the machines which runs a NameNode also runs a ZKFC, and that ZKFC is responsible for: - - **Health monitoring** - the ZKFC pings its local NameNode on a periodic basis with a health-check command. - So long as the NameNode responds in a timely fashion with a healthy status, the ZKFC considers the node healthy. - If the node has crashed, frozen, or otherwise entered an unhealthy state, the health monitor will mark it as unhealthy. - - **ZooKeeper session management** - when the local NameNode is healthy, the ZKFC holds a session open in ZooKeeper. - If the local NameNode is active, it also holds a special “lock” znode. This lock uses ZooKeeper’s support for “ephemeral” nodes; - if the session expires, the lock node will be automatically deleted. - - **ZooKeeper-based election** - if the local NameNode is healthy, and the ZKFC sees that no other node currently holds the lock znode, - it will itself try to acquire the lock. If it succeeds, then it has “won the election”, and is responsible for running a failover to make its local NameNode active. - The failover process is similar to the manual failover described above: first, the previous active is fenced if necessary, - and then the local NameNode transitions to active state [7]. - -### [Apache HBase](https://hbase.apache.org/) - - HBase is the Hadoop database. It's an open-source, distributed, column-oriented store model. - - HBase uses ZooKeeper for master election, server lease management, bootstrapping, and coordination between servers. - A distributed Apache HBase installation depends on a running ZooKeeper cluster. All participating nodes and clients - need to be able to access the running ZooKeeper ensemble [8]. - - As you can see, ZooKeeper is a fundamental part of HBase. All operations that require coordination, such as Regions - assignment, Master-Failover, replication, and snapshots, are built on ZooKeeper [20]. - -### [Apache Helix](http://helix.apache.org/) - - A cluster management framework for partitioned and replicated distributed resources. - - We need a distributed store to maintain the state of the cluster and a notification system to notify if there is any change in the cluster state. - Helix uses Apache ZooKeeper to achieve this functionality [21]. - Zookeeper provides: - - A way to represent PERSISTENT state which remains until its deleted - - A way to represent TRANSIENT/EPHEMERAL state which vanishes when the process that created the state dies - - A notification mechanism when there is a change in PERSISTENT and EPHEMERAL state - -### [Apache Hive](https://hive.apache.org) - - The Apache Hive data warehouse software facilitates reading, writing, and managing large datasets residing in distributed - storage using SQL. Structure can be projected onto data already in storage. A command line tool and JDBC driver are provided to connect users to Hive. - - Hive has been using ZooKeeper as distributed lock manager to support concurrency in HiveServer2 [25,26]. - -### [Apache Ignite](https://ignite.apache.org/) - - Ignite is a memory-centric distributed database, caching, and processing platform for - transactional, analytical, and streaming workloads delivering in-memory speeds at petabyte scale - - Apache Ignite discovery mechanism goes with a ZooKeeper implementations which allows scaling Ignite clusters to 100s and 1000s of nodes - preserving linear scalability and performance [31,34].​ - -### [Apache James Mailbox](http://james.apache.org/mailbox/) - - The Apache James Mailbox is a library providing a flexible Mailbox storage accessible by mail protocols - (IMAP4, POP3, SMTP,...) and other protocols. - - Uses Zookeeper and Curator Framework for generating distributed unique ID's [31]. - -### [Apache Kafka](https://kafka.apache.org/) - - Kafka is a distributed publish/subscribe messaging system - - Apache Kafka relies on ZooKeeper for the following things: - - **Controller election** - The controller is one of the most important broking entity in a Kafka ecosystem, and it also has the responsibility - to maintain the leader-follower relationship across all the partitions. If a node by some reason is shutting down, - it’s the controller’s responsibility to tell all the replicas to act as partition leaders in order to fulfill the - duties of the partition leaders on the node that is about to fail. So, whenever a node shuts down, a new controller - can be elected and it can also be made sure that at any given time, there is only one controller and all the follower nodes have agreed on that. - - **Configuration Of Topics** - The configuration regarding all the topics including the list of existing topics, the number of partitions for each topic, - the location of all the replicas, list of configuration overrides for all topics and which node is the preferred leader, etc. - - **Access control lists** - Access control lists or ACLs for all the topics are also maintained within Zookeeper. - - **Membership of the cluster** - Zookeeper also maintains a list of all the brokers that are functioning at any given moment and are a part of the cluster [9]. - -### [Apache Kylin](http://kylin.apache.org/) - - Apache Kylin is an open source Distributed Analytics Engine designed to provide SQL interface and multi-dimensional analysis (OLAP) on Hadoop/Spark supporting extremely large datasets, - original contributed from eBay Inc. - - Apache Kylin leverages Zookeeper for job coordination [31,33]. - -### [Apache Mesos](http://mesos.apache.org/) - - Apache Mesos abstracts CPU, memory, storage, and other compute resources away from machines (physical or virtual), - enabling fault-tolerant and elastic distributed systems to easily be built and run effectively. - - Mesos has a high-availability mode that uses multiple Mesos masters: one active master (called the leader or leading master) - and several backups in case it fails. The masters elect the leader, with Apache ZooKeeper both coordinating the election - and handling leader detection by masters, agents, and scheduler drivers [10]. - -### [Apache Oozie](https://oozie.apache.org) - - Oozie is a workflow scheduler system to manage Apache Hadoop jobs. - - the Oozie servers use it for coordinating access to the database and communicating with each other. In order to have full HA, - there should be at least 3 ZooKeeper servers [29]. - -### [Apache Pulsar](https://pulsar.apache.org) - - Apache Pulsar is an open-source distributed pub-sub messaging system originally created at Yahoo and now part of the Apache Software Foundation - - Pulsar uses Apache Zookeeper for metadata storage, cluster configuration, and coordination. In a Pulsar instance: - - A configuration store quorum stores configuration for tenants, namespaces, and other entities that need to be globally consistent. - - Each cluster has its own local ZooKeeper ensemble that stores cluster-specific configuration and coordination such as ownership metadata, - broker load reports, BookKeeper ledger metadata, and more [24]. - -### [Apache Solr](https://lucene.apache.org/solr/) - - Solr is the popular, blazing-fast, open source enterprise search platform built on Apache Lucene. - - In the "Cloud" edition (v4.x and up) of enterprise search engine Apache Solr, ZooKeeper is used for configuration, - leader election and more [12,13]. - -### [Apache Spark](https://spark.apache.org/) - - Apache Spark is a unified analytics engine for large-scale data processing. - - Utilizing ZooKeeper to provide leader election and some state storage, you can launch multiple Masters in your cluster connected to the same ZooKeeper instance. - One will be elected “leader” and the others will remain in standby mode. If the current leader dies, another Master will be elected, - recover the old Master’s state, and then resume scheduling [14]. - -### [Apache Storm](http://storm.apache.org) - - Apache Storm is a free and open source distributed realtime computation system. Apache Storm makes it easy to reliably - process unbounded streams of data, doing for realtime processing what Hadoop did for batch processing. - Apache Storm is simple, can be used with any programming language, and is a lot of fun to use! - - Storm uses Zookeeper for coordinating the cluster [22]. - - -## Companies - -### [AGETO](http://www.ageto.de/) - - The AGETO RnD team uses ZooKeeper in a variety of internal as well as external consulting projects [1]. - -### [Benipal Technologies](http://www.benipaltechnologies.com/) - - ZooKeeper is used for internal application development with Solr and Hadoop with Hbase [1]. - -### [Box](http://box.net/) - - Box uses ZooKeeper for service discovery, service coordination, Solr and Hadoop support, etc [1]. - -### [Deepdyve](http://www.deepdyve.com/) - - We do search for research and provide access to high quality content using advanced search technologies Zookeeper is used to - manage server state, control index deployment and a myriad other tasks [1]. - -### [Facebook](https://www.facebook.com/) - - Facebook uses the Zeus ([17,18]) for configuration management which is a forked version of ZooKeeper, with many scalability - and performance en- hancements in order to work at the Facebook scale. - It runs a consensus protocol among servers distributed across mul- tiple regions for resilience. If the leader fails, - a follower is converted into a new leader. - -### [Idium Portal](http://www.idium.no/no/idium_portal/) - - Idium Portal is a hosted web-publishing system delivered by Norwegian company, Idium AS. - - ZooKeeper is used for cluster messaging, service bootstrapping, and service coordination [1]. - -### [Makara](http://www.makara.com/) - - Using ZooKeeper on 2-node cluster on VMware workstation, Amazon EC2, Zen - - Using zkpython - - Looking into expanding into 100 node cluster [1]. - -### [Midokura](http://www.midokura.com/) - - We do virtualized networking for the cloud computing era. We use ZooKeeper for various aspects of our distributed control plane [1]. - -### [Pinterest](https://www.pinterest.com/) - - Pinterest uses the ZooKeeper for Service discovery and dynamic configuration.Like many large scale web sites, Pinterest’s infrastructure consists of servers that communicate with - backend services composed of a number of individual servers for managing load and fault tolerance. Ideally, we’d like the configuration to reflect only the active hosts, - so clients don’t need to deal with bad hosts as often. ZooKeeper provides a well known pattern to solve this problem [19]. - -### [Rackspace](http://www.rackspace.com/email_hosting) - - The Email & Apps team uses ZooKeeper to coordinate sharding and responsibility changes in a distributed e-mail client - that pulls and indexes data for search. ZooKeeper also provides distributed locking for connections to prevent a cluster from overwhelming servers [1]. - -### [Sematext](http://sematext.com/) - - Uses ZooKeeper in SPM (which includes ZooKeeper monitoring component, too!), Search Analytics, and Logsene [1]. - -### [Tubemogul](http://tubemogul.com/) - - Uses ZooKeeper for leader election, configuration management, locking, group membership [1]. - -### [Twitter](https://twitter.com/) - - ZooKeeper is used at Twitter as the source of truth for storing critical metadata. It serves as a coordination kernel to - provide distributed coordination services, such as leader election and distributed locking. - Some concrete examples of ZooKeeper in action include [15,16]: - - ZooKeeper is used to store service registry, which is used by Twitter’s naming service for service discovery. - - Manhattan (Twitter’s in-house key-value database), Nighthawk (sharded Redis), and Blobstore (in-house photo and video storage), - stores its cluster topology information in ZooKeeper. - - EventBus, Twitter’s pub-sub messaging system, stores critical metadata in ZooKeeper and uses ZooKeeper for leader election. - - Mesos, Twitter’s compute platform, uses ZooKeeper for leader election. - -### [Vast.com](http://www.vast.com/) - - Used internally as a part of sharding services, distributed synchronization of data/index updates, configuration management and failover support [1]. - -### [Wealthfront](http://wealthfront.com/) - - Wealthfront uses ZooKeeper for service discovery, leader election and distributed locking among its many backend services. - ZK is an essential part of Wealthfront's continuous [deployment infrastructure](http://eng.wealthfront.com/2010/05/02/deployment-infrastructure-for-continuous-deployment/) [1]. - -### [Yahoo!](http://www.yahoo.com/) - - ZooKeeper is used for a myriad of services inside Yahoo! for doing leader election, configuration management, sharding, locking, group membership etc [1]. - -### [Zynga](http://www.zynga.com/) - - ZooKeeper at Zynga is used for a variety of services including configuration management, leader election, sharding and more [1]. - - -#### References -- [1] https://cwiki.apache.org/confluence/display/ZOOKEEPER/PoweredBy -- [2] https://www.youtube.com/watch?v=Ew53T6h9oRw -- [3] https://bookkeeper.apache.org/docs/4.7.3/getting-started/concepts/#ledgers -- [4] http://cxf.apache.org/dosgi-discovery-demo-page.html -- [5] https://flume.apache.org/FlumeUserGuide.html -- [6] http://dubbo.apache.org/en-us/blog/dubbo-zk.html -- [7] https://hadoop.apache.org/docs/r2.7.1/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html -- [8] https://hbase.apache.org/book.html#zookeeper -- [9] https://www.cloudkarafka.com/blog/2018-07-04-cloudkarafka_what_is_zookeeper.html -- [10] http://mesos.apache.org/documentation/latest/high-availability/ -- [11] http://incubator.apache.org/projects/s4.html -- [12] https://lucene.apache.org/solr/guide/6_6/using-zookeeper-to-manage-configuration-files.html#UsingZooKeepertoManageConfigurationFiles-StartupBootstrap -- [13] https://lucene.apache.org/solr/guide/6_6/setting-up-an-external-zookeeper-ensemble.html -- [14] https://spark.apache.org/docs/latest/spark-standalone.html#standby-masters-with-zookeeper -- [15] https://blog.twitter.com/engineering/en_us/topics/infrastructure/2018/zookeeper-at-twitter.html -- [16] https://blog.twitter.com/engineering/en_us/topics/infrastructure/2018/dynamic-configuration-at-twitter.html -- [17] TANG, C., KOOBURAT, T., VENKATACHALAM, P.,CHANDER, A., WEN, Z., NARAYANAN, A., DOWELL,P., AND KARL, R. Holistic Configuration Management - at Facebook. In Proceedings of the 25th Symposium on Operating System Principles (SOSP’15) (Monterey, CA,USA, Oct. 2015). -- [18] https://www.youtube.com/watch?v=SeZV373gUZc -- [19] https://medium.com/@Pinterest_Engineering/zookeeper-resilience-at-pinterest-adfd8acf2a6b -- [20] https://blog.cloudera.com/what-are-hbase-znodes/ -- [21] https://helix.apache.org/Architecture.html -- [22] http://storm.apache.org/releases/current/Setting-up-a-Storm-cluster.html -- [23] https://ci.apache.org/projects/flink/flink-docs-release-1.9/ops/jobmanager_high_availability.html -- [24] https://pulsar.apache.org/docs/en/concepts-architecture-overview/#metadata-store -- [25] https://cwiki.apache.org/confluence/display/Hive/Locking -- [26] *ZooKeeperHiveLockManager* implementation in the [hive](https://github.com/apache/hive/) code base -- [27] https://druid.apache.org/docs/latest/dependencies/zookeeper.html -- [28] https://mapr.com/blog/apache-drill-architecture-ultimate-guide/ -- [29] https://oozie.apache.org/docs/4.1.0/AG_Install.html -- [30] https://docs.spring.io/spring-xd/docs/current/reference/html/ -- [31] https://cwiki.apache.org/confluence/display/CURATOR/Powered+By -- [32] https://projects.spring.io/spring-statemachine/ -- [33] https://www.tigeranalytics.com/blog/apache-kylin-architecture/ -- [34] https://apacheignite.readme.io/docs/cluster-discovery -- [35] http://atlas.apache.org/HighAvailability.html -- [36] http://griffin.apache.org/docs/usecases.html -- [37] https://fluo.apache.org/ -- [38] https://spring.io/projects/spring-cloud-zookeeper diff --git a/zookeeper-website/.gitignore b/zookeeper-website/.gitignore new file mode 100644 index 00000000000..583284939ff --- /dev/null +++ b/zookeeper-website/.gitignore @@ -0,0 +1,43 @@ +# Editor directories and files +.vscode/* +.cursor/* +!.vscode/extensions.json +.idea +.DS_Store +*.suo +*.ntvs* +*.njsproj +*.sln +*.sw? + +.env +/node_modules/ + +# React Router +/.react-router/ +/build/ +.vite + +# Fumadocs +.source/ + +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +lerna-debug.log* + +# Maven +/target/ +/node/ + +# Playwright +node_modules/ +/test-results/ +/playwright-report/ +/blob-report/ +/playwright/.cache/ +/playwright/.auth/ diff --git a/zookeeper-website/Dockerfile b/zookeeper-website/Dockerfile new file mode 100644 index 00000000000..3e1bda42319 --- /dev/null +++ b/zookeeper-website/Dockerfile @@ -0,0 +1,40 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +FROM node:22-alpine AS development-dependencies-env +COPY . /app +WORKDIR /app +RUN npm ci + +FROM node:22-alpine AS production-dependencies-env +COPY ./package.json package-lock.json /app/ +WORKDIR /app +RUN npm ci --omit=dev + +FROM node:22-alpine AS build-env +COPY . /app/ +COPY --from=development-dependencies-env /app/node_modules /app/node_modules +WORKDIR /app +RUN npm run build + +FROM node:22-alpine +COPY ./package.json package-lock.json /app/ +COPY --from=production-dependencies-env /app/node_modules /app/node_modules +COPY --from=build-env /app/build /app/build +WORKDIR /app +CMD ["npm", "run", "start"] \ No newline at end of file diff --git a/zookeeper-website/README.md b/zookeeper-website/README.md new file mode 100644 index 00000000000..157c4b2ec5f --- /dev/null +++ b/zookeeper-website/README.md @@ -0,0 +1,620 @@ + + +# Apache ZooKeeper Website + +The official website for Apache ZooKeeper, built with modern web technologies to provide a fast, accessible, and maintainable web presence. + +--- + +## Table of Contents + +- [Content Editing](#content-editing) +- [Development](#development) + - [Prerequisites](#prerequisites) + - [Technology Stack](#technology-stack) + - [Project Architecture](#project-architecture) + - [Getting Started](#getting-started) + - [Development Workflow](#development-workflow) + - [Building for Production](#building-for-production) + - [Maven Integration](#maven-integration) + - [Deployment](#deployment) + - [Publishing a New ZooKeeper Release](#publishing-a-new-zookeeper-release) + - [Troubleshooting](#troubleshooting) + +--- + +## Content Editing + +Most landing pages store content in **Markdown (`.md`)** or **JSON (`.json`)** files located in `app/pages/_landing/[page-name]/`. Docs content lives under `app/pages/_docs/` and is authored in MDX. + +Legacy documentation is preserved for those users who have old bookmarked links and notes: the old book lives at `/public/book.html`, and its static assets are in `public/old-book-static-files/`. + +**Examples:** + +- `app/pages/_landing/credits/developers.json` - JSON data for developers +- `app/pages/_landing/releases/index.tsx` - Releases page +- `app/pages/_docs/docs/_mdx/...` - MDX content for documentation + +--- + +## Development + +### Prerequisites + +Before you begin, ensure you have the following installed: + +- **Node.js version 22** - JavaScript runtime (like the JVM for Java) + - Download from [nodejs.org](https://nodejs.org/) + - Verify installation: `node --version` (should show v20.19+ or v22.12+) + +- **NPM** - Node Package Manager (like Maven for Java) + - Comes bundled with Node.js + - Verify installation: `npm --version` + +### Technology Stack + +This website uses modern web technologies. Here's what each one does (with Java analogies): + +#### Core Framework + +- **React Router** - Full-stack web framework with Server-Side Generation (SSG) + - Handles routing (like Spring MVC controllers) + - Provides server-side rendering for better performance and SEO + - Enables progressive enhancement (see below) + - [Documentation](https://reactrouter.com/) + +#### Documentation Framework + +- **Fumadocs** - Documentation framework used for the docs section + - Provides MDX-based docs structure and navigation + - Lives alongside the landing pages in the same React Router app + - [Documentation](https://fumadocs.com/) + +#### Progressive Enhancement + +The website uses **progressive enhancement** ([learn more](https://reactrouter.com/explanation/progressive-enhancement)), which means: + +- **With JavaScript enabled**: Users get a Single Page Application (SPA) experience + - Fast page transitions without full page reloads + - Smooth animations and interactive features + - Enhanced user experience + +- **Without JavaScript**: Users still get a fully functional website + - All links and forms work via traditional HTML + - Content is accessible to everyone + - Better for search engines and accessibility tools + +This approach ensures the website works for all users, regardless of their browser capabilities or connection speed. + +#### UI Components + +- **shadcn/ui** - Pre-built, accessible UI components + - Similar to a component library like PrimeFaces or Vaadin in Java + - Provides buttons, cards, navigation menus, etc. + - [Documentation](https://ui.shadcn.com/) + +#### Styling + +- **TailwindCSS** - Utility-first CSS framework, aka Bootstrap on steroids + - Instead of writing CSS files, you apply classes directly in components + - Example: `className="text-blue-500 font-bold"` makes blue, bold text + +#### Code Quality Tools + +- **TypeScript** - Typed superset of JavaScript + - Similar to Java's type system + - Catches errors at compile-time instead of runtime + - Provides autocomplete and better IDE support + +- **ESLint + Prettier** - Code linting and formatting (like Checkstyle) + - ESLint analyzes code for potential errors and enforces coding standards + - Prettier handles automatic code formatting (spacing, indentation, etc.) + - Integrated together: `npm run lint:fix` handles both linting and formatting + - Configuration: `eslint.config.js` and `prettier.config.js` + +### Project Architecture + +The project follows a clear directory structure with separation of concerns: + +``` +my-react-router-app/ +├── app/ # Application source code +│ ├── ui/ # Reusable UI components (no business logic) +│ │ ├── button.tsx # Generic button component +│ │ ├── card.tsx # Card container component +│ │ └── ... # Other UI primitives +│ │ +│ ├── components/ # Reusable components WITH business logic +│ │ ├── site-navbar.tsx # Website navigation bar +│ │ ├── site-footer.tsx # Website footer +│ │ ├── theme-toggle.tsx # Dark/light mode toggle +│ │ └── markdown-layout.tsx # Layout for markdown content pages +│ │ +│ ├── pages/ # Complete pages (composed of ui + components) +│ │ ├── _landing/ # Landing pages + layout +│ │ │ ├── home/ # Home page +│ │ │ │ ├── index.tsx # Main page component (exported) +│ │ │ │ ├── hero.tsx # Hero section (not exported) +│ │ │ │ ├── features.tsx # Features section (not exported) +│ │ │ │ └── ... +│ │ │ ├── team/ # Landing page content +│ │ │ └── ... +│ │ ├── _docs/ # Documentation (Fumadocs) +│ │ │ ├── docs/ # MDX content and structure +│ │ │ ├── docs-layout.tsx # Fumadocs layout wrapper +│ │ │ └── ... +│ │ +│ ├── routes/ # Route definitions and metadata +│ │ ├── home.tsx # Home route configuration +│ │ ├── team.tsx # Team route configuration +│ │ └── ... +│ │ +│ ├── lib/ # Utility functions and integrations +│ │ ├── utils.ts # Helper functions +│ │ └── theme-provider.tsx # Theme management +│ │ +│ ├── routes.ts # Main routing configuration +│ ├── root.tsx # Root layout component +│ └── app.css # Global styles +│ +├── build/ # Generated files (DO NOT EDIT) +│ ├── client/ # Browser-side assets +│ │ ├── index.html # HTML files for each page +│ │ ├── assets/ # JavaScript, CSS bundles +│ │ └── images/ # Optimized images +│ +├── public/ # Static files (copied as-is to build/) +│ ├── favicon.ico # Website icon +│ ├── images/ # Image assets +│ └── ... +│ +├── node_modules/ # Dependencies (like Maven's .m2 directory) +├── package.json # Project metadata and dependencies (like pom.xml) +├── tsconfig.json # TypeScript configuration +└── react-router.config.ts # React Router framework configuration +``` + +#### Key Principles + +1. **UI Components (`/ui`)**: Pure, reusable components with no business logic + - Can be used anywhere in the application + - Only concerned with appearance and basic interaction + +2. **Business Components (`/components`)**: Reusable across pages + - May contain business logic specific to ZooKeeper website + - Examples: navigation, footer, theme toggle + +3. **Pages (`/pages`)**: Complete pages combining ui and components + - Each page has its own directory + - Only `index.tsx` is exported + - Internal components stay within the page directory + - If a component needs to be reused, move it to `/components` + +4. **Routes (`/routes`)**: Define routing and metadata + - Maps URLs to pages + - Sets page titles, meta tags, etc. + +5. **Two Layout Systems in One App**: + - **Landing pages** live under `app/pages/_landing/` and use the landing layout. + - **Docs pages** live under `app/pages/_docs/` and use Fumadocs layouts. + - Both are part of the same React Router application, but render with different layouts and visual styles. + +6. **Documentation Structure**: + - **Docs** live under `app/pages/_docs/docs/_mdx/` and are the source of truth. + +#### Important Conventions + +##### Custom Link Component + +**Always use the custom Link component from `@/components/link` instead of importing Link directly from `react-router`.** + +The ZooKeeper website includes pages that are not part of this React Router application (e.g., documentation pages, API docs). The custom Link component automatically determines whether a link should trigger a hard reload or use React Router's client-side navigation: + +**Usage:** + +```typescript +// ✅ CORRECT - Use custom Link component +import { Link } from "@/components/link"; + +export const MyComponent = () => ( + Team +); +``` + +```typescript +// ❌ WRONG - Do not import Link from react-router +import { Link } from "react-router"; + +export const MyComponent = () => ( + Team +); +``` + +The ESLint configuration includes a custom rule (`custom/no-react-router-link`) that will throw an error if you attempt to import `Link` from `react-router`, helping enforce this convention automatically. + +### Getting Started + +#### 1. Install Dependencies + +Think of this as `mvn install`: + +```bash +npm install +``` + +This downloads all required packages from npm (similar to Maven Central). + +#### 2. Start Development Server + +```bash +npm run dev +``` + +This starts a local development server with: + +- **Hot Module Replacement (HMR)**: Code changes appear instantly without full page reload +- **Live at**: `http://localhost:5173` + +### Development Workflow + +#### Making Changes + +1. **Edit code** in the `app/` directory +2. **Save the file** - changes appear automatically in the browser +3. **Check for errors** in the terminal where `npm run dev` is running and in browser console + +#### Common Tasks + +**Add a new page:** + +1. Create directory in `app/pages/my-new-page/` +2. Create `index.tsx` in that directory +3. Create route file in `app/routes/my-new-page.tsx` +4. Register route in `app/routes.ts` + +**Add a new documentation page:** + +1. Create a new `.mdx` file in `app/pages/_docs/docs/_mdx/` (for example `my-topic.mdx`). +2. Add the new file to the relevant `meta.json` in the same section folder so it appears in navigation. + +**Update content:** + +- Edit the appropriate `.md` or `.json` file +- Changes appear automatically + +**Add a UI component:** + +- Check if shadcn/ui has what you need first +- Only create custom components if necessary + +**Update the 404 page:** + +- Edit the content in `app/routes/404.tsx`. +- Apache 404 handling lives in `public/.htaccess` (uses `ErrorDocument 404 /404`). + +**Check code quality:** + +```bash +npm run lint +``` + +**Fix linting and formatting issues:** + +```bash +npm run lint:fix +``` + +### Testing + +The project uses [Vitest](https://vitest.dev/) and [Playwright](http://playwright.dev/) for testing. Vitest is for unit testing, while Playwright is for e2e testing. + +**Note:** Playwright tests are configured to run against the production build. Therefore, you must build the project (`npm run build`) before running the e2e tests locally. + +**Run tests:** + +```bash +# Run all tests (unit + e2e) +# Note: e2e tests require a production build first (`npm run build`) +npm test + +# Run unit tests once (for CI/CD) +npm run test:unit:run + +# Run unit tests with UI +npm run test:unit:ui + +# Run e2e tests (requires `npm run build` first) +npm run test:e2e + +# Run e2e tests with UI (requires `npm run build` first) +npm run test:e2e:ui +``` + +**Writing new tests:** + +Use the `renderWithProviders` utility in `test/utils.tsx` to ensure components have access to routing and theme context: + +```typescript +import { renderWithProviders, screen } from './utils' +import { MyComponent } from '@/components/my-component' + +describe('MyComponent', () => { + it('renders correctly', () => { + renderWithProviders() + expect(screen.getByText('Hello World')).toBeInTheDocument() + }) +}) +``` + +### Building for Production + +**CI/CD Workflow:** + +Before merging or deploying, run the full CI pipeline: + +```bash +npm run ci +``` + +This command runs all quality checks and builds the project. All checks must pass before code is considered ready. + +If you need the CI flow without unit/e2e test suites, use: + +```bash +npm run ci-skip-tests +``` + +This runs docs initialization and the production build (without lint/typecheck and without unit/e2e test suites). + +Generated files are located under the `build/` directory. + +### Maven Integration + +The website is integrated with the Apache ZooKeeper Maven build system using the `frontend-maven-plugin`. The website is configured to build **only during site generation** (`mvn site`) and will not build during regular Maven lifecycle phases like `mvn clean install`. + +#### When the Website Builds + +The website build is triggered **only** when you run: + +```bash +mvn site +``` + +The website will **NOT** build during regular commands like: + +- `mvn clean install` +- `mvn package` +- `mvn compile` + +This keeps regular ZooKeeper builds fast while still allowing the website to be generated when needed. + +#### What Gets Executed During `mvn site` + +When you run `mvn site`, the website module automatically: + +1. **Cleans previous build artifacts** + - Removes `build/` directory + - Removes `node_modules/` directory + - Ensures a fresh build environment + +2. **Installs Node.js v22.20.0 and npm 11.6.2** (if not already available) + - Installed to `target/` directory + - Does not affect your system Node/npm installation + +3. **Runs `npm install`** to install all dependencies + - Reads from `package.json` + - Installs to `node_modules/` + +4. **Runs a website CI command**: + - Default (`mvn site`): `npm run ci` + - With test skipping (`mvn site -DskipTests`): `npm run ci-skip-tests` + + `npm run ci` executes: + - `npm run fumadocs-init` - Initialize Fumadocs + - `npm run lint` - ESLint code quality checks + - `npm run typecheck` - TypeScript type checking + - `npm run test:unit:run` - Vitest unit tests + - `npm run build` - Production build + - `npx playwright install` - Installs Playwright browsers + - `npm run test:e2e` - Playwright e2e tests + + `npm run ci-skip-tests` executes: + - `npm run fumadocs-init` - Initialize Fumadocs + - `npm run build` - Production build + +5. **Build Output**: Generated files are in `build/` directory + +#### Maven Commands + +**Build ZooKeeper WITHOUT the Website (default):** + +```bash +# From ZooKeeper root directory +mvn clean install +``` + +**Build the Website:** + +```bash +# From ZooKeeper root or zookeeper-website directory +mvn site +``` + +This generates the full ZooKeeper website including documentation and the React-based website. + +**Build the Website While Skipping Test Suites:** + +```bash +# From ZooKeeper root or zookeeper-website directory +mvn site -DskipTests +``` + +This runs `npm run ci-skip-tests` for the website module. + +**Build Website Only:** + +```bash +# From zookeeper-website directory +cd zookeeper-website +mvn clean install +``` + +**Skip Website Build:** + +If you want to build ZooKeeper but skip the website: + +```bash +# From ZooKeeper root directory +mvn clean install -DskipSite +``` + +### Deployment + +The website source lives on the **`website`** branch of the [apache/zookeeper](https://github.com/apache/zookeeper) repository. The live production site at [zookeeper.apache.org](https://zookeeper.apache.org) is served from the **`asf-site`** branch. Any commit pushed to `asf-site` is immediately reflected on the live site via Apache's gitpubsub infrastructure. + +#### Basic workflow + +1. Make changes on the `website` branch. +2. Run the CI pipeline locally to verify everything passes. +3. Build the production bundle — the output ends up in `build/client/`. +4. Replace the contents of `asf-site` with the new `build/client/` and push. + +```bash +# 1. Clone / switch to the website source branch +git clone -b website https://github.com/apache/zookeeper.git +cd zookeeper + +# 2. Edit content, then verify +npm run ci + +# 3. Commit the source changes +git add +git commit -m "Update website content" +git push origin website + +# 4. Publish: switch to asf-site and replace content +git checkout asf-site +rm -rf content +mkdir -p content +cp -R build/client/. content/ +git add content +git commit -m "Publish website " +git push origin asf-site +``` + +Once `asf-site` is pushed the updates are live within minutes. + +--- + +### Publishing a New ZooKeeper Release + +When a new ZooKeeper version is released, update the **current version** identifier and archive the previous release's generated documentation. + +#### Step 1 — Archive the outgoing documentation + +The built HTML of the outgoing release docs must be preserved so users can still access them via the "Older docs" picker in the sidebar and navbar. Each archived version lives in its own folder under `public/released-docs/`, named `r` (e.g. `r3.9.4`). + +Copy the fully-rendered HTML documentation into that folder: + +```bash +# Example: archiving 3.9.4 before bumping to 3.9.5 +mkdir -p public/released-docs/r3.9.4 +cp -R /* public/released-docs/r3.9.4/ +``` + +> The "Older docs" picker reads folder names from `public/released-docs/` at build time — no configuration file needs to be updated. + +#### Step 2 — Bump `CURRENT_VERSION` + +Open `app/lib/current-version.ts` and update the version string: + +```typescript +// app/lib/current-version.ts +export const CURRENT_VERSION = "3.9.5"; // ← change to the new version +``` + +This single constant drives the version shown across the current docs experience, including: + +- The docs overview page title and description (`3.9.5 Overview`, `Official Apache ZooKeeper 3.9.5 documentation…`) +- Other components that reference `CURRENT_VERSION` + +#### Step 3 — Update the in-app documentation + +The current release's documentation source lives in `app/pages/_docs/docs/_mdx/`. Update or replace the MDX files there to reflect the new release. + +#### Step 4 — Build and publish + +```bash +npm run ci # verify everything passes +# then follow the deployment steps above to push to asf-site +``` + +### Troubleshooting + +#### TypeScript Types Are Broken + +If you see type errors related to React Router's `+types`, regenerate them: + +```bash +npx react-router typegen +``` + +#### Port Already in Use + +If `npm run dev` fails because port 5173 is in use: + +```bash +# Kill the process using the port +lsof -ti:5173 | xargs kill -9 + +# Or change the port in vite.config.ts +``` + +#### Build Fails + +1. **Clear generated files:** + + ```bash + rm -rf build/ node_modules/ .vite/ .react-router/ .source/ + ``` + +2. **Reinstall dependencies:** + + ```bash + npm i + ``` + +3. **Try building again:** + ```bash + npm run build + ``` + +--- + +## Additional Resources + +- **React Router Documentation**: https://reactrouter.com/ +- **Progressive Enhancement Explained**: https://reactrouter.com/explanation/progressive-enhancement +- **shadcn/ui Components**: https://ui.shadcn.com/ +- **TailwindCSS Docs**: https://tailwindcss.com/ +- **TypeScript Handbook**: https://www.typescriptlang.org/docs/ + +--- + +Built with ❤️ for the Apache ZooKeeper community. diff --git a/zookeeper-website/app/app.css b/zookeeper-website/app/app.css new file mode 100644 index 00000000000..5d665a3ab70 --- /dev/null +++ b/zookeeper-website/app/app.css @@ -0,0 +1,287 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +@import "tailwindcss"; +@import "tw-animate-css"; +@import "fumadocs-ui/css/shadcn.css"; +@import "fumadocs-ui/css/preset.css"; + +@plugin "@tailwindcss/typography" { + className: prose-original; +} + +@custom-variant dark (&:is(.dark *)); +@custom-variant js (&:is(.js *)); + +/* Inter — normal axis */ +@font-face { + font-family: "Inter"; + src: url("/fonts/inter-latin-wght-normal.woff2") format("woff2"); + font-weight: 100 900; /* adjust if your file isn't variable */ + font-style: normal; + font-display: swap; +} + +/* Inter — italic axis */ +@font-face { + font-family: "Inter"; + src: url("/fonts/inter-latin-wght-italic.woff2") format("woff2"); + font-weight: 100 900; /* adjust if needed */ + font-style: italic; + font-display: swap; +} + +:root { + --background: oklch(1 0 0); + --foreground: oklch(0.145 0 0); + --card: oklch(1 0 0); + --card-foreground: oklch(0.145 0 0); + --popover: oklch(1 0 0); + --popover-foreground: oklch(0.145 0 0); + --primary: oklch(55.31% 0.12 136.93); + --primary-foreground: oklch(0.985 0 0); + --secondary: oklch(0.97 0 0); + --secondary-foreground: oklch(0.205 0 0); + --muted: oklch(0.97 0 0); + --muted-foreground: oklch(0.556 0 0); + --accent: oklch(0.97 0 0); + --accent-foreground: oklch(0.205 0 0); + --destructive: oklch(0.577 0.245 27.325); + --destructive-foreground: oklch(0.577 0.245 27.325); + --border: oklch(0.922 0 0); + --input: oklch(0.922 0 0); + --ring: oklch(0.708 0 0); + --chart-1: oklch(0.646 0.222 41.116); + --chart-2: oklch(0.6 0.118 184.704); + --chart-3: oklch(0.398 0.07 227.392); + --chart-4: oklch(0.828 0.189 84.429); + --chart-5: oklch(0.769 0.188 70.08); + --radius: 0.625rem; + --sidebar: oklch(0.985 0 0); + --sidebar-foreground: oklch(0.145 0 0); + --sidebar-primary: oklch(0.205 0 0); + --sidebar-primary-foreground: oklch(0.985 0 0); + --sidebar-accent: oklch(0.97 0 0); + --sidebar-accent-foreground: oklch(0.205 0 0); + --sidebar-border: oklch(0.922 0 0); + --sidebar-ring: oklch(0.708 0 0); +} + +.dark { + --background: oklch(0.17 0 0); + --foreground: oklch(0.92 0 0); + --card: oklch(0.2 0 0); + --card-foreground: oklch(0.92 0 0); + --popover: oklch(0.2 0 0); + --popover-foreground: oklch(0.92 0 0); + --primary: oklch(55.31% 0.12 136.93); + --primary-strong: oklch(0.40 0.13 145); + --primary-foreground: oklch(97% 0 0); + --secondary: oklch(0.25 0 0); + --secondary-foreground: oklch(0.92 0 0); + --muted: oklch(0.25 0 0); + --muted-foreground: oklch(0.62 0 0); + --accent: oklch(0.25 0 0); + --accent-foreground: oklch(0.92 0 0); + --destructive: oklch(0.577 0.245 27.325); + --destructive-foreground: oklch(0.98 0 0); + --border: oklch(0.3 0 0); + --input: oklch(0.3 0 0); + --ring: oklch(55.31% 0.12 136.93); + --chart-1: oklch(0.646 0.222 41.116); + --chart-2: oklch(0.6 0.118 184.704); + --chart-3: oklch(0.398 0.07 227.392); + --chart-4: oklch(0.828 0.189 84.429); + --chart-5: oklch(0.769 0.188 70.08); + --sidebar: oklch(0.2 0 0); + --sidebar-foreground: oklch(0.92 0 0); + --sidebar-primary: oklch(55.31% 0.12 136.93); + --sidebar-primary-foreground: oklch(0.98 0 0); + --sidebar-accent: oklch(0.25 0 0); + --sidebar-accent-foreground: oklch(0.92 0 0); + --sidebar-border: oklch(0.3 0 0); + --sidebar-ring: oklch(55.31% 0.12 136.93); +} + +@theme inline { + --color-background: var(--background); + --color-foreground: var(--foreground); + --color-card: var(--card); + --color-card-foreground: var(--card-foreground); + --color-popover: var(--popover); + --color-popover-foreground: var(--popover-foreground); + --color-primary: var(--primary); + --color-primary-strong: var(--primary-strong); + --color-primary-foreground: var(--primary-foreground); + --color-secondary: var(--secondary); + --color-secondary-foreground: var(--secondary-foreground); + --color-muted: var(--muted); + --color-muted-foreground: var(--muted-foreground); + --color-accent: var(--accent); + --color-accent-foreground: var(--accent-foreground); + --color-destructive: var(--destructive); + --color-destructive-foreground: var(--destructive-foreground); + --color-border: var(--border); + --color-input: var(--input); + --color-ring: var(--ring); + --color-chart-1: var(--chart-1); + --color-chart-2: var(--chart-2); + --color-chart-3: var(--chart-3); + --color-chart-4: var(--chart-4); + --color-chart-5: var(--chart-5); + --radius-sm: calc(var(--radius) - 4px); + --radius-md: calc(var(--radius) - 2px); + --radius-lg: var(--radius); + --radius-xl: calc(var(--radius) + 4px); + --color-sidebar: var(--sidebar); + --color-sidebar-foreground: var(--sidebar-foreground); + --color-sidebar-primary: var(--sidebar-primary); + --color-sidebar-primary-foreground: var(--sidebar-primary-foreground); + --color-sidebar-accent: var(--sidebar-accent); + --color-sidebar-accent-foreground: var(--sidebar-accent-foreground); + --color-sidebar-border: var(--sidebar-border); + --color-sidebar-ring: var(--sidebar-ring); +} + +@layer base { + * { + @apply border-border outline-ring/50; + } + + body { + @apply bg-background text-foreground; + } + + .font-base { + font-family: "Inter", sans-serif; + font-synthesis: none; + } + + .print-only { + display: none; + } +} + +@layer utilities { + @media (width >= 80rem) { + .container { + @apply max-w-6xl; + } + } +} + +/* For rendering a PDF */ +@media print { + @page { + size: A4; + } + + /* Utility classes */ + .print-only { + display: block !important; + } + .no-print { + display: none !important; + } + + /* Hide layout elements */ + #nd-docs-layout { + --fd-sidebar-width: 0px !important; + } + #nd-sidebar { + display: none; + } + header { + display: none !important; + } + /* Hide copy button in the code blocks */ + figure > div > button { + display: none !important; + } + + /* Every major section starts on a new page */ + h1:not(:first-of-type) { + break-before: page; + margin-top: 0; /* Remove top margin since it's at the top of a page now */ + } + + h1, + h2, + h3, + h4, + h5, + h6 { + break-after: avoid; + break-inside: avoid; + } + + /* Hides the
line */ + hr { + display: none; + } + + /* Force tables to wrap the content */ + table { + max-width: 100%; + table-layout: fixed; + word-wrap: break-word; + } + th, + td { + padding: 6px 10px !important; + word-break: break-all; /* Older browsers */ + overflow-wrap: anywhere; /* Modern browsers: breaks at any character */ + hyphens: auto; /* Adds a hyphen if the language is defined */ + } + thead { + display: table-header-group; /* Re-renders header on every new page */ + } + /* Don't split a row on two pages, just move it to the next page */ + tr { + break-inside: avoid; + } + + /* Force code blocks to wrap instead of scroll */ + pre, + code { + max-width: 100% !important; + white-space: pre-wrap !important; + word-break: break-all !important; + overflow-wrap: break-word !important; + } + + /* Targets Code and Tables */ + pre, + table, + blockquote { + /* Try to keep it on one page if possible */ + break-inside: auto; + /* If it breaks, ensure at least 3 lines stay on the current page */ + orphans: 3; + /* If it breaks, ensure at least 3 lines move to the next page */ + widows: 3; + } + + /* Remove the height restriction and scrolling from the code blocks */ + figure .fd-scroll-container.max-h-\[600px\] { + max-height: none !important; + overflow: visible !important; + height: auto !important; + display: block !important; + } +} diff --git a/zookeeper-website/app/components/docs/layout/docs/client.tsx b/zookeeper-website/app/components/docs/layout/docs/client.tsx new file mode 100644 index 00000000000..a6a86586495 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/docs/client.tsx @@ -0,0 +1,166 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + type ComponentProps, + createContext, + type ReactNode, + use, + useEffect, + useMemo, + useState +} from "react"; +import { useSidebar } from "../sidebar/base"; +import { usePathname } from "fumadocs-core/framework"; +import Link from "fumadocs-core/link"; +import type { SidebarTab } from "../sidebar/tabs"; +import { isTabActive } from "../sidebar/tabs/dropdown"; +import { cn } from "@/lib/utils"; + +export const LayoutContext = createContext<{ + isNavTransparent: boolean; +} | null>(null); + +export function LayoutContextProvider({ + navTransparentMode = "none", + children +}: { + navTransparentMode?: "always" | "top" | "none"; + children: ReactNode; +}) { + const isTop = + useIsScrollTop({ enabled: navTransparentMode === "top" }) ?? true; + const isNavTransparent = + navTransparentMode === "top" ? isTop : navTransparentMode === "always"; + + return ( + ({ + isNavTransparent + }), + [isNavTransparent] + )} + > + {children} + + ); +} + +export function LayoutHeader(props: ComponentProps<"header">) { + const { isNavTransparent } = use(LayoutContext)!; + + return ( +
+ {props.children} +
+ ); +} + +export function LayoutBody({ + className, + style, + children, + ...props +}: ComponentProps<"div">) { + const { collapsed } = useSidebar(); + + return ( +
+ {children} +
+ ); +} + +export function LayoutTabs({ + options, + ...props +}: ComponentProps<"div"> & { + options: SidebarTab[]; +}) { + const pathname = usePathname(); + const selected = useMemo(() => { + return options.findLast((option) => isTabActive(option, pathname)); + }, [options, pathname]); + + return ( +
+ {options.map((option, i) => ( + + {option.title} + + ))} +
+ ); +} + +export function useIsScrollTop({ enabled = true }: { enabled?: boolean }) { + const [isTop, setIsTop] = useState(); + + useEffect(() => { + if (!enabled) return; + + const listener = () => { + setIsTop(window.scrollY < 10); + }; + + listener(); + window.addEventListener("scroll", listener); + return () => { + window.removeEventListener("scroll", listener); + }; + }, [enabled]); + + return isTop; +} diff --git a/zookeeper-website/app/components/docs/layout/docs/index.tsx b/zookeeper-website/app/components/docs/layout/docs/index.tsx new file mode 100644 index 00000000000..0bf6e17334e --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/docs/index.tsx @@ -0,0 +1,330 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type * as PageTree from "fumadocs-core/page-tree"; +import { + type ComponentProps, + type HTMLAttributes, + type ReactNode, + useMemo +} from "react"; +import { Languages, Sidebar as SidebarIcon } from "lucide-react"; +import { buttonVariants } from "../../../../ui/button"; +import { + Sidebar, + SidebarCollapseTrigger, + SidebarContent, + SidebarDrawer, + SidebarLinkItem, + SidebarPageTree, + SidebarTrigger, + SidebarViewport +} from "./sidebar"; +import { + type BaseLayoutProps, + renderTitleNav, + resolveLinkItems +} from "../shared"; +import { LinkItem } from "../link-item"; +import { LanguageToggle, LanguageToggleText } from "../language-toggle"; +import { + LayoutBody, + LayoutContextProvider, + LayoutHeader, + LayoutTabs +} from "./client"; +import { TreeContextProvider } from "fumadocs-ui/contexts/tree"; +import { ThemeToggle } from "../theme-toggle"; +import { LargeSearchToggle, SearchToggle } from "../search-toggle"; +import { getSidebarTabs, type GetSidebarTabsOptions } from "../sidebar/tabs"; +import type { SidebarPageTreeComponents } from "../sidebar/page-tree"; +import { + SidebarTabsDropdown, + type SidebarTabWithProps +} from "../sidebar/tabs/dropdown"; +import { cn } from "@/lib/utils"; + +export interface DocsLayoutProps extends BaseLayoutProps { + tree: PageTree.Root; + + sidebar?: SidebarOptions; + + tabMode?: "top" | "auto"; + + /** + * Props for the `div` container + */ + containerProps?: HTMLAttributes; + + shouldRenderPageTree?: boolean; +} + +interface SidebarOptions + extends ComponentProps<"aside">, + Pick, "defaultOpenLevel" | "prefetch"> { + enabled?: boolean; + component?: ReactNode; + components?: Partial; + + /** + * Root Toggle options + */ + tabs?: SidebarTabWithProps[] | GetSidebarTabsOptions | false; + + banner?: ReactNode; + footer?: ReactNode; + + /** + * Support collapsing the sidebar on desktop mode + * + * @defaultValue true + */ + collapsible?: boolean; +} + +export function DocsLayout({ + nav: { transparentMode, ...nav } = {}, + sidebar: { + tabs: sidebarTabs, + enabled: sidebarEnabled = true, + defaultOpenLevel, + prefetch, + ...sidebarProps + } = {}, + searchToggle = {}, + themeSwitch = {}, + tabMode = "auto", + i18n = false, + children, + tree, + shouldRenderPageTree = true, + ...props +}: DocsLayoutProps) { + const tabs = useMemo(() => { + if (Array.isArray(sidebarTabs)) { + return sidebarTabs; + } + if (typeof sidebarTabs === "object") { + return getSidebarTabs(tree, sidebarTabs); + } + if (sidebarTabs !== false) { + return getSidebarTabs(tree); + } + return []; + }, [tree, sidebarTabs]); + const links = resolveLinkItems(props); + + function sidebar() { + const { + footer, + banner, + collapsible = true, + component, + components, + ...rest + } = sidebarProps; + if (component) return component; + + const iconLinks = links.filter((item) => item.type === "icon"); + const viewport = ( + + {links + .filter((v) => v.type !== "icon") + .map((item, i, list) => ( + + ))} + {shouldRenderPageTree && } + + ); + + return ( + <> + +
+
+ {renderTitleNav(nav, { + className: + "inline-flex text-[0.9375rem] items-center gap-2.5 font-medium me-auto" + })} + {nav.children} + {collapsible && ( + + + + )} +
+ {searchToggle.enabled !== false && + (searchToggle.components?.lg ?? ( + + ))} + {tabs.length > 0 && tabMode === "auto" && ( + + )} + {banner} +
+ {viewport} + {(i18n || + iconLinks.length > 0 || + themeSwitch?.enabled !== false || + footer) && ( +
+
+ {i18n && ( + + + + )} + {iconLinks.map((item, i) => ( + + {item.icon} + + ))} + {themeSwitch.enabled !== false && + (themeSwitch.component ?? ( + + ))} +
+ {footer} +
+ )} + + +
+
+
+ {iconLinks.map((item, i) => ( + + {item.icon} + + ))} +
+ {i18n && ( + + + + + )} + {themeSwitch.enabled !== false && + (themeSwitch.component ?? ( + + ))} + + + +
+ {tabs.length > 0 && } + {banner} +
+ {viewport} +
+ {footer} +
+ + + ); + } + + return ( + + + + + {nav.enabled !== false && + (nav.component ?? ( + + {renderTitleNav(nav, { + className: "inline-flex items-center gap-2.5 font-semibold" + })} +
{nav.children}
+ {searchToggle.enabled !== false && + (searchToggle.components?.sm ?? ( + + ))} + {sidebarEnabled && ( + + + + )} + + ))} + {sidebarEnabled && sidebar()} + {tabMode === "top" && tabs.length > 0 && ( + + )} + {children} + + + + + ); +} diff --git a/zookeeper-website/app/components/docs/layout/docs/page/client.tsx b/zookeeper-website/app/components/docs/layout/docs/page/client.tsx new file mode 100644 index 00000000000..affc22a8428 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/docs/page/client.tsx @@ -0,0 +1,421 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + type ComponentProps, + createContext, + Fragment, + use, + useEffect, + useEffectEvent, + useMemo, + useRef, + useState +} from "react"; +import { ChevronDown, ChevronLeft, ChevronRight } from "lucide-react"; +import Link from "fumadocs-core/link"; +import { useI18n } from "fumadocs-ui/contexts/i18n"; +import { useTreeContext, useTreePath } from "fumadocs-ui/contexts/tree"; +import type * as PageTree from "fumadocs-core/page-tree"; +import { usePathname } from "fumadocs-core/framework"; +import { + type BreadcrumbOptions, + getBreadcrumbItemsFromPath +} from "fumadocs-core/breadcrumb"; +import { isActive } from "../../../../../lib/urls"; +import { + Collapsible, + CollapsibleContent, + CollapsibleTrigger +} from "../../../../../ui/collapsible"; +import { useTOCItems } from "../../../toc"; +import { useActiveAnchor } from "fumadocs-core/toc"; +import { LayoutContext } from "../client"; +import { cn } from "@/lib/utils"; + +const TocPopoverContext = createContext<{ + open: boolean; + setOpen: (open: boolean) => void; +} | null>(null); + +export function PageTOCPopover({ + className, + children, + ...rest +}: ComponentProps<"div">) { + const ref = useRef(null); + const [open, setOpen] = useState(false); + const { isNavTransparent } = use(LayoutContext)!; + + const onClick = useEffectEvent((e: Event) => { + if (!open) return; + + if (ref.current && !ref.current.contains(e.target as HTMLElement)) + setOpen(false); + }); + + useEffect(() => { + window.addEventListener("click", onClick); + + return () => { + window.removeEventListener("click", onClick); + }; + }, [onClick]); + + return ( + ({ + open, + setOpen + }), + [setOpen, open] + )} + > + +
+ {children} +
+ + + ); +} + +export function PageTOCPopoverTrigger({ + className, + ...props +}: ComponentProps<"button">) { + const { text } = useI18n(); + const { open } = use(TocPopoverContext)!; + const items = useTOCItems(); + const active = useActiveAnchor(); + const selected = useMemo( + () => items.findIndex((item) => active === item.url.slice(1)), + [items, active] + ); + const path = useTreePath().at(-1); + const showItem = selected !== -1 && !open; + + return ( + + + + + {path?.name ?? text.toc} + + + {items[selected]?.title} + + + + + ); +} + +interface ProgressCircleProps + extends Omit, "strokeWidth"> { + value: number; + strokeWidth?: number; + size?: number; + min?: number; + max?: number; +} + +function clamp(input: number, min: number, max: number): number { + if (input < min) return min; + if (input > max) return max; + return input; +} + +function ProgressCircle({ + value, + strokeWidth = 2, + size = 24, + min = 0, + max = 100, + ...restSvgProps +}: ProgressCircleProps) { + const normalizedValue = clamp(value, min, max); + const radius = (size - strokeWidth) / 2; + const circumference = 2 * Math.PI * radius; + const progress = (normalizedValue / max) * circumference; + const circleProps = { + cx: size / 2, + cy: size / 2, + r: radius, + fill: "none", + strokeWidth + }; + + return ( + + + + + ); +} + +export function PageTOCPopoverContent(props: ComponentProps<"div">) { + return ( + + {props.children} + + ); +} + +export function PageLastUpdate({ + date: value, + ...props +}: Omit, "children"> & { date: Date }) { + const { text } = useI18n(); + const [date, setDate] = useState(""); + + useEffect(() => { + // to the timezone of client + setDate(value.toLocaleDateString()); + }, [value]); + + return ( +

+ {text.lastUpdate} {date} +

+ ); +} + +type Item = Pick; +export interface FooterProps extends ComponentProps<"div"> { + /** + * Items including information for the next and previous page + */ + items?: { + previous?: Item; + next?: Item; + }; +} + +export function PageFooter({ + items, + children, + className, + ...props +}: FooterProps) { + const footerList = useFooterItems(); + const pathname = usePathname(); + const { previous, next } = useMemo(() => { + if (items) return items; + + const idx = footerList.findIndex((item) => + isActive(item.url, pathname, false) + ); + + if (idx === -1) return {}; + return { + previous: footerList[idx - 1], + next: footerList[idx + 1] + }; + }, [footerList, items, pathname]); + + return ( + <> +
+ {previous && } + {next && } +
+ {children} + + ); +} + +function FooterItem({ item, index }: { item: Item; index: 0 | 1 }) { + const { text } = useI18n(); + const Icon = index === 0 ? ChevronLeft : ChevronRight; + + return ( + +
+ +

{item.name}

+
+

+ {item.description ?? (index === 0 ? text.previousPage : text.nextPage)} +

+ + ); +} + +export type BreadcrumbProps = BreadcrumbOptions & ComponentProps<"div">; + +export function PageBreadcrumb({ + includeRoot, + includeSeparator, + includePage, + ...props +}: BreadcrumbProps) { + const path = useTreePath(); + const { root } = useTreeContext(); + const items = useMemo(() => { + return getBreadcrumbItemsFromPath(root, path, { + includePage, + includeSeparator, + includeRoot + }); + }, [includePage, includeRoot, includeSeparator, path, root]); + + if (items.length === 0) return null; + + return ( +
+ {items.map((item, i) => { + const className = cn( + "truncate", + i === items.length - 1 && "text-fd-primary font-medium" + ); + + return ( + + {i !== 0 && } + {item.url ? ( + + {item.name} + + ) : ( + {item.name} + )} + + ); + })} +
+ ); +} + +const footerCache = new Map(); + +/** + * @returns a list of page tree items (linear), that you can obtain footer items + */ +export function useFooterItems(): PageTree.Item[] { + const { root } = useTreeContext(); + const cached = footerCache.get(root.$id); + if (cached) return cached; + + const list: PageTree.Item[] = []; + function onNode(node: PageTree.Node) { + if (node.type === "folder") { + if (node.index) onNode(node.index); + for (const child of node.children) onNode(child); + } else if (node.type === "page" && !node.external) { + list.push(node); + } + } + + for (const child of root.children) onNode(child); + footerCache.set(root.$id, list); + return list; +} diff --git a/zookeeper-website/app/components/docs/layout/docs/page/index.tsx b/zookeeper-website/app/components/docs/layout/docs/page/index.tsx new file mode 100644 index 00000000000..05c0fde3f20 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/docs/page/index.tsx @@ -0,0 +1,282 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentProps, ReactNode } from "react"; +import { buttonVariants } from "../../../../../ui/button"; +import { Edit, Text } from "lucide-react"; +import { I18nLabel } from "fumadocs-ui/contexts/i18n"; +import { + type BreadcrumbProps, + type FooterProps, + PageBreadcrumb, + PageFooter, + PageTOCPopover, + PageTOCPopoverContent, + PageTOCPopoverTrigger +} from "./client"; +import type { AnchorProviderProps, TOCItemType } from "fumadocs-core/toc"; +import * as TocDefault from "../../../toc/default"; +import * as TocClerk from "../../../toc/clerk"; +import { TOCProvider, TOCScrollArea } from "../../../toc"; +import { cn } from "@/lib/utils"; + +interface BreadcrumbOptions extends BreadcrumbProps { + enabled: boolean; + component: ReactNode; +} + +interface FooterOptions extends FooterProps { + enabled: boolean; + component: ReactNode; +} + +export interface DocsPageProps { + toc?: TOCItemType[]; + tableOfContent?: Partial; + tableOfContentPopover?: Partial; + + /** + * Extend the page to fill all available space + * + * @defaultValue false + */ + full?: boolean; + + /** + * Replace or disable breadcrumb + */ + breadcrumb?: Partial; + + /** + * Footer navigation, located under the page body. + * + * You can specify `footer.children` to add extra components under the footer. + */ + footer?: Partial; + + children?: ReactNode; + + /** + * Apply class names to the `#nd-page` container. + */ + className?: string; +} + +type TableOfContentOptions = Pick & { + /** + * Custom content in TOC container, before the main TOC + */ + header?: ReactNode; + + /** + * Custom content in TOC container, after the main TOC + */ + footer?: ReactNode; + + enabled: boolean; + component: ReactNode; + + /** + * @defaultValue 'normal' + */ + style?: "normal" | "clerk"; +}; + +type TableOfContentPopoverOptions = Omit; + +export function DocsPage({ + breadcrumb: { + enabled: breadcrumbEnabled = true, + component: breadcrumb, + ...breadcrumbProps + } = {}, + footer: { + enabled: footerEnabled, + component: footerReplace, + ...footerProps + } = {}, + full = false, + tableOfContentPopover: { + enabled: tocPopoverEnabled, + component: tocPopover, + ...tocPopoverOptions + } = {}, + tableOfContent: { + enabled: tocEnabled, + component: tocReplace, + ...tocOptions + } = {}, + toc = [], + children, + className +}: DocsPageProps) { + // disable TOC on full mode, you can still enable it with `enabled` option. + tocEnabled ??= + !full && + (toc.length > 0 || + tocOptions.footer !== undefined || + tocOptions.header !== undefined); + + tocPopoverEnabled ??= + toc.length > 0 || + tocPopoverOptions.header !== undefined || + tocPopoverOptions.footer !== undefined; + + let wrapper = (children: ReactNode) => children; + + if (tocEnabled || tocPopoverEnabled) { + wrapper = (children) => ( + + {children} + + ); + } + + return wrapper( + <> + {tocPopoverEnabled && + (tocPopover ?? ( + + + + {tocPopoverOptions.header} + + {tocPopoverOptions.style === "clerk" ? ( + + ) : ( + + )} + + {tocPopoverOptions.footer} + + + ))} +
+ {breadcrumbEnabled && + (breadcrumb ?? )} + {children} + {footerEnabled !== false && + (footerReplace ?? )} +
+ {tocEnabled && + (tocReplace ?? ( +
+ {tocOptions.header} +

+ + +

+ + {tocOptions.style === "clerk" ? ( + + ) : ( + + )} + + {tocOptions.footer} +
+ ))} + + ); +} + +export function EditOnGitHub(props: ComponentProps<"a">) { + return ( + + {props.children ?? ( + <> + + + + )} + + ); +} + +/** + * Add typography styles + */ +export function DocsBody({ + children, + className, + ...props +}: ComponentProps<"div">) { + return ( +
+ {children} +
+ ); +} + +export function DocsDescription({ + children, + className, + ...props +}: ComponentProps<"p">) { + // Don't render if no description provided + if (children === undefined) return null; + + return ( +

+ {children} +

+ ); +} + +export function DocsTitle({ + children, + className, + ...props +}: ComponentProps<"h1">) { + return ( +

+ {children} +

+ ); +} + +export { PageLastUpdate, PageBreadcrumb } from "./client"; diff --git a/zookeeper-website/app/components/docs/layout/docs/sidebar.tsx b/zookeeper-website/app/components/docs/layout/docs/sidebar.tsx new file mode 100644 index 00000000000..623b68a9554 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/docs/sidebar.tsx @@ -0,0 +1,285 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import * as Base from "../sidebar/base"; +import { type ComponentProps, useRef } from "react"; +import { cva } from "class-variance-authority"; +import { createPageTreeRenderer } from "../sidebar/page-tree"; +import { createLinkItemRenderer } from "../sidebar/link-item"; +import { buttonVariants } from "../../../../ui/button"; +import { SearchToggle } from "../search-toggle"; +import { Sidebar as SidebarIcon } from "lucide-react"; +import { cn, mergeRefs } from "@/lib/utils"; + +const itemVariants = cva( + "relative flex flex-row items-center gap-2 rounded-lg p-2 text-start text-fd-muted-foreground wrap-anywhere [&_svg]:size-4 [&_svg]:shrink-0", + { + variants: { + variant: { + link: "transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 hover:transition-none data-[active=true]:bg-fd-primary/10 data-[active=true]:text-fd-primary data-[active=true]:hover:transition-colors", + button: + "transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 hover:transition-none" + }, + highlight: { + true: "data-[active=true]:before:content-[''] data-[active=true]:before:bg-fd-primary data-[active=true]:before:absolute data-[active=true]:before:w-px data-[active=true]:before:inset-y-2.5 data-[active=true]:before:start-2.5" + } + } + } +); + +function getItemOffset(depth: number) { + return `calc(${2 + 3 * depth} * var(--spacing))`; +} + +export { + SidebarProvider as Sidebar, + SidebarFolder, + SidebarCollapseTrigger, + SidebarViewport, + SidebarTrigger +} from "../sidebar/base"; + +export function SidebarContent({ + ref: refProp, + className, + children, + isSearchToggleEnabled = true, + ...props +}: ComponentProps<"aside"> & { isSearchToggleEnabled?: boolean }) { + const ref = useRef(null); + + return ( + + {({ collapsed, hovered, ref: asideRef, ...rest }) => ( + <> +
+ {collapsed && ( +
+ )} + +
+
+ + + + {isSearchToggleEnabled && ( + + )} +
+ + )} + + ); +} + +export function SidebarDrawer({ + children, + className, + ...props +}: ComponentProps) { + return ( + <> + + + {children} + + + ); +} + +export function SidebarSeparator({ + className, + style, + children, + ...props +}: ComponentProps<"p">) { + const depth = Base.useFolderDepth(); + + return ( + + {children} + + ); +} + +export function SidebarItem({ + className, + style, + children, + ...props +}: ComponentProps) { + const depth = Base.useFolderDepth(); + + return ( + = 1 }), + className + )} + style={{ + paddingInlineStart: getItemOffset(depth), + ...style + }} + {...props} + > + {children} + + ); +} + +export function SidebarFolderTrigger({ + className, + style, + ...props +}: ComponentProps) { + const { depth, collapsible } = Base.useFolder()!; + + return ( + + {props.children} + + ); +} + +export function SidebarFolderLink({ + className, + style, + ...props +}: ComponentProps) { + const depth = Base.useFolderDepth(); + + return ( + 1 }), + "w-full", + className + )} + style={{ + paddingInlineStart: getItemOffset(depth - 1), + ...style + }} + {...props} + > + {props.children} + + ); +} + +export function SidebarFolderContent({ + className, + children, + ...props +}: ComponentProps) { + const depth = Base.useFolderDepth(); + + return ( + + {children} + + ); +} + +export const SidebarPageTree = createPageTreeRenderer({ + SidebarFolder: Base.SidebarFolder, + SidebarFolderContent, + SidebarFolderLink, + SidebarFolderTrigger, + SidebarItem, + SidebarSeparator +}); + +export const SidebarLinkItem = createLinkItemRenderer({ + SidebarFolder: Base.SidebarFolder, + SidebarFolderContent, + SidebarFolderLink, + SidebarFolderTrigger, + SidebarItem +}); diff --git a/zookeeper-website/app/components/docs/layout/language-toggle.tsx b/zookeeper-website/app/components/docs/layout/language-toggle.tsx new file mode 100644 index 00000000000..6b423932043 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/language-toggle.tsx @@ -0,0 +1,79 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentProps } from "react"; +import { useI18n } from "fumadocs-ui/contexts/i18n"; +import { Popover, PopoverContent, PopoverTrigger } from "../../../ui/popover"; +import { buttonVariants } from "../../../ui/button"; +import { cn } from "@/lib/utils"; + +export type LanguageSelectProps = ComponentProps<"button">; + +export function LanguageToggle(props: LanguageSelectProps): React.ReactElement { + const context = useI18n(); + if (!context.locales) throw new Error("Missing ``"); + + return ( + + + {props.children} + + +

+ {context.text.chooseLanguage} +

+ {context.locales.map((item) => ( + + ))} + + + ); +} + +export function LanguageToggleText(props: ComponentProps<"span">) { + const context = useI18n(); + const text = context.locales?.find( + (item) => item.locale === context.locale + )?.name; + + return {text}; +} diff --git a/zookeeper-website/app/components/docs/layout/link-item.tsx b/zookeeper-website/app/components/docs/layout/link-item.tsx new file mode 100644 index 00000000000..5fc30acec54 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/link-item.tsx @@ -0,0 +1,136 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentProps, ReactNode } from "react"; +import { usePathname } from "fumadocs-core/framework"; +import { isActive } from "../../../lib/urls"; +import Link from "fumadocs-core/link"; + +interface Filterable { + /** + * Restrict where the item is displayed + * + * @defaultValue 'all' + */ + on?: "menu" | "nav" | "all"; +} + +interface WithHref { + url: string; + /** + * When the item is marked as active + * + * @defaultValue 'url' + */ + active?: "url" | "nested-url" | "none"; + external?: boolean; +} + +export interface MainItemType extends WithHref, Filterable { + type?: "main"; + icon?: ReactNode; + text: ReactNode; + description?: ReactNode; +} + +export interface IconItemType extends WithHref, Filterable { + type: "icon"; + /** + * `aria-label` of icon button + */ + label?: string; + icon: ReactNode; + text: ReactNode; + /** + * @defaultValue true + */ + secondary?: boolean; +} + +export interface ButtonItemType extends WithHref, Filterable { + type: "button"; + icon?: ReactNode; + text: ReactNode; + /** + * @defaultValue false + */ + secondary?: boolean; +} + +export interface MenuItemType extends Partial, Filterable { + type: "menu"; + icon?: ReactNode; + text: ReactNode; + + items: ( + | (MainItemType & { + /** + * Options when displayed on navigation menu + */ + menu?: ComponentProps<"a"> & { + banner?: ReactNode; + }; + }) + | CustomItemType + )[]; + + /** + * @defaultValue false + */ + secondary?: boolean; +} + +export interface CustomItemType extends Filterable { + type: "custom"; + /** + * @defaultValue false + */ + secondary?: boolean; + children: ReactNode; +} + +export type LinkItemType = + | MainItemType + | IconItemType + | ButtonItemType + | MenuItemType + | CustomItemType; + +export function LinkItem({ + ref, + item, + ...props +}: Omit, "href"> & { item: WithHref }) { + const pathname = usePathname(); + const activeType = item.active ?? "url"; + const active = + activeType !== "none" && + isActive(item.url, pathname, activeType === "nested-url"); + + return ( + + {props.children} + + ); +} diff --git a/zookeeper-website/app/components/docs/layout/search-toggle.tsx b/zookeeper-website/app/components/docs/layout/search-toggle.tsx new file mode 100644 index 00000000000..707d6f23a30 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/search-toggle.tsx @@ -0,0 +1,96 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentProps } from "react"; +import { Search } from "lucide-react"; +import { useSearchContext } from "fumadocs-ui/contexts/search"; +import { useI18n } from "fumadocs-ui/contexts/i18n"; +import { type ButtonProps, buttonVariants } from "../../../ui/button"; +import { cn } from "@/lib/utils"; + +interface SearchToggleProps + extends Omit, "color">, + ButtonProps { + hideIfDisabled?: boolean; +} + +export function SearchToggle({ + hideIfDisabled, + size = "icon-sm", + variant = "ghost", + ...props +}: SearchToggleProps) { + const { setOpenSearch, enabled } = useSearchContext(); + if (hideIfDisabled && !enabled) return null; + + return ( + + ); +} + +export function LargeSearchToggle({ + hideIfDisabled, + ...props +}: ComponentProps<"button"> & { + hideIfDisabled?: boolean; +}) { + const { enabled, hotKey, setOpenSearch } = useSearchContext(); + const { text } = useI18n(); + if (hideIfDisabled && !enabled) return null; + + return ( + + ); +} diff --git a/zookeeper-website/app/components/docs/layout/shared.tsx b/zookeeper-website/app/components/docs/layout/shared.tsx new file mode 100644 index 00000000000..130221692a5 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/shared.tsx @@ -0,0 +1,120 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentProps, ReactNode } from "react"; +import type { I18nConfig } from "fumadocs-core/i18n"; +import type { LinkItemType } from "./link-item"; +import Link from "fumadocs-core/link"; + +export interface NavOptions { + enabled: boolean; + component: ReactNode; + + title?: ReactNode | ((props: ComponentProps<"a">) => ReactNode); + + /** + * Redirect url of title + * @defaultValue '/' + */ + url?: string; + + /** + * Use transparent background + * + * @defaultValue none + */ + transparentMode?: "always" | "top" | "none"; + + children?: ReactNode; +} + +export interface BaseLayoutProps { + themeSwitch?: { + enabled?: boolean; + component?: ReactNode; + mode?: "light-dark" | "light-dark-system"; + }; + + searchToggle?: Partial<{ + enabled: boolean; + components: Partial<{ + sm: ReactNode; + lg: ReactNode; + }>; + }>; + + /** + * I18n options + * + * @defaultValue false + */ + i18n?: boolean | I18nConfig; + + /** + * GitHub url + */ + githubUrl?: string; + + links?: LinkItemType[]; + /** + * Replace or disable navbar + */ + nav?: Partial; + + children?: ReactNode; +} + +/** + * Get link items with shortcuts + */ +export function resolveLinkItems({ + links = [], + githubUrl +}: Pick): LinkItemType[] { + const result = [...links]; + + if (githubUrl) + result.push({ + type: "icon", + url: githubUrl, + text: "Github", + label: "GitHub", + icon: ( + + + + ), + external: true + }); + + return result; +} + +export function renderTitleNav( + { title, url = "/" }: Partial, + props: ComponentProps<"a"> +) { + if (typeof title === "function") return title({ href: url, ...props }); + return ( + + {title} + + ); +} + +export type * from "./link-item"; diff --git a/zookeeper-website/app/components/docs/layout/sidebar/base.tsx b/zookeeper-website/app/components/docs/layout/sidebar/base.tsx new file mode 100644 index 00000000000..87737126051 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/sidebar/base.tsx @@ -0,0 +1,471 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { ChevronDown, ExternalLink } from "lucide-react"; +import { + type ComponentProps, + createContext, + type PointerEvent, + type ReactNode, + type RefObject, + use, + useEffect, + useMemo, + useRef, + useState +} from "react"; +import Link, { type LinkProps } from "fumadocs-core/link"; +import { useOnChange } from "fumadocs-core/utils/use-on-change"; +import { + ScrollArea, + type ScrollAreaProps, + ScrollViewport +} from "../../../../ui/scroll-area"; +import { isActive } from "../../../../lib/urls"; +import { + Collapsible, + CollapsibleContent, + type CollapsibleContentProps, + CollapsibleTrigger, + type CollapsibleTriggerProps +} from "../../../../ui/collapsible"; +import { useMediaQuery } from "fumadocs-core/utils/use-media-query"; +import { Presence } from "@radix-ui/react-presence"; +import scrollIntoView from "scroll-into-view-if-needed"; +import { usePathname } from "fumadocs-core/framework"; +import { cn } from "@/lib/utils"; + +interface SidebarContext { + open: boolean; + setOpen: React.Dispatch>; + collapsed: boolean; + setCollapsed: React.Dispatch>; + + /** + * When set to false, don't close the sidebar when navigate to another page + */ + closeOnRedirect: RefObject; + defaultOpenLevel: number; + prefetch?: boolean; + mode: Mode; +} + +export interface SidebarProviderProps { + /** + * Open folders by default if their level is lower or equal to a specific level + * (Starting from 1) + * + * @defaultValue 0 + */ + defaultOpenLevel?: number; + + /** + * Prefetch links, default behaviour depends on your React.js framework. + */ + prefetch?: boolean; + + children?: ReactNode; +} + +type Mode = "drawer" | "full"; + +const SidebarContext = createContext(null); + +const FolderContext = createContext<{ + open: boolean; + setOpen: React.Dispatch>; + depth: number; + collapsible: boolean; +} | null>(null); + +export function SidebarProvider({ + defaultOpenLevel = 0, + prefetch, + children +}: SidebarProviderProps) { + const closeOnRedirect = useRef(true); + const [open, setOpen] = useState(false); + const [collapsed, setCollapsed] = useState(false); + const pathname = usePathname(); + const mode: Mode = useMediaQuery("(width < 768px)") ? "drawer" : "full"; + + useOnChange(pathname, () => { + if (closeOnRedirect.current) { + setOpen(false); + } + closeOnRedirect.current = true; + }); + + return ( + ({ + open, + setOpen, + collapsed, + setCollapsed, + closeOnRedirect, + defaultOpenLevel, + prefetch, + mode + }), + [open, collapsed, defaultOpenLevel, prefetch, mode] + )} + > + {children} + + ); +} + +export function useSidebar(): SidebarContext { + const ctx = use(SidebarContext); + if (!ctx) + throw new Error( + "Missing SidebarContext, make sure you have wrapped the component in and the context is available." + ); + + return ctx; +} + +export function useFolder() { + return use(FolderContext); +} + +export function useFolderDepth() { + return use(FolderContext)?.depth ?? 0; +} + +export function SidebarContent({ + children +}: { + children: (state: { + ref: RefObject; + collapsed: boolean; + hovered: boolean; + onPointerEnter: (event: PointerEvent) => void; + onPointerLeave: (event: PointerEvent) => void; + }) => ReactNode; +}) { + const { collapsed, mode } = useSidebar(); + const [hover, setHover] = useState(false); + const ref = useRef(null); + const timerRef = useRef(0); + + useOnChange(collapsed, () => { + if (collapsed) setHover(false); + }); + + if (mode !== "full") return; + + function shouldIgnoreHover(e: PointerEvent): boolean { + const element = ref.current; + if (!element) return true; + + return ( + !collapsed || + e.pointerType === "touch" || + element.getAnimations().length > 0 + ); + } + + return children({ + ref, + collapsed, + hovered: hover, + onPointerEnter(e) { + if (shouldIgnoreHover(e)) return; + window.clearTimeout(timerRef.current); + setHover(true); + }, + onPointerLeave(e) { + if (shouldIgnoreHover(e)) return; + window.clearTimeout(timerRef.current); + + timerRef.current = window.setTimeout( + () => setHover(false), + // if mouse is leaving the viewport, add a close delay + Math.min(e.clientX, document.body.clientWidth - e.clientX) > 100 + ? 0 + : 500 + ); + } + }); +} + +export function SidebarDrawerOverlay(props: ComponentProps<"div">) { + const { open, setOpen, mode } = useSidebar(); + + if (mode !== "drawer") return; + return ( + +
setOpen(false)} + {...props} + /> + + ); +} + +export function SidebarDrawerContent({ + className, + children, + ...props +}: ComponentProps<"aside">) { + const { open, mode } = useSidebar(); + const state = open ? "open" : "closed"; + + if (mode !== "drawer") return; + return ( + + {({ present }) => ( + + )} + + ); +} + +export function SidebarViewport(props: ScrollAreaProps) { + return ( + + + {props.children} + + + ); +} + +export function SidebarSeparator(props: ComponentProps<"p">) { + const depth = useFolderDepth(); + return ( +

+ {props.children} +

+ ); +} + +export function SidebarItem({ + icon, + children, + ...props +}: LinkProps & { + icon?: ReactNode; +}) { + const pathname = usePathname(); + const ref = useRef(null); + const { prefetch } = useSidebar(); + const active = + props.href !== undefined && isActive(props.href, pathname, false); + + useAutoScroll(active, ref); + + return ( + + {icon ?? (props.external ? : null)} + {children} + + ); +} + +export function SidebarFolder({ + defaultOpen: defaultOpenProp, + collapsible = true, + active = false, + children, + ...props +}: ComponentProps<"div"> & { + active?: boolean; + defaultOpen?: boolean; + collapsible?: boolean; +}) { + const { defaultOpenLevel } = useSidebar(); + const depth = useFolderDepth() + 1; + const defaultOpen = + collapsible === false || + active || + (defaultOpenProp ?? defaultOpenLevel >= depth); + const [open, setOpen] = useState(defaultOpen); + + useOnChange(defaultOpen, (v) => { + if (v) setOpen(v); + }); + + return ( + + ({ open, setOpen, depth, collapsible }), + [collapsible, depth, open] + )} + > + {children} + + + ); +} + +export function SidebarFolderTrigger({ + children, + ...props +}: CollapsibleTriggerProps) { + const { open, collapsible } = use(FolderContext)!; + + if (collapsible) { + return ( + + {children} + + + ); + } + + return
)}>{children}
; +} + +export function SidebarFolderLink({ children, ...props }: LinkProps) { + const ref = useRef(null); + const { open, setOpen, collapsible } = use(FolderContext)!; + const { prefetch } = useSidebar(); + const pathname = usePathname(); + const active = + props.href !== undefined && isActive(props.href, pathname, false); + + useAutoScroll(active, ref); + + return ( + { + if (!collapsible) return; + + if ( + e.target instanceof Element && + e.target.matches("[data-icon], [data-icon] *") + ) { + setOpen(!open); + e.preventDefault(); + } else { + setOpen(active ? !open : true); + } + }} + prefetch={prefetch} + {...props} + > + {children} + {collapsible && ( + + )} + + ); +} + +export function SidebarFolderContent(props: CollapsibleContentProps) { + return {props.children}; +} + +export function SidebarTrigger({ + children, + ...props +}: ComponentProps<"button">) { + const { setOpen } = useSidebar(); + + return ( + + ); +} + +export function SidebarCollapseTrigger(props: ComponentProps<"button">) { + const { collapsed, setCollapsed } = useSidebar(); + + return ( + + ); +} + +/** + * scroll to the element if `active` is true + */ +export function useAutoScroll( + active: boolean, + ref: RefObject +) { + const { mode } = useSidebar(); + + useEffect(() => { + if (active && ref.current) { + scrollIntoView(ref.current, { + boundary: document.getElementById( + mode === "drawer" ? "nd-sidebar-mobile" : "nd-sidebar" + ), + scrollMode: "if-needed" + }); + } + }, [active, mode, ref]); +} diff --git a/zookeeper-website/app/components/docs/layout/sidebar/link-item.tsx b/zookeeper-website/app/components/docs/layout/sidebar/link-item.tsx new file mode 100644 index 00000000000..8fc13971ef1 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/sidebar/link-item.tsx @@ -0,0 +1,83 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { HTMLAttributes } from "react"; +import type * as Base from "./base"; +import type { LinkItemType } from "../link-item"; + +type InternalComponents = Pick< + typeof Base, + | "SidebarFolder" + | "SidebarFolderLink" + | "SidebarFolderContent" + | "SidebarFolderTrigger" + | "SidebarItem" +>; + +export function createLinkItemRenderer({ + SidebarFolder, + SidebarFolderContent, + SidebarFolderLink, + SidebarFolderTrigger, + SidebarItem +}: InternalComponents) { + /** + * Render sidebar items from page tree + */ + return function SidebarLinkItem({ + item, + ...props + }: HTMLAttributes & { + item: Exclude; + }) { + if (item.type === "custom") return
{item.children}
; + + if (item.type === "menu") + return ( + + {item.url ? ( + + {item.icon} + {item.text} + + ) : ( + + {item.icon} + {item.text} + + )} + + {item.items.map((child, i) => ( + + ))} + + + ); + + return ( + + {item.text} + + ); + }; +} diff --git a/zookeeper-website/app/components/docs/layout/sidebar/page-tree.tsx b/zookeeper-website/app/components/docs/layout/sidebar/page-tree.tsx new file mode 100644 index 00000000000..e6b969e6d89 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/sidebar/page-tree.tsx @@ -0,0 +1,130 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { useTreeContext, useTreePath } from "fumadocs-ui/contexts/tree"; +import { type FC, type ReactNode, useMemo, Fragment } from "react"; +import type * as PageTree from "fumadocs-core/page-tree"; +import type * as Base from "./base"; + +export interface SidebarPageTreeComponents { + Item: FC<{ item: PageTree.Item }>; + Folder: FC<{ item: PageTree.Folder; children: ReactNode }>; + Separator: FC<{ item: PageTree.Separator }>; +} + +type InternalComponents = Pick< + typeof Base, + | "SidebarSeparator" + | "SidebarFolder" + | "SidebarFolderLink" + | "SidebarFolderContent" + | "SidebarFolderTrigger" + | "SidebarItem" +>; + +export function createPageTreeRenderer({ + SidebarFolder, + SidebarFolderContent, + SidebarFolderLink, + SidebarFolderTrigger, + SidebarSeparator, + SidebarItem +}: InternalComponents) { + function PageTreeFolder({ + item, + children + }: { + item: PageTree.Folder; + children: ReactNode; + }) { + const path = useTreePath(); + + return ( + + {item.index ? ( + + {item.icon} + {item.name} + + ) : ( + + {item.icon} + {item.name} + + )} + {children} + + ); + } + + /** + * Render sidebar items from page tree + */ + return function SidebarPageTree( + components: Partial + ) { + const { root } = useTreeContext(); + const { Separator, Item, Folder = PageTreeFolder } = components; + + return useMemo(() => { + function renderSidebarList(items: PageTree.Node[]) { + return items.map((item, i) => { + if (item.type === "separator") { + if (Separator) return ; + return ( + + {item.icon} + {item.name} + + ); + } + + if (item.type === "folder") { + return ( + + {renderSidebarList(item.children)} + + ); + } + + if (Item) return ; + return ( + + {item.name} + + ); + }); + } + + return ( + {renderSidebarList(root.children)} + ); + }, [Folder, Item, Separator, root]); + }; +} diff --git a/zookeeper-website/app/components/docs/layout/sidebar/tabs/dropdown.tsx b/zookeeper-website/app/components/docs/layout/sidebar/tabs/dropdown.tsx new file mode 100644 index 00000000000..fc3e5239cd9 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/sidebar/tabs/dropdown.tsx @@ -0,0 +1,128 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Check, ChevronsUpDown } from "lucide-react"; +import { type ComponentProps, type ReactNode, useMemo, useState } from "react"; +import Link from "fumadocs-core/link"; +import { usePathname } from "fumadocs-core/framework"; +import { isActive, normalize } from "@/lib/urls"; +import { useSidebar } from "../base"; +import { Popover, PopoverContent, PopoverTrigger } from "@/ui/popover"; +import type { SidebarTab } from "./index"; +import { cn } from "@/lib/utils"; + +export interface SidebarTabWithProps extends SidebarTab { + props?: ComponentProps<"a">; +} + +export function SidebarTabsDropdown({ + options, + placeholder, + ...props +}: { + placeholder?: ReactNode; + options: SidebarTabWithProps[]; +} & ComponentProps<"button">) { + const [open, setOpen] = useState(false); + const { closeOnRedirect } = useSidebar(); + const pathname = usePathname(); + + const selected = useMemo(() => { + return options.findLast((item) => isTabActive(item, pathname)); + }, [options, pathname]); + + const onClick = () => { + closeOnRedirect.current = false; + setOpen(false); + }; + + const item = selected ? ( + <> +
+ {selected.icon} +
+
+

{selected.title}

+

+ {selected.description} +

+
+ + ) : ( + placeholder + ); + + return ( + + {item && ( + + {item} + + + )} + + {options.map((item) => { + const isActive = selected && item.url === selected.url; + if (!isActive && item.unlisted) return; + + return ( + +
+ {item.icon} +
+
+

{item.title}

+

+ {item.description} +

+
+ + + + ); + })} + + + ); +} + +export function isTabActive(tab: SidebarTab, pathname: string) { + if (tab.urls) return tab.urls.has(normalize(pathname)); + + return isActive(tab.url, pathname, true); +} diff --git a/zookeeper-website/app/components/docs/layout/sidebar/tabs/index.tsx b/zookeeper-website/app/components/docs/layout/sidebar/tabs/index.tsx new file mode 100644 index 00000000000..ea27fc93739 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/sidebar/tabs/index.tsx @@ -0,0 +1,107 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type * as PageTree from "fumadocs-core/page-tree"; +import type { ReactNode } from "react"; + +export interface SidebarTab { + /** + * Redirect URL of the folder, usually the index page + */ + url: string; + + icon?: ReactNode; + title: ReactNode; + description?: ReactNode; + + /** + * Detect from a list of urls + */ + urls?: Set; + unlisted?: boolean; +} + +export interface GetSidebarTabsOptions { + transform?: (option: SidebarTab, node: PageTree.Folder) => SidebarTab | null; +} + +const defaultTransform: GetSidebarTabsOptions["transform"] = (option, node) => { + if (!node.icon) return option; + + return { + ...option, + icon: ( +
+ {node.icon} +
+ ) + }; +}; + +export function getSidebarTabs( + tree: PageTree.Root, + { transform = defaultTransform }: GetSidebarTabsOptions = {} +): SidebarTab[] { + const results: SidebarTab[] = []; + + function scanOptions( + node: PageTree.Root | PageTree.Folder, + unlisted?: boolean + ) { + if ("root" in node && node.root) { + const urls = getFolderUrls(node); + + if (urls.size > 0) { + const option: SidebarTab = { + url: urls.values().next().value ?? "", + title: node.name, + icon: node.icon, + unlisted, + description: node.description, + urls + }; + + const mapped = transform ? transform(option, node) : option; + if (mapped) results.push(mapped); + } + } + + for (const child of node.children) { + if (child.type === "folder") scanOptions(child, unlisted); + } + } + + scanOptions(tree); + if (tree.fallback) scanOptions(tree.fallback, true); + + return results; +} + +function getFolderUrls( + folder: PageTree.Folder, + output: Set = new Set() +): Set { + if (folder.index) output.add(folder.index.url); + + for (const child of folder.children) { + if (child.type === "page" && !child.external) output.add(child.url); + if (child.type === "folder") getFolderUrls(child, output); + } + + return output; +} diff --git a/zookeeper-website/app/components/docs/layout/theme-toggle.tsx b/zookeeper-website/app/components/docs/layout/theme-toggle.tsx new file mode 100644 index 00000000000..a566ccbf976 --- /dev/null +++ b/zookeeper-website/app/components/docs/layout/theme-toggle.tsx @@ -0,0 +1,103 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { cn } from "@/lib/utils"; +import { cva } from "class-variance-authority"; +import { Airplay, Moon, Sun } from "lucide-react"; +import { useTheme } from "next-themes"; +import { type ComponentProps, useEffect, useState } from "react"; + +const itemVariants = cva( + "size-6.5 rounded-full p-1.5 text-fd-muted-foreground", + { + variants: { + active: { + true: "bg-fd-accent text-fd-accent-foreground", + false: "text-fd-muted-foreground" + } + } + } +); + +const full = [ + ["light", Sun] as const, + ["dark", Moon] as const, + ["system", Airplay] as const +]; + +export function ThemeToggle({ + className, + mode = "light-dark", + ...props +}: ComponentProps<"div"> & { + mode?: "light-dark" | "light-dark-system"; +}) { + const { setTheme, theme, resolvedTheme } = useTheme(); + const [mounted, setMounted] = useState(false); + + useEffect(() => { + setMounted(true); + }, []); + + const container = cn( + "inline-flex items-center rounded-full border p-1", + className + ); + + if (mode === "light-dark") { + const value = mounted ? resolvedTheme : null; + + return ( + + ); + } + + const value = mounted ? theme : null; + + return ( +
+ {full.map(([key, Icon]) => ( + + ))} +
+ ); +} diff --git a/zookeeper-website/app/components/docs/older-docs-picker.tsx b/zookeeper-website/app/components/docs/older-docs-picker.tsx new file mode 100644 index 00000000000..178a81cf416 --- /dev/null +++ b/zookeeper-website/app/components/docs/older-docs-picker.tsx @@ -0,0 +1,73 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { ChevronRight, BookOpen } from "lucide-react"; +import { Popover, PopoverContent, PopoverTrigger } from "@/ui/popover"; +import { + Command, + CommandEmpty, + CommandGroup, + CommandInput, + CommandItem, + CommandList +} from "@/ui/command"; +import { RELEASED_DOC_VERSIONS } from "@/lib/released-docs-versions"; + +/** Shared Command palette (search + list), used in both the + * sidebar popover and the navbar sub-menu. */ +export function OlderDocsVersionList() { + return ( + (value.includes(search) ? 1 : 0)}> + + + No versions found + + {RELEASED_DOC_VERSIONS.map((version) => ( + + {version} + + ))} + + + + ); +} + +/** Sidebar variant — Popover that opens to the right of the trigger button. */ +export function OlderDocsPicker() { + return ( + + + + + + + + + ); +} diff --git a/zookeeper-website/app/components/docs/search/create-db.ts b/zookeeper-website/app/components/docs/search/create-db.ts new file mode 100644 index 00000000000..108def1e5e5 --- /dev/null +++ b/zookeeper-website/app/components/docs/search/create-db.ts @@ -0,0 +1,110 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + create, + insertMultiple, + type Orama, + type PartialSchemaDeep, + type TypedDocument +} from "@orama/orama"; +import type { AdvancedOptions } from "fumadocs-core/search/server"; + +export type AdvancedDocument = TypedDocument>; +export const advancedSchema = { + content: "string", + page_id: "string", + type: "string", + breadcrumbs: "string[]", + tags: "enum[]", + url: "string", + embeddings: "vector[512]" +} as const; + +export async function createDB({ + indexes, + tokenizer, + ...rest +}: AdvancedOptions): Promise> { + const items = typeof indexes === "function" ? await indexes() : indexes; + + const db = create({ + schema: advancedSchema, + ...rest, + components: { + ...rest.components, + tokenizer: tokenizer ?? rest.components?.tokenizer + } + }) as Orama; + + const mapTo: PartialSchemaDeep[] = []; + items.forEach((page) => { + const pageTag = page.tag ?? []; + const tags = Array.isArray(pageTag) ? pageTag : [pageTag]; + const data = page.structuredData; + let id = 0; + + mapTo.push({ + id: page.id, + page_id: page.id, + type: "page", + content: page.title, + breadcrumbs: page.breadcrumbs, + tags, + url: page.url + }); + + const nextId = () => `${page.id}-${id++}`; + + if (page.description) { + mapTo.push({ + id: nextId(), + page_id: page.id, + tags, + type: "text", + url: page.url, + content: page.description + }); + } + + for (const heading of data.headings) { + mapTo.push({ + id: nextId(), + page_id: page.id, + type: "heading", + tags, + url: `${page.url}#${heading.id}`, + content: heading.content + }); + } + + for (const content of data.contents) { + mapTo.push({ + id: nextId(), + page_id: page.id, + tags, + type: "text", + url: content.heading ? `${page.url}#${content.heading}` : page.url, + content: content.content + }); + } + }); + + await insertMultiple(db, mapTo); + return db; +} diff --git a/zookeeper-website/app/components/docs/search/create-from-source.ts b/zookeeper-website/app/components/docs/search/create-from-source.ts new file mode 100644 index 00000000000..c43aef2959b --- /dev/null +++ b/zookeeper-website/app/components/docs/search/create-from-source.ts @@ -0,0 +1,141 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + type AdvancedIndex, + type AdvancedOptions, + createI18nSearchAPI, + type SearchAPI, + createSearchAPI +} from "fumadocs-core/search/server"; +import { PathUtils } from "fumadocs-core/source"; +import type { Language } from "@orama/orama"; +import type { LoaderConfig, LoaderOutput, Page } from "fumadocs-core/source"; +import type { I18nConfig } from "fumadocs-core/i18n"; +import { findPath } from "fumadocs-core/page-tree"; +import type { StructuredData } from "fumadocs-core/mdx-plugins"; + +type Awaitable = T | Promise; + +function defaultBuildIndex( + source: LoaderOutput, + tag?: (pageUrl: string) => string +) { + function isBreadcrumbItem(item: unknown): item is string { + return typeof item === "string" && item.length > 0; + } + + return async (page: Page): Promise => { + let breadcrumbs: string[] | undefined; + let structuredData: StructuredData | undefined; + + if ("structuredData" in page.data) { + structuredData = page.data.structuredData as StructuredData; + } else if ("load" in page.data && typeof page.data.load === "function") { + structuredData = (await page.data.load()).structuredData; + } + + if (!structuredData) + throw new Error( + "Cannot find structured data from page, please define the page to index function." + ); + + const pageTree = source.getPageTree(page.locale); + const path = findPath( + pageTree.children, + (node) => node.type === "page" && node.url === page.url + ); + if (path) { + breadcrumbs = []; + path.pop(); + + if (isBreadcrumbItem(pageTree.name)) { + breadcrumbs.push(pageTree.name); + } + + for (const segment of path) { + if (!isBreadcrumbItem(segment.name)) continue; + + breadcrumbs.push(segment.name); + } + } + + return { + title: + page.data.title ?? + PathUtils.basename(page.path, PathUtils.extname(page.path)), + breadcrumbs, + description: page.data.description, + url: page.url, + id: page.url, + structuredData, + tag: tag?.(page.url) + }; + }; +} + +interface Options + extends Omit { + localeMap?: { + [K in C["i18n"] extends I18nConfig ? Languages : string]?: + | Partial + | Language; + }; + buildIndex?: ( + page: Page + ) => Awaitable; + tag?: (pageUrl: string) => string; +} + +export function createFromSource( + source: LoaderOutput, + options?: Options +): SearchAPI; + +export function createFromSource( + source: LoaderOutput, + options: Options = {} +): SearchAPI { + const { buildIndex = defaultBuildIndex(source, options.tag) } = options; + + if (source._i18n) { + return createI18nSearchAPI("advanced", { + ...options, + i18n: source._i18n, + indexes: async () => { + const indexes = source.getLanguages().flatMap((entry) => { + return entry.pages.map(async (page) => ({ + ...(await buildIndex(page)), + locale: entry.language + })); + }); + + return Promise.all(indexes); + } + }); + } + + return createSearchAPI("advanced", { + ...options, + indexes: async () => { + const indexes = source.getPages().map((page) => buildIndex(page)); + + return Promise.all(indexes); + } + }); +} diff --git a/zookeeper-website/app/components/docs/search/docs-search.tsx b/zookeeper-website/app/components/docs/search/docs-search.tsx new file mode 100644 index 00000000000..c8cc5d3ae30 --- /dev/null +++ b/zookeeper-website/app/components/docs/search/docs-search.tsx @@ -0,0 +1,80 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + SearchDialog as FumaDocsSearchDialog, + SearchDialogClose, + SearchDialogContent, + SearchDialogHeader, + SearchDialogIcon, + SearchDialogInput, + SearchDialogList, + SearchDialogOverlay, + type SharedProps +} from "fumadocs-ui/components/dialog/search"; +import { useDocsSearch } from "./use-docs-search"; +import { create } from "@orama/orama"; +import { useI18n } from "fumadocs-ui/contexts/i18n"; + +function initOrama() { + return create({ + schema: { _: "string" }, + language: "english" + }); +} + +export function SearchDialog(props: SharedProps) { + const { locale } = useI18n(); + + const { search, setSearch, query } = useDocsSearch({ + type: "static", + initOrama, + locale, + tag: "multi-page" + }); + + return ( + + + + + + + + + ({ + ...i, + breadcrumbs: i.breadcrumbs?.filter( + (k) => k !== "Multi-Page Documentation" + ) + })) + : null + } + /> + + + ); +} diff --git a/zookeeper-website/app/components/docs/search/static.ts b/zookeeper-website/app/components/docs/search/static.ts new file mode 100644 index 00000000000..cfdb42f8668 --- /dev/null +++ b/zookeeper-website/app/components/docs/search/static.ts @@ -0,0 +1,329 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + type AnyOrama, + create, + load, + type Orama, + type SearchParams, + search as searchOrama, + getByID +} from "@orama/orama"; +import { type AdvancedDocument, type advancedSchema } from "./create-db"; +import { + createContentHighlighter, + type SortedResult +} from "fumadocs-core/search"; +import type { ExportedData } from "fumadocs-core/search/server"; +import { removeUndefined } from "./utils"; + +export interface StaticOptions { + /** + * Where to download exported search indexes (URL) + * + * @defaultValue '/api/search' + */ + from?: string; + + initOrama?: (locale?: string) => AnyOrama | Promise; + + /** + * Filter results with specific tag(s). + */ + tag?: string | string[]; + + /** + * Filter by locale (unsupported at the moment) + */ + locale?: string; +} + +const cache = new Map>(); + +// locale -> db +type Database = Map< + string, + { + db: AnyOrama; + } +>; + +async function loadDB({ + from = "/api/search", + initOrama = (locale) => create({ schema: { _: "string" }, language: locale }) +}: StaticOptions): Promise { + const cacheKey = from; + const cached = cache.get(cacheKey); + if (cached) return cached; + + async function init() { + const res = await fetch(from); + + if (!res.ok) + throw new Error( + `failed to fetch exported search indexes from ${from}, make sure the search database is exported and available for client.` + ); + + const data = (await res.json()) as ExportedData; + const dbs: Database = new Map(); + + if (data.type === "i18n") { + await Promise.all( + Object.entries(data.data).map(async ([k, v]) => { + const db = await initOrama(k); + + load(db, v); + dbs.set(k, { + db + }); + }) + ); + + return dbs; + } + + const db = await initOrama(); + load(db, data); + dbs.set("", { + db + }); + return dbs; + } + + const result = init(); + cache.set(cacheKey, result); + return result; +} + +export async function search(query: string, options: StaticOptions) { + const { tag, locale } = options; + + const db = (await loadDB(options)).get(locale ?? ""); + + if (!db) return []; + + return searchAdvanced(db.db as Orama, query, tag); +} + +export async function searchAdvanced( + db: Orama, + query: string, + tag: string | string[] = [], + { + mode = "fulltext", + ...override + }: Partial, AdvancedDocument>> = {} +): Promise { + if (typeof tag === "string") tag = [tag]; + + let params = { + ...override, + mode, + where: removeUndefined({ + tags: + tag.length > 0 + ? { + containsAll: tag + } + : undefined, + ...override.where + }), + groupBy: { + properties: ["page_id"], + maxResult: 8, + ...override.groupBy + } + } as SearchParams; + + if (query.length > 0) { + params = { + ...params, + term: query, + properties: mode === "fulltext" ? ["content"] : ["content", "embeddings"] + } as SearchParams; + } + + const highlighter = createContentHighlighter(query); + const result = await searchOrama(db, params); + + // Helper to detect phrase matches (3+ consecutive words) + const getPhraseMatchBoost = (content: string, searchTerm: string): number => { + const contentLower = content.toLowerCase(); + const termLower = searchTerm.toLowerCase(); + + // Split search term into words + const searchWords = termLower.split(/\s+/).filter((w) => w.length > 0); + + // Need at least 3 words for phrase matching + if (searchWords.length < 3) return 0; + + // Check for longest consecutive word match + let maxConsecutiveMatch = 0; + + for (let i = 0; i <= searchWords.length - 3; i++) { + // Try matching from 3 words up to all remaining words + for (let len = 3; len <= searchWords.length - i; len++) { + const phrase = searchWords.slice(i, i + len).join(" "); + if (contentLower.includes(phrase)) { + maxConsecutiveMatch = Math.max(maxConsecutiveMatch, len); + } + } + } + + // Boost based on length of consecutive match + // Make this VERY high to dominate over heading matches + // 3 words: +10000, 4 words: +15000, 5+ words: +20000+ + if (maxConsecutiveMatch >= 3) { + return 10000 + (maxConsecutiveMatch - 3) * 5000; + } + + return 0; + }; + + // Helper to score match quality (exact > starts with > contains) + const getMatchQuality = (content: string, searchTerm: string): number => { + const lower = content.toLowerCase(); + const term = searchTerm.toLowerCase(); + + if (lower === term) return 1000; // Exact match + if (lower.startsWith(term + " ")) return 500; // Starts with term + space + if (lower.startsWith(term)) return 400; // Starts with term + if (new RegExp(`\\b${term}\\b`, "i").test(content)) return 300; // Whole word + if (lower.includes(term)) return 100; // Contains + return 0; + }; + + // Collect all groups with scoring + const groupsWithScores: Array<{ + pageId: string; + pageScore: number; + matchQuality: number; + phraseBoost: number; + totalScore: number; + page: any; + hits: any[]; + }> = []; + + for (const item of result.groups ?? []) { + const pageId = item.values[0] as string; + const page = getByID(db, pageId); + if (!page) continue; + + // Find the page hit to get its Orama score + const pageHit = item.result.find( + (hit: any) => hit.document.type === "page" + ); + const pageScore = pageHit?.score || 0; + + // Check for phrase matches in ALL hits (page title + all content sections) + // Use the BEST phrase match from any hit to boost the entire group + let bestPhraseBoost = 0; + let bestMatchQuality = 0; + + for (const hit of item.result) { + const hitPhraseBoost = getPhraseMatchBoost(hit.document.content, query); + const hitMatchQuality = getMatchQuality(hit.document.content, query); + + if (hitPhraseBoost > bestPhraseBoost) { + bestPhraseBoost = hitPhraseBoost; + } + if (hitMatchQuality > bestMatchQuality) { + bestMatchQuality = hitMatchQuality; + } + } + + const totalScore = bestMatchQuality + bestPhraseBoost; + + groupsWithScores.push({ + pageId, + pageScore, + matchQuality: bestMatchQuality, + phraseBoost: bestPhraseBoost, + totalScore, + page, + hits: item.result + }); + } + + // Sort groups: phrase matches + exact matches first, then by Orama score + groupsWithScores.sort((a, b) => { + // Prioritize results with phrase matches and exact matches + if (a.totalScore !== b.totalScore) { + return b.totalScore - a.totalScore; + } + // Then by Orama relevance + return b.pageScore - a.pageScore; + }); + + const list: SortedResult[] = []; + + // Build final list from sorted groups + for (const { pageId, page, hits } of groupsWithScores) { + // Add page title + list.push({ + id: pageId, + type: "page", + content: page.content, + breadcrumbs: page.breadcrumbs, + contentWithHighlights: highlighter.highlight(page.content), + url: page.url + }); + + // Sort hits within this group: by phrase match + match quality, then type, then Orama score + const sortedHits = [...hits] + .filter((hit: any) => hit.document.type !== "page") + .map((hit: any) => { + const typeScore = hit.document.type === "heading" ? 2 : 1; + const matchQuality = getMatchQuality(hit.document.content, query); + const phraseBoost = getPhraseMatchBoost(hit.document.content, query); + const totalScore = matchQuality + phraseBoost; + + return { + hit, + typeScore, + matchQuality, + phraseBoost, + totalScore + }; + }) + .sort((a, b) => { + // First prioritize phrase matches and exact matches (combined score) + if (a.totalScore !== b.totalScore) return b.totalScore - a.totalScore; + // Then by type (heading > text) + if (a.typeScore !== b.typeScore) return b.typeScore - a.typeScore; + // Then by Orama relevance + return b.hit.score - a.hit.score; + }) + .map((item) => item.hit); + + // Add sorted hits + for (const hit of sortedHits) { + list.push({ + id: hit.document.id.toString(), + content: hit.document.content, + breadcrumbs: hit.document.breadcrumbs, + contentWithHighlights: highlighter.highlight(hit.document.content), + type: hit.document.type as SortedResult["type"], + url: hit.document.url + }); + } + } + + return list; +} diff --git a/zookeeper-website/app/components/docs/search/use-docs-search.ts b/zookeeper-website/app/components/docs/search/use-docs-search.ts new file mode 100644 index 00000000000..bc3314de11d --- /dev/null +++ b/zookeeper-website/app/components/docs/search/use-docs-search.ts @@ -0,0 +1,138 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { type DependencyList, useRef, useState } from "react"; +import { type StaticOptions } from "fumadocs-core/search/client"; +import type { SortedResult } from "fumadocs-core/search"; +import { useDebounce, useOnChange } from "./utils"; + +interface UseDocsSearch { + search: string; + setSearch: (v: string) => void; + query: { + isLoading: boolean; + data?: SortedResult[] | "empty"; + error?: Error; + }; +} + +export type Client = { + type: "static"; +} & StaticOptions; + +function isDeepEqual(a: unknown, b: unknown): boolean { + if (a === b) return true; + + if (Array.isArray(a) && Array.isArray(b)) { + return b.length === a.length && a.every((v, i) => isDeepEqual(v, b[i])); + } + + if (typeof a === "object" && a && typeof b === "object" && b) { + const aKeys = Object.keys(a); + const bKeys = Object.keys(b); + + return ( + aKeys.length === bKeys.length && + aKeys.every( + (key) => + Object.hasOwn(b, key) && + isDeepEqual(a[key as keyof object], b[key as keyof object]) + ) + ); + } + + return false; +} + +/** + * Provide a hook to query different official search clients. + * + * Note: it will re-query when its parameters changed, make sure to use `useMemo()` on `clientOptions` or define `deps` array. + */ +export function useDocsSearch( + clientOptions: Client & { + /** + * The debounced delay for performing a search (in ms). + * . + * @defaultValue 100 + */ + delayMs?: number; + + /** + * still perform search even if query is empty. + * + * @defaultValue false + */ + allowEmpty?: boolean; + }, + deps?: DependencyList +): UseDocsSearch { + const { delayMs = 100, allowEmpty = false, ...client } = clientOptions; + + const [search, setSearch] = useState(""); + const [results, setResults] = useState("empty"); + const [error, setError] = useState(); + const [isLoading, setIsLoading] = useState(false); + const debouncedValue = useDebounce(search, delayMs); + const onStart = useRef<() => void>(undefined); + + useOnChange( + [deps ?? clientOptions, debouncedValue], + () => { + if (onStart.current) { + onStart.current(); + onStart.current = undefined; + } + + setIsLoading(true); + let interrupt = false; + onStart.current = () => { + interrupt = true; + }; + + async function run(): Promise { + if (debouncedValue.length === 0 && !allowEmpty) return "empty"; + switch (client.type) { + case "static": { + const { search } = await import("./static"); + return search(debouncedValue, client); + } + default: + throw new Error("unknown search client"); + } + } + + void run() + .then((res) => { + if (interrupt) return; + + setError(undefined); + setResults(res); + }) + .catch((err: Error) => { + setError(err); + }) + .finally(() => { + setIsLoading(false); + }); + }, + deps ? undefined : (a, b) => !isDeepEqual(a, b) + ); + + return { search, setSearch, query: { isLoading, data: results, error } }; +} diff --git a/zookeeper-website/app/components/docs/search/utils.ts b/zookeeper-website/app/components/docs/search/utils.ts new file mode 100644 index 00000000000..04b58029c6e --- /dev/null +++ b/zookeeper-website/app/components/docs/search/utils.ts @@ -0,0 +1,83 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { useEffect, useState } from "react"; + +export function removeUndefined(value: T, deep = false): T { + const obj = value as Record; + + for (const key in obj) { + if (obj[key] === undefined) delete obj[key]; + if (!deep) continue; + + const entry = obj[key]; + + if (typeof entry === "object" && entry !== null) { + removeUndefined(entry, deep); + continue; + } + + if (Array.isArray(entry)) { + for (const item of entry) removeUndefined(item, deep); + } + } + + return value; +} + +/** + * @param value - state to watch + * @param onChange - when the state changed + * @param isUpdated - a function that determines if the state is updated + */ +export function useOnChange( + value: T, + onChange: (current: T, previous: T) => void, + isUpdated: (prev: T, current: T) => boolean = isDifferent +): void { + const [prev, setPrev] = useState(value); + + if (isUpdated(prev, value)) { + onChange(value, prev); + setPrev(value); + } +} + +function isDifferent(a: unknown, b: unknown): boolean { + if (Array.isArray(a) && Array.isArray(b)) { + return b.length !== a.length || a.some((v, i) => isDifferent(v, b[i])); + } + + return a !== b; +} + +export function useDebounce(value: T, delayMs = 1000): T { + const [debouncedValue, setDebouncedValue] = useState(value); + + useEffect(() => { + if (delayMs === 0) return; + const handler = window.setTimeout(() => { + setDebouncedValue(value); + }, delayMs); + + return () => clearTimeout(handler); + }, [delayMs, value]); + + if (delayMs === 0) return value; + return debouncedValue; +} diff --git a/zookeeper-website/app/components/docs/toc/clerk.tsx b/zookeeper-website/app/components/docs/toc/clerk.tsx new file mode 100644 index 00000000000..61d69180041 --- /dev/null +++ b/zookeeper-website/app/components/docs/toc/clerk.tsx @@ -0,0 +1,189 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import * as Primitive from "fumadocs-core/toc"; +import { type ComponentProps, useEffect, useRef, useState } from "react"; +import { TocThumb, useTOCItems } from "./index"; +import { useI18n } from "fumadocs-ui/contexts/i18n"; +import { cn, mergeRefs } from "@/lib/utils"; + +export function TOCItems({ ref, className, ...props }: ComponentProps<"div">) { + const containerRef = useRef(null); + const items = useTOCItems(); + const { text } = useI18n(); + + const [svg, setSvg] = useState<{ + path: string; + width: number; + height: number; + }>(); + + useEffect(() => { + if (!containerRef.current) return; + const container = containerRef.current; + + function onResize(): void { + if (container.clientHeight === 0) return; + let w = 0, + h = 0; + const d: string[] = []; + for (let i = 0; i < items.length; i++) { + const element: HTMLElement | null = container.querySelector( + `a[href="#${items[i].url.slice(1)}"]` + ); + if (!element) continue; + + const styles = getComputedStyle(element); + const offset = getLineOffset(items[i].depth) + 1, + top = element.offsetTop + parseFloat(styles.paddingTop), + bottom = + element.offsetTop + + element.clientHeight - + parseFloat(styles.paddingBottom); + + w = Math.max(offset, w); + h = Math.max(h, bottom); + + d.push(`${i === 0 ? "M" : "L"}${offset} ${top}`); + d.push(`L${offset} ${bottom}`); + } + + setSvg({ + path: d.join(" "), + width: w + 1, + height: h + }); + } + + const observer = new ResizeObserver(onResize); + onResize(); + + observer.observe(container); + return () => { + observer.disconnect(); + }; + }, [items]); + + if (items.length === 0) + return ( +
+ {text.tocNoHeadings} +
+ ); + + return ( + <> + {svg && ( +
` + ) + }")` + }} + > + +
+ )} +
+ {items.map((item, i) => ( + + ))} +
+ + ); +} + +function getItemOffset(depth: number): number { + if (depth <= 2) return 14; + if (depth === 3) return 26; + return 36; +} + +function getLineOffset(depth: number): number { + return depth >= 3 ? 10 : 0; +} + +function TOCItem({ + item, + upper = item.depth, + lower = item.depth +}: { + item: Primitive.TOCItemType; + upper?: number; + lower?: number; +}) { + const offset = getLineOffset(item.depth), + upperOffset = getLineOffset(upper), + lowerOffset = getLineOffset(lower); + + return ( + + {offset !== upperOffset && ( + + + + )} +
+ {item.title} + + ); +} diff --git a/zookeeper-website/app/components/docs/toc/default.tsx b/zookeeper-website/app/components/docs/toc/default.tsx new file mode 100644 index 00000000000..2af90220ffe --- /dev/null +++ b/zookeeper-website/app/components/docs/toc/default.tsx @@ -0,0 +1,73 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { useI18n } from "fumadocs-ui/contexts/i18n"; +import { type ComponentProps, useRef } from "react"; +import { TocThumb, useTOCItems } from "./index"; +import * as Primitive from "fumadocs-core/toc"; +import { cn, mergeRefs } from "@/lib/utils"; + +export function TOCItems({ ref, className, ...props }: ComponentProps<"div">) { + const containerRef = useRef(null); + const items = useTOCItems(); + const { text } = useI18n(); + + if (items.length === 0) + return ( +
+ {text.tocNoHeadings} +
+ ); + + return ( + <> + +
+ {items.map((item) => ( + + ))} +
+ + ); +} + +function TOCItem({ item }: { item: Primitive.TOCItemType }) { + return ( + = 4 && "ps-8" + )} + > + {item.title} + + ); +} diff --git a/zookeeper-website/app/components/docs/toc/index.tsx b/zookeeper-website/app/components/docs/toc/index.tsx new file mode 100644 index 00000000000..746c9a5e844 --- /dev/null +++ b/zookeeper-website/app/components/docs/toc/index.tsx @@ -0,0 +1,144 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import * as Primitive from "fumadocs-core/toc"; +import { + type ComponentProps, + createContext, + type RefObject, + use, + useEffect, + useEffectEvent, + useRef +} from "react"; +import { useOnChange } from "fumadocs-core/utils/use-on-change"; +import { cn, mergeRefs } from "@/lib/utils"; + +const TOCContext = createContext([]); + +export function useTOCItems(): Primitive.TOCItemType[] { + return use(TOCContext); +} + +export function TOCProvider({ + toc, + children, + ...props +}: ComponentProps) { + return ( + + + {children} + + + ); +} + +export function TOCScrollArea({ + ref, + className, + ...props +}: ComponentProps<"div">) { + const viewRef = useRef(null); + + return ( +
+ + {props.children} + +
+ ); +} + +type TocThumbType = [top: number, height: number]; + +interface RefProps { + containerRef: RefObject; +} + +export function TocThumb({ + containerRef, + ...props +}: ComponentProps<"div"> & RefProps) { + const thumbRef = useRef(null); + const active = Primitive.useActiveAnchors(); + function update(info: TocThumbType): void { + const element = thumbRef.current; + if (!element) return; + element.style.setProperty("--fd-top", `${info[0]}px`); + element.style.setProperty("--fd-height", `${info[1]}px`); + } + + const onPrint = useEffectEvent(() => { + if (containerRef.current) { + update(calc(containerRef.current, active)); + } + }); + + useEffect(() => { + if (!containerRef.current) return; + const container = containerRef.current; + + const observer = new ResizeObserver(onPrint); + observer.observe(container); + + return () => { + observer.disconnect(); + }; + }, [containerRef, onPrint]); + + useOnChange(active, () => { + if (containerRef.current) { + update(calc(containerRef.current, active)); + } + }); + + return
; +} + +function calc(container: HTMLElement, active: string[]): TocThumbType { + if (active.length === 0 || container.clientHeight === 0) { + return [0, 0]; + } + + let upper = Number.MAX_VALUE, + lower = 0; + + for (const item of active) { + const element = container.querySelector(`a[href="#${item}"]`); + if (!element) continue; + + const styles = getComputedStyle(element); + upper = Math.min(upper, element.offsetTop + parseFloat(styles.paddingTop)); + lower = Math.max( + lower, + element.offsetTop + + element.clientHeight - + parseFloat(styles.paddingBottom) + ); + } + + return [upper, lower - upper]; +} diff --git a/zookeeper-website/app/components/getting-started.tsx b/zookeeper-website/app/components/getting-started.tsx new file mode 100644 index 00000000000..7c0915435b3 --- /dev/null +++ b/zookeeper-website/app/components/getting-started.tsx @@ -0,0 +1,77 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Link } from "@/components/link"; +import { ArrowRight } from "lucide-react"; + +export function GettingStartedSection() { + const steps = [ + { + title: "1. Download", + desc: "Grab the latest stable release and verify checksums.", + to: "/releases" + }, + { + title: "2. Quick Start", + desc: "Set up a single ZooKeeper server and learn the basics of the CLI.", + to: "/docs/overview/quick-start" + }, + { + title: "3. Write a Client", + desc: "Follow the basic tutorial to implement distributed primitives like barriers and queues.", + to: "/docs/developer/basic-tutorial" + } + ]; + return ( +
+
+
+

+ Getting Started +

+

+ Up and running with ZooKeeper in a few simple steps. +

+
+
+ {steps.map((s) => ( + +

+ {s.title} +

+

+ {s.desc} +

+
+ Learn more{" "} + +
+ + ))} +
+
+
+ ); +} diff --git a/zookeeper-website/app/components/link.tsx b/zookeeper-website/app/components/link.tsx new file mode 100644 index 00000000000..a89c955f1a4 --- /dev/null +++ b/zookeeper-website/app/components/link.tsx @@ -0,0 +1,30 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { ComponentPropsWithoutRef } from "react"; +import { Link as ReactRouterLink } from "react-router"; + +export const Link = ( + props: ComponentPropsWithoutRef +) => { + const BASE_URL = "https://zookeeper.apache.org"; + const href = typeof props.to === "string" ? props.to : props.to.pathname; + const reloadDocument = href?.startsWith(BASE_URL); + + return ; +}; diff --git a/zookeeper-website/app/components/links.ts b/zookeeper-website/app/components/links.ts new file mode 100644 index 00000000000..ec7508113a4 --- /dev/null +++ b/zookeeper-website/app/components/links.ts @@ -0,0 +1,128 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { CURRENT_VERSION } from "@/lib/current-version"; + +interface LinkType { + label: string; + to: string; + external?: boolean; +} + +interface NestedLinkType { + label: string; + links: LinkType[]; +} + +export const projectLinks: LinkType[] = [ + { + label: "Overview", + to: "/" + }, + { + label: "Releases", + to: "/releases" + }, + { + label: "Events", + to: "/events" + }, + { + label: "News", + to: "/news" + }, + { + label: "Mailing Lists", + to: "/mailing-lists" + }, + { + label: "Credits", + to: "/credits" + }, + { + label: "Bylaws", + to: "/bylaws" + } +]; + +export const documentationLinks: (LinkType | NestedLinkType)[] = [ + { + label: `${CURRENT_VERSION} Documentation`, + to: "/docs" + }, + { + label: "Issue Tracking", + to: "https://issues.apache.org/jira/browse/ZOOKEEPER", + external: true + }, + { + label: "Security", + to: "/security" + }, + { + label: "Version Control", + to: "/version-control" + }, + { + label: "Resources", + links: [ + { + label: "Wiki", + to: "https://cwiki.apache.org/confluence/display/ZOOKEEPER", + external: true + }, + { + label: "IRC Channel", + to: "/irc" + } + ] + } +]; + +export const asfLinks: LinkType[] = [ + { + label: "Apache Software Foundation", + to: "http://www.apache.org/foundation/", + external: true + }, + { + label: "License", + to: "https://www.apache.org/licenses/", + external: true + }, + { + label: "How Apache Works", + to: "http://www.apache.org/foundation/how-it-works.html", + external: true + }, + { + label: "Foundation Program", + to: "http://www.apache.org/foundation/sponsorship.html", + external: true + }, + { + label: "Sponsors", + to: "https://www.apache.org/foundation/sponsors", + external: true + }, + { + label: "Privacy Policy", + to: "https://privacy.apache.org/policies/privacy-policy-public.html", + external: true + } +]; diff --git a/zookeeper-website/app/components/mdx-components.tsx b/zookeeper-website/app/components/mdx-components.tsx new file mode 100644 index 00000000000..a014bdc0502 --- /dev/null +++ b/zookeeper-website/app/components/mdx-components.tsx @@ -0,0 +1,152 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { MDXComponents } from "mdx/types"; +import { ExternalLinkIcon } from "lucide-react"; +import defaultMdxComponents from "fumadocs-ui/mdx"; +import { cn } from "@/lib/utils"; +import { Link } from "./link"; + +export function getMDXComponents(overrides?: MDXComponents): MDXComponents { + return { + ...defaultMdxComponents, + h1: (props) => ( +

+ ), + h2: (props) => ( +

+ ), + h3: (props) => ( +

+ ), + p: (props) => ( +

+ ), + ol: (props) => ( +

    + ), + ul: (props) =>
      , + li: (props) =>
    • , + + a: ({ href, children, ...rest }) => { + const isExternal = + href?.startsWith("http") && + !href?.startsWith("https://zookeeper.apache.org/"); + if (isExternal) { + const onlyImg = Array.isArray(children) + ? children.every( + (c: any) => c?.type === "img" || typeof c === "object" + ) + : typeof children === "object"; + return ( + + {children} + {!onlyImg && ( + <> + {"\u00A0"} + + + )} + + ); + } + return ( + + {children} + + ); + }, + blockquote: (props) => ( +
      + ), + img: ({ src = "", alt = "", ...rest }) => ( + {alt} + ), + table: (props) => ( +
      + + + ), + thead: (props) => , + tr: (props) => ( + + ), + th: (props) => ( +
      + ), + td: (props) => ( + + ), + + ...overrides + }; +} + +interface MdLayoutProps { + className?: string; + overrides?: MDXComponents; + Content: any; +} + +export function MdLayout({ className, overrides, Content }: MdLayoutProps) { + return ( +
      +
      + +
      +
      + ); +} diff --git a/zookeeper-website/app/components/site-footer.tsx b/zookeeper-website/app/components/site-footer.tsx new file mode 100644 index 00000000000..37513719137 --- /dev/null +++ b/zookeeper-website/app/components/site-footer.tsx @@ -0,0 +1,123 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Link } from "@/components/link"; +import { projectLinks, documentationLinks, asfLinks } from "./links"; +import { ExternalLink } from "lucide-react"; + +export function SiteFooter() { + return ( +
      +
      +
      +
      +

      Apache ZooKeeper

      +

      + Open-source coordination service for distributed applications — + naming, synchronization, and group services made simple. +

      +
      +
      +

      Project

      +
        + {projectLinks.map((link) => ( +
      • + + {link.label} + {link.external && ( + + )} + +
        • + ))} +
      +
      +
      +

      Documentation

      +
        + {documentationLinks.map((link) => + "to" in link ? ( +
      • + + {link.label} + {link.external && ( + + )} + +
        • + ) : ( + link.links.map((link) => ( +
      • + + {link.label} + {link.external && ( + + )} + +
        • + )) + ) + )} +
      +
      +
      +

      ASF

      +
        + {asfLinks.map((link) => ( +
      • + + {link.label} + {link.external && ( + + )} + +
        • + ))} +
      +
      +
      + +
      + +

      + Copyright ©2007-2026 The Apache Software Foundation. All rights + reserved. Apache ZooKeeper, ZooKeeper, Apache, the Apache ZooKeeper + logo and the ASF logo are either registered trademarks or trademarks + of the Apache Software Foundation. All other marks mentioned may be + trademarks or registered trademarks of their respective owners. +

      +
      +
      + ); +} diff --git a/zookeeper-website/app/components/site-navbar.tsx b/zookeeper-website/app/components/site-navbar.tsx new file mode 100644 index 00000000000..f04fd2e28fd --- /dev/null +++ b/zookeeper-website/app/components/site-navbar.tsx @@ -0,0 +1,655 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { cn } from "@/lib/utils"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuSeparator, + DropdownMenuSub, + DropdownMenuSubContent, + DropdownMenuSubTrigger, + DropdownMenuTrigger +} from "@/ui/dropdown-menu"; +import { + Collapsible, + CollapsibleContent, + CollapsibleTrigger +} from "@/ui/collapsible"; +import { ChevronDown, ChevronRight, ExternalLink } from "lucide-react"; +import { useEffect, useState } from "react"; +import { createPortal } from "react-dom"; +import { Link } from "@/components/link"; +import { asfLinks, documentationLinks, projectLinks } from "./links"; +import { OlderDocsVersionList } from "@/components/docs/older-docs-picker"; +import { ThemeToggle } from "./theme-toggle"; + +const navLinkClass = + "text-sm font-medium text-foreground/70 hover:text-foreground transition-colors"; + +export function SiteNavbar() { + const [isScrolled, setIsScrolled] = useState(false); + + useEffect(() => { + if (typeof window === "undefined") { + return; + } + + document.documentElement.classList.add("js"); + + setIsScrolled(window.scrollY > 0); + const handleScroll = () => { + setIsScrolled(window.scrollY > 0); + }; + + document.addEventListener("scroll", handleScroll); + + return () => { + document.removeEventListener("scroll", handleScroll); + }; + }, []); + + return ( +
      + +
      + ); +} + +function ProjectMenu() { + return ( + + + + + + {projectLinks.map((item) => ( + + + {item.label} + {item.external && } + + + ))} + + + ); +} + +function OlderDocsSubMenu() { + return ( + + Older docs + + + + + ); +} + +function DocsMenu() { + return ( + + + + + + {documentationLinks.map((item) => + "to" in item ? ( + + + {item.label} + {item.external && } + + + ) : ( + + {item.label} + + {item.links.map((item) => ( + + + {item.label} + {item.external && } + + + ))} + + + ) + )} + + + + + ); +} + +function AsfMenu() { + return ( + + + + + + {asfLinks.map((item) => ( + + + {item.label} + {item.external && } + + + ))} + + + ); +} + +function MobileMenu() { + const [isOpen, setIsOpen] = useState(false); + const [isMounted, setIsMounted] = useState(false); + + useEffect(() => { + setIsMounted(true); + }, []); + + useEffect(() => { + if (isOpen) { + document.body.style.overflow = "hidden"; + } else { + document.body.style.overflow = "unset"; + } + return () => { + document.body.style.overflow = "unset"; + }; + }, [isOpen]); + + useEffect(() => { + const handleEscape = (e: KeyboardEvent) => { + if (e.key === "Escape" && isOpen) { + setIsOpen(false); + } + }; + + document.addEventListener("keydown", handleEscape); + return () => document.removeEventListener("keydown", handleEscape); + }, [isOpen]); + + useEffect(() => { + const mediaQuery = window.matchMedia("(min-width: 768px)"); + const handleMediaChange = (e: MediaQueryListEvent | MediaQueryList) => { + if (e.matches && isOpen) { + setIsOpen(false); + } + }; + + handleMediaChange(mediaQuery); + mediaQuery.addEventListener("change", handleMediaChange); + return () => mediaQuery.removeEventListener("change", handleMediaChange); + }, [isOpen]); + + return ( + <> + + + {/* Fullscreen overlay - rendered in portal */} + {isMounted && + createPortal( +
      +
      + +
      +
      , + document.body + )} + + ); +} + +function MobileOlderDocsSection() { + return ( + + + Older docs + + + + + + + ); +} + +function MobileDocsSection({ onLinkClick }: { onLinkClick: () => void }) { + return ( + + + Documentation + + + + {documentationLinks.map((link) => + "to" in link ? ( + + {link.label} + {link.external && } + + ) : ( + + + {link.label} + + + + {link.links.map((item) => ( + + {item.label} + + ))} + + + ) + )} + + + + ); +} + +function MobileMenuSection({ + title, + links, + onLinkClick +}: { + title: string; + links: typeof projectLinks; + onLinkClick: () => void; +}) { + const [isOpen, setIsOpen] = useState(false); + + return ( + + + {title} + + + + {links.map((link) => ( + + {link.label} + {link.external && } + + ))} + + + ); +} + +/* No-JS fallback components using details/summary */ + +function NoJSProjectMenu() { + return ( +
      + + Apache ZooKeeper Project + +
      + {projectLinks.map((item) => ( + + {item.label} + {item.external && } + + ))} +
      +
      + ); +} + +function NoJSDocsMenu() { + return ( +
      + + Documentation + +
      + {documentationLinks.map((item) => + "to" in item ? ( + + {item.label} + {item.external && } + + ) : ( +
      + + {item.label} + + +
      + {item.links.map((subItem) => ( + + {subItem.label} + {subItem.external && } + + ))} +
      +
      + ) + )} +
      +
      + ); +} + +function NoJSAsfMenu() { + return ( +
      + + ASF + +
      + {asfLinks.map((item) => ( + + {item.label} + {item.external && } + + ))} +
      +
      + ); +} + +function NoJSMobileMenu() { + return ( +
      + +
      + + + +
      +       +
      + +
      +
      + ); +} + +function NoJSMobileMenuSection({ + title, + links +}: { + title: string; + links: typeof projectLinks; +}) { + return ( +
      + + {title} + + +
      + {links.map((link) => ( + + {link.label} + {link.external && } + + ))} +
      +
      + ); +} + +function NoJSMobileDocsSection() { + return ( +
      + + Documentation + + +
      + {documentationLinks.map((link) => + "to" in link ? ( + + {link.label} + {link.external && } + + ) : ( +
      + + {link.label} + + +
      + {link.links.map((item) => ( + + {item.label} + + ))} +
      +
      + ) + )} +
      +
      + ); +} diff --git a/zookeeper-website/app/components/theme-toggle.tsx b/zookeeper-website/app/components/theme-toggle.tsx new file mode 100644 index 00000000000..0c252f2de36 --- /dev/null +++ b/zookeeper-website/app/components/theme-toggle.tsx @@ -0,0 +1,37 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Moon, Sun } from "lucide-react"; +import { Button } from "@/ui/button"; +import { useTheme } from "@/lib/theme-provider"; + +export function ThemeToggle() { + const { theme, setTheme } = useTheme(); + + const toggleTheme = () => { + setTheme(theme === "light" ? "dark" : "light"); + }; + + return ( + + ); +} diff --git a/zookeeper-website/app/lib/current-version.ts b/zookeeper-website/app/lib/current-version.ts new file mode 100644 index 00000000000..d02009316e6 --- /dev/null +++ b/zookeeper-website/app/lib/current-version.ts @@ -0,0 +1,19 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +export const CURRENT_VERSION = "3.9.5"; diff --git a/zookeeper-website/app/lib/released-docs-versions.ts b/zookeeper-website/app/lib/released-docs-versions.ts new file mode 100644 index 00000000000..e252bd197ea --- /dev/null +++ b/zookeeper-website/app/lib/released-docs-versions.ts @@ -0,0 +1,69 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +type PreRelease = "alpha" | "beta" | "stable"; + +interface ParsedVersion { + major: number; + minor: number; + patch: number; + preRelease: PreRelease; + raw: string; +} + +function parseVersion(version: string): ParsedVersion { + const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-(alpha|beta))?/); + if (!match) { + return { major: 0, minor: 0, patch: 0, preRelease: "stable", raw: version }; + } + const preRelease = (match[4] as PreRelease | undefined) ?? "stable"; + return { + major: parseInt(match[1], 10), + minor: parseInt(match[2], 10), + patch: parseInt(match[3], 10), + preRelease, + raw: version + }; +} + +const preReleaseOrder: Record = { + stable: 2, + beta: 1, + alpha: 0 +}; + +export function sortVersionsDesc(versions: string[]): string[] { + return [...versions].sort((a, b) => { + const pa = parseVersion(a); + const pb = parseVersion(b); + if (pb.major !== pa.major) return pb.major - pa.major; + if (pb.minor !== pa.minor) return pb.minor - pa.minor; + if (pb.patch !== pa.patch) return pb.patch - pa.patch; + return preReleaseOrder[pb.preRelease] - preReleaseOrder[pa.preRelease]; + }); +} + +import { RAW_RELEASED_DOC_VERSIONS } from "virtual:released-docs-versions"; + +/** + * All released documentation versions available under /released-docs/. + * Derived from the actual folder names at build time, sorted newest to oldest. + */ +export const RELEASED_DOC_VERSIONS: string[] = sortVersionsDesc( + RAW_RELEASED_DOC_VERSIONS +); diff --git a/zookeeper-website/app/lib/source.ts b/zookeeper-website/app/lib/source.ts new file mode 100644 index 00000000000..54746a49634 --- /dev/null +++ b/zookeeper-website/app/lib/source.ts @@ -0,0 +1,25 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { loader } from "fumadocs-core/source"; +import { create, docs } from "@/.source"; + +export const source = loader({ + source: await create.sourceAsync(docs.doc, docs.meta), + baseUrl: "/docs" +}); diff --git a/zookeeper-website/app/lib/theme-provider.tsx b/zookeeper-website/app/lib/theme-provider.tsx new file mode 100644 index 00000000000..4a4e896d75c --- /dev/null +++ b/zookeeper-website/app/lib/theme-provider.tsx @@ -0,0 +1,94 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { createContext, useContext, useEffect, useState } from "react"; + +type Theme = "dark" | "light"; + +type ThemeProviderProps = { + children: React.ReactNode; + defaultTheme?: Theme; + storageKey?: string; +}; + +type ThemeProviderState = { + theme: Theme; + setTheme: (theme: Theme) => void; +}; + +const ThemeProviderContext = createContext( + undefined +); + +function getSystemTheme(): Theme { + if (typeof window === "undefined") return "light"; + return window.matchMedia("(prefers-color-scheme: dark)").matches + ? "dark" + : "light"; +} + +export function ThemeProvider({ + children, + defaultTheme = "light", + storageKey = "theme" +}: ThemeProviderProps) { + const [theme, setTheme] = useState(defaultTheme); + + useEffect(() => { + const storedTheme = localStorage.getItem(storageKey) as Theme; + if (storedTheme && ["light", "dark"].includes(storedTheme)) { + setTheme(storedTheme); + } else { + // No stored theme, detect system preference + const systemTheme = getSystemTheme(); + setTheme(systemTheme); + localStorage.setItem(storageKey, systemTheme); + } + }, [storageKey]); + + useEffect(() => { + const root = document.documentElement; + root.classList.remove("light", "dark"); + root.classList.add(theme); + }, [theme]); + + const value = { + theme, + setTheme: (theme: Theme) => { + if (typeof window !== "undefined") { + localStorage.setItem(storageKey, theme); + } + setTheme(theme); + } + }; + + return ( + + {children} + + ); +} + +export const useTheme = () => { + const context = useContext(ThemeProviderContext); + + if (context === undefined) + throw new Error("useTheme must be used within a ThemeProvider"); + + return context; +}; diff --git a/zookeeper-website/app/lib/urls.ts b/zookeeper-website/app/lib/urls.ts new file mode 100644 index 00000000000..5e0b6d55f49 --- /dev/null +++ b/zookeeper-website/app/lib/urls.ts @@ -0,0 +1,37 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +export function normalize(urlOrPath: string) { + if (urlOrPath.length > 1 && urlOrPath.endsWith("/")) + return urlOrPath.slice(0, -1); + return urlOrPath; +} + +/** + * @returns if `href` is matching the given pathname + */ +export function isActive( + href: string, + pathname: string, + nested = true +): boolean { + href = normalize(href); + pathname = normalize(pathname); + + return href === pathname || (nested && pathname.startsWith(`${href}/`)); +} diff --git a/zookeeper-website/app/lib/utils.ts b/zookeeper-website/app/lib/utils.ts new file mode 100644 index 00000000000..9e2355bd41d --- /dev/null +++ b/zookeeper-website/app/lib/utils.ts @@ -0,0 +1,39 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { clsx, type ClassValue } from "clsx"; +import { twMerge } from "tailwind-merge"; +import type * as React from "react"; + +export function cn(...inputs: ClassValue[]) { + return twMerge(clsx(inputs)); +} + +export function mergeRefs( + ...refs: (React.Ref | undefined)[] +): React.RefCallback { + return (value) => { + refs.forEach((ref) => { + if (typeof ref === "function") { + ref(value); + } else if (ref) { + ref.current = value; + } + }); + }; +} diff --git a/zookeeper-website/app/pages/_docs/docs-layout.tsx b/zookeeper-website/app/pages/_docs/docs-layout.tsx new file mode 100644 index 00000000000..cadfd4b4a1e --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs-layout.tsx @@ -0,0 +1,33 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { RootProvider } from "fumadocs-ui/provider/react-router"; +import { Outlet } from "react-router"; +import { SearchDialog } from "@/components/docs/search/docs-search"; + +export default function DocsLayout() { + return ( + + + + ); +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/administration.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/administration.mdx new file mode 100644 index 00000000000..2bdc3ec8344 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/administration.mdx @@ -0,0 +1,170 @@ +--- +title: "Administration" +description: "Operational guidance for running a ZooKeeper cluster, including provisioning, maintenance tasks, data directory cleanup, supervision, monitoring, logging, and troubleshooting." +--- + +## Maintenance + +Little long term maintenance is required for a ZooKeeper +cluster however you must be aware of the following: + +### Ongoing Data Directory Cleanup + +The ZooKeeper [Data +Directory](/docs/admin-ops/administrators-guide/data-file-management#the-data-directory) contains files which are a persistent copy +of the znodes stored by a particular serving ensemble. These +are the snapshot and transactional log files. As changes are +made to the znodes these changes are appended to a +transaction log. Occasionally, when a log grows large, a +snapshot of the current state of all znodes will be written +to the filesystem and a new transaction log file is created +for future transactions. During snapshotting, ZooKeeper may +continue appending incoming transactions to the old log file. +Therefore, some transactions which are newer than a snapshot +may be found in the last transaction log preceding the +snapshot. + +A ZooKeeper server **will not remove +old snapshots and log files** when using the default +configuration (see autopurge below), this is the +responsibility of the operator. Every serving environment is +different and therefore the requirements of managing these +files may differ from install to install (backup for example). + +The PurgeTxnLog utility implements a simple retention +policy that administrators can use. The [API docs](/docs) contains details on +calling conventions (arguments, etc...). + +In the following example the last count snapshots and +their corresponding logs are retained and the others are +deleted. The value of \ should typically be +greater than 3 (although not required, this provides 3 backups +in the unlikely event a recent log has become corrupted). This +can be run as a cron job on the ZooKeeper server machines to +clean up the logs daily. + +```bash +$ java -cp zookeeper.jar:lib/slf4j-api-1.7.30.jar:lib/logback-classic-1.2.10.jar:lib/logback-core-1.2.10.jar:conf org.apache.zookeeper.server.PurgeTxnLog -n +``` + +Automatic purging of the snapshots and corresponding +transaction logs was introduced in version 3.4.0 and can be +enabled via the following configuration parameters **autopurge.snapRetainCount** and **autopurge.purgeInterval**. For more on +this, see [Advanced Configuration](/docs/admin-ops/administrators-guide/configuration-parameters#advanced-configuration). + +### Debug Log Cleanup (logback) + +See the section on [logging](#logging) in this document. It is +expected that you will setup a rolling file appender using the +in-built logback feature. The sample configuration file in the +release tar's `conf/logback.xml` provides an example of +this. + +## Supervision + +You will want to have a supervisory process that manages +each of your ZooKeeper server processes (JVM). The ZK server is +designed to be "fail fast" meaning that it will shut down +(process exit) if an error occurs that it cannot recover +from. As a ZooKeeper serving cluster is highly reliable, this +means that while the server may go down the cluster as a whole +is still active and serving requests. Additionally, as the +cluster is "self healing" the failed server once restarted will +automatically rejoin the ensemble w/o any manual +interaction. + +Having a supervisory process such as [daemontools](http://cr.yp.to/daemontools.html) or +[SMF](http://en.wikipedia.org/wiki/Service_Management_Facility) +(other options for supervisory process are also available, it's +up to you which one you would like to use, these are just two +examples) managing your ZooKeeper server ensures that if the +process does exit abnormally it will automatically be restarted +and will quickly rejoin the cluster. + +It is also recommended to configure the ZooKeeper server process to +terminate and dump its heap if an OutOfMemoryError\** occurs. This is achieved +by launching the JVM with the following arguments on Linux and Windows +respectively. The *zkServer.sh* and +*zkServer.cmd\* scripts that ship with ZooKeeper set +these options. + +``` +-XX:+HeapDumpOnOutOfMemoryError -XX:OnOutOfMemoryError='kill -9 %p' + +"-XX:+HeapDumpOnOutOfMemoryError" "-XX:OnOutOfMemoryError=cmd /c taskkill /pid %%%%p /t /f" +``` + +## Monitoring + +The ZooKeeper service can be monitored in one of three primary ways: + +- the command port through the use of [4 letter words](/docs/admin-ops/administrators-guide/commands#the-four-letter-words) +- with [JMX](/docs/admin-ops/jmx) +- using the [`zkServer.sh status` command](/docs/admin-ops/tools#zkserversh) + +## Logging + +ZooKeeper uses **[SLF4J](http://www.slf4j.org)** +version 1.7 as its logging infrastructure. By default ZooKeeper is shipped with +**[LOGBack](http://logback.qos.ch/)** as the logging backend, but you can use +any other supported logging framework of your choice. + +The ZooKeeper default _logback.xml_ +file resides in the _conf_ directory. Logback requires that +_logback.xml_ either be in the working directory +(the directory from which ZooKeeper is run) or be accessible from the classpath. + +For more information about SLF4J, see +[its manual](http://www.slf4j.org/manual.html). + +For more information about Logback, see +[Logback website](http://logback.qos.ch/). + +## Troubleshooting + +- _Server not coming up because of file corruption_ : + A server might not be able to read its database and fail to come up because of + some file corruption in the transaction logs of the ZooKeeper server. You will + see some IOException on loading ZooKeeper database. In such a case, + make sure all the other servers in your ensemble are up and working. Use "stat" + command on the command port to see if they are in good health. After you have verified that + all the other servers of the ensemble are up, you can go ahead and clean the database + of the corrupt server. Delete all the files in datadir/version-2 and datalogdir/version-2/. + Restart the server. + +## Metrics Providers + +**New in 3.6.0:** The following options are used to configure metrics. + +By default ZooKeeper server exposes useful metrics using the [AdminServer](/docs/admin-ops/administrators-guide/commands#the-adminserver) +and [Four Letter Words](/docs/admin-ops/administrators-guide/commands#the-four-letter-words) interface. + +Since 3.6.0 you can configure a different Metrics Provider, that exports metrics +to your favourite system. + +Since 3.6.0 ZooKeeper binary package bundles an integration with [Prometheus.io](https://prometheus.io) + +- _metricsProvider.className_ : + Set to "org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider" to + enable Prometheus.io exporter. +- _metricsProvider.httpHost_ : + **New in 3.8.0:** Prometheus.io exporter will start a Jetty server and listen this address, default is "0.0.0.0" +- _metricsProvider.httpPort_ : + Prometheus.io exporter will start a Jetty server and bind to this port, it defaults to 7000. + Prometheus end point will be http://hostname:httPort/metrics. +- _metricsProvider.exportJvmInfo_ : + If this property is set to **true** Prometheus.io will export useful metrics about the JVM. + The default is true. +- _metricsProvider.numWorkerThreads_ : + **New in 3.7.1:** + Number of worker threads for reporting Prometheus summary metrics. + Default value is 1. + If the number is less than 1, the main thread will be used. +- _metricsProvider.maxQueueSize_ : + **New in 3.7.1:** + The max queue size for Prometheus summary metrics reporting task. + Default value is 10000. +- _metricsProvider.workerShutdownTimeoutMs_ : + **New in 3.7.1:** + The timeout in ms for Prometheus worker threads shutdown. + Default value is 1000ms. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/best-practices.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/best-practices.mdx new file mode 100644 index 00000000000..6228789b881 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/best-practices.mdx @@ -0,0 +1,56 @@ +--- +title: "Best Practices" +description: "Recommended best practices and common pitfalls to avoid when deploying and configuring ZooKeeper, covering server lists, transaction log placement, Java heap sizing, and more." +--- + +## Things to Avoid + +Here are some common problems you can avoid by configuring +ZooKeeper correctly: + +- _inconsistent lists of servers_ : + The list of ZooKeeper servers used by the clients must match + the list of ZooKeeper servers that each ZooKeeper server has. + Things work okay if the client list is a subset of the real list, + but things will really act strange if clients have a list of + ZooKeeper servers that are in different ZooKeeper clusters. Also, + the server lists in each Zookeeper server configuration file + should be consistent with one another. + +- _incorrect placement of transaction log_ : + The most performance critical part of ZooKeeper is the + transaction log. ZooKeeper syncs transactions to media before it + returns a response. A dedicated transaction log device is key to + consistent good performance. Putting the log on a busy device will + adversely affect performance. If you only have one storage device, + increase the snapCount so that snapshot files are generated less often; + it does not eliminate the problem, but it makes more resources available + for the transaction log. + +- _incorrect Java heap size_ : + You should take special care to set your Java max heap size + correctly. In particular, you should not create a situation in + which ZooKeeper swaps to disk. The disk is death to ZooKeeper. + Everything is ordered, so if processing one request swaps the + disk, all other queued requests will probably do the same. DON'T SWAP. + Be conservative in your estimates: if you have 4G of RAM, do + not set the Java max heap size to 6G or even 4G. For example, it + is more likely you would use a 3G heap for a 4G machine, as the + operating system and the cache also need memory. The best and only + recommend practice for estimating the heap size your system needs + is to run load tests, and then make sure you are well below the + usage limit that would cause the system to swap. + +- _Publicly accessible deployment_ : + A ZooKeeper ensemble is expected to operate in a trusted computing environment. + It is thus recommended deploying ZooKeeper behind a firewall. + +## Best Practices + +For best results, take note of the following list of good +Zookeeper practices: + +For multi-tenant installations see the [section](/docs/developer/programmers-guide/sessions) +detailing ZooKeeper "chroot" support, this can be very useful +when deploying many applications/services interfacing to a +single ZooKeeper cluster. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/commands.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/commands.mdx new file mode 100644 index 00000000000..4e5b0d0d4b9 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/commands.mdx @@ -0,0 +1,382 @@ +--- +title: "Commands" +description: "Reference for ZooKeeper's built-in commands: the four-letter words issued via telnet or nc, and the HTTP-based AdminServer interface with its endpoints and SSL/TLS configuration." +--- + +## The Four Letter Words + +ZooKeeper responds to a small set of commands. Each command is +composed of four letters. You issue the commands to ZooKeeper via telnet +or nc, at the client port. + +Three of the more interesting commands: "stat" gives some +general information about the server and connected clients, +while "srvr" and "cons" give extended details on server and +connections respectively. + +**New in 3.5.3:** +Four Letter Words need to be explicitly white listed before using. +Please refer to **4lw.commands.whitelist** +described in [cluster configuration section](/docs/admin-ops/administrators-guide/configuration-parameters#cluster-options) for details. +Moving forward, Four Letter Words will be deprecated, please use +[AdminServer](#the-adminserver) instead. + +- _conf_ : + **New in 3.3.0:** Print + details about serving configuration. + +- _cons_ : + **New in 3.3.0:** List + full connection/session details for all clients connected + to this server. Includes information on numbers of packets + received/sent, session id, operation latencies, last + operation performed, etc... + +- _crst_ : + **New in 3.3.0:** Reset + connection/session statistics for all connections. + +- _dump_ : + Lists the outstanding sessions and ephemeral nodes. + +- _envi_ : + Print details about serving environment + +- _ruok_ : + Tests if the server is running in a non-error state. + When the whitelist enables ruok, the server will respond with `imok` + if it is running, otherwise it will not respond at all. + When ruok is disabled, the server responds with: + "ruok is not executed because it is not in the whitelist." + A response of "imok" does not necessarily indicate that the + server has joined the quorum, just that the server process is active + and bound to the specified client port. Use "stat" for details on + state wrt quorum and client connection information. + +- _srst_ : + Reset server statistics. + +- _srvr_ : + **New in 3.3.0:** Lists + full details for the server. + +- _stat_ : + Lists brief details for the server and connected + clients. + +- _wchs_ : + **New in 3.3.0:** Lists + brief information on watches for the server. + +- _wchc_ : + **New in 3.3.0:** Lists + detailed information on watches for the server, by + session. This outputs a list of sessions(connections) + with associated watches (paths). Note, depending on the + number of watches this operation may be expensive (ie + impact server performance), use it carefully. + +- _dirs_ : + **New in 3.5.1:** + Shows the total size of snapshot and log files in bytes + +- _wchp_ : + **New in 3.3.0:** Lists + detailed information on watches for the server, by path. + This outputs a list of paths (znodes) with associated + sessions. Note, depending on the number of watches this + operation may be expensive (ie impact server performance), + use it carefully. + +- _mntr_ : + **New in 3.4.0:** Outputs a list + of variables that could be used for monitoring the health of the cluster. + + ```bash + $ echo mntr | nc localhost 2185 + zk_version 3.4.0 + zk_avg_latency 0.7561 - be account to four decimal places + zk_max_latency 0 + zk_min_latency 0 + zk_packets_received 70 + zk_packets_sent 69 + zk_outstanding_requests 0 + zk_server_state leader + zk_znode_count 4 + zk_watch_count 0 + zk_ephemerals_count 0 + zk_approximate_data_size 27 + zk_learners 4 - only exposed by the Leader + zk_synced_followers 4 - only exposed by the Leader + zk_pending_syncs 0 - only exposed by the Leader + zk_open_file_descriptor_count 23 - only available on Unix platforms + zk_max_file_descriptor_count 1024 - only available on Unix platforms + ``` + + The output is compatible with java properties format and the content + may change over time (new keys added). Your scripts should expect changes. + ATTENTION: Some of the keys are platform specific and some of the keys are only exported by the Leader. + The output contains multiple lines with the following format: + + ``` + key \t value + ``` + +- _isro_ : + **New in 3.4.0:** Tests if + server is running in read-only mode. The server will respond with + "ro" if in read-only mode or "rw" if not in read-only mode. + +- _hash_ : + **New in 3.6.0:** + Return the latest history of the tree digest associated with zxid. + +- _gtmk_ : + Gets the current trace mask as a 64-bit signed long value in + decimal format. See `stmk` for an explanation of + the possible values. + +- _stmk_ : + Sets the current trace mask. The trace mask is 64 bits, + where each bit enables or disables a specific category of trace + logging on the server. Logback must be configured to enable + `TRACE` level first in order to see trace logging + messages. The bits of the trace mask correspond to the following + trace logging categories. + + | Trace Mask Bit Values | | + | --------------------- | ----------------------------------------------------------------------------------------------- | + | 0b0000000000 | Unused, reserved for future use. | + | 0b0000000010 | Logs client requests, excluding ping requests. | + | 0b0000000100 | Unused, reserved for future use. | + | 0b0000001000 | Logs client ping requests. | + | 0b0000010000 | Logs packets received from the quorum peer that is the current leader, excluding ping requests. | + | 0b0000100000 | Logs addition, removal and validation of client sessions. | + | 0b0001000000 | Logs delivery of watch events to client sessions. | + | 0b0010000000 | Logs ping packets received from the quorum peer that is the current leader. | + | 0b0100000000 | Unused, reserved for future use. | + | 0b1000000000 | Unused, reserved for future use. | + + All remaining bits in the 64-bit value are unused and reserved for future use. + Multiple trace logging categories are specified by calculating the bitwise OR of the documented values. + The default trace mask is 0b0100110010. Thus, by default, trace logging includes client requests, + packets received from the leader and sessions. + To set a different trace mask, send a request containing the `stmk` four-letter word followed + by the trace mask represented as a 64-bit signed long value. This example uses + the Perl `pack` function to construct a trace mask that enables all trace logging categories + described above and convert it to a 64-bit signed long value with big-endian byte order. + The result is appended to `stmk` and sent to the server using netcat. + The server responds with the new trace mask in decimal format. + + ```bash + $ perl -e "print 'stmk', pack('q>', 0b0011111010)" | nc localhost 2181 + 250 + ``` + +Here's an example of the **ruok** +command: + +```bash +$ echo ruok | nc 127.0.0.1 5111 + imok +``` + +## The AdminServer + +**New in 3.5.0:** The AdminServer is +an embedded Jetty server that provides an HTTP interface to the four-letter +word commands. By default, the server is started on port 8080, +and commands are issued by going to the URL "/commands/\[command name]", +e.g., http://localhost:8080/commands/stat. The command response is +returned as JSON. Unlike the original protocol, commands are not +restricted to four-letter names, and commands can have multiple names; +for instance, "stmk" can also be referred to as "set_trace_mask". To +view a list of all available commands, point a browser to the URL +/commands (e.g., http://localhost:8080/commands). See the [AdminServer configuration options](#configuring-adminserver-for-ssltls) +for how to change the port and URLs. + +The AdminServer is enabled by default, but can be disabled by either: + +- Setting the zookeeper.admin.enableServer system + property to false. +- Removing Jetty from the classpath. (This option is + useful if you would like to override ZooKeeper's jetty + dependency.) + +Note that the TCP four-letter word interface is still available if +the AdminServer is disabled. + +## Configuring AdminServer for SSL/TLS + +- Generating the **keystore.jks** and **truststore.jks** which can be found in the [Quorum TLS](/docs/admin-ops/administrators-guide/communication-using-the-netty-framework#quorum-tls). +- Add the following configuration settings to the `zoo.cfg` config file: + + ``` + admin.portUnification=true + ssl.quorum.keyStore.location=/path/to/keystore.jks + ssl.quorum.keyStore.password=password + ssl.quorum.trustStore.location=/path/to/truststore.jks + ssl.quorum.trustStore.password=password + ``` + +- Verify that the following entries in the logs can be seen: + + ``` + 2019-08-03 15:44:55,213 [myid:] - INFO [main:JettyAdminServer@123] - Successfully loaded private key from /data/software/cert/keystore.jks + 2019-08-03 15:44:55,213 [myid:] - INFO [main:JettyAdminServer@124] - Successfully loaded certificate authority from /data/software/cert/truststore.jks + 2019-08-03 15:44:55,403 [myid:] - INFO [main:JettyAdminServer@170] - Started AdminServer on address 0.0.0.0, port 8080 and command URL /commands + ``` + +Available commands include: + +- _connection_stat_reset/crst_: + Reset all client connection statistics. + No new fields returned. + +- _configuration/conf/config_ : + Print basic details about serving configuration, e.g. + client port, absolute path to data directory. + +- _connections/cons_ : + Information on client connections to server. + Note, depending on the number of client connections this operation may be expensive + (i.e. impact server performance). + Returns "connections", a list of connection info objects. + +- _hash_: + Txn digests in the historical digest list. + One is recorded every 128 transactions. + Returns "digests", a list to transaction digest objects. + +- _dirs_ : + Information on logfile directory and snapshot directory + size in bytes. + Returns "datadir_size" and "logdir_size". + +- _dump_ : + Information on session expirations and ephemerals. + Note, depending on the number of global sessions and ephemerals + this operation may be expensive (i.e. impact server performance). + Returns "expiry_time_to_session_ids" and "session_id_to_ephemeral_paths" as maps. + +- _environment/env/envi_ : + All defined environment variables. + Returns each as its own field. + +- _get_trace_mask/gtmk_ : + The current trace mask. Read-only version of _set_trace_mask_. + See the description of the four letter command _stmk_ for + more details. + Returns "tracemask". + +- _initial_configuration/icfg_ : + Print the text of the configuration file used to start the peer. + Returns "initial_configuration". + +- _is_read_only/isro_ : + A true/false if this server is in read-only mode. + Returns "read_only". + +- _last_snapshot/lsnp_ : + Information of the last snapshot that zookeeper server has finished saving to disk. + If called during the initial time period between the server starting up + and the server finishing saving its first snapshot, the command returns the + information of the snapshot read when starting up the server. + Returns "zxid" and "timestamp", the latter using a time unit of seconds. + +- _leader/lead_ : + If the ensemble is configured in quorum mode then emits the current leader + status of the peer and the current leader location. + Returns "is_leader", "leader_id", and "leader_ip". + +- _monitor/mntr_ : + Emits a wide variety of useful info for monitoring. + Includes performance stats, information about internal queues, and + summaries of the data tree (among other things). + Returns each as its own field. + +- _observer_connection_stat_reset/orst_ : + Reset all observer connection statistics. Companion command to _observers_. + No new fields returned. + +- _restore/rest_ : + Restore database from snapshot input stream on the current server. + Returns the following data in response payload: + "last_zxid": String + Note: this API is rate-limited (once every 5 mins by default) to protect the server + from being over-loaded. + +- _ruok_ : + No-op command, check if the server is running. + A response does not necessarily indicate that the + server has joined the quorum, just that the admin server + is active and bound to the specified port. + No new fields returned. + +- _set_trace_mask/stmk_ : + Sets the trace mask (as such, it requires a parameter). + Write version of _get_trace_mask_. + See the description of the four letter command _stmk_ for + more details. + Returns "tracemask". + +- _server_stats/srvr_ : + Server information. + Returns multiple fields giving a brief overview of server state. + +- _snapshot/snap_ : + Takes a snapshot of the current server in the datadir and stream out data. + Optional query parameter: + "streaming": Boolean (defaults to true if the parameter is not present) + Returns the following via Http headers: + "last_zxid": String + "snapshot_size": String + Note: this API is rate-limited (once every 5 mins by default) to protect the server + from being over-loaded. + +- _stats/stat_ : + Same as _server_stats_ but also returns the "connections" field (see _connections_ + for details). + Note, depending on the number of client connections this operation may be expensive + (i.e. impact server performance). + +- _stat_reset/srst_ : + Resets server statistics. This is a subset of the information returned + by _server_stats_ and _stats_. + No new fields returned. + +- _observers/obsr_ : + Information on observer connections to server. + Always available on a Leader, available on a Follower if its + acting as a learner master. + Returns "synced_observers" (int) and "observers" (list of per-observer properties). + +- _system_properties/sysp_ : + All defined system properties. + Returns each as its own field. + +- _voting_view_ : + Provides the current voting members in the ensemble. + Returns "current_config" as a map. + +- _watches/wchc_ : + Watch information aggregated by session. + Note, depending on the number of watches this operation may be expensive + (i.e. impact server performance). + Returns "session_id_to_watched_paths" as a map. + +- _watches_by_path/wchp_ : + Watch information aggregated by path. + Note, depending on the number of watches this operation may be expensive + (i.e. impact server performance). + Returns "path_to_session_ids" as a map. + +- _watch_summary/wchs_ : + Summarized watch information. + Returns "num_total_watches", "num_paths", and "num_connections". + +- _zabstate_ : + The current phase of Zab protocol that peer is running and whether it is a + voting member. + Peers can be in one of these phases: ELECTION, DISCOVERY, SYNCHRONIZATION, BROADCAST. + Returns fields "voting" and "zabstate". diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/communication-using-the-netty-framework.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/communication-using-the-netty-framework.mdx new file mode 100644 index 00000000000..5cb8761d3e3 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/communication-using-the-netty-framework.mdx @@ -0,0 +1,152 @@ +--- +title: "Communication using the Netty framework" +description: "Explains how to configure ZooKeeper to use Netty instead of NIO for client/server communication, including Quorum TLS setup and zero-downtime migration from non-TLS clusters." +--- + +[Netty](http://netty.io) +is an NIO based client/server communication framework, it +simplifies (over NIO being used directly) many of the +complexities of network level communication for java +applications. Additionally the Netty framework has built +in support for encryption (SSL) and authentication +(certificates). These are optional features and can be +turned on or off individually. + +In versions 3.5+, a ZooKeeper server can use Netty +instead of NIO (default option) by setting the environment +variable **zookeeper.serverCnxnFactory** +to **org.apache.zookeeper.server.NettyServerCnxnFactory**; +for the client, set **zookeeper.clientCnxnSocket** +to **org.apache.zookeeper.ClientCnxnSocketNetty**. + +## Quorum TLS + +_New in 3.5.5_ + +Based on the Netty Framework ZooKeeper ensembles can be set up +to use TLS encryption in their communication channels. This section +describes how to set up encryption on the quorum communication. + +Please note that Quorum TLS encapsulates securing both leader election +and quorum communication protocols. + + + + Create SSL keystore JKS to store local credentials. One keystore should be created for each ZK + instance. In this example we generate a self-signed certificate and store it together with the + private key in `keystore.jks`. This is suitable for testing purposes, but you probably need an + official certificate to sign your keys in a production environment. Please note that the alias + (`-alias`) and the distinguished name (`-dname`) must match the hostname of the machine that is + associated with, otherwise hostname verification won't work. + +``` +keytool -genkeypair -alias $(hostname -f) -keyalg RSA -keysize 2048 -dname "cn=$(hostname -f)" -keypass password -keystore keystore.jks -storepass password +``` + + + + Extract the signed public key (certificate) from keystore. _This step might only be necessary + for self-signed certificates._ + +``` +keytool -exportcert -alias $(hostname -f) -keystore keystore.jks -file $(hostname -f).cer -rfc +``` + + + + Create SSL truststore JKS containing certificates of all ZooKeeper instances. The same + truststore (storing all accepted certs) should be shared on participants of the ensemble. You + need to use different aliases to store multiple certificates in the same truststore. Name of + the aliases doesn't matter. + +``` +keytool -importcert -alias [host1..3] -file [host1..3].cer -keystore truststore.jks -storepass password +``` + + + + Use `NettyServerCnxnFactory` as serverCnxnFactory, because SSL is not supported by NIO. Add + the following configuration settings to your `zoo.cfg` config file: + +``` +sslQuorum=true +serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory +ssl.quorum.keyStore.location=/path/to/keystore.jks +ssl.quorum.keyStore.password=password +ssl.quorum.trustStore.location=/path/to/truststore.jks +ssl.quorum.trustStore.password=password +``` + + + + Verify in the logs that your ensemble is running on TLS: + +``` +INFO [main:QuorumPeer@1789] - Using TLS encrypted quorum communication +INFO [main:QuorumPeer@1797] - Port unification disabled +... +INFO [QuorumPeerListener:QuorumCnxManager$Listener@877] - Creating TLS-only quorum server socket +``` + + + + +## Upgrading existing non-TLS cluster with no downtime + +_New in 3.5.5_ + +Here are the steps needed to upgrade an already running ZooKeeper ensemble +to TLS without downtime by taking advantage of port unification functionality. + + + + Create the necessary keystores and truststores for all ZK participants as described in the + previous section. + + + Add the following config settings and restart the first node. Note that TLS is not yet + enabled, but we turn on port unification. + +``` +sslQuorum=false +portUnification=true +serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory +ssl.quorum.keyStore.location=/path/to/keystore.jks +ssl.quorum.keyStore.password=password +ssl.quorum.trustStore.location=/path/to/truststore.jks +ssl.quorum.trustStore.password=password +``` + + + + Repeat step 2 on the remaining nodes. Verify that you see the following entries in the logs, + and double-check after each node restart that the quorum becomes healthy again. + +``` +INFO [main:QuorumPeer@1791] - Using insecure (non-TLS) quorum communication +INFO [main:QuorumPeer@1797] - Port unification enabled +... +INFO [QuorumPeerListener:QuorumCnxManager$Listener@874] - Creating TLS-enabled quorum server socket +``` + + + + Enable Quorum TLS on each node and do a rolling restart: + +``` +sslQuorum=true +portUnification=true +``` + + + + Once you verify that your entire ensemble is running on TLS, disable port unification and do + another rolling restart: + +``` +sslQuorum=true +portUnification=false +``` + + + diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/configuration-parameters.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/configuration-parameters.mdx new file mode 100644 index 00000000000..92180323c54 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/configuration-parameters.mdx @@ -0,0 +1,1699 @@ +--- +title: "Configuration Parameters" +description: "Complete reference for all ZooKeeper configuration parameters, including minimum and advanced settings, cluster options, encryption and authentication, performance tuning, and the AdminServer." +--- + +ZooKeeper's behavior is governed by the ZooKeeper configuration +file. This file is designed so that the exact same file can be used by +all the servers that make up a ZooKeeper server assuming the disk +layouts are the same. If servers use different configuration files, care +must be taken to ensure that the list of servers in all of the different +configuration files match. + + + In 3.5.0 and later, some of these parameters should be placed in a dynamic + configuration file. If they are placed in the static configuration file, + ZooKeeper will automatically move them over to the dynamic configuration file. + See [Dynamic Reconfiguration](/docs/admin-ops/dynamic-reconfiguration) for + more information. + + +## Minimum Configuration + +Here are the minimum configuration keywords that must be defined +in the configuration file: + +- _clientPort_ : + the port to listen for client connections; that is, the + port that clients attempt to connect to. + +- _secureClientPort_ : + the port to listen on for secure client connections using SSL. + **clientPort** specifies + the port for plaintext connections while **secureClientPort** specifies the port for SSL + connections. Specifying both enables mixed-mode while omitting + either will disable that mode. + Note that SSL feature will be enabled when user plugs-in + zookeeper.serverCnxnFactory, zookeeper.clientCnxnSocket as Netty. + +- _observerMasterPort_ : + the port to listen for observer connections; that is, the + port that observers attempt to connect to. + if the property is set then the server will host observer connections + when in follower mode in addition to when in leader mode and correspondingly + attempt to connect to any voting peer when in observer mode. + +- _dataDir_ : + the location where ZooKeeper will store the in-memory + database snapshots and, unless specified otherwise, the + transaction log of updates to the database. + + + Be careful where you put the transaction log. A dedicated transaction log + device is key to consistent good performance. Putting the log on a busy + device will adversely affect performance. + + +- _tickTime_ : + the length of a single tick, which is the basic time unit + used by ZooKeeper, as measured in milliseconds. It is used to + regulate heartbeats, and timeouts. For example, the minimum + session timeout will be two ticks. + +## Advanced Configuration + +The configuration settings in the section are optional. You can +use them to further fine tune the behaviour of your ZooKeeper servers. +Some can also be set using Java system properties, generally of the +form _zookeeper.keyword_. The exact system +property, when available, is noted below. + +- _dataLogDir_ : + (No Java system property) + This option will direct the machine to write the + transaction log to the **dataLogDir** rather than the **dataDir**. This allows a dedicated log + device to be used, and helps avoid competition between logging + and snapshots. + + + Having a dedicated log device has a large impact on throughput and stable + latencies. It is highly recommended dedicating a log device and set + **dataLogDir** to point to a directory on that device, and then make sure to + point **dataDir** to a directory _not_ residing on that device. + + +- _globalOutstandingLimit_ : + (Java system property: **zookeeper.globalOutstandingLimit.**) + Clients can submit requests faster than ZooKeeper can + process them, especially if there are a lot of clients. To + prevent ZooKeeper from running out of memory due to queued + requests, ZooKeeper will throttle clients so that there are no + more than globalOutstandingLimit outstanding requests across + entire ensemble, equally divided. The default limit is 1,000 + and, for example, with 3 members each of them will have + 1000 / 2 = 500 individual limit. + +- _preAllocSize_ : + (Java system property: **zookeeper.preAllocSize**) + To avoid seeks ZooKeeper allocates space in the + transaction log file in blocks of preAllocSize kilobytes. The + default block size is 64M. One reason for changing the size of + the blocks is to reduce the block size if snapshots are taken + more often. (Also, see **snapCount** and **snapSizeLimitInKb**). + +- _snapCount_ : + (Java system property: **zookeeper.snapCount**) + ZooKeeper records its transactions using snapshots and + a transaction log (think write-ahead log). The number of + transactions recorded in the transaction log before a snapshot + can be taken (and the transaction log rolled) is determined + by snapCount. In order to prevent all of the machines in the quorum + from taking a snapshot at the same time, each ZooKeeper server + will take a snapshot when the number of transactions in the transaction log + reaches a runtime generated random value in the \[snapCount/2+1, snapCount] + range. The default snapCount is 100,000. + +- _commitLogCount_ \* : + (Java system property: **zookeeper.commitLogCount**) + Zookeeper maintains an in-memory list of last committed requests for fast synchronization with + followers when the followers are not too behind. This improves sync performance in case when your + snapshots are large (>100,000). The default value is 500 which is the recommended minimum. + +- _snapSizeLimitInKb_ : + (Java system property: **zookeeper.snapSizeLimitInKb**) + ZooKeeper records its transactions using snapshots and + a transaction log (think write-ahead log). The total size in bytes allowed + in the set of transactions recorded in the transaction log before a snapshot + can be taken (and the transaction log rolled) is determined + by snapSize. In order to prevent all of the machines in the quorum + from taking a snapshot at the same time, each ZooKeeper server + will take a snapshot when the size in bytes of the set of transactions in the + transaction log reaches a runtime generated random value in the \[snapSize/2+1, snapSize] + range. Each file system has a minimum standard file size and in order + to for valid functioning of this feature, the number chosen must be larger + than that value. The default snapSizeLimitInKb is 4,194,304 (4GB). + A non-positive value will disable the feature. + +- _txnLogSizeLimitInKb_ : + (Java system property: **zookeeper.txnLogSizeLimitInKb**) + Zookeeper transaction log file can also be controlled more + directly using txnLogSizeLimitInKb. Larger txn logs can lead to + slower follower syncs when sync is done using transaction log. + This is because leader has to scan through the appropriate log + file on disk to find the transaction to start sync from. + This feature is turned off by default and snapCount and snapSizeLimitInKb are the + only values that limit transaction log size. When enabled + Zookeeper will roll the log when any of the limits is hit. + Please note that actual log size can exceed this value by the size + of the serialized transaction. On the other hand, if this value is + set too close to (or smaller than) **preAllocSize**, + it can cause Zookeeper to roll the log for every transaction. While + this is not a correctness issue, this may cause severely degraded + performance. To avoid this and to get most out of this feature, it is + recommended to set the value to N \* **preAllocSize** + where N >= 2. + +- _maxCnxns_ : + (Java system property: **zookeeper.maxCnxns**) + Limits the total number of concurrent connections that can be made to a + zookeeper server (per client Port of each server ). This is used to prevent certain + classes of DoS attacks. The default is 0 and setting it to 0 entirely removes + the limit on total number of concurrent connections. Accounting for the + number of connections for serverCnxnFactory and a secureServerCnxnFactory is done + separately, so a peer is allowed to host up to 2\*maxCnxns provided they are of appropriate types. + +- _maxClientCnxns_ : + (No Java system property) + Limits the number of concurrent connections (at the socket + level) that a single client, identified by IP address, may make + to a single member of the ZooKeeper ensemble. This is used to + prevent certain classes of DoS attacks, including file + descriptor exhaustion. The default is 60. Setting this to 0 + entirely removes the limit on concurrent connections. + +- _clientPortAddress_ : + **New in 3.3.0:** the + address (ipv4, ipv6 or hostname) to listen for client + connections; that is, the address that clients attempt + to connect to. This is optional, by default we bind in + such a way that any connection to the **clientPort** for any + address/interface/nic on the server will be + accepted. + +- _minSessionTimeout_ : + (No Java system property) + **New in 3.3.0:** the + minimum session timeout in milliseconds that the server + will allow the client to negotiate. Defaults to 2 times + the **tickTime**. + +- _maxSessionTimeout_ : + (No Java system property) + **New in 3.3.0:** the + maximum session timeout in milliseconds that the server + will allow the client to negotiate. Defaults to 20 times + the **tickTime**. + +- _fsync.warningthresholdms_ : + (Java system property: **zookeeper.fsync.warningthresholdms**) + **New in 3.3.4:** A + warning message will be output to the log whenever an + fsync in the Transactional Log (WAL) takes longer than + this value. The values is specified in milliseconds and + defaults to 1000. This value can only be set as a + system property. + +- _maxResponseCacheSize_ : + (Java system property: **zookeeper.maxResponseCacheSize**) + When set to a positive integer, it determines the size + of the cache that stores the serialized form of recently + read records. Helps save the serialization cost on + popular znodes. The metrics **response_packet_cache_hits** + and **response_packet_cache_misses** can be used to tune + this value to a given workload. The feature is turned on + by default with a value of 400, set to 0 or a negative + integer to turn the feature off. + +- _maxGetChildrenResponseCacheSize_ : + (Java system property: **zookeeper.maxGetChildrenResponseCacheSize**) + **New in 3.6.0:** + Similar to **maxResponseCacheSize**, but applies to get children + requests. The metrics **response_packet_get_children_cache_hits** + and **response_packet_get_children_cache_misses** can be used to tune + this value to a given workload. The feature is turned on + by default with a value of 400, set to 0 or a negative + integer to turn the feature off. + +- _autopurge.snapRetainCount_ : + (No Java system property) + **New in 3.4.0:** + When enabled, ZooKeeper auto purge feature retains + the **autopurge.snapRetainCount** most + recent snapshots and the corresponding transaction logs in the + **dataDir** and **dataLogDir** respectively and deletes the rest. + Defaults to 3. Minimum value is 3. + +- _autopurge.purgeInterval_ : + (No Java system property) + **New in 3.4.0:** The + time interval in hours for which the purge task has to + be triggered. Set to a positive integer (1 and above) + to enable the auto purging. Defaults to 0. + **Suffix support added in 3.10.0:** The interval is specified as an integer with an optional suffix to indicate the time unit. + Supported suffixes are: `ms` for milliseconds, `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. + For example, "10m" represents 10 minutes, and "5h" represents 5 hours. + If no suffix is provided, the default unit is hours. + +- _syncEnabled_ : + (Java system property: **zookeeper.observer.syncEnabled**) + **New in 3.4.6, 3.5.0:** + The observers now log transaction and write snapshot to disk + by default like the participants. This reduces the recovery time + of the observers on restart. Set to "false" to disable this + feature. Default is "true" + +- _extendedTypesEnabled_ : + (Java system property only: **zookeeper.extendedTypesEnabled**) + **New in 3.5.4, 3.6.0:** Define to `true` to enable + extended features such as the creation of [TTL Nodes](/docs/developer/programmers-guide/data-model#ttl-nodes). + They are disabled by default. IMPORTANT: when enabled server IDs must + be less than 255 due to internal limitations. + +- _emulate353TTLNodes_ : + (Java system property only:**zookeeper.emulate353TTLNodes**). + **New in 3.5.4, 3.6.0:** Due to [ZOOKEEPER-2901] + (https://issues.apache.org/jira/browse/ZOOKEEPER-2901) TTL nodes + created in version 3.5.3 are not supported in 3.5.4/3.6.0. However, a workaround is provided via the + zookeeper.emulate353TTLNodes system property. If you used TTL nodes in ZooKeeper 3.5.3 and need to maintain + compatibility set **zookeeper.emulate353TTLNodes** to `true` in addition to + **zookeeper.extendedTypesEnabled**. NOTE: due to the bug, server IDs + must be 127 or less. Additionally, the maximum support TTL value is `1099511627775` which is smaller + than what was allowed in 3.5.3 (`1152921504606846975`) + +- _watchManagerName_ : + (Java system property only: **zookeeper.watchManagerName**) + **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + New watcher manager WatchManagerOptimized is added to optimize the memory overhead in heavy watch use cases. This + config is used to define which watcher manager to be used. Currently, we only support WatchManager and + WatchManagerOptimized. + +- _watcherCleanThreadsNum_ : + (Java system property only: **zookeeper.watcherCleanThreadsNum**) + **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, this config is used to decide how + many thread is used in the WatcherCleaner. More thread usually means larger clean up throughput. The + default value is 2, which is good enough even for heavy and continuous session closing/recreating cases. + +- _watcherCleanThreshold_ : + (Java system property only: **zookeeper.watcherCleanThreshold**) + **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, the cleanup process is relatively + heavy, batch processing will reduce the cost and improve the performance. This setting is used to decide + the batch size. The default one is 1000, we don't need to change it if there is no memory or clean up + speed issue. + +- _watcherCleanIntervalInSeconds_ : + (Java system property only:**zookeeper.watcherCleanIntervalInSeconds**) + **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + The new watcher manager WatchManagerOptimized will clean up the dead watchers lazily, the cleanup process is relatively + heavy, batch processing will reduce the cost and improve the performance. Besides watcherCleanThreshold, + this setting is used to clean up the dead watchers after certain time even the dead watchers are not larger + than watcherCleanThreshold, so that we won't leave the dead watchers there for too long. The default setting + is 10 minutes, which usually don't need to be changed. + +- _maxInProcessingDeadWatchers_ : + (Java system property only: **zookeeper.maxInProcessingDeadWatchers**) + **New in 3.6.0:** Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + This is used to control how many backlog can we have in the WatcherCleaner, when it reaches this number, it will + slow down adding the dead watcher to WatcherCleaner, which will in turn slow down adding and closing + watchers, so that we can avoid OOM issue. By default there is no limit, you can set it to values like + watcherCleanThreshold \* 1000. + +- _bitHashCacheSize_ : + (Java system property only: **zookeeper.bitHashCacheSize**) + **New 3.6.0**: Added in [ZOOKEEPER-1179](https://issues.apache.org/jira/browse/ZOOKEEPER-1179) + This is the setting used to decide the HashSet cache size in the BitHashSet implementation. Without HashSet, we + need to use O(N) time to get the elements, N is the bit numbers in elementBits. But we need to + keep the size small to make sure it doesn't cost too much in memory, there is a trade off between memory + and time complexity. The default value is 10, which seems a relatively reasonable cache size. + +- _fastleader.minNotificationInterval_ : + (Java system property: **zookeeper.fastleader.minNotificationInterval**) + Lower bound for length of time between two consecutive notification + checks on the leader election. This interval determines how long a + peer waits to check the set of election votes and effects how + quickly an election can resolve. The interval follows a backoff + strategy from the configured minimum (this) and the configured maximum + (fastleader.maxNotificationInterval) for long elections. + +- _fastleader.maxNotificationInterval_ : + (Java system property: **zookeeper.fastleader.maxNotificationInterval**) + Upper bound for length of time between two consecutive notification + checks on the leader election. This interval determines how long a + peer waits to check the set of election votes and effects how + quickly an election can resolve. The interval follows a backoff + strategy from the configured minimum (fastleader.minNotificationInterval) + and the configured maximum (this) for long elections. + +- _connectionMaxTokens_ : + (Java system property: **zookeeper.connection_throttle_tokens**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the maximum number of tokens in the token-bucket. + When set to 0, throttling is disabled. Default is 0. + +- _connectionTokenFillTime_ : + (Java system property: **zookeeper.connection_throttle_fill_time**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the interval in milliseconds when the token bucket is re-filled with + _connectionTokenFillCount_ tokens. Default is 1. + +- _connectionTokenFillCount_ : + (Java system property: **zookeeper.connection_throttle_fill_count**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the number of tokens to add to the token bucket every + _connectionTokenFillTime_ milliseconds. Default is 1. + +- _connectionFreezeTime_ : + (Java system property: **zookeeper.connection_throttle_freeze_time**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the interval in milliseconds when the dropping + probability is adjusted. When set to -1, probabilistic dropping is disabled. + Default is -1. + +- _connectionDropIncrease_ : + (Java system property: **zookeeper.connection_throttle_drop_increase**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the dropping probability to increase. The throttler + checks every _connectionFreezeTime_ milliseconds and if the token bucket is + empty, the dropping probability will be increased by _connectionDropIncrease_. + The default is 0.02. + +- _connectionDropDecrease_ : + (Java system property: **zookeeper.connection_throttle_drop_decrease**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. + This parameter defines the dropping probability to decrease. The throttler + checks every _connectionFreezeTime_ milliseconds and if the token bucket has + more tokens than a threshold, the dropping probability will be decreased by + _connectionDropDecrease_. The threshold is _connectionMaxTokens_ \* + _connectionDecreaseRatio_. The default is 0.002. + +- _connectionDecreaseRatio_ : + (Java system property: **zookeeper.connection_throttle_decrease_ratio**) + **New in 3.6.0:** + This is one of the parameters to tune the server-side connection throttler, + which is a token-based rate limiting mechanism with optional probabilistic + dropping. This parameter defines the threshold to decrease the dropping + probability. The default is 0. + +- _zookeeper.connection_throttle_weight_enabled_ : + (Java system property only) + **New in 3.6.0:** + Whether to consider connection weights when throttling. Only useful when connection throttle is enabled, that is, connectionMaxTokens is larger than 0. The default is false. + +- _zookeeper.connection_throttle_global_session_weight_ : + (Java system property only) + **New in 3.6.0:** + The weight of a global session. It is the number of tokens required for a global session request to get through the connection throttler. It has to be a positive integer no smaller than the weight of a local session. The default is 3. + +- _zookeeper.connection_throttle_local_session_weight_ : + (Java system property only) + **New in 3.6.0:** + The weight of a local session. It is the number of tokens required for a local session request to get through the connection throttler. It has to be a positive integer no larger than the weight of a global session or a renew session. The default is 1. + +- _zookeeper.connection_throttle_renew_session_weight_ : + (Java system property only) + **New in 3.6.0:** + The weight of renewing a session. It is also the number of tokens required for a reconnect request to get through the throttler. It has to be a positive integer no smaller than the weight of a local session. The default is 2. + +- _clientPortListenBacklog_ : + (No Java system property) + **New in 3.4.14, 3.5.5, 3.6.0:** + The socket backlog length for the ZooKeeper server socket. This controls + the number of requests that will be queued server-side to be processed + by the ZooKeeper server. Connections that exceed this length will receive + a network timeout (30s) which may cause ZooKeeper session expiry issues. + By default, this value is unset (`-1`) which, on Linux, uses a backlog of + `50`. This value must be a positive number. + +- _serverCnxnFactory_ : + (Java system property: **zookeeper.serverCnxnFactory**) + Specifies ServerCnxnFactory implementation. + This should be set to `NettyServerCnxnFactory` in order to use TLS based server communication. + Default is `NIOServerCnxnFactory`. + +- _flushDelay_ : + (Java system property: **zookeeper.flushDelay**) + Time in milliseconds to delay the flush of the commit log. + Does not affect the limit defined by _maxBatchSize_. + Disabled by default (with value 0). Ensembles with high write rates + may see throughput improved with a value of 10-20 ms. + +- _maxWriteQueuePollTime_ : + (Java system property: **zookeeper.maxWriteQueuePollTime**) + If _flushDelay_ is enabled, this determines the amount of time in milliseconds + to wait before flushing when no new requests are being queued. + Set to _flushDelay_/3 by default (implicitly disabled by default). + +- _maxBatchSize_ : + (Java system property: **zookeeper.maxBatchSize**) + The number of transactions allowed in the server before a flush of the + commit log is triggered. + Does not affect the limit defined by _flushDelay_. + Default is 1000. + +- _enforceQuota_ : + (Java system property: **zookeeper.enforceQuota**) + **New in 3.7.0:** + Enforce the quota check. When enabled and the client exceeds the total bytes or children count hard quota under a znode, the server will reject the request and reply the client a `QuotaExceededException` by force. + The default value is: false. Exploring [quota feature](/docs/admin-ops/quota-guide) for more details. + +- _requestThrottleLimit_ : + (Java system property: **zookeeper.request_throttle_max_requests**) + **New in 3.6.0:** + The total number of outstanding requests allowed before the RequestThrottler starts stalling. When set to 0, throttling is disabled. The default is 0. + +- _requestThrottleStallTime_ : + (Java system property: **zookeeper.request_throttle_stall_time**) + **New in 3.6.0:** + The maximum time (in milliseconds) for which a thread may wait to be notified that it may proceed processing a request. The default is 100. + +- _requestThrottleDropStale_ : + (Java system property: **request_throttle_drop_stale**) + **New in 3.6.0:** + When enabled, the throttler will drop stale requests rather than issue them to the request pipeline. A stale request is a request sent by a connection that is now closed, and/or a request that will have a request latency higher than the sessionTimeout. The default is true. + +- _requestStaleLatencyCheck_ : + (Java system property: **zookeeper.request_stale_latency_check**) + **New in 3.6.0:** + When enabled, a request is considered stale if the request latency is higher than its associated session timeout. Disabled by default. + +- _requestStaleConnectionCheck_ : + (Java system property: **zookeeper.request_stale_connection_check**) + **New in 3.6.0:** + When enabled, a request is considered stale if the request's connection has closed. Enabled by default. + +- _zookeeper.request_throttler.shutdownTimeout_ : + (Java system property only) + **New in 3.6.0:** + The time (in milliseconds) the RequestThrottler waits for the request queue to drain during shutdown before it shuts down forcefully. The default is 10000. + +- _advancedFlowControlEnabled_ : + (Java system property: **zookeeper.netty.advancedFlowControl.enabled**) + Using accurate flow control in netty based on the status of ZooKeeper + pipeline to avoid direct buffer OOM. It will disable the AUTO_READ in + Netty. + +- _enableEagerACLCheck_ : + (Java system property only: **zookeeper.enableEagerACLCheck**) + When set to "true", enables eager ACL check on write requests on each local + server before sending the requests to quorum. Default is "false". + +- _maxConcurrentSnapSyncs_ : + (Java system property: **zookeeper.leader.maxConcurrentSnapSyncs**) + The maximum number of snap syncs a leader or a follower can serve at the same + time. The default is 10. + +- _maxConcurrentDiffSyncs_ : + (Java system property: **zookeeper.leader.maxConcurrentDiffSyncs**) + The maximum number of diff syncs a leader or a follower can serve at the same + time. The default is 100. + +- _digest.enabled_ : + (Java system property only: **zookeeper.digest.enabled**) + **New in 3.6.0:** + The digest feature is added to detect the data inconsistency inside + ZooKeeper when loading database from disk, catching up and following + leader, its doing incrementally hash check for the DataTree based on + the adHash paper mentioned in + + https://cseweb.ucsd.edu/~daniele/papers/IncHash.pdf + + The idea is simple, the hash value of DataTree will be updated incrementally + based on the changes to the set of data. When the leader is preparing the txn, + it will pre-calculate the hash of the tree based on the changes happened with + formula: + + `current_hash = current_hash + hash(new node data) - hash(old node data)` + + If it’s creating a new node, the hash(old node data) will be 0, and if it’s a + delete node op, the hash(new node data) will be 0. + + This hash will be associated with each txn to represent the expected hash value + after applying the txn to the data tree, it will be sent to followers with + original proposals. Learner will compare the actual hash value with the one in + the txn after applying the txn to the data tree, and report mismatch if it’s not + the same. + + These digest value will also be persisted with each txn and snapshot on the disk, + so when servers restarted and load data from disk, it will compare and see if + there is hash mismatch, which will help detect data loss issue on disk. + + For the actual hash function, we’re using CRC internally, it’s not a collisionless + hash function, but it’s more efficient compared to collisionless hash, and the + collision possibility is really really rare and can already meet our needs here. + + This feature is backward and forward compatible, so it can safely roll upgrade, + downgrade, enabled and later disabled without any compatible issue. Here are the + scenarios have been covered and tested: + 1. When leader runs with new code while follower runs with old one, the digest will + be appended to the end of each txn, follower will only read header and txn data, + digest value in the txn will be ignored. It won't affect the follower reads and + processes the next txn. + 2. When leader runs with old code while follower runs with new one, the digest won't + be sent with txn, when follower tries to read the digest, it will throw EOF which + is caught and handled gracefully with digest value set to null. + 3. When loading old snapshot with new code, it will throw IOException when trying to + read the non-exist digest value, and the exception will be caught and digest will + be set to null, which means we won't compare digest when loading this snapshot, + which is expected to happen during rolling upgrade + 4. When loading new snapshot with old code, it will finish successfully after deserializing + the data tree, the digest value at the end of snapshot file will be ignored + 5. The scenarios of rolling restart with flags change are similar to the 1st and 2nd + scenarios discussed above, if the leader enabled but follower not, digest value will + be ignored, and follower won't compare the digest during runtime; if leader disabled + but follower enabled, follower will get EOF exception which is handled gracefully. + + Note: the current digest calculation excluded nodes under /zookeeper + due to the potential inconsistency in the /zookeeper/quota stat node, + we can include that after that issue is fixed. + + By default, this feature is enabled, set "false" to disable it. + +- _snapshot.compression.method_ : + (Java system property: **zookeeper.snapshot.compression.method**) + **New in 3.6.0:** + This property controls whether or not ZooKeeper should compress snapshots + before storing them on disk (see [ZOOKEEPER-3179](https://issues.apache.org/jira/browse/ZOOKEEPER-3179)). + Possible values are: + - "": Disabled (no snapshot compression). This is the default behavior. + - "gz": See [gzip compression](https://en.wikipedia.org/wiki/Gzip). + - "snappy": See [Snappy compression](). + +- _snapshot.trust.empty_ : + (Java system property: **zookeeper.snapshot.trust.empty**) + **New in 3.5.6:** + This property controls whether or not ZooKeeper should treat missing + snapshot files as a fatal state that can't be recovered from. + Set to true to allow ZooKeeper servers recover without snapshot + files. This should only be set during upgrading from old versions of + ZooKeeper (3.4.x, pre 3.5.3) where ZooKeeper might only have transaction + log files but without presence of snapshot files. If the value is set + during upgrade, we recommend setting the value back to false after upgrading + and restart ZooKeeper process so ZooKeeper can continue normal data + consistency check during recovery process. + Default value is false. + +- _audit.enable_ : + (Java system property: **zookeeper.audit.enable**) + **New in 3.6.0:** + By default audit logs are disabled. Set to "true" to enable it. Default value is "false". + See the [ZooKeeper audit logs](/docs/admin-ops/monitor-and-audit-logs) for more information. + +- _audit.impl.class_ : + (Java system property: **zookeeper.audit.impl.class**) + **New in 3.6.0:** + Class to implement the audit logger. By default logback based audit logger org.apache.zookeeper.audit + .Slf4jAuditLogger is used. + See the [ZooKeeper audit logs](/docs/admin-ops/monitor-and-audit-logs) for more information. + +- _largeRequestMaxBytes_ : + (Java system property: **zookeeper.largeRequestMaxBytes**) + **New in 3.6.0:** + The maximum number of bytes of all inflight large request. The connection will be closed if a coming large request causes the limit exceeded. The default is 100 \* 1024 \* 1024. + +- _largeRequestThreshold_ : + (Java system property: **zookeeper.largeRequestThreshold**) + **New in 3.6.0:** + The size threshold after which a request is considered a large request. If it is -1, then all requests are considered small, effectively turning off large request throttling. The default is -1. + +- _outstandingHandshake.limit_ + (Java system property only: **zookeeper.netty.server.outstandingHandshake.limit**) + The maximum in-flight TLS handshake connections could have in ZooKeeper, + the connections exceed this limit will be rejected before starting handshake. + This setting doesn't limit the max TLS concurrency, but helps avoid herd + effect due to TLS handshake timeout when there are too many in-flight TLS + handshakes. Set it to something like 250 is good enough to avoid herd effect. + +- _netty.server.earlyDropSecureConnectionHandshakes_ + (Java system property: **zookeeper.netty.server.earlyDropSecureConnectionHandshakes**) + If the ZooKeeper server is not fully started, drop TCP connections before performing the TLS handshake. + This is useful in order to prevent flooding the server with many concurrent TLS handshakes after a restart. + Please note that if you enable this flag the server won't answer to 'ruok' commands if it is not fully started. + The behaviour of dropping the connection has been introduced in ZooKeeper 3.7 and it was not possible to disable it. + Since 3.7.1 and 3.8.0 this feature is disabled by default. + +- _throttledOpWaitTime_ + (Java system property: **zookeeper.throttled_op_wait_time**) + The time in the RequestThrottler queue longer than which a request will be marked as throttled. + A throttled requests will not be processed other than being fed down the pipeline of the server it belongs + to preserve the order of all requests. + The FinalProcessor will issue an error response (new error code: ZTHROTTLEDOP) for these undigested requests. + The intent is for the clients not to retry them immediately. + When set to 0, no requests will be throttled. The default is 0. + +- _learner.closeSocketAsync_ + (Java system property: **zookeeper.learner.closeSocketAsync**) + (Java system property: **learner.closeSocketAsync**)(Added for backward compatibility) + **New in 3.7.0:** + When enabled, a learner will close the quorum socket asynchronously. This is useful for TLS connections where closing a socket might take a long time, block the shutdown process, potentially delay a new leader election, and leave the quorum unavailable. Closing the socket asynchronously avoids blocking the shutdown process despite the long socket closing time and a new leader election can be started while the socket being closed. + The default is false. + +- _leader.closeSocketAsync_ + (Java system property: **zookeeper.leader.closeSocketAsync**) + (Java system property: **leader.closeSocketAsync**)(Added for backward compatibility) + **New in 3.7.0:** + When enabled, the leader will close a quorum socket asynchronously. This is useful for TLS connections where closing a socket might take a long time. If disconnecting a follower is initiated in ping() because of a failed SyncLimitCheck then the long socket closing time will block the sending of pings to other followers. Without receiving pings, the other followers will not send session information to the leader, which causes sessions to expire. Setting this flag to true ensures that pings will be sent regularly. + The default is false. + +- _learner.asyncSending_ + (Java system property: **zookeeper.learner.asyncSending**) + (Java system property: **learner.asyncSending**)(Added for backward compatibility) + **New in 3.7.0:** + The sending and receiving packets in Learner were done synchronously in a critical section. An untimely network issue could cause the followers to hang (see [ZOOKEEPER-3575](https://issues.apache.org/jira/browse/ZOOKEEPER-3575) and [ZOOKEEPER-4074](https://issues.apache.org/jira/browse/ZOOKEEPER-4074)). The new design moves sending packets in Learner to a separate thread and sends the packets asynchronously. The new design is enabled with this parameter (learner.asyncSending). + The default is false. + +- _forward_learner_requests_to_commit_processor_disabled_ + (Java system property: **zookeeper.forward_learner_requests_to_commit_processor_disabled**) + When this property is set, the requests from learners won't be enqueued to + CommitProcessor queue, which will help save the resources and GC time on + leader. The default value is false. + +- _serializeLastProcessedZxid.enabled_ + (Java system property: **zookeeper.serializeLastProcessedZxid.enabled**) + **New in 3.9.0:** + If enabled, ZooKeeper serializes the lastProcessedZxid when snapshot and deserializes it + when restore. Defaults to true. Needs to be enabled for performing snapshot and restore + via admin server commands, as there is no snapshot file name to extract the lastProcessedZxid. + + This feature is backward and forward compatible. Here are the different scenarios. + 1. Snapshot triggered by server internally + - When loading old snapshot with new code, it will throw EOFException when trying to + read the non-exist lastProcessedZxid value, and the exception will be caught. + The lastProcessedZxid will be set using the snapshot file name. + - When loading new snapshot with old code, it will finish successfully after deserializing + the digest value, the lastProcessedZxid at the end of snapshot file will be ignored. + The lastProcessedZxid will be set using the snapshot file name. + + 2. Sync up between leader and follower: The lastProcessedZxid will not be serialized by + leader and deserialized by follower in both new and old code. It will be set to the + lastProcessedZxid sent from leader via QuorumPacket. + + 3. Snapshot triggered via admin server APIs: The feature flag need to be enabled for the + snapshot command to work. + +## Cluster Options + +The options in this section are designed for use with an ensemble +of servers — that is, when deploying clusters of servers. + +- _electionAlg_ : + (No Java system property) + Election implementation to use. A value of "1" corresponds to the + non-authenticated UDP-based version of fast leader election, "2" + corresponds to the authenticated UDP-based version of fast + leader election, and "3" corresponds to TCP-based version of + fast leader election. Algorithm 3 was made default in 3.2.0 and + prior versions (3.0.0 and 3.1.0) were using algorithm 1 and 2 as well. + + + The implementations of leader election 1, and 2 were **deprecated** in + 3.4.0. Since 3.6.0 only FastLeaderElection is available, in case of upgrade + you have to shut down all of your servers and restart them with + electionAlg=3 (or by removing the line from the configuration file). + + +- _maxTimeToWaitForEpoch_ : + (Java system property: **zookeeper.leader.maxTimeToWaitForEpoch**) + **New in 3.6.0:** + The maximum time to wait for epoch from voters when activating + leader. If leader received a LOOKING notification from one of + its voters, and it hasn't received epoch packets from majority + within maxTimeToWaitForEpoch, then it will goto LOOKING and + elect leader again. + This can be tuned to reduce the quorum or server unavailable + time, it can be set to be much smaller than initLimit \* tickTime. + In cross datacenter environment, it can be set to something + like 2s. + +- _initLimit_ : + (No Java system property) + Amount of time, in ticks (see [tickTime](#minimum-configuration)), to allow followers to + connect and sync to a leader. Increased this value as needed, if + the amount of data managed by ZooKeeper is large. + +- _connectToLearnerMasterLimit_ : + (Java system property: zookeeper.**connectToLearnerMasterLimit**) + Amount of time, in ticks (see [tickTime](#minimum-configuration)), to allow followers to + connect to the leader after leader election. Defaults to the value of initLimit. + Use when initLimit is high so connecting to learner master doesn't result in higher timeout. + +- _leaderServes_ : + (Java system property: zookeeper.**leaderServes**) + Leader accepts client connections. Default value is "yes". + The leader machine coordinates updates. For higher update + throughput at the slight expense of read throughput the leader + can be configured to not accept clients and focus on + coordination. The default to this option is yes, which means + that a leader will accept client connections. + + + Turning on leader selection is highly recommended when you have more than + three ZooKeeper servers in an ensemble. + + +- _server.x=[hostname]:nnnnn[:nnnnn] etc_ : + (No Java system property) + Servers making up the ZooKeeper ensemble. When the server + starts up, it determines which server it is by looking for the + file _myid_ in the data directory. That file contains the server number, in ASCII, + and it should match **x** in **server.x** in the left hand side of this setting. + The list of servers that make up ZooKeeper servers that is + used by the clients must match the list of ZooKeeper servers + that each ZooKeeper server has. + There are two port numbers **nnnnn**. + The first followers used to connect to the leader, and the second is for + leader election. If you want to test multiple servers on a single machine, then + different ports can be used for each server. + + Since ZooKeeper 3.6.0 it is possible to specify **multiple addresses** for each + ZooKeeper server (see [ZOOKEEPER-3188](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3188)). + To enable this feature, you must set the _multiAddress.enabled_ configuration property + to _true_. This helps to increase availability and adds network level + resiliency to ZooKeeper. When multiple physical network interfaces are used + for the servers, ZooKeeper is able to bind on all interfaces and runtime switching + to a working interface in case a network error. The different addresses can be specified + in the config using a pipe ('|') character. A valid configuration using multiple addresses looks like: + + ``` + server.1=zoo1-net1:2888:3888|zoo1-net2:2889:3889 + server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889 + server.3=zoo3-net1:2888:3888|zoo3-net2:2889:3889 + ``` + + + By enabling this feature, the Quorum protocol (ZooKeeper Server-Server + protocol) will change. The users will not notice this and when anyone starts + a ZooKeeper cluster with the new config, everything will work normally. + However, it's not possible to enable this feature and specify multiple + addresses during a rolling upgrade if the old ZooKeeper cluster didn't + support the *multiAddress* feature (and the new Quorum protocol). In case if + you need this feature but you also need to perform a rolling upgrade from a + ZooKeeper cluster older than *3.6.0*, then you first need to do the rolling + upgrade without enabling the MultiAddress feature and later make a separate + rolling restart with the new configuration where **multiAddress.enabled** is + set to **true** and multiple addresses are provided. + + +- _syncLimit_ : + (No Java system property) + Amount of time, in ticks (see [tickTime](#minimum-configuration)), to allow followers to sync + with ZooKeeper. If followers fall too far behind a leader, they + will be dropped. + +- _group.x=nnnnn[:nnnnn]_ : + (No Java system property) + Enables a hierarchical quorum construction."x" is a group identifier + and the numbers following the "=" sign correspond to server identifiers. + The left-hand side of the assignment is a colon-separated list of server + identifiers. Note that groups must be disjoint and the union of all groups + must be the ZooKeeper ensemble. + You will find an example [here](/docs/admin-ops/quorums) + +- _weight.x=nnnnn_ : + (No Java system property) + Used along with "group", it assigns a weight to a server when + forming quorums. Such a value corresponds to the weight of a server + when voting. There are a few parts of ZooKeeper that require voting + such as leader election and the atomic broadcast protocol. By default + the weight of server is 1. If the configuration defines groups, but not + weights, then a value of 1 will be assigned to all servers. + You will find an example [here](/docs/admin-ops/quorums) + +- _cnxTimeout_ : + (Java system property: zookeeper.**cnxTimeout**) + Sets the timeout value for opening connections for leader election notifications. + Only applicable if you are using electionAlg 3. + + Default value is 5 seconds. + +- _quorumCnxnTimeoutMs_ : + (Java system property: zookeeper.**quorumCnxnTimeoutMs**) + Sets the read timeout value for the connections for leader election notifications. + Only applicable if you are using electionAlg 3. + + + Default value is -1, which will then use the syncLimit * tickTime as the + timeout. + + +- _standaloneEnabled_ : + (No Java system property) + **New in 3.5.0:** + When set to false, a single server can be started in replicated + mode, a lone participant can run with observers, and a cluster + can reconfigure down to one node, and up from one node. The + default is true for backwards compatibility. It can be set + using QuorumPeerConfig's setStandaloneEnabled method or by + adding "standaloneEnabled=false" or "standaloneEnabled=true" + to a server's config file. + +- _reconfigEnabled_ : + (No Java system property) + **New in 3.5.3:** + This controls the enabling or disabling of + [Dynamic Reconfiguration](/docs/admin-ops/dynamic-reconfiguration) feature. When the feature + is enabled, users can perform reconfigure operations through + the ZooKeeper client API or through ZooKeeper command line tools + assuming users are authorized to perform such operations. + When the feature is disabled, no user, including the super user, + can perform a reconfiguration. Any attempt to reconfigure will return an error. + **"reconfigEnabled"** option can be set as + **"reconfigEnabled=false"** or + **"reconfigEnabled=true"** + to a server's config file, or using QuorumPeerConfig's + setReconfigEnabled method. The default value is false. + If present, the value should be consistent across every server in + the entire ensemble. Setting the value as true on some servers and false + on other servers will cause inconsistent behavior depending on which server + is elected as leader. If the leader has a setting of + **"reconfigEnabled=true"**, then the ensemble + will have reconfig feature enabled. If the leader has a setting of + **"reconfigEnabled=false"**, then the ensemble + will have reconfig feature disabled. It is thus recommended having a consistent + value for **"reconfigEnabled"** across servers + in the ensemble. + +- _4lw.commands.whitelist_ : + (Java system property: **zookeeper.4lw.commands.whitelist**) + **New in 3.5.3:** + A list of comma separated [Four Letter Words](/docs/admin-ops/administrators-guide/commands#the-four-letter-words) + commands that user wants to use. A valid Four Letter Words + command must be put in this list else ZooKeeper server will + not enable the command. + By default the whitelist only contains "srvr" command + which zkServer.sh uses. Additionally, if Read Only Mode is enabled by setting + Java system property **readonlymode.enabled**, then the "isro" command is + added to the whitelist. The rest of four-letter word commands are disabled + by default: attempting to use them will gain a response + ".... is not executed because it is not in the whitelist." + Here's an example of the configuration that enables stat, ruok, conf, and isro + command while disabling the rest of Four Letter Words command: + + ``` + 4lw.commands.whitelist=stat, ruok, conf, isro + ``` + + If you really need enable all four-letter word commands by default, you can use + the asterisk option so you don't have to include every command one by one in the list. + As an example, this will enable all four-letter word commands: + + ``` + 4lw.commands.whitelist=* + ``` + +- _tcpKeepAlive_ : + (Java system property: **zookeeper.tcpKeepAlive**) + **New in 3.5.4:** + Setting this to true sets the TCP keepAlive flag on the + sockets used by quorum members to perform elections. + This will allow for connections between quorum members to + remain up when there is network infrastructure that may + otherwise break them. Some NATs and firewalls may terminate + or lose state for long-running or idle connections. + Enabling this option relies on OS level settings to work + properly, check your operating system's options regarding TCP + keepalive for more information. Defaults to + **false**. + +- _clientTcpKeepAlive_ : + (Java system property: **zookeeper.clientTcpKeepAlive**) + **New in 3.6.1:** + Setting this to true sets the TCP keepAlive flag on the + client sockets. Some broken network infrastructure may lose + the FIN packet that is sent from closing client. These never + closed client sockets cause OS resource leak. Enabling this + option terminates these zombie sockets by idle check. + Enabling this option relies on OS level settings to work + properly, check your operating system's options regarding TCP + keepalive for more information. Defaults to **false**. Please + note the distinction between it and **tcpKeepAlive**. It is + applied for the client sockets while **tcpKeepAlive** is for + the sockets used by quorum members. Currently this option is + only available when default `NIOServerCnxnFactory` is used. + +- _electionPortBindRetry_ : + (Java system property only: **zookeeper.electionPortBindRetry**) + Property set max retry count when Zookeeper server fails to bind + leader election port. Such errors can be temporary and recoverable, + such as DNS issue described in [ZOOKEEPER-3320](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3320), + or non-retryable, such as port already in use. + In case of transient errors, this property can improve availability + of Zookeeper server and help it to self recover. + Default value 3. In container environment, especially in Kubernetes, + this value should be increased or set to 0(infinite retry) to overcome issues + related to DNS name resolving. + +- _observer.reconnectDelayMs_ : + (Java system property: **zookeeper.observer.reconnectDelayMs**) + When observer loses its connection with the leader, it waits for the + specified value before trying to reconnect with the leader so that + the entire observer fleet won't try to run leader election and reconnect + to the leader at once. + Defaults to 0 ms. + +- _observer.election.DelayMs_ : + (Java system property: **zookeeper.observer.election.DelayMs**) + Delay the observer's participation in a leader election upon disconnect + so as to prevent unexpected additional load on the voting peers during + the process. Defaults to 200 ms. + +- _localSessionsEnabled_ and _localSessionsUpgradingEnabled_ : + **New in 3.5:** + Optional value is true or false. Their default values are false. + Turning on the local session feature by setting _localSessionsEnabled=true_. Turning on + _localSessionsUpgradingEnabled_ can upgrade a local session to a global session automatically as required (e.g. creating ephemeral nodes), + which only matters when _localSessionsEnabled_ is enabled. + +## Encryption, Authentication, Authorization Options + +The options in this section allow control over +encryption/authentication/authorization performed by the service. + +Beside this page, you can also find useful information about client side configuration in the +[Programmers Guide](/docs/developer/programmers-guide/bindings#client-configuration-parameters). +The ZooKeeper Wiki also has useful pages about [ZooKeeper SSL support](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide), +and [SASL authentication for ZooKeeper](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+and+SASL). + +- _DigestAuthenticationProvider.enabled_ : + (Java system property: **zookeeper.DigestAuthenticationProvider.enabled**) + **New in 3.7:** + Determines whether the `digest` authentication provider is + enabled. The default value is **true** for backwards + compatibility, but it may be a good idea to disable this provider + if not used, as it can result in misleading entries appearing in + audit logs + (see [ZOOKEEPER-3979](https://issues.apache.org/jira/browse/ZOOKEEPER-3979)) + +- _DigestAuthenticationProvider.superDigest_ : + (Java system property: **zookeeper.DigestAuthenticationProvider.superDigest**) + By default this feature is **disabled** + **New in 3.2:** + Enables a ZooKeeper ensemble administrator to access the + znode hierarchy as a "super" user. In particular no ACL + checking occurs for a user authenticated as + super. + org.apache.zookeeper.server.auth.DigestAuthenticationProvider + can be used to generate the superDigest, call it with + one parameter of `"super:"`. Provide the + generated `"super:"` as the system property value + when starting each server of the ensemble. + When authenticating to a ZooKeeper server (from a + ZooKeeper client) pass a scheme of `"digest"` and authdata + of `"super:"`. Note that digest auth passes + the authdata in plaintext to the server, it would be + prudent to use this authentication method only on + localhost (not over the network) or over an encrypted + connection. + +- _DigestAuthenticationProvider.digestAlg_ : + (Java system property: **zookeeper.DigestAuthenticationProvider.digestAlg**) + **New in 3.7.0:** + Set ACL digest algorithm. The default value is: `SHA1` which will be deprecated in the future for security issues. + + Set this property the same value in all the servers. + - How to support other more algorithms? + - Modify the `java.security` configuration file under `$JAVA_HOME/jre/lib/security/java.security` by specifying + `security.provider.=`. + + For example: + + ``` + set zookeeper.DigestAuthenticationProvider.digestAlg=RipeMD160 + security.provider.3=org.bouncycastle.jce.provider.BouncyCastleProvider + ``` + + - Copy the jar file to `$JAVA_HOME/jre/lib/ext/`. + + For example: + + ``` + copy bcprov-jdk18on-1.60.jar to $JAVA_HOME/jre/lib/ext/ + ``` + + - How to migrate from one digest algorithm to another? + - Regenerate `superDigest` when migrating to new algorithm. + - Run `SetAcl` for a znode which already had a digest auth of old algorithm. + +- _IPAuthenticationProvider.usexforwardedfor_ : + (Java system property: **zookeeper.IPAuthenticationProvider.usexforwardedfor**) + **New in 3.9.3:** + IPAuthenticationProvider uses the client IP address to authenticate the user. By + default it reads the **Host** HTTP header to detect client IP address. In some + proxy configurations the proxy server adds the **X-Forwarded-For** header to + the request in order to provide the IP address of the original client request. + By enabling **usexforwardedfor** ZooKeeper setting, **X-Forwarded-For** will be preferred + over the standard **Host** header. + Default value is **false**. + +- _X509AuthenticationProvider.superUser_ : + (Java system property: **zookeeper.X509AuthenticationProvider.superUser**) + The SSL-backed way to enable a ZooKeeper ensemble + administrator to access the znode hierarchy as a "super" user. + When this parameter is set to an X500 principal name, only an + authenticated client with that principal will be able to bypass + ACL checking and have full privileges to all znodes. + +- _zookeeper.superUser_ : + (Java system property: **zookeeper.superUser**) + Similar to **zookeeper.X509AuthenticationProvider.superUser** + but is generic for SASL based logins. It stores the name of + a user that can access the znode hierarchy as a "super" user. + You can specify multiple SASL super users using the + **zookeeper.superUser.[suffix]** notation, e.g.: + `zookeeper.superUser.1=...`. + +- _ssl.authProvider_ : + (Java system property: **zookeeper.ssl.authProvider**) + Specifies a subclass of **org.apache.zookeeper.auth.X509AuthenticationProvider** + to use for secure client authentication. This is useful in + certificate key infrastructures that do not use JKS. It may be + necessary to extend **javax.net.ssl.X509KeyManager** and **javax.net.ssl.X509TrustManager** + to get the desired behavior from the SSL stack. To configure the + ZooKeeper server to use the custom provider for authentication, + choose a scheme name for the custom AuthenticationProvider and + set the property **zookeeper.authProvider.[scheme]** to the fully-qualified class name of the custom + implementation. This will load the provider into the ProviderRegistry. + Then set this property **zookeeper.ssl.authProvider=[scheme]** and that provider + will be used for secure authentication. + +- _zookeeper.ensembleAuthName_ : + (Java system property only: **zookeeper.ensembleAuthName**) + **New in 3.6.0:** + Specify a list of comma-separated valid names/aliases of an ensemble. A client + can provide the ensemble name it intends to connect as the credential for scheme "ensemble". The EnsembleAuthenticationProvider will check the credential against + the list of names/aliases of the ensemble that receives the connection request. + If the credential is not in the list, the connection request will be refused. + This prevents a client accidentally connecting to a wrong ensemble. + +- _sessionRequireClientSASLAuth_ : + (Java system property: **zookeeper.sessionRequireClientSASLAuth**) + **New in 3.6.0:** + When set to **true**, ZooKeeper server will only accept connections and requests from clients + that have authenticated with server via SASL. Clients that are not configured with SASL + authentication, or configured with SASL but failed authentication (i.e. with invalid credential) + will not be able to establish a session with server. A typed error code (-124) will be delivered + in such case, both Java and C client will close the session with server thereafter, + without further attempts on retrying to reconnect. + +This configuration is shorthand for **enforce.auth.enabled=true** and **enforce.auth.scheme=sasl** + +By default, this feature is disabled. Users who would like to opt-in can enable the feature +by setting **sessionRequireClientSASLAuth** to **true**. + +This feature overrules the zookeeper.allowSaslFailedClients option, so even if server is +configured to allow clients that fail SASL authentication to login, client will not be able to +establish a session with server if this feature is enabled. + +- _enforce.auth.enabled_ : + (Java system property : **zookeeper.enforce.auth.enabled**) + **New in 3.7.0:** + When set to **true**, ZooKeeper server will only accept connections and requests from clients + that have authenticated with server via configured auth scheme. Authentication schemes + can be configured using property enforce.auth.schemes. Clients that are not + configured with the any of the auth scheme configured at server or configured but failed authentication (i.e. with invalid credential) + will not be able to establish a session with server. A typed error code (-124) will be delivered + in such case, both Java and C client will close the session with server thereafter, + without further attempts on retrying to reconnect. + +By default, this feature is disabled. Users who would like to opt-in can enable the feature +by setting **enforce.auth.enabled** to **true**. + +When **enforce.auth.enabled=true** and **enforce.auth.schemes=sasl** then + +zookeeper.allowSaslFailedClients configuration +is overruled. So even if server is configured to allow clients that fail SASL +authentication to login, client will not be able to establish a session with +server if this feature is enabled with sasl as authentication scheme. + +- _enforce.auth.schemes_ : + (Java system property : **zookeeper.enforce.auth.schemes**) + **New in 3.7.0:** + Comma separated list of authentication schemes. Clients must be authenticated with at least one + authentication scheme before doing any zookeeper operations. + This property is used only when **enforce.auth.enabled** is to **true**. + +- _sslQuorum_ : + (Java system property: **zookeeper.sslQuorum**) + **New in 3.5.5:** + Enables encrypted quorum communication. Default is `false`. When enabling this feature, please also consider enabling _leader.closeSocketAsync_ + and _learner.closeSocketAsync_ to avoid issues associated with the potentially long socket closing time when shutting down an SSL connection. + +- _ssl.keyStore.location and ssl.keyStore.password_ and _ssl.quorum.keyStore.location_ and _ssl.quorum.keyStore.password_ : + (Java system properties: **zookeeper.ssl.keyStore.location** and **zookeeper.ssl.keyStore.password** and **zookeeper.ssl.quorum.keyStore.location** and **zookeeper.ssl.quorum.keyStore.password**) + **New in 3.5.5:** + Specifies the file path to a Java keystore containing the local + credentials to be used for client and quorum TLS connections, and the + password to unlock the file. + +- _ssl.keyStore.passwordPath_ and _ssl.quorum.keyStore.passwordPath_ : + (Java system properties: **zookeeper.ssl.keyStore.passwordPath** and **zookeeper.ssl.quorum.keyStore.passwordPath**) + **New in 3.8.0:** + Specifies the file path that contains the keystore password. Reading the password from a file takes precedence over + the explicit password property. + +- _ssl.keyStore.type_ and _ssl.quorum.keyStore.type_ : + (Java system properties: **zookeeper.ssl.keyStore.type** and **zookeeper.ssl.quorum.keyStore.type**) + **New in 3.5.5:** + Specifies the file format of client and quorum keystores. Values: JKS, PEM, PKCS12 or null (detect by filename). + Default: null. + **New in 3.5.10, 3.6.3, 3.7.0:** + The format BCFKS was added. + +- _ssl.trustStore.location_ and _ssl.trustStore.password_ and _ssl.quorum.trustStore.location_ and _ssl.quorum.trustStore.password_ : + (Java system properties: **zookeeper.ssl.trustStore.location** and **zookeeper.ssl.trustStore.password** and **zookeeper.ssl.quorum.trustStore.location** and **zookeeper.ssl.quorum.trustStore.password**) + **New in 3.5.5:** + Specifies the file path to a Java truststore containing the remote + credentials to be used for client and quorum TLS connections, and the + password to unlock the file. + +- _ssl.trustStore.passwordPath_ and _ssl.quorum.trustStore.passwordPath_ : + (Java system properties: **zookeeper.ssl.trustStore.passwordPath** and **zookeeper.ssl.quorum.trustStore.passwordPath**) + **New in 3.8.0:** + Specifies the file path that contains the truststore password. Reading the password from a file takes precedence over + the explicit password property. + +- _ssl.trustStore.type_ and _ssl.quorum.trustStore.type_ : + (Java system properties: **zookeeper.ssl.trustStore.type** and **zookeeper.ssl.quorum.trustStore.type**) + **New in 3.5.5:** + Specifies the file format of client and quorum trustStores. Values: JKS, PEM, PKCS12 or null (detect by filename). + Default: null. + **New in 3.5.10, 3.6.3, 3.7.0:** + The format BCFKS was added. + +- _ssl.protocol_ and _ssl.quorum.protocol_ : + (Java system properties: **zookeeper.ssl.protocol** and **zookeeper.ssl.quorum.protocol**) + **New in 3.5.5:** + Specifies to protocol to be used in client and quorum TLS negotiation. + Default: TLSv1.3 or TLSv1.2 depending on Java runtime version being used. + +- _ssl.enabledProtocols_ and _ssl.quorum.enabledProtocols_ : + (Java system properties: **zookeeper.ssl.enabledProtocols** and **zookeeper.ssl.quorum.enabledProtocols**) + **New in 3.5.5:** + Specifies the enabled protocols in client and quorum TLS negotiation. + Default: TLSv1.3, TLSv1.2 if value of `protocol` property is TLSv1.3. TLSv1.2 if `protocol` is TLSv1.2. + +- _ssl.ciphersuites_ and _ssl.quorum.ciphersuites_ : + (Java system properties: **zookeeper.ssl.ciphersuites** and **zookeeper.ssl.quorum.ciphersuites**) + **New in 3.5.5:** + Specifies the enabled cipher suites to be used in client and quorum TLS negotiation. + Default: JDK defaults since 3.10.0, and hard coded cipher suites for 3.9 and earlier versions. See [TLS Cipher Suites](#tls-cipher-suites). + +- _ssl.context.supplier.class_ and _ssl.quorum.context.supplier.class_ : + (Java system properties: **zookeeper.ssl.context.supplier.class** and **zookeeper.ssl.quorum.context.supplier.class**) + **New in 3.5.5:** + Specifies the class to be used for creating SSL context in client and quorum SSL communication. + This allows you to use custom SSL context and implement the following scenarios: 1. Use hardware keystore, loaded in using PKCS11 or something similar. 2. You don't have access to the software keystore, but can retrieve an already-constructed SSLContext from their container. + Default: null + +- _ssl.hostnameVerification_ and _ssl.quorum.hostnameVerification_ : + (Java system properties: **zookeeper.ssl.hostnameVerification** and **zookeeper.ssl.quorum.hostnameVerification**) + **New in 3.5.5:** + Specifies whether the hostname verification is enabled in client and quorum TLS negotiation process. + Disabling it only recommended for testing purposes. + Default: true + +- _ssl.clientHostnameVerification_ and _ssl.quorum.clientHostnameVerification_ : + (Java system properties: **zookeeper.ssl.clientHostnameVerification** and **zookeeper.ssl.quorum.clientHostnameVerification**) + **New in 3.9.4:** + Specifies whether the client's hostname verification is enabled in client and quorum TLS negotiation process. + This option requires the corresponding _hostnameVerification_ option to be `true`, or it will be ignored. + Default: true for quorum, false for clients + +- _ssl.allowReverseDnsLookup_ and _ssl.quorum.allowReverseDnsLookup_ : + (Java system properties: **zookeeper.ssl.allowReverseDnsLookup** and **zookeeper.ssl.quorum.allowReverseDnsLookup**) + **New in 3.9.5:** + Allow reverse DNS lookup in both server- and client hostname verifications if the hostname verification is enabled in + `ZKTrustManager`. Supported in both quorum and client TLS protocols. Not supported in FIPS mode. Reverse DNS lookups are + expensive and unnecessary in most cases. Make sure that certificates are created with all required Subject Alternative + Names (SAN) for successful identity verification. It's recommended to add SAN:IP entries for identity verification + of client certificates. + Default: false + +- _ssl.crl_ and _ssl.quorum.crl_ : + (Java system properties: **zookeeper.ssl.crl** and **zookeeper.ssl.quorum.crl**) + **New in 3.5.5:** + Specifies whether Certificate Revocation List is enabled in client and quorum TLS protocols. + Default: jvm property "com.sun.net.ssl.checkRevocation" since 3.10.0, false otherwise + +- _ssl.ocsp_ and _ssl.quorum.ocsp_ : + (Java system properties: **zookeeper.ssl.ocsp** and **zookeeper.ssl.quorum.ocsp**) + **New in 3.5.5:** + Specifies whether Online Certificate Status Protocol is enabled in client and quorum TLS protocols. + **Changed in 3.10.0:** + Before 3.10.0, _ssl.ocsp_ and _ssl.quorum.ocsp_ implies _ssl.crl_ and _ssl.quorum.crl_ correspondingly. + After 3.10.0, one has to setup both _ssl.crl_ and _ssl.ocsp_ (or _ssl.quorum.crl_ and _ssl.quorum.ocsp_) + to enable OCSP. This is consistent with jdk's method of [Setting up a Java Client to use Client-Driven OCSP](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ocsp.html#setting-up-a-java-client-to-use-client-driven-ocsp). + Default: jvm security property "ocsp.enable" since 3.10.0, false otherwise + +- _ssl.clientAuth_ and _ssl.quorum.clientAuth_ : + (Java system properties: **zookeeper.ssl.clientAuth** and **zookeeper.ssl.quorum.clientAuth**) + **Added in 3.5.5, but broken until 3.5.7:** + Specifies options to authenticate ssl connections from clients. Valid values are + + * "none": server will not request client authentication + * "want": server will "request" client authentication + * "need": server will "require" client authentication + + Default: "need" + +- _ssl.handshakeDetectionTimeoutMillis_ and _ssl.quorum.handshakeDetectionTimeoutMillis_ : + (Java system properties: **zookeeper.ssl.handshakeDetectionTimeoutMillis** and **zookeeper.ssl.quorum.handshakeDetectionTimeoutMillis**) + **New in 3.5.5:** + TBD + +- _ssl.sslProvider_ : + (Java system property: **zookeeper.ssl.sslProvider**) + **New in 3.9.0:** + Allows to select SSL provider in the client-server communication when TLS is enabled. Netty-tcnative native library + has been added to ZooKeeper in version 3.9.0 which allows us to use native SSL libraries like OpenSSL on supported + platforms. See the available options in Netty-tcnative documentation. Default value is "JDK". + +- _sslQuorumReloadCertFiles_ : + (No Java system property) + **New in 3.5.5, 3.6.0:** + Allows Quorum SSL keyStore and trustStore reloading when the certificates on the filesystem change without having to restart the ZK process. Default: false + +- _client.certReload_ : + (Java system property: **zookeeper.client.certReload**) + **New in 3.7.2, 3.8.1, 3.9.0:** + Allows client SSL keyStore and trustStore reloading when the certificates on the filesystem change without having to restart the ZK process. Default: false + +- _client.portUnification_: + (Java system property: **zookeeper.client.portUnification**) + Specifies that the client port should accept SSL connections + (using the same configuration as the secure client port). + Default: false + +- _authProvider_: + (Java system property: **zookeeper.authProvider**) + You can specify multiple authentication provider classes for ZooKeeper. + Usually you use this parameter to specify the SASL authentication provider + like: `authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider` + +- _kerberos.removeHostFromPrincipal_ + (Java system property: **zookeeper.kerberos.removeHostFromPrincipal**) + You can instruct ZooKeeper to remove the host from the client principal name during authentication. + (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk@EXAMPLE.COM) + Default: false + +- _kerberos.removeRealmFromPrincipal_ + (Java system property: **zookeeper.kerberos.removeRealmFromPrincipal**) + You can instruct ZooKeeper to remove the realm from the client principal name during authentication. + (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk/myhost) + Default: false + +- _kerberos.canonicalizeHostNames_ + (Java system property: **zookeeper.kerberos.canonicalizeHostNames**) + **New in 3.7.0:** + Instructs ZooKeeper to canonicalize server host names extracted from _server.x_ lines. + This allows using e.g. `CNAME` records to reference servers in configuration files, while still enabling SASL Kerberos authentication between quorum members. + It is essentially the quorum equivalent of the _zookeeper.sasl.client.canonicalize.hostname_ property for clients. + The default value is **false** for backwards compatibility. + +- _multiAddress.enabled_ : + (Java system property: **zookeeper.multiAddress.enabled**) + **New in 3.6.0:** + Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#cluster-options) + for each ZooKeeper server instance (this can increase availability when multiple physical + network interfaces can be used parallel in the cluster). Setting this parameter to + **true** will enable this feature. Please note, that you can not enable this feature + during a rolling upgrade if the version of the old ZooKeeper cluster is prior to 3.6.0. + The default value is **false**. + +- _multiAddress.reachabilityCheckTimeoutMs_ : + (Java system property: **zookeeper.multiAddress.reachabilityCheckTimeoutMs**) + **New in 3.6.0:** + Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#cluster-options) + for each ZooKeeper server instance (this can increase availability when multiple physical + network interfaces can be used parallel in the cluster). ZooKeeper will perform ICMP ECHO requests + or try to establish a TCP connection on port 7 (Echo) of the destination host in order to find + the reachable addresses. This happens only if you provide multiple addresses in the configuration. + In this property you can set the timeout in milliseconds for the reachability check. The check happens + in parallel for the different addresses, so the timeout you set here is the maximum time will be taken + by checking the reachability of all addresses. + The default value is **1000**. + + This parameter has no effect, unless you enable the MultiAddress feature by setting _multiAddress.enabled=true_. + +- _fips-mode_ : + (Java system property: **zookeeper.fips-mode**) + **New in 3.8.2:** + Enable FIPS compatibility mode in ZooKeeper. If enabled, the following things will be changed in order to comply + with FIPS requirements: + - Custom trust manager (`ZKTrustManager`) that is used for hostname verification will be disabled. As a consequence, + hostname verification is not available in the Quorum protocol, but still can be set in client-server communication. + - DIGEST-MD5 Sasl auth mechanism will be disabled in Quorum and ZooKeeper Sasl clients. Only GSSAPI (Kerberos) + can be used. + + Default: **true** (3.9.0+), **false** (3.8.x) + +## TLS Cipher Suites + +From 3.5.5 to 3.9 a hard coded default cipher list was used, with the ordering +dependent on whether it is run Java 8 or a later version. + +The list on Java 8 includes TLSv1.2 CBC, GCM and TLSv1.3 ciphers in ordering: _TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256_ + +The list on Java 9+ includes TLSv1.2 GCM, CBC and TLSv1.3 ciphers in ordering: _TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA, TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256, TLS_CHACHA20_POLY1305_SHA256_ + +Since 3.10 there is no hardcoded list, and the JDK defaults are used. + +## Experimental Options/Features + +New features that are currently considered experimental. + +- _Read Only Mode Server_ : + (Java system property: **readonlymode.enabled**) + **New in 3.4.0:** + Setting this value to true enables Read Only Mode server + support (disabled by default). + _localSessionsEnabled_ has to be activated to serve clients. + A downgrade of an existing connections is currently not supported. + ROM allows clients sessions which requested ROM support to connect to the + server even when the server might be partitioned from + the quorum. In this mode ROM clients can still read + values from the ZK service, but will be unable to write + values and see changes from other clients. See + ZOOKEEPER-784 for more details. + +- _zookeeper.follower.skipLearnerRequestToNextProcessor_ : + (Java system property: **zookeeper.follower.skipLearnerRequestToNextProcessor**) + When our cluster has observers which are connected with ObserverMaster, then turning on this flag might help + you reduce some memory pressure on the Observer Master. If your cluster doesn't have any observers or + they are not connected with ObserverMaster or your Observer's don't make much writes, then using this flag + won't help you. + Currently the change here is guarded behind the flag to help us get more confidence around the memory gains. + In Long run, we might want to remove this flag and set its behavior as the default codepath. + +## Unsafe Options + +The following options can be useful, but be careful when you use +them. The risk of each is explained along with the explanation of what +the variable does. + +- _forceSync_ : + (Java system property: **zookeeper.forceSync**) + Requires updates to be synced to media of the transaction + log before finishing processing the update. If this option is + set to no, ZooKeeper will not require updates to be synced to + the media. + +- _jute.maxbuffer_ : + (Java system property:**jute.maxbuffer**). + - This option can only be set as a Java system property. + There is no zookeeper prefix on it. It specifies the maximum + size of the data that can be stored in a znode. The unit is: byte. The default is + 0xfffff(1048575) bytes, or just under 1M. + - If this option is changed, the system property must be set on all servers and clients otherwise + problems will arise. + - When _jute.maxbuffer_ in the client side is greater than the server side, the client wants to write the data + exceeds _jute.maxbuffer_ in the server side, the server side will get **java.io.IOException: Len error** + - When _jute.maxbuffer_ in the client side is less than the server side, the client wants to read the data + exceeds _jute.maxbuffer_ in the client side, the client side will get **java.io.IOException: Unreasonable length** + or **Packet len is out of range!** + - This is really a sanity check. ZooKeeper is designed to store data on the order of kilobytes in size. + In the production environment, increasing this property to exceed the default value is not recommended for the following reasons: + - Large size znodes cause unwarranted latency spikes, worsen the throughput + - Large size znodes make the synchronization time between leader and followers unpredictable and non-convergent(sometimes timeout), cause the quorum unstable + +- _jute.maxbuffer.extrasize_: + (Java system property: **zookeeper.jute.maxbuffer.extrasize**) + **New in 3.5.7:** + While processing client requests ZooKeeper server adds some additional information into + the requests before persisting it as a transaction. Earlier this additional information size + was fixed to 1024 bytes. For many scenarios, specially scenarios where jute.maxbuffer value + is more than 1 MB and request type is multi, this fixed size was insufficient. + To handle all the scenarios additional information size is increased from 1024 byte + to same as jute.maxbuffer size and also it is made configurable through jute.maxbuffer.extrasize. + Generally this property is not required to be configured as default value is the most optimal value. + +- _skipACL_ : + (Java system property: **zookeeper.skipACL**) + Skips ACL checks. This results in a boost in throughput, + but opens up full access to the data tree to everyone. + +- _quorumListenOnAllIPs_ : + When set to true the ZooKeeper server will listen + for connections from its peers on all available IP addresses, + and not only the address configured in the server list of the + configuration file. It affects the connections handling the + ZAB protocol and the Fast Leader Election protocol. Default + value is **false**. + +- _multiAddress.reachabilityCheckEnabled_ : + (Java system property: **zookeeper.multiAddress.reachabilityCheckEnabled**) + **New in 3.6.0:** + Since ZooKeeper 3.6.0 you can also [specify multiple addresses](#cluster-options) + for each ZooKeeper server instance (this can increase availability when multiple physical + network interfaces can be used parallel in the cluster). ZooKeeper will perform ICMP ECHO requests + or try to establish a TCP connection on port 7 (Echo) of the destination host in order to find + the reachable addresses. This happens only if you provide multiple addresses in the configuration. + The reachable check can fail if you hit some ICMP rate-limitation, (e.g. on macOS) when you try to + start a large (e.g. 11+) ensemble members cluster on a single machine for testing. + + Default value is **true**. By setting this parameter to 'false' you can disable the reachability checks. + Please note, disabling the reachability check will cause the cluster not to be able to reconfigure + itself properly during network problems, so the disabling is advised only during testing. + + This parameter has no effect, unless you enable the MultiAddress feature by setting _multiAddress.enabled=true_. + +## Disabling data directory autocreation + +**New in 3.5:** The default +behavior of a ZooKeeper server is to automatically create the +data directory (specified in the configuration file) when +started if that directory does not already exist. This can be +inconvenient and even dangerous in some cases. Take the case +where a configuration change is made to a running server, +wherein the **dataDir** parameter +is accidentally changed. When the ZooKeeper server is +restarted it will create this non-existent directory and begin +serving - with an empty znode namespace. This scenario can +result in an effective "split brain" situation (i.e. data in +both the new invalid directory and the original valid data +store). As such is would be good to have an option to turn off +this autocreate behavior. In general for production +environments this should be done, unfortunately however the +default legacy behavior cannot be changed at this point and +therefore this must be done on a case by case basis. This is +left to users and to packagers of ZooKeeper distributions. + +When running **zkServer.sh** autocreate can be disabled +by setting the environment variable **ZOO_DATADIR_AUTOCREATE_DISABLE** to 1. +When running ZooKeeper servers directly from class files this +can be accomplished by setting **zookeeper.datadir.autocreate=false** on +the java command line, i.e. **-Dzookeeper.datadir.autocreate=false** + +When this feature is disabled, and the ZooKeeper server +determines that the required directories do not exist it will +generate an error and refuse to start. + +A new script **zkServer-initialize.sh** is provided to +support this new feature. If autocreate is disabled it is +necessary for the user to first install ZooKeeper, then create +the data directory (and potentially txnlog directory), and +then start the server. Otherwise as mentioned in the previous +paragraph the server will not start. Running **zkServer-initialize.sh** will create the +required directories, and optionally set up the myid file +(optional command line parameter). This script can be used +even if the autocreate feature itself is not used, and will +likely be of use to users as this (setup, including creation +of the myid file) has been an issue for users in the past. +Note that this script ensures the data directories exist only, +it does not create a config file, but rather requires a config +file to be available in order to execute. + +## Enabling db existence validation + +**New in 3.6.0:** The default +behavior of a ZooKeeper server on startup when no data tree +is found is to set zxid to zero and join the quorum as a +voting member. This can be dangerous if some event (e.g. a +rogue 'rm -rf') has removed the data directory while the +server was down since this server may help elect a leader +that is missing transactions. Enabling db existence validation +will change the behavior on startup when no data tree is +found: the server joins the ensemble as a non-voting participant +until it is able to sync with the leader and acquire an up-to-date +version of the ensemble data. To indicate an empty data tree is +expected (ensemble creation), the user should place a file +'initialize' in the same directory as 'myid'. This file will +be detected and deleted by the server on startup. + +Initialization validation can be enabled when running +ZooKeeper servers directly from class files by setting +**zookeeper.db.autocreate=false** +on the java command line, i.e. +**-Dzookeeper.db.autocreate=false**. +Running **zkServer-initialize.sh** +will create the required initialization file. + +## Performance Tuning Options + +**New in 3.5.0:** Several subsystems have been reworked +to improve read throughput. This includes multi-threading of the NIO communication subsystem and +request processing pipeline (Commit Processor). NIO is the default client/server communication +subsystem. Its threading model comprises 1 acceptor thread, 1-N selector threads and 0-M +socket I/O worker threads. In the request processing pipeline the system can be configured +to process multiple read request at once while maintaining the same consistency guarantee +(same-session read-after-write). The Commit Processor threading model comprises 1 main +thread and 0-N worker threads. + +The default values are aimed at maximizing read throughput on a dedicated ZooKeeper machine. +Both subsystems need to have sufficient amount of threads to achieve peak read throughput. + +- _zookeeper.nio.numSelectorThreads_ : + (Java system property only: **zookeeper.nio.numSelectorThreads**) + **New in 3.5.0:** + Number of NIO selector threads. At least 1 selector thread required. + It is recommended to use more than one selector for large numbers + of client connections. The default value is sqrt( number of cpu cores / 2 ). + +- _zookeeper.nio.numWorkerThreads_ : + (Java system property only: **zookeeper.nio.numWorkerThreads**) + **New in 3.5.0:** + Number of NIO worker threads. If configured with 0 worker threads, the selector threads + do the socket I/O directly. The default value is 2 times the number of cpu cores. + +- _zookeeper.commitProcessor.numWorkerThreads_ : + (Java system property only: **zookeeper.commitProcessor.numWorkerThreads**) + **New in 3.5.0:** + Number of Commit Processor worker threads. If configured with 0 worker threads, the main thread + will process the request directly. The default value is the number of cpu cores. + +- _zookeeper.commitProcessor.maxReadBatchSize_ : + (Java system property only: **zookeeper.commitProcessor.maxReadBatchSize**) + Max number of reads to process from queuedRequests before switching to processing commits. + If the value < 0 (default), we switch whenever we have a local write, and pending commits. + A high read batch size will delay commit processing, causing stale data to be served. + If reads are known to arrive in fixed size batches then matching that batch size with + the value of this property can smooth queue performance. Since reads are handled in parallel, + one recommendation is to set this property to match _zookeeper.commitProcessor.numWorkerThread_ + (default is the number of cpu cores) or lower. + +- _zookeeper.commitProcessor.maxCommitBatchSize_ : + (Java system property only: **zookeeper.commitProcessor.maxCommitBatchSize**) + Max number of commits to process before processing reads. We will try to process as many + remote/local commits as we can till we reach this count. A high commit batch size will delay + reads while processing more commits. A low commit batch size will favor reads. + It is recommended to only set this property when an ensemble is serving a workload with a high + commit rate. If writes are known to arrive in a set number of batches then matching that + batch size with the value of this property can smooth queue performance. A generic + approach would be to set this value to equal the ensemble size so that with the processing + of each batch the current server will probabilistically handle a write related to one of + its direct clients. + Default is "1". Negative and zero values are not supported. + +- _znode.container.checkIntervalMs_ : + (Java system property only) + **New in 3.6.0:** The + time interval in milliseconds for each check of candidate container + and ttl nodes. Default is "60000". + +- _znode.container.maxPerMinute_ : + (Java system property only) + **New in 3.6.0:** The + maximum number of container and ttl nodes that can be deleted per + minute. This prevents herding during container deletion. + Default is "10000". + +- _znode.container.maxNeverUsedIntervalMs_ : + (Java system property only) + **New in 3.6.0:** The + maximum interval in milliseconds that a container that has never had + any children is retained. Should be long enough for your client to + create the container, do any needed work and then create children. + Default is "300000"(a.k.a. 5 minutes) since 3.10.0, for earlier versions, + it is "0" which is used to indicate that containers that have never had + any children are never deleted. + +## Debug Observability Configurations + +**New in 3.6.0:** The following options are introduced to make zookeeper easier to debug. + +- _zookeeper.messageTracker.BufferSize_ : + (Java system property only) + Controls the maximum number of messages stored in **MessageTracker**. Value should be positive + integers. The default value is 10. **MessageTracker** is introduced in **3.6.0** to record the + last set of messages between a server (follower or observer) and a leader, when a server + disconnects with leader. These set of messages will then be dumped to zookeeper's log file, + and will help reconstruct the state of the servers at the time of the disconnection and + will be useful for debugging purpose. + +- _zookeeper.messageTracker.Enabled_ : + (Java system property only) + When set to "true", will enable **MessageTracker** to track and record messages. Default value + is "false". + +## AdminServer configuration + +**New in 3.9.0:** The following +options are used to configure the [AdminServer](#adminserver-configuration). + +- _admin.rateLimiterIntervalInMS_ : + (Java system property: **zookeeper.admin.rateLimiterIntervalInMS**) + The time interval for rate limiting admin command to protect the server. + Defaults to 5 mins. + +- _admin.snapshot.enabled_ : + (Java system property: **zookeeper.admin.snapshot.enabled**) + The flag for enabling the snapshot command. Defaults to true. +- _admin.restore.enabled_ : + (Java system property: **zookeeper.admin.restore.enabled**) + The flag for enabling the restore command. Defaults to true. + +- _admin.needClientAuth_ : + (Java system property: **zookeeper.admin.needClientAuth**) + The flag to control whether client auth is needed. Using x509 auth requires true. + Defaults to false. + + **New in 3.7.1:** The following + options are used to configure the [AdminServer](#adminserver-configuration). + +- _admin.forceHttps_ : + (Java system property: **zookeeper.admin.forceHttps**) + Force AdminServer to use SSL, thus allowing only HTTPS traffic. + Defaults to disabled. + Overwrites **admin.portUnification** settings. + + **New in 3.6.0:** The following + options are used to configure the [AdminServer](#adminserver-configuration). + +- _admin.portUnification_ : + (Java system property: **zookeeper.admin.portUnification**) + Enable the admin port to accept both HTTP and HTTPS traffic. + Defaults to disabled. + + **New in 3.5.0:** The following + options are used to configure the [AdminServer](#adminserver-configuration). + +- _admin.enableServer_ : + (Java system property: **zookeeper.admin.enableServer**) + Set to "false" to disable the AdminServer. By default the + AdminServer is enabled. + +- _admin.serverAddress_ : + (Java system property: **zookeeper.admin.serverAddress**) + The address the embedded Jetty server listens on. Defaults to 0.0.0.0. + +- _admin.serverPort_ : + (Java system property: **zookeeper.admin.serverPort**) + The port the embedded Jetty server listens on. Defaults to 8080. + +- _admin.idleTimeout_ : + (Java system property: **zookeeper.admin.idleTimeout**) + Set the maximum idle time in milliseconds that a connection can wait + before sending or receiving data. Defaults to 30000 ms. + +- _admin.commandURL_ : + (Java system property: **zookeeper.admin.commandURL**) + The URL for listing and issuing commands relative to the + root URL. Defaults to "/commands". diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/data-file-management.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/data-file-management.mdx new file mode 100644 index 00000000000..7aeb4635566 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/data-file-management.mdx @@ -0,0 +1,94 @@ +--- +title: "Data File Management" +description: "Describes how ZooKeeper manages its data and transaction log directories, snapshot and log file lifecycle, file cleanup, and recovery using the TxnLogToolkit." +--- + +ZooKeeper stores its data in a data directory and its transaction +log in a transaction log directory. By default these two directories are +the same. The server can (and should) be configured to store the +transaction log files in a separate directory than the data files. +Throughput increases and latency decreases when transaction logs reside +on a dedicated log devices. + +## The Data Directory + +This directory has two or three files in it: + +- _myid_ - contains a single integer in + human readable ASCII text that represents the server id. +- _initialize_ - presence indicates lack of + data tree is expected. Cleaned up once data tree is created. +- _snapshot.\_ - holds the fuzzy + snapshot of a data tree. + +Each ZooKeeper server has a unique id. This id is used in two +places: the _myid_ file and the configuration file. +The _myid_ file identifies the server that +corresponds to the given data directory. The configuration file lists +the contact information for each server identified by its server id. +When a ZooKeeper server instance starts, it reads its id from the +_myid_ file and then, using that id, reads from the +configuration file, looking up the port on which it should +listen. + +The _snapshot_ files stored in the data +directory are fuzzy snapshots in the sense that during the time the +ZooKeeper server is taking the snapshot, updates are occurring to the +data tree. The suffix of the _snapshot_ file names +is the _zxid_, the ZooKeeper transaction id, of the +last committed transaction at the start of the snapshot. Thus, the +snapshot includes a subset of the updates to the data tree that +occurred while the snapshot was in process. The snapshot, then, may +not correspond to any data tree that actually existed, and for this +reason we refer to it as a fuzzy snapshot. Still, ZooKeeper can +recover using this snapshot because it takes advantage of the +idempotent nature of its updates. By replaying the transaction log +against fuzzy snapshots ZooKeeper gets the state of the system at the +end of the log. + +## The Log Directory + +The Log Directory contains the ZooKeeper transaction logs. +Before any update takes place, ZooKeeper ensures that the transaction +that represents the update is written to non-volatile storage. A new +log file is started when the number of transactions written to the +current log file reaches a (variable) threshold. The threshold is +computed using the same parameter which influences the frequency of +snapshotting (see snapCount and snapSizeLimitInKb above). The log file's +suffix is the first zxid written to that log. + +## File Management + +The format of snapshot and log files does not change between +standalone ZooKeeper servers and different configurations of +replicated ZooKeeper servers. Therefore, you can pull these files from +a running replicated ZooKeeper server to a development machine with a +stand-alone ZooKeeper server for troubleshooting. + +Using older log and snapshot files, you can look at the previous +state of ZooKeeper servers and even restore that state. + +The ZooKeeper server creates snapshot and log files, but +never deletes them. The retention policy of the data and log +files is implemented outside of the ZooKeeper server. The +server itself only needs the latest complete fuzzy snapshot, all log +files following it, and the last log file preceding it. The latter +requirement is necessary to include updates which happened after this +snapshot was started but went into the existing log file at that time. +This is possible because snapshotting and rolling over of logs +proceed somewhat independently in ZooKeeper. See the +[maintenance](/docs/admin-ops/administrators-guide/administration#maintenance) section +for more details on setting a retention policy +and maintenance of ZooKeeper storage. + + + The data stored in these files is not encrypted. In the case of storing + sensitive data in ZooKeeper, necessary measures need to be taken to prevent + unauthorized access. Such measures are external to ZooKeeper (e.g., control + access to the files) and depend on the individual settings in which it is + being deployed. + + +## Recovery - TxnLogToolkit + +More details can be found in [this](/docs/admin-ops/tools#zktxnlogtoolkitsh) diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/deployment.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/deployment.mdx new file mode 100644 index 00000000000..8f8ad7ad012 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/deployment.mdx @@ -0,0 +1,280 @@ +--- +title: "Deployment" +description: "Covers ZooKeeper deployment requirements and setup: supported platforms, system requirements, clustered multi-server ensemble configuration, and single-server developer setup." +--- + +This section contains information about deploying Zookeeper and +covers these topics: + +- [System Requirements](#system-requirements) +- [Clustered (Multi-Server) Setup](#clustered-multi-server-setup) +- [Single Server and Developer Setup](#single-server-and-developer-setup) + +The first two sections assume you are interested in installing +ZooKeeper in a production environment such as a datacenter. The final +section covers situations in which you are setting up ZooKeeper on a +limited basis - for evaluation, testing, or development - but not in a +production environment. + +## System Requirements + +### Supported Platforms + +ZooKeeper consists of multiple components. Some components are +supported broadly, and other components are supported only on a smaller +set of platforms. + +- **Client** is the Java client + library, used by applications to connect to a ZooKeeper ensemble. +- **Server** is the Java server + that runs on the ZooKeeper ensemble nodes. +- **Native Client** is a client + implemented in C, similar to the Java client, used by applications + to connect to a ZooKeeper ensemble. +- **Contrib** refers to multiple + optional add-on components. + +The following matrix describes the level of support committed for +running each component on different operating system platforms. + +### Support Matrix + +| Operating System | Client | Server | Native Client | Contrib | +| ---------------- | -------------------------- | -------------------------- | -------------------------- | -------------------------- | +| GNU/Linux | Development and Production | Development and Production | Development and Production | Development and Production | +| Solaris | Development and Production | Development and Production | Not Supported | Not Supported | +| FreeBSD | Development and Production | Development and Production | Not Supported | Not Supported | +| Windows | Development and Production | Development and Production | Not Supported | Not Supported | +| Mac OS X | Development Only | Development Only | Not Supported | Not Supported | + +For any operating system not explicitly mentioned as supported in +the matrix, components may or may not work. The ZooKeeper community +will fix obvious bugs that are reported for other platforms, but there +is no full support. + +### Required Software + +ZooKeeper runs in Java, release 1.8 or greater +(JDK 8 LTS, JDK 11 LTS, JDK 12 - Java 9 and 10 are not supported). +It runs as an _ensemble_ of ZooKeeper servers. Three +ZooKeeper servers is the minimum recommended size for an +ensemble, and we also recommend that they run on separate +machines. At Yahoo!, ZooKeeper is usually deployed on +dedicated RHEL boxes, with dual-core processors, 2GB of RAM, +and 80GB IDE hard drives. + +## Clustered (Multi-Server) Setup + +For reliable ZooKeeper service, you should deploy ZooKeeper in a +cluster known as an _ensemble_. As long as a majority +of the ensemble are up, the service will be available. Because Zookeeper +requires a majority, it is best to use an +odd number of machines. For example, with four machines ZooKeeper can +only handle the failure of a single machine; if two machines fail, the +remaining two machines do not constitute a majority. However, with five +machines ZooKeeper can handle the failure of two machines. + + + As mentioned in the [ZooKeeper Getting Started + Guide](/docs/overview/quick-start), a minimum of three servers are required + for a fault tolerant clustered setup, and it is strongly recommended that you + have an odd number of servers. + +Usually three servers is more than enough for a production +install, but for maximum reliability during maintenance, you may +wish to install five servers. With three servers, if you perform +maintenance on one of them, you are vulnerable to a failure on one +of the other two servers during that maintenance. If you have five +of them running, you can take one down for maintenance, and know +that you're still OK if one of the other four suddenly fails. + +Your redundancy considerations should include all aspects of +your environment. If you have three ZooKeeper servers, but their +network cables are all plugged into the same network switch, then +the failure of that switch will take down your entire ensemble. + + + +Here are the steps to set a server that will be part of an +ensemble. These steps should be performed on every host in the +ensemble: + + + + Install the Java JDK. You can use the native packaging system for your system, or download + the JDK from: [http://java.sun.com/javase/downloads/index.jsp](http://java.sun.com/javase/downloads/index.jsp) + + + Set the Java heap size. This is very important to avoid swapping, which will seriously degrade + ZooKeeper performance. To determine the correct value, use load tests, and make sure you are + well below the usage limit that would cause you to swap. Be conservative — use a maximum heap + size of 3GB for a 4GB machine. + + + Install the ZooKeeper Server Package. It can be downloaded + from: [/releases](/releases) + + + Create a configuration file. This file can be called anything. Use the following settings as a + starting point: + +``` +tickTime=2000 +dataDir=/var/lib/zookeeper/ +clientPort=2181 +initLimit=5 +syncLimit=2 +server.1=zoo1:2888:3888 +server.2=zoo2:2888:3888 +server.3=zoo3:2888:3888 +``` + + You can find the meanings of these and other configuration settings in the section + [Configuration Parameters](/docs/admin-ops/administrators-guide/configuration-parameters). Every machine that is part of the ZooKeeper + ensemble should know about every other machine in the ensemble. You accomplish this with the + series of lines of the form **server.id=host:port:port**. (The parameters **host** and **port** + are straightforward; for each server you need to specify first a Quorum port then a dedicated + port for ZooKeeper leader election). Since ZooKeeper 3.6.0 you can also + specify multiple addresses for each ZooKeeper server instance (this can + increase availability when multiple physical network interfaces can be used parallel in the + cluster). You attribute the server id to each machine by creating a file named _myid_, one for + each server, which resides in that server's data directory, as specified by the configuration + file parameter **dataDir**. + + + + The _myid_ file consists of a single line containing only the text of that machine's id. So + _myid_ of server 1 would contain the text "1" and nothing else. The id must be unique within + the ensemble and should have a value between 1 and 255. **IMPORTANT:** if you enable extended + features such as TTL Nodes (see below) the id must be between 1 and 254 due to internal + limitations. + + + Create an initialization marker file _initialize_ in the same directory as _myid_. This file + indicates that an empty data directory is expected. When present, an empty database is created + and the marker file deleted. When not present, an empty data directory will mean this peer will + not have voting rights and it will not populate the data directory until it communicates with + an active leader. Intended use is to only create this file when bringing up a new ensemble. + + + If your configuration file is set up, you can start a ZooKeeper server: + +``` +$ java -cp zookeeper.jar:lib/*:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.conf +``` + + QuorumPeerMain starts a ZooKeeper server; [JMX](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) + management beans are also registered which allows management through a JMX management console. + The [ZooKeeper JMX document](/docs/admin-ops/jmx) contains details on managing ZooKeeper with JMX. + See the script _bin/zkServer.sh_, which is included in the release, for an example of starting + server instances. + + + + Test your deployment by connecting to the hosts. In Java, you can run the following command to + execute simple operations: + +``` +$ bin/zkCli.sh -server 127.0.0.1:2181 +``` + + + + +## Single Server and Developer Setup + +If you want to set up ZooKeeper for development purposes, you will +probably want to set up a single server instance of ZooKeeper, and then +install either the Java or C client-side libraries and bindings on your +development machine. + +The steps to setting up a single server instance are the similar +to the above, except the configuration file is simpler. You can find the +complete instructions in the [Installing and +Running ZooKeeper in Single Server Mode](/docs/overview/quick-start#standalone-operation) section of the [ZooKeeper Getting Started +Guide](/docs/overview/quick-start). + +For information on installing the client side libraries, refer to +the [Bindings](/docs/developer/programmers-guide/bindings) +section of the [ZooKeeper +Programmer's Guide](/docs/developer/programmers-guide). + +## Designing a ZooKeeper Deployment + +The reliability of ZooKeeper rests on two basic assumptions. + +1. Only a minority of servers in a deployment + will fail. _Failure_ in this context + means a machine crash, or some error in the network that + partitions a server off from the majority. +1. Deployed machines operate correctly. To + operate correctly means to execute code correctly, to have + clocks that work properly, and to have storage and network + components that perform consistently. + +The sections below contain considerations for ZooKeeper +administrators to maximize the probability for these assumptions +to hold true. Some of these are cross-machines considerations, +and others are things you should consider for each and every +machine in your deployment. + +### Cross Machine Requirements + +For the ZooKeeper service to be active, there must be a +majority of non-failing machines that can communicate with +each other. For a ZooKeeper ensemble with N servers, +if N is odd, the ensemble is able to tolerate up to N/2 +server failures without losing any znode data; +if N is even, the ensemble is able to tolerate up to N/2-1 +server failures. + +For example, if we have a ZooKeeper ensemble with 3 servers, +the ensemble is able to tolerate up to 1 (3/2) server failures. +If we have a ZooKeeper ensemble with 5 servers, +the ensemble is able to tolerate up to 2 (5/2) server failures. +If the ZooKeeper ensemble with 6 servers, the ensemble +is also able to tolerate up to 2 (6/2-1) server failures +without losing data and prevent the "brain split" issue. + +ZooKeeper ensemble is usually has odd number of servers. +This is because with the even number of servers, +the capacity of failure tolerance is the same as +the ensemble with one less server +(2 failures for both 5-node ensemble and 6-node ensemble), +but the ensemble has to maintain extra connections and +data transfers for one more server. + +To achieve the highest probability of tolerating a failure +you should try to make machine failures independent. For +example, if most of the machines share the same switch, +failure of that switch could cause a correlated failure and +bring down the service. The same holds true of shared power +circuits, cooling systems, etc. + +### Single Machine Requirements + +If ZooKeeper has to contend with other applications for +access to resources like storage media, CPU, network, or +memory, its performance will suffer markedly. ZooKeeper has +strong durability guarantees, which means it uses storage +media to log changes before the operation responsible for the +change is allowed to complete. You should be aware of this +dependency then, and take great care if you want to ensure +that ZooKeeper operations aren’t held up by your media. Here +are some things you can do to minimize that sort of +degradation: + +- ZooKeeper's transaction log must be on a dedicated + device. (A dedicated partition is not enough.) ZooKeeper + writes the log sequentially, without seeking Sharing your + log device with other processes can cause seeks and + contention, which in turn can cause multi-second + delays. +- Do not put ZooKeeper in a situation that can cause a + swap. In order for ZooKeeper to function with any sort of + timeliness, it simply cannot be allowed to swap. + Therefore, make certain that the maximum heap size given + to ZooKeeper is not bigger than the amount of real memory + available to ZooKeeper. For more on this, see + [Things to Avoid](/docs/admin-ops/administrators-guide/best-practices#things-to-avoid) + in the Best Practices guide. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/index.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/index.mdx new file mode 100644 index 00000000000..ef645189ba8 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/index.mdx @@ -0,0 +1,4 @@ +--- +title: "Administrator's Guide" +description: "This document is a guide for operators deploying and managing ZooKeeper in production environments. It covers the full lifecycle of running a ZooKeeper ensemble: hardware and software requirements, configuration, day-to-day administration, monitoring, and troubleshooting." +--- diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/meta.json new file mode 100644 index 00000000000..80f3d80f278 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/administrators-guide/meta.json @@ -0,0 +1,12 @@ +{ + "title": "Administrator's Guide", + "pages": [ + "deployment", + "administration", + "configuration-parameters", + "communication-using-the-netty-framework", + "commands", + "data-file-management", + "best-practices" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/cli.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/cli.mdx new file mode 100644 index 00000000000..a5c873d4553 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/cli.mdx @@ -0,0 +1,605 @@ +--- +title: "CLI" +description: "Reference guide for all zkCli.sh commands, with examples showing command syntax, options, and expected output." +--- + +## Connecting + +```bash +# connect to localhost on the default port 2181 +bin/zkCli.sh +# connect to a remote host with a 3-second timeout +bin/zkCli.sh -timeout 3000 -server remoteIP:2181 +# wait for connection before executing commands +bin/zkCli.sh -waitforconnection -timeout 3000 -server remoteIP:2181 +# use a custom client configuration properties file +bin/zkCli.sh -client-configuration /path/to/client.properties +``` + +## help + +Show all available ZooKeeper commands. + +``` +[zkshell: 1] help +ZooKeeper -server host:port cmd args +addauth scheme auth +close +config [-c] [-w] [-s] +connect host:port +create [-s] [-e] [-c] [-t ttl] path [data] [acl] +delete [-v version] path +deleteall path +delquota [-n|-b|-N|-B] path +get [-s] [-w] path +getAcl [-s] path +getAllChildrenNumber path +getEphemerals path +history +listquota path +ls [-s] [-w] [-R] path +printwatches on|off +quit +reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*] +redo cmdno +removewatches path [-c|-d|-a] [-l] +set [-s] [-v version] path data +setAcl [-s] [-v version] [-R] path acl +setquota -n|-b|-N|-B val path +stat [-w] path +sync path +version +``` + +## addauth + +Add an authorized user for ACL authentication. + +``` +[zkshell: 9] getAcl /acl_digest_test +Insufficient permission : /acl_digest_test + +[zkshell: 10] addauth digest user1:12345 +[zkshell: 11] getAcl /acl_digest_test +'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= +: cdrwa + +# add a super user +# set zookeeper.DigestAuthenticationProvider.superDigest, e.g.: +# zookeeper.DigestAuthenticationProvider.superDigest=zookeeper:qW/HnTfCSoQpB5G8LgkwT3IbiFc= +[zkshell: 12] addauth digest zookeeper:admin +``` + +## close + +Close the current client session. + +``` +[zkshell: 0] close +2019-03-09 06:42:22,178 [myid:] - INFO [main-EventThread:ClientCnxn$EventThread@528] - EventThread shut down for session: 0x10007ab7c550006 +2019-03-09 06:42:22,179 [myid:] - INFO [main:ZooKeeper@1346] - Session: 0x10007ab7c550006 closed +``` + +## config + +Show the current quorum membership configuration. + +``` +[zkshell: 17] config +server.1=[2001:db8:1:0:0:242:ac11:2]:2888:3888:participant +server.2=[2001:db8:1:0:0:242:ac11:2]:12888:13888:participant +server.3=[2001:db8:1:0:0:242:ac11:2]:22888:23888:participant +version=0 +``` + +## connect + +Connect to a ZooKeeper server. + +``` +[zkshell: 4] connect +2019-03-09 06:43:33,179 [myid:localhost:2181] - INFO [main-SendThread(localhost:2181):ClientCnxn$SendThread@986] - Socket connection established, initiating session, client: /127.0.0.1:35144, server: localhost/127.0.0.1:2181 +2019-03-09 06:43:33,189 [myid:localhost:2181] - INFO [main-SendThread(localhost:2181):ClientCnxn$SendThread@1421] - Session establishment complete on server localhost/127.0.0.1:2181, sessionid = 0x10007ab7c550007, negotiated timeout = 30000 +connect "localhost:2181,localhost:2182,localhost:2183" + +# connect to a remote server +[zkshell: 5] connect remoteIP:2181 +``` + +## create + +Create a znode. + +``` +# persistent node +[zkshell: 7] create /persistent_node +Created /persistent_node + +# ephemeral node (deleted when session ends) +[zkshell: 8] create -e /ephemeral_node mydata +Created /ephemeral_node + +# persistent sequential node +[zkshell: 9] create -s /persistent_sequential_node mydata +Created /persistent_sequential_node0000000176 + +# ephemeral sequential node +[zkshell: 10] create -s -e /ephemeral_sequential_node mydata +Created /ephemeral_sequential_node0000000174 +``` + +Create a node with an ACL schema: + +``` +[zkshell: 11] create /zk-node-create-schema mydata digest:user1:+owfoSBn/am19roBPzR1/MfCblE=:crwad +Created /zk-node-create-schema +[zkshell: 12] addauth digest user1:12345 +[zkshell: 13] getAcl /zk-node-create-schema +'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= +: cdrwa +``` + +Create a container node (automatically deleted when its last child is deleted): + +``` +[zkshell: 14] create -c /container_node mydata +Created /container_node +[zkshell: 15] create -c /container_node/child_1 mydata +Created /container_node/child_1 +[zkshell: 16] create -c /container_node/child_2 mydata +Created /container_node/child_2 +[zkshell: 17] delete /container_node/child_1 +[zkshell: 18] delete /container_node/child_2 +[zkshell: 19] get /container_node +org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /container_node +``` + +Create a TTL node (requires `zookeeper.extendedTypesEnabled=true`; otherwise returns `KeeperErrorCode = Unimplemented`): + +``` +[zkshell: 20] create -t 3000 /ttl_node mydata +Created /ttl_node + +# after 3 seconds +[zkshell: 21] get /ttl_node +org.apache.zookeeper.KeeperException$NoNodeException: KeeperErrorCode = NoNode for /ttl_node +``` + +## delete + +Delete a node at the specified path. + +``` +[zkshell: 2] delete /config/topics/test +[zkshell: 3] ls /config/topics/test +Node does not exist: /config/topics/test +``` + +## deleteall + +Delete a node and all of its descendants. + +``` +[zkshell: 1] ls /config +[changes, clients, topics] +[zkshell: 2] deleteall /config +[zkshell: 3] ls /config +Node does not exist: /config +``` + +## delquota + +Delete the quota on a path. + +``` +[zkshell: 1] delquota /quota_test +[zkshell: 2] listquota /quota_test +absolute path is /zookeeper/quota/quota_test/zookeeper_limits +quota for /quota_test does not exist. + +# delete specific quota types +[zkshell: 3] delquota -n /c1 +[zkshell: 4] delquota -N /c2 +[zkshell: 5] delquota -b /c3 +[zkshell: 6] delquota -B /c4 +``` + +## get + +Get the data stored at a path. + +``` +[zkshell: 10] get /latest_producer_id_block +{"version":1,"broker":0,"block_start":"0","block_end":"999"} + +# -s: also show node stats +[zkshell: 11] get -s /latest_producer_id_block +{"version":1,"broker":0,"block_start":"0","block_end":"999"} +cZxid = 0x90000009a +ctime = Sat Jul 28 08:14:09 UTC 2018 +mZxid = 0x9000000a2 +mtime = Sat Jul 28 08:14:12 UTC 2018 +pZxid = 0x90000009a +cversion = 0 +dataVersion = 1 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 60 +numChildren = 0 + +# -w: set a watch on data changes (requires printwatches to be on) +[zkshell: 12] get -w /latest_producer_id_block +{"version":1,"broker":0,"block_start":"0","block_end":"999"} + +[zkshell: 13] set /latest_producer_id_block mydata +WATCHER:: +WatchedEvent state:SyncConnected type:NodeDataChanged path:/latest_producer_id_block +``` + +## getAcl + +Get the ACL permissions for a path. + +``` +[zkshell: 4] create /acl_test mydata ip:127.0.0.1:crwda +Created /acl_test +[zkshell: 5] getAcl /acl_test +'ip,'127.0.0.1 +: cdrwa +[zkshell: 6] getAcl /testwatch +'world,'anyone +: cdrwa +``` + +## getAllChildrenNumber + +Get the total number of descendant nodes under a path. + +``` +[zkshell: 1] getAllChildrenNumber / +73779 +[zkshell: 2] getAllChildrenNumber /ZooKeeper +2 +[zkshell: 3] getAllChildrenNumber /ZooKeeper/quota +0 +``` + +## getEphemerals + +Get all ephemeral nodes created by the current session. + +``` +[zkshell: 1] create -e /test-get-ephemerals "ephemeral node" +Created /test-get-ephemerals +[zkshell: 2] getEphemerals +[/test-get-ephemerals] +[zkshell: 3] getEphemerals / +[/test-get-ephemerals] +[zkshell: 4] create -e /test-get-ephemerals-1 "ephemeral node" +Created /test-get-ephemerals-1 +[zkshell: 5] getEphemerals /test-get-ephemerals +test-get-ephemerals test-get-ephemerals-1 +[zkshell: 6] getEphemerals /test-get-ephemerals +[/test-get-ephemerals-1, /test-get-ephemerals] +[zkshell: 7] getEphemerals /test-get-ephemerals-1 +[/test-get-ephemerals-1] +``` + +## history + +Show the most recent 11 commands executed in this session. + +``` +[zkshell: 7] history +0 - close +1 - close +2 - ls / +3 - ls / +4 - connect +5 - ls / +6 - ll +7 - history +``` + +## listquota + +List the quota configured for a path. + +``` +[zkshell: 1] listquota /c1 +absolute path is /zookeeper/quota/c1/zookeeper_limits +Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2 +Output stat for /c1 count=4,bytes=0 +``` + +## ls + +List the child nodes of a path. + +``` +[zkshell: 36] ls /quota_test +[child_1, child_2, child_3] + +# -s: also show node stats +[zkshell: 37] ls -s /quota_test +[child_1, child_2, child_3] +cZxid = 0x110000002d +ctime = Thu Mar 07 11:19:07 UTC 2019 +mZxid = 0x110000002d +mtime = Thu Mar 07 11:19:07 UTC 2019 +pZxid = 0x1100000033 +cversion = 3 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 0 +numChildren = 3 + +# -R: recursively list all descendant nodes +[zkshell: 38] ls -R /quota_test +/quota_test +/quota_test/child_1 +/quota_test/child_2 +/quota_test/child_3 + +# -w: set a watch on child changes (requires printwatches to be on) +[zkshell: 39] ls -w /brokers +[ids, seqid, topics] +[zkshell: 40] delete /brokers/ids +WATCHER:: +WatchedEvent state:SyncConnected type:NodeChildrenChanged path:/brokers +``` + +## printwatches + +Toggle whether watch events are printed to the console. + +``` +[zkshell: 0] printwatches +printwatches is on +[zkshell: 1] printwatches off +[zkshell: 2] printwatches +printwatches is off +[zkshell: 3] printwatches on +[zkshell: 4] printwatches +printwatches is on +``` + +## quit + +Quit the CLI. + +```bash +[zkshell: 1] quit +``` + +## reconfig + +Change ensemble membership at runtime. Before using this command, read the details in [Dynamic Reconfiguration](/docs/admin-ops/dynamic-reconfiguration), especially the Security section. + +Prerequisites: + +1. Set `reconfigEnabled=true` in `zoo.cfg`. +2. Add a super user or set `skipACL`; otherwise you will get `Insufficient permission`. For example: `addauth digest zookeeper:admin`. + +``` +# Change follower 2 to an observer on port 12182, add observer 5, remove observer 4 +[zkshell: 1] reconfig --add 2=localhost:2781:2786:observer;12182 --add 5=localhost:2781:2786:observer;2185 -remove 4 +Committed new configuration: +server.1=localhost:2780:2785:participant;0.0.0.0:2181 +server.2=localhost:2781:2786:observer;0.0.0.0:12182 +server.3=localhost:2782:2787:participant;0.0.0.0:2183 +server.5=localhost:2784:2789:observer;0.0.0.0:2185 +version=1c00000002 + +# -members: specify the full new membership list +[zkshell: 2] reconfig -members server.1=localhost:2780:2785:participant;0.0.0.0:2181,server.2=localhost:2781:2786:observer;0.0.0.0:12182,server.3=localhost:2782:2787:participant;0.0.0.0:12183 +Committed new configuration: +server.1=localhost:2780:2785:participant;0.0.0.0:2181 +server.2=localhost:2781:2786:observer;0.0.0.0:12182 +server.3=localhost:2782:2787:participant;0.0.0.0:12183 +version=f9fe0000000c + +# -file with -v: apply config from file only if current version matches +[zkshell: 3] reconfig -file /data/software/zookeeper/zookeeper-test/conf/myNewConfig.txt -v 2100000010 +Committed new configuration: +server.1=localhost:2780:2785:participant;0.0.0.0:2181 +server.2=localhost:2781:2786:observer;0.0.0.0:12182 +server.3=localhost:2782:2787:participant;0.0.0.0:2183 +server.5=localhost:2784:2789:observer;0.0.0.0:2185 +version=220000000c +``` + +## redo + +Re-execute a command from history by its index. + +``` +[zkshell: 4] history +0 - ls / +1 - get /consumers +2 - get /hbase +3 - ls /hbase +4 - history +[zkshell: 5] redo 3 +[backup-masters, draining, flush-table-proc, hbaseid, master-maintenance, meta-region-server, namespace, online-snapshot, replication, rs, running, splitWAL, switch, table, table-lock] +``` + +## removewatches + +Remove watches from a node. + +``` +[zkshell: 1] get -w /brokers +null +[zkshell: 2] removewatches /brokers +WATCHER:: +WatchedEvent state:SyncConnected type:DataWatchRemoved path:/brokers +``` + +## set + +Set or update the data at a path. + +``` +[zkshell: 50] set /brokers myNewData + +# -s: show the node stats after the update +[zkshell: 51] set -s /quota_test mydata_for_quota_test +cZxid = 0x110000002d +ctime = Thu Mar 07 11:19:07 UTC 2019 +mZxid = 0x1100000038 +mtime = Thu Mar 07 11:42:41 UTC 2019 +pZxid = 0x1100000033 +cversion = 3 +dataVersion = 2 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 21 +numChildren = 3 + +# -v: optimistic locking (CAS) — version from dataVersion in stat +[zkshell: 52] set -v 0 /brokers myNewData +[zkshell: 53] set -v 0 /brokers myNewData +version No is not valid : /brokers +``` + +## setAcl + +Set ACL permissions on a node. + +``` +[zkshell: 28] addauth digest user1:12345 +[zkshell: 30] setAcl /acl_auth_test auth:user1:12345:crwad +[zkshell: 31] getAcl /acl_auth_test +'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= +: cdrwa +``` + +Use `-R` to set ACL recursively on all child nodes: + +``` +[zkshell: 32] ls /acl_auth_test +[child_1, child_2] +[zkshell: 33] getAcl /acl_auth_test/child_2 +'world,'anyone +: cdrwa +[zkshell: 34] setAcl -R /acl_auth_test auth:user1:12345:crwad +[zkshell: 35] getAcl /acl_auth_test/child_2 +'digest,'user1:+owfoSBn/am19roBPzR1/MfCblE= +: cdrwa +``` + +Use `-v` to set ACL with optimistic locking (version from `aclVersion` in stat): + +``` +[zkshell: 36] stat /acl_auth_test +cZxid = 0xf9fc0000001c +ctime = Tue Mar 26 16:50:58 CST 2019 +mZxid = 0xf9fc0000001c +mtime = Tue Mar 26 16:50:58 CST 2019 +pZxid = 0xf9fc0000001f +cversion = 2 +dataVersion = 0 +aclVersion = 3 +ephemeralOwner = 0x0 +dataLength = 0 +numChildren = 2 +[zkshell: 37] setAcl -v 3 /acl_auth_test auth:user1:12345:crwad +``` + +## setquota + +Set a quota on a path. Soft limits (`-n`, `-b`) log a warning but do not block operations. Hard limits (`-N`, `-B`) reject operations that exceed the quota. + +``` +# -n: soft limit on node count (includes the node itself) +[zkshell: 18] setquota -n 2 /quota_test +[zkshell: 19] create /quota_test/child_1 +Created /quota_test/child_1 +[zkshell: 20] create /quota_test/child_2 +Created /quota_test/child_2 +[zkshell: 21] create /quota_test/child_3 +Created /quota_test/child_3 +# soft limit: creation succeeds but a warning is logged +2019-03-07 11:22:36,680 [myid:1] - WARN [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=3 limit=2 +2019-03-07 11:22:41,861 [myid:1] - WARN [SyncThread:0:DataTree@374] - Quota exceeded: /quota_test count=4 limit=2 + +# -b: soft limit on data bytes +[zkshell: 22] setquota -b 5 /brokers +[zkshell: 23] set /brokers "I_love_zookeeper" +# soft limit: write succeeds but a warning is logged +WARN [CommitProcWorkThread-7:DataTree@379] - Quota exceeded: /brokers bytes=4206 limit=5 + +# -N: hard limit on node count +[zkshell: 3] create /c1 +Created /c1 +[zkshell: 4] setquota -N 2 /c1 +[zkshell: 5] listquota /c1 +absolute path is /zookeeper/quota/c1/zookeeper_limits +Output quota for /c1 count=-1,bytes=-1=;byteHardLimit=-1;countHardLimit=2 +Output stat for /c1 count=2,bytes=0 +[zkshell: 6] create /c1/ch-3 +Count Quota has exceeded : /c1/ch-3 + +# -B: hard limit on bytes +[zkshell: 3] create /c2 +[zkshell: 4] setquota -B 4 /c2 +[zkshell: 5] set /c2 "foo" +[zkshell: 6] set /c2 "foo-bar" +Bytes Quota has exceeded : /c2 +[zkshell: 7] get /c2 +foo +``` + +## stat + +Show the metadata (stat) of a node. + +``` +[zkshell: 1] stat /hbase +cZxid = 0x4000013d9 +ctime = Wed Jun 27 20:13:07 CST 2018 +mZxid = 0x4000013d9 +mtime = Wed Jun 27 20:13:07 CST 2018 +pZxid = 0x500000001 +cversion = 17 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0x0 +dataLength = 0 +numChildren = 15 +``` + +## sync + +Sync the data of a node between the leader and followers (asynchronous). + +```bash +[zkshell: 14] sync / +[zkshell: 15] Sync is OK +``` + +## version + +Show the ZooKeeper CLI version. + +```bash +[zkshell: 1] version +ZooKeeper CLI version: 3.6.0-SNAPSHOT-29f9b2c1c0e832081f94d59a6b88709c5f1bb3ca, built on 05/30/2019 09:26 GMT +``` + +## whoami + +Show all authentication information for the current session. + +``` +[zkshell: 1] whoami +Auth scheme: User +ip: 127.0.0.1 +[zkshell: 2] addauth digest user1:12345 +[zkshell: 3] whoami +Auth scheme: User +ip: 127.0.0.1 +digest: user1 +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/dynamic-reconfiguration.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/dynamic-reconfiguration.mdx new file mode 100644 index 00000000000..9dd0e66acfd --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/dynamic-reconfiguration.mdx @@ -0,0 +1,725 @@ +--- +title: "Dynamic Reconfiguration" +description: "How to use ZooKeeper's dynamic reconfiguration support (available since 3.5.0) to change ensemble membership, server roles, ports, and the quorum system at runtime without service interruption." +--- + +Prior to the 3.5.0 release, the membership and all other configuration +parameters of ZooKeeper were static — loaded during boot and immutable at +runtime. Operators resorted to "rolling restarts" — a manually intensive +and error-prone method of changing the configuration that has caused data +loss and inconsistency in production. + +Starting with 3.5.0, rolling restarts are no longer needed. +ZooKeeper comes with full support for automated configuration changes: the +set of ZooKeeper servers, their roles (participant / observer), all ports, +and even the quorum system can be changed dynamically, without service +interruption and while maintaining data consistency. Reconfigurations are +performed immediately, just like other operations in ZooKeeper. Multiple +changes can be done using a single reconfiguration command. The dynamic +reconfiguration functionality does not limit operation concurrency, does +not require client operations to be stopped during reconfigurations, has a +very simple interface for administrators, and adds no complexity to other +client operations. + +New client-side features allow clients to find out about configuration +changes and to update the connection string (list of servers and their +client ports) stored in their ZooKeeper handle. A probabilistic algorithm +is used to rebalance clients across the new configuration servers while +keeping the extent of client migrations proportional to the change in +ensemble membership. + +This document provides the administrator manual for reconfiguration. +For a detailed description of the reconfiguration algorithms, performance +measurements, and more, see: + +_Shraer, A., Reed, B., Malkhi, D., Junqueira, F. Dynamic Reconfiguration of Primary/Backup Clusters. In USENIX Annual Technical Conference (ATC) (2012), 425–437._ +Links: [paper (pdf)](https://www.usenix.org/system/files/conference/atc12/atc12-final74.pdf), [slides (pdf)](https://www.usenix.org/sites/default/files/conference/protected-files/shraer_atc12_slides.pdf), [video](https://www.usenix.org/conference/atc12/technical-sessions/presentation/shraer), [hadoop summit slides](http://www.slideshare.net/Hadoop_Summit/dynamic-reconfiguration-of-zookeeper) + + + Starting with 3.5.3, the dynamic reconfiguration feature is disabled by + default and must be explicitly turned on via the `reconfigEnabled` + configuration option. + + +## Changes to Configuration Format + +### Specifying the Client Port + +A client port is the port on which the server accepts plaintext (non-TLS) client connection requests. +A secure client port is the port on which the server accepts TLS client connection requests. + +Starting with 3.5.0, the `clientPort` and `clientPortAddress` configuration parameters should no longer be used in `zoo.cfg`. + +Starting with 3.10.0, the `secureClientPort` and `secureClientPortAddress` configuration parameters should no longer be used in `zoo.cfg`. + +Instead, this information is now part of the server keyword specification: + +``` +server. = ::[:role];[[:]][;[:]] +``` + +- [New in ZK 3.10.0] The client port specification is optional and is to the right of the + first semicolon. The secure client port specification is also optional and is to the right + of the second semicolon. However, both the client port and secure client port specification + cannot be omitted — at least one of them must be present. If the user intends to omit the client + port specification and provide only the secure client port (TLS-only server), a second + semicolon should still be specified to indicate an empty client port specification (see last + example below). In either spec, the port address is optional and defaults to `0.0.0.0`. +- Role is also optional — it can be `participant` or `observer` (`participant` by default). + +Examples of legal server statements: + +``` +server.5 = 125.23.63.23:1234:1235;1236 (non-TLS server) +server.5 = 125.23.63.23:1234:1235;1236;1237 (non-TLS + TLS server) +server.5 = 125.23.63.23:1234:1235;;1237 (TLS-only server) +server.5 = 125.23.63.23:1234:1235:participant;1236 (non-TLS server) +server.5 = 125.23.63.23:1234:1235:observer;1236 (non-TLS server) +server.5 = 125.23.63.23:1234:1235;125.23.63.24:1236 (non-TLS server) +server.5 = 125.23.63.23:1234:1235:participant;125.23.63.23:1236 (non-TLS server) +server.5 = 125.23.63.23:1234:1235:participant;125.23.63.23:1236;125.23.63.23:1237 (non-TLS + TLS server) +server.5 = 125.23.63.23:1234:1235:participant;;125.23.63.23:1237 (TLS-only server) +``` + +### Specifying Multiple Server Addresses + +Since ZooKeeper 3.6.0 it is possible to specify multiple addresses for each +ZooKeeper server (see [ZOOKEEPER-3188](https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3188)). +This helps to increase availability and adds network-level resiliency to ZooKeeper. When multiple +physical network interfaces are used for the servers, ZooKeeper is able to bind on all interfaces +and switch to a working interface at runtime in case of a network error. Multiple addresses are +separated by a pipe (`|`) character. + +Examples of valid configurations using multiple addresses: + +``` +server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889;2188 +server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889|zoo2-net3:2890:3890;2188 +server.2=zoo2-net1:2888:3888|zoo2-net2:2889:3889;zoo2-net1:2188 +server.2=zoo2-net1:2888:3888:observer|zoo2-net2:2889:3889:observer;2188 +``` + +### The `standaloneEnabled` Flag + +Prior to 3.5.0, one could run ZooKeeper in Standalone mode or in +Distributed mode. These are separate implementation stacks and switching +between them at runtime is not possible. By default (for backward +compatibility) `standaloneEnabled` is set to `true`. The consequence is that +if started with a single server the ensemble will not be allowed to grow, +and if started with more than one server it will not be allowed to shrink +below two participants. + +Setting the flag to `false` instructs the system to run the Distributed +software stack even if there is only a single participant in the ensemble. +To achieve this the static configuration file should contain: + +``` +standaloneEnabled=false +``` + +With this setting it is possible to start a ZooKeeper ensemble containing +a single participant and to dynamically grow it by adding more servers. +Similarly, it is possible to shrink an ensemble so that just a single +participant remains by removing servers. + +Since running the Distributed mode allows more flexibility, we recommend +setting the flag to `false`. The legacy Standalone mode is expected to be +deprecated in the future. + +### The `reconfigEnabled` Flag + +Starting with 3.5.0 and prior to 3.5.3, there is no way to disable +dynamic reconfiguration. To address the security concern that a malicious +actor could make arbitrary changes to the ensemble configuration, the +`reconfigEnabled` option was introduced in 3.5.3. Any attempt +to reconfigure a cluster through the reconfig API — with or without authentication — +will fail by default unless `reconfigEnabled` is set to `true`. + +To enable reconfiguration, add the following to `zoo.cfg`: + +``` +reconfigEnabled=true +``` + +### Dynamic Configuration File + +Starting with 3.5.0, ZooKeeper distinguishes between dynamic configuration +parameters (which can be changed during runtime) and static configuration +parameters (which are read from a configuration file at boot and do not change +during execution). The dynamic configuration keywords are: `server`, `group`, +and `weight`. + +Dynamic configuration parameters are stored in a separate file on the server +(the dynamic configuration file), linked from the static config file using the +`dynamicConfigFile` keyword. + +#### Example 1 + +**`zoo_replicated1.cfg`** + +``` +tickTime=2000 +dataDir=/zookeeper/data/zookeeper1 +initLimit=5 +syncLimit=2 +dynamicConfigFile=/zookeeper/conf/zoo_replicated1.cfg.dynamic +``` + +**`zoo_replicated1.cfg.dynamic`** + +``` +server.1=125.23.63.23:2780:2783:participant;2791 +server.2=125.23.63.24:2781:2784:participant;2792 +server.3=125.23.63.25:2782:2785:participant;2793 +``` + +When the ensemble configuration changes, the static configuration parameters +remain the same. The dynamic parameters are pushed by ZooKeeper and overwrite +the dynamic configuration files on all servers. Thus the dynamic configuration +files on different servers are usually identical (they can differ momentarily +while a reconfiguration is in progress or before a new configuration has +propagated to all servers). Once created, the dynamic configuration file should +not be manually altered — changes are made only through the reconfiguration +commands described below. Changing the config of an offline cluster could +result in an inconsistency with configuration information stored in the +ZooKeeper log and is therefore highly discouraged. + +#### Example 2 + +Users may prefer to initially specify a single configuration file. The +following is also legal: + +**`zoo_replicated1.cfg`** + +``` +tickTime=2000 +dataDir=/zookeeper/data/zookeeper1 +initLimit=5 +syncLimit=2 +clientPort= +``` + +The configuration files on each server will be automatically split into +dynamic and static files if they are not already in this format. The +configuration above will be automatically transformed into the two files in +Example 1. Note that the `clientPort` and `clientPortAddress` lines (if +specified) will be automatically removed during this process if they are +redundant (as in the example above). The original static configuration file +is backed up (as a `.bak` file). + +### Backward Compatibility + +The old configuration format is still supported. For example, the +following configuration file is acceptable (but not recommended): + +**`zoo_replicated1.cfg`** + +``` +tickTime=2000 +dataDir=/zookeeper/data/zookeeper1 +initLimit=5 +syncLimit=2 +clientPort=2791 +server.1=125.23.63.23:2780:2783:participant +server.2=125.23.63.24:2781:2784:participant +server.3=125.23.63.25:2782:2785:participant +``` + +During boot, a dynamic configuration file is created containing the dynamic +part of the configuration as explained earlier. In this case, however, the +line `clientPort=2791` will remain in the static configuration file of +server 1 since it is not redundant — it was not specified as part of +`server.1=...` using the format described in +[Changes to Configuration Format](#changes-to-configuration-format). If a +reconfiguration is invoked that sets the client port of server 1, `clientPort=2791` +is removed from the static configuration file (the dynamic file then contains +this information as part of the server 1 specification). + +## Upgrading to 3.5.0 + +Upgrading a running ZooKeeper ensemble to 3.5.0 should be done only +after upgrading to the 3.4.6 release. This is only necessary for rolling +upgrades — if you are fine with shutting down the system completely, you +do not need to go through 3.4.6. If you attempt a rolling upgrade without +going through 3.4.6 (for example from 3.4.5), you may get the following error: + +``` +2013-01-30 11:32:10,663 [myid:2] - INFO [localhost/127.0.0.1:2784:QuorumCnxManager$Listener@498] - Received connection request /127.0.0.1:60876 +2013-01-30 11:32:10,663 [myid:2] - WARN [localhost/127.0.0.1:2784:QuorumCnxManager@349] - Invalid server id: -65536 +``` + +During a rolling upgrade, each server is taken down in turn and rebooted +with the new 3.5.0 binaries. Before starting a server with 3.5.0 binaries, +we highly recommend updating the configuration file so that all server +statements `server.x=...` contain client ports (see +[Specifying the Client Port](#specifying-the-client-port)). You may leave +the configuration in a single file and may also leave the +`clientPort`/`clientPortAddress` statements (although if you specify client +ports in the new format, these statements become redundant). + +## Dynamic Reconfiguration of the ZooKeeper Ensemble + +The ZooKeeper Java and C APIs were extended with `getConfig` and `reconfig` +commands that facilitate reconfiguration. Both commands have a synchronous +(blocking) variant and an asynchronous one. The examples below use the Java +CLI, but you can similarly use the C CLI or invoke the commands directly from +a program just like any other ZooKeeper command. + +### API + +There are two sets of APIs for both Java and C clients. + +- **Reconfiguration API:** Used to reconfigure the ZooKeeper cluster. + Starting with 3.5.3, reconfiguration Java APIs are moved into the `ZooKeeperAdmin` + class from the `ZooKeeper` class. Use of this API requires ACL setup and user + authentication (see [Security](#security) for more information). + +- **Get Configuration API:** Used to retrieve ZooKeeper cluster configuration + information stored in the `/zookeeper/config` znode. Use of this API does not + require specific setup or authentication, because `/zookeeper/config` is readable + by any user. + +### Security + +Prior to **3.5.3**, there is no enforced security mechanism over reconfig, +so any ZooKeeper client that can connect to the ensemble has the ability to +change its state via reconfig. It is thus possible for a malicious client to +add a compromised server to an ensemble or remove legitimate servers, which +can be a security vulnerability. + +Starting from **3.5.3**, access control over reconfig is enforced: only a +specific set of explicitly configured users can use reconfig commands or APIs, +and the ZooKeeper cluster must have authentication enabled so that clients can +be authenticated. + +An escape hatch is provided for users operating in a secured environment (e.g. +behind a company firewall) who want to use reconfiguration without the overhead +of configuring an explicit authorized user list: setting +`skipACL` to `yes` skips +ACL checks and allows any user to reconfigure the cluster. + +- **Access Control:** The dynamic configuration is stored in the special znode + `ZooDefs.CONFIG_NODE = /zookeeper/config`. This node is read-only for all users + by default, except the super user and users explicitly configured for write access. + Clients that need to use reconfig commands or the reconfig API must be configured + with write access to `CONFIG_NODE`. Additional users can be granted write access + through the superuser by setting an ACL with write permission. Examples of how to + set up ACLs and use the reconfiguration API with authentication can be found in + `ReconfigExceptionTest.java` and `TestReconfigServer.cc`. + +- **Authentication:** Authentication is orthogonal to access control and is + delegated to ZooKeeper's pluggable authentication schemes. See + [ZooKeeper and SASL](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Zookeeper+and+SASL) + for more details. + +- **Disable ACL check:** ZooKeeper supports the + `skipACL` option such that + ACL checks are completely skipped when `skipACL` is set to `yes`. In such cases + any unauthenticated user can use the reconfig API. + +### Retrieving the Current Dynamic Configuration + +The dynamic configuration is stored in a special znode +`ZooDefs.CONFIG_NODE = /zookeeper/config`. The `config` CLI command reads +this znode (it is essentially a wrapper around `get /zookeeper/config`). As +with normal reads, to retrieve the latest committed value you should do a +`sync` first. + +``` +[zk: 127.0.0.1:2791(CONNECTED) 3] config +server.1=localhost:2780:2783:participant;localhost:2791 +server.2=localhost:2781:2784:participant;localhost:2792 +server.3=localhost:2782:2785:participant;localhost:2793 +``` + +Notice the last line of the output — this is the configuration version. The +version equals the zxid of the reconfiguration command that created this +configuration. The version of the first established configuration equals the +zxid of the NEWLEADER message sent by the first successfully established leader. +When a configuration is written to a dynamic configuration file, the version +automatically becomes part of the filename and the static configuration file is +updated with the path to the new dynamic configuration file. Configuration files +corresponding to earlier versions are retained for backup purposes. + +During boot, the version (if it exists) is extracted from the filename. The +version should never be manually altered — it is used by the system to determine +which configuration is most up-to-date, and manipulating it can result in data +loss and inconsistency. + +Like the `get` command, the `config` CLI command accepts the `-w` flag for +setting a watch on the znode and the `-s` flag for displaying its stats. It +additionally accepts a `-c` flag that outputs only the version and the client +connection string for the current configuration. For example: + +``` +[zk: 127.0.0.1:2791(CONNECTED) 17] config -c +400000003 localhost:2791,localhost:2793,localhost:2792 +``` + +Note that when using the API directly, this command is called `getConfig`. + +As any read command, it returns the configuration known to the follower your +client is connected to, which may be slightly out-of-date. Use the `sync` +command for stronger guarantees. For example using the Java API: + +```java +zk.sync(ZooDefs.CONFIG_NODE, void_callback, context); +zk.getConfig(watcher, callback, context); +``` + +Note: in 3.5.0 it doesn't matter which path is passed to `sync()` since all +server state is brought up to date with the leader (a different path could be +used instead of `ZooDefs.CONFIG_NODE`). However, this may change in the future. + +### Modifying the Current Dynamic Configuration + +Configuration is modified through the `reconfig` command. There are two +modes: incremental and non-incremental (bulk). The non-incremental mode +specifies the complete new dynamic configuration. The incremental mode specifies +changes to the current configuration. The `reconfig` command returns the new +configuration. + +A few examples can be found in: `ReconfigTest.java`, `ReconfigRecoveryTest.java`, +and `TestReconfigServer.cc`. + +#### General + +**Removing servers:** Any server can be removed, including the leader (although +removing the leader will result in a short unavailability, see Figures 6 and 8 in +the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters)). +The server will not be shut down automatically. Instead, it becomes a +"non-voting follower" — similar to an observer in that its votes don't count +towards the quorum, but unlike an observer, a non-voting follower still sees +operation proposals and ACKs them. Thus a non-voting follower has a more +significant negative effect on throughput compared to an observer. +Non-voting follower mode should only be used temporarily before shutting the +server down or adding it back as a follower or observer. Servers are not +shut down automatically for two main reasons: first, to avoid immediately +disconnecting all connected clients and causing a flood of reconnection requests +to other servers; second, because removing a server may sometimes be necessary +as a step to change it from observer to participant (see +[Additional comments](#additional-comments)). + +Note that the new configuration must have some minimum number of participants +to be considered legal. If the proposed change would leave fewer than 2 +participants and standalone mode is enabled (`standaloneEnabled=true`, see +[The `standaloneEnabled` Flag](#the-standaloneenabled-flag)), the reconfig +will not be processed (`BadArgumentsException`). If standalone mode is disabled +(`standaloneEnabled=false`) then 1 or more participants is legal. + +**Adding servers:** Before invoking a reconfiguration, the administrator must +ensure that a quorum (majority) of participants from the new configuration are +already connected and synced with the current leader. To achieve this, a new +joining server must be connected to the leader before it officially becomes part +of the ensemble. This is done by starting the joining server with an initial +server list that is not a legal configuration but (a) contains the joiner, and +(b) gives the joiner enough information to find and connect to the current leader. +A few safe options for doing this: + +1. The initial configuration of joiners consists of servers in the last committed + configuration plus one or more joiners, where **joiners are listed as observers.** + For example, if servers D and E are added at the same time to (A, B, C) and C + is being removed, D's initial config could be (A, B, C, D) or (A, B, C, D, E) + with D and E listed as observers. **Note that listing joiners as observers does + not actually make them observers** — it only prevents them from accidentally + forming a quorum with other joiners. Instead, they contact the servers in the + current configuration and adopt the last committed configuration (A, B, C). + Configuration files of joiners are backed up and replaced automatically. + After connecting to the current leader, joiners become non-voting followers until + the system is reconfigured and they are added to the ensemble. + +1. The initial configuration of each joiner consists of servers in the last committed + configuration **plus the joiner itself, listed as a participant.** For example, + to add a new server D to (A, B, C), start D with an initial config consisting of + (A, B, C, D). If both D and E are added at the same time, D's initial config + could be (A, B, C, D) and E's could be (A, B, C, E). Never list more than one + joiner as participant in the initial configuration (see warning below). + +1. Whether listing the joiner as an observer or participant, it is also fine not + to list all current configuration servers, as long as the current leader is + included. For example, when adding D, it could be started with just (A, D) if + A is the current leader. However, this is more fragile since if A fails before + D officially joins, D has no other servers to contact and the administrator + must restart D with another server list. + + + Never specify more than one joining server in the same initial configuration + as participants. The joining servers do not know they are joining an existing + ensemble — if multiple joiners are listed as participants they may form an + independent quorum, creating a split-brain situation and processing operations + independently from the main ensemble. It is safe to list multiple joiners as + observers in an initial config. + + +If the configuration of existing servers changes or they become unavailable before +the joiner succeeds in connecting and learning about configuration changes, the +joiner may need to be restarted with an updated configuration file. + +Finally, note that once connected to the leader, a joiner adopts the last committed +configuration (in which it is absent), and the initial config is backed up before +being rewritten. If the joiner restarts in this state it will not be able to boot +since it is absent from its configuration file — you will need to specify an initial +configuration again. + +**Modifying server parameters:** Any of the ports or the role (participant/observer) +of a server can be modified by adding it to the ensemble with different parameters. +This works in both incremental and bulk reconfiguration modes — it is not necessary +to remove the server and re-add it; just specify the new parameters as if the server +is not yet in the system. The server will detect the configuration change and perform +the necessary adjustments. See an example in [Incremental mode](#incremental-mode) +and an exception in [Additional comments](#additional-comments). + +It is also possible to change the Quorum System used by the ensemble (for example, +change from a Majority Quorum System to a Hierarchical Quorum System on the fly). +This is only allowed using the bulk (non-incremental) reconfiguration mode. Incremental +reconfiguration only works with the Majority Quorum System. Bulk reconfiguration +works with both Hierarchical and Majority Quorum Systems. + +**Performance impact:** There is practically no performance impact when removing a +follower, since it is not automatically shut down (the effect of removal is that the +server's votes are no longer counted). When adding a server, there is no leader change +and no noticeable performance disruption. For details and graphs see Figures 6, 7 and +8 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters). + +The most significant disruption occurs when a leader change is triggered, in the +following cases: + +1. Leader is removed from the ensemble. +1. Leader's role is changed from participant to observer. +1. The port used by the leader to send transactions to others (quorum port) is modified. + +In these cases a leader hand-off is performed where the old leader nominates a new +leader. The resulting unavailability is usually shorter than when a leader crashes +since failure detection is unnecessary and electing a new leader can usually be +avoided during a hand-off (see Figures 6 and 8 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters)). + +When the client port of a server is modified, existing client connections are not +dropped. New connections to the server will use the new client port. + +**Progress guarantees:** Up to the invocation of the reconfig operation, a quorum of +the old configuration must be available and connected for ZooKeeper to make progress. +Once reconfig is invoked, a quorum of both the old and new configurations must be +available. The final transition happens once (a) the new configuration is activated and +(b) all operations scheduled before the new configuration was activated by the leader +are committed. Once both (a) and (b) have happened, only a quorum of the new +configuration is required. Note that neither (a) nor (b) are visible to a client — +when a reconfiguration operation commits it only means that an activation message was +sent by the leader, not that a quorum of the new configuration has received it. +To ensure both (a) and (b) have occurred (for example, before safely shutting down +removed servers), invoke an update (`set-data` or another quorum operation, but not +`sync`) and wait for it to commit. + +#### Incremental Mode + +The incremental mode allows adding and removing servers from the current +configuration. Multiple changes are allowed at once. For example: + +```bash +> reconfig -remove 3 -add \ +server.5=125.23.63.23:1234:1235;1236 +``` + +Both the add and remove options take comma-separated arguments (no spaces): + +```bash +> reconfig -remove 3,4 -add \ +server.5=localhost:2111:2112;2113,6=localhost:2114:2115:observer;2116 +``` + +The format of the server statement is exactly as described in +[Specifying the Client Port](#specifying-the-client-port) and includes the client +port. Note that `5=` can be used as a shorthand for `server.5=`. In the example +above, if server 5 is already in the system with different ports or is not an +observer, it is updated — once the configuration commits it becomes an observer +using the new ports. This is an easy way to turn participants into observers and +vice versa, or change any ports, without rebooting the server. + +ZooKeeper supports two types of Quorum Systems: the simple Majority system (where +the leader commits operations after receiving ACKs from a majority of voters) and a +more complex Hierarchical system (where votes of different servers have different +weights and servers are divided into voting groups). Incremental reconfiguration is +currently allowed only if the last proposed configuration uses a Majority Quorum +System (`BadArgumentsException` is thrown otherwise). + +Incremental mode — examples using the Java API: + +```java +List leavingServers = new ArrayList(); +leavingServers.add("1"); +leavingServers.add("2"); +byte[] config = zk.reconfig(null, leavingServers, null, -1, new Stat()); + +List leavingServers = new ArrayList(); +List joiningServers = new ArrayList(); +leavingServers.add("1"); +joiningServers.add("server.4=localhost:1234:1235;1236"); +byte[] config = zk.reconfig(joiningServers, leavingServers, null, -1, new Stat()); + +String configStr = new String(config); +System.out.println(configStr); +``` + +There is also an asynchronous API, and an API accepting comma-separated Strings +instead of `List`. See +`src/java/main/org/apache/zookeeper/ZooKeeper.java`. + +#### Non-incremental Mode + +The non-incremental mode accepts a complete specification of the new dynamic +configuration. The new configuration can be given inline or read from a file: + +```bash +> reconfig -file newconfig.cfg +``` + +`newconfig.cfg` is a dynamic config file — see [Dynamic Configuration File](#dynamic-configuration-file). + +```bash +> reconfig -members \ +server.1=125.23.63.23:2780:2783:participant;2791,server.2=125.23.63.24:2781:2784:participant;2792,server.3=125.23.63.25:2782:2785:participant;2793 +``` + +The new configuration may use a different Quorum System. For example, you may +specify a Hierarchical Quorum System even if the current ensemble uses a Majority +Quorum System. + +Bulk mode — example using the Java API: + +```java +List newMembers = new ArrayList(); +newMembers.add("server.1=1111:1234:1235;1236"); +newMembers.add("server.2=1112:1237:1238;1239"); +newMembers.add("server.3=1114:1240:1241:observer;1242"); + +byte[] config = zk.reconfig(null, null, newMembers, -1, new Stat()); + +String configStr = new String(config); +System.out.println(configStr); +``` + +There is also an asynchronous API, and an API accepting a comma-separated String +containing the new members instead of `List`. See +`src/java/main/org/apache/zookeeper/ZooKeeper.java`. + +#### Conditional Reconfig + +Sometimes (especially in non-incremental mode) a proposed configuration depends +on what the client believes to be the current configuration, and should only be +applied to that configuration. The `reconfig` succeeds only if the last +configuration at the leader has the specified version: + +```bash +> reconfig -file -v +``` + +In the Java examples above, instead of `-1` you can specify a configuration +version to condition the reconfiguration. + +#### Error Conditions + +In addition to normal ZooKeeper error conditions, a reconfiguration may fail for +the following reasons: + +1. Another reconfig is currently in progress (`ReconfigInProgress`). +1. The proposed change would leave fewer than 2 participants and standalone mode + is enabled, or, if standalone mode is disabled, fewer than 1 participant would + remain (`BadArgumentsException`). +1. No quorum of the new configuration was connected and up-to-date with the leader + when reconfiguration processing began (`NewConfigNoQuorum`). +1. `-v x` was specified but the latest configuration version `y` is not `x` + (`BadVersionException`). +1. An incremental reconfiguration was requested but the last configuration at the + leader uses a Quorum System other than Majority (`BadArgumentsException`). +1. Syntax error (`BadArgumentsException`). +1. I/O exception when reading the configuration from a file (`BadArgumentsException`). + +Most of these are illustrated by test cases in `ReconfigFailureCases.java`. + +#### Additional Comments + +**Liveness:** To understand the difference between incremental and non-incremental +reconfiguration, suppose client C1 adds server D while a different client C2 adds +server E. With non-incremental mode, each client first invokes `config` to find out +the current configuration, then locally creates a new server list by adding its own +suggested server. After both reconfigurations complete, only one of D or E will be +added (not both), depending on which request arrives second at the leader. The other +client can repeat the process until its change takes effect. This guarantees +system-wide progress (for one client) but not for every client. C2 may use +[Conditional reconfig](#conditional-reconfig) to avoid blindly overwriting C1's +configuration if C1's request arrived first. + +With incremental reconfiguration, both changes take effect as they are applied by +the leader one after the other to the current configuration. Since both clients are +guaranteed to make progress, this method guarantees stronger liveness. In practice, +multiple concurrent reconfigurations are probably rare. Non-incremental reconfiguration +is currently the only way to dynamically change the Quorum System. Incremental +reconfiguration is currently only allowed with the Majority Quorum System. + +**Changing an observer into a follower:** Changing a voting server into an observer +may fail if fewer than the minimal allowed number of participants would remain (error 2). +Converting an observer into a participant may sometimes fail for a more subtle reason. +Suppose the current configuration is (A, B, C, D), where A is the leader, B and C are +followers, and D is an observer, and B has crashed. If a reconfiguration makes D a +follower, it will fail with error 3 since a majority of voters in the new configuration +(any 3 voters) must be connected and up-to-date with the leader. An observer cannot +acknowledge the history prefix sent during reconfiguration and therefore does not count +towards the 3 required servers. In this case, a client can achieve the task with two +reconfig commands: first remove D from the configuration, then add it back as a +participant. During the intermediate state D is a non-voting follower and can ACK the +state transfer performed during the second reconfig command. + +## Rebalancing Client Connections + +When a ZooKeeper cluster is started and each client is given the same connection +string, the client randomly chooses a server to connect to, making the expected +number of client connections per server equal across all servers. ZooKeeper preserves +this property when the set of servers changes through reconfiguration (see Sections +4 and 5.1 in the [paper](https://www.usenix.org/conference/usenixfederatedconferencesweek/dynamic-recon%EF%AC%81guration-primarybackup-clusters)). + +For the method to work, all clients must subscribe to configuration changes by setting +a watch on `/zookeeper/config` — either directly or through the `getConfig` API. When +the watch is triggered, the client should read the new configuration by invoking +`sync` and `getConfig`, and if the configuration is indeed new, invoke `updateServerList`. +To avoid mass client migration at the same time, each client should sleep a random +short period before invoking `updateServerList`. + +A few examples can be found in `StaticHostProviderTest.java` and `TestReconfig.cc`. + +Example (simplified to illustrate the general idea, not a production recipe): + +```java +public void process(WatchedEvent event) { + synchronized (this) { + if (event.getType() == EventType.None) { + connected = (event.getState() == KeeperState.SyncConnected); + notifyAll(); + } else if (event.getPath() != null && event.getPath().equals(ZooDefs.CONFIG_NODE)) { + // in prod code never block the event thread! + zk.sync(ZooDefs.CONFIG_NODE, this, null); + zk.getConfig(this, this, null); + } + } +} + +public void processResult(int rc, String path, Object ctx, byte[] data, Stat stat) { + if (path != null && path.equals(ZooDefs.CONFIG_NODE)) { + String config[] = ConfigUtils.getClientConfigStr(new String(data)).split(" "); // similar to config -c + long version = Long.parseLong(config[0], 16); + if (this.configVersion == null) { + this.configVersion = version; + } else if (version > this.configVersion) { + hostList = config[1]; + try { + // not blocking, but may cause the client to close the socket and migrate + // to a different server; in practice wait a short random period so clients + // migrate at different times + zk.updateServerList(hostList); + } catch (IOException e) { + System.err.println("Error updating server list"); + e.printStackTrace(); + } + this.configVersion = version; + } + } +} +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/jmx.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/jmx.mdx new file mode 100644 index 00000000000..e50ccb8ac94 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/jmx.mdx @@ -0,0 +1,96 @@ +--- +title: "JMX" +description: "How to enable and use JMX monitoring and management for ZooKeeper ensembles, including starting with JMX, connecting via jconsole, and a full MBean reference for replicated and standalone servers." +--- + +Apache ZooKeeper has extensive support for JMX, allowing you +to view and manage a ZooKeeper serving ensemble. + +This document assumes that you have basic knowledge of +JMX. See the [Sun JMX Technology](http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/) page to get started with JMX. + +See the [JMX Management Guide](http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html) for details on setting up local and +remote management of VM instances. By default the included +_zkServer.sh_ supports only local management — +review the linked document to enable support for remote management +(beyond the scope of this document). + +## Starting ZooKeeper with JMX Enabled + +The class `org.apache.zookeeper.server.quorum.QuorumPeerMain` +will start a JMX manageable ZooKeeper server. This class +registers the proper MBeans during initialization to support JMX +monitoring and management of the instance. See _bin/zkServer.sh_ for one +example of starting ZooKeeper using QuorumPeerMain. + +## Running a JMX Console + +There are a number of JMX consoles available which can connect +to the running server. For this example we will use Sun's _jconsole_. + +The Java JDK ships with a simple JMX console +named [jconsole](http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html) +which can be used to connect to ZooKeeper and inspect a running +server. Once you've started ZooKeeper using QuorumPeerMain, +start _jconsole_, which typically resides in _JDK_HOME/bin/jconsole_. + +When the "new connection" window is displayed, either connect +to the local process (if jconsole was started on the same host as the server) or +use the remote process connection. + +By default the "overview" tab for the VM is displayed. Select +the "MBeans" tab. + +You should now see _org.apache.ZooKeeperService_ +on the left hand side. Expand this item and depending on how you've +started the server you will be able to monitor and manage various +service related features. + +### Logback MBeans _(new in 3.8.0)_ + +Logback is the default logging backend of ZooKeeper since version 3.8.0. +It can be configured to register JMX MBeans by adding `` to _logback.xml_. More +information can be found on Logback's [website](https://logback.qos.ch/manual/jmxConfig.html). + +### Log4j MBeans _(deprecated)_ + +ZooKeeper will register log4j MBeans if log4j1 is configured as the logging backend of SLF4J. +In the same section along the left hand side you will see +"log4j". Expand that to manage log4j through JMX. Of particular +interest is the ability to dynamically change the logging levels +used by editing the appender and root thresholds. Log4j MBean +registration can be disabled by passing +_-Dzookeeper.jmx.log4j.disable=true_ to the JVM +when starting ZooKeeper. In addition, we can specify the name of +the MBean with the _-Dzookeeper.jmx.log4j.mbean=log4j:hierarchy=default_ +option, in case we need to upgrade an integrated system +using the old MBean name (`log4j:hierarchy = default`). + +## ZooKeeper MBean Reference + +### Replicated Ensemble MBeans + +This table details JMX for a server participating in a +replicated ZooKeeper ensemble (i.e. not standalone). This is the +typical case for a production environment. + +| MBean | MBean Object Name | Description | +| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Quorum | `ReplicatedServer_id<#>` | Represents the Quorum, or Ensemble — parent of all cluster members. Note that the object name includes the "myid" of the server (name suffix) that your JMX agent has connected to. | +| LocalPeer/RemotePeer | `replica.<#>` | Represents a local or remote peer (i.e. server participating in the ensemble). Note that the object name includes the "myid" of the server (name suffix). | +| LeaderElection | `LeaderElection` | Represents a ZooKeeper cluster leader election which is in progress. Provides information about the election, such as when it started. | +| Leader | `Leader` | Indicates that the parent replica is the leader and provides attributes/operations for that server. Note that Leader is a subclass of ZooKeeperServer, so it provides all of the information normally associated with a ZooKeeperServer node. | +| Follower | `Follower` | Indicates that the parent replica is a follower and provides attributes/operations for that server. Note that Follower is a subclass of ZooKeeperServer, so it provides all of the information normally associated with a ZooKeeperServer node. | +| DataTree | `InMemoryDataTree` | Statistics on the in-memory znode database, also operations to access finer (and more computationally intensive) statistics on the data (such as ephemeral count). InMemoryDataTrees are children of ZooKeeperServer nodes. | +| ServerCnxn | `` | Statistics on each client connection, also operations on those connections (such as termination). Note the object name is the session id of the connection in hex form. | + +### Standalone Server MBeans + +This table details JMX for a standalone server. Standalone is typically +only used in development situations. + +| MBean | MBean Object Name | Description | +| --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ZooKeeperServer | `StandaloneServer_port<#>` | Statistics on the running server, also operations to reset these attributes. Note that the object name includes the client port of the server (name suffix). | +| DataTree | `InMemoryDataTree` | Statistics on the in-memory znode database, also operations to access finer (and more computationally intensive) statistics on the data (such as ephemeral count). | +| ServerCnxn | `` | Statistics on each client connection, also operations on those connections (such as termination). Note the object name is the session id of the connection in hex form. | diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/meta.json new file mode 100644 index 00000000000..e60674705a1 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/meta.json @@ -0,0 +1,15 @@ +{ + "title": "Admin & Ops", + "pages": [ + "administrators-guide", + "quota-guide", + "snapshot-and-restore-guide", + "jmx", + "quorums", + "observers-guide", + "dynamic-reconfiguration", + "cli", + "tools", + "monitor-and-audit-logs" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/monitor-and-audit-logs.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/monitor-and-audit-logs.mdx new file mode 100644 index 00000000000..f4deb3f5092 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/monitor-and-audit-logs.mdx @@ -0,0 +1,371 @@ +--- +title: "Monitor & Audit Logs" +description: "How to monitor ZooKeeper with Prometheus, Grafana, and InfluxDB metrics, and how to enable and configure audit logging to track operations performed on the cluster." +--- + +## New Metrics System + +The New Metrics System has been available since 3.6.0. It provides rich metrics covering +znodes, network, disk, quorum, leader election, clients, security, failures, watches/sessions, +request processors, and more. + +### Metrics + +All available metrics are defined in `ServerMetrics.java`. + +### Configuring the Metrics Provider + +Enable the Prometheus `MetricsProvider` by adding the following to `zoo.cfg`: + +```properties +metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider +``` + +The HTTP port for Prometheus metrics scraping can be configured with (default is `7000`): + +```properties +metricsProvider.httpPort=7000 +``` + +#### Enabling HTTPS for Prometheus Metrics + +ZooKeeper supports SSL for the Prometheus metrics endpoint to provide secure data transmission. + +Define the HTTPS port: + +```properties +metricsProvider.httpsPort=4443 +``` + +Configure the SSL key store (holds the server's private key and certificate): + +```properties +metricsProvider.ssl.keyStore.location=/path/to/keystore.jks +metricsProvider.ssl.keyStore.password=your_keystore_password +metricsProvider.ssl.keyStore.type=jks # Default is JKS +``` + +Configure the SSL trust store (used to verify client certificates): + +```properties +metricsProvider.ssl.trustStore.location=/path/to/truststore.jks +metricsProvider.ssl.trustStore.password=your_truststore_password +metricsProvider.ssl.trustStore.type=jks # Default is JKS +``` + + +HTTP and HTTPS can be enabled simultaneously by defining both ports: + +```properties +metricsProvider.httpPort=7000 +metricsProvider.httpsPort=4443 +``` + + + +### Prometheus + +[Prometheus](https://prometheus.io/) is the easiest way to ingest and record ZooKeeper metrics. + +Install Prometheus from the official [download page](https://prometheus.io/download/). + +Configure the scraper to target your ZooKeeper cluster endpoints: + +```bash +cat > /tmp/test-zk.yaml <> /tmp/test-zk.log 2>&1 & +``` + +Prometheus will now scrape ZooKeeper metrics every 10 seconds. + +### Alerting with Prometheus + +Read the [Prometheus alerting documentation](https://prometheus.io/docs/practices/alerting/) +for alerting principles, and use [Prometheus Alertmanager](https://www.prometheus.io/docs/alerting/latest/alertmanager/) +to receive alert notifications via email or webhook. + +The following is a reference alerting rules file for common ZooKeeper metrics. Adjust +thresholds to match your environment. + +Validate the rules file with: + +```bash +./promtool check rules rules/zk.yml +``` + +`rules/zk.yml`: + +```yaml +groups: + - name: zk-alert-example + rules: + - alert: ZooKeeper server is down + expr: up == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "Instance {{ $labels.instance }} ZooKeeper server is down" + description: "{{ $labels.instance }} of job {{$labels.job}} ZooKeeper server is down: [{{ $value }}]." + + - alert: create too many znodes + expr: znode_count > 1000000 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} create too many znodes" + description: "{{ $labels.instance }} of job {{$labels.job}} create too many znodes: [{{ $value }}]." + + - alert: create too many connections + expr: num_alive_connections > 50 # suppose we use the default maxClientCnxns: 60 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} create too many connections" + description: "{{ $labels.instance }} of job {{$labels.job}} create too many connections: [{{ $value }}]." + + - alert: znode total occupied memory is too big + expr: approximate_data_size /1024 /1024 > 1 * 1024 # more than 1024 MB (1 GB) + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} znode total occupied memory is too big" + description: "{{ $labels.instance }} of job {{$labels.job}} znode total occupied memory is too big: [{{ $value }}] MB." + + - alert: set too many watch + expr: watch_count > 10000 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} set too many watch" + description: "{{ $labels.instance }} of job {{$labels.job}} set too many watch: [{{ $value }}]." + + - alert: a leader election happens + expr: increase(election_time_count[5m]) > 0 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} a leader election happens" + description: "{{ $labels.instance }} of job {{$labels.job}} a leader election happens: [{{ $value }}]." + + - alert: open too many files + expr: open_file_descriptor_count > 300 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} open too many files" + description: "{{ $labels.instance }} of job {{$labels.job}} open too many files: [{{ $value }}]." + + - alert: fsync time is too long + expr: rate(fsynctime_sum[1m]) > 100 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} fsync time is too long" + description: "{{ $labels.instance }} of job {{$labels.job}} fsync time is too long: [{{ $value }}]." + + - alert: take snapshot time is too long + expr: rate(snapshottime_sum[5m]) > 100 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} take snapshot time is too long" + description: "{{ $labels.instance }} of job {{$labels.job}} take snapshot time is too long: [{{ $value }}]." + + - alert: avg latency is too high + expr: avg_latency > 100 + for: 1m + labels: + severity: warning + annotations: + summary: "Instance {{ $labels.instance }} avg latency is too high" + description: "{{ $labels.instance }} of job {{$labels.job}} avg latency is too high: [{{ $value }}]." + + - alert: JvmMemoryFillingUp + expr: jvm_memory_bytes_used / jvm_memory_bytes_max{area="heap"} > 0.8 + for: 5m + labels: + severity: warning + annotations: + summary: "JVM memory filling up (instance {{ $labels.instance }})" + description: "JVM memory is filling up (> 80%)\n labels: {{ $labels }} value = {{ $value }}\n" +``` + +### Grafana + +Grafana has built-in Prometheus support. Add a Prometheus data source with the following settings: + +``` +Name: test-zk +Type: Prometheus +Url: http://localhost:9090 +Access: proxy +``` + +Download and import the default [ZooKeeper dashboard template](https://grafana.com/grafana/dashboards/10465) +and customize it to your needs. If you have improvements to share, send them to **dev@zookeeper.apache.org**. + +### InfluxDB + +InfluxDB is an open source time series database often used to store ZooKeeper metrics. +You can [download](https://portal.influxdata.com/downloads/) the open source version or +create a [free cloud account](https://cloud2.influxdata.com/signup). In either case, +configure the [Apache ZooKeeper Telegraf plugin](https://www.influxdata.com/integration/apache-zookeeper/) +to collect and store metrics from your ZooKeeper clusters. There is also an +[Apache ZooKeeper InfluxDB template](https://www.influxdata.com/influxdb-templates/zookeeper-monitor/) +that includes Telegraf configuration and a pre-built dashboard to get you started quickly. + +## JMX + +See the [JMX guide](/docs/admin-ops/jmx) for details. + +## Four Letter Words + +See the [Four Letter Words section](/docs/admin-ops/administrators-guide/commands) in the Administrator's Guide. + +## Audit Logs + +Apache ZooKeeper supports audit logging from version 3.6.0. By default audit logs are disabled. +To enable them, set `audit.enable=true` in `conf/zoo.cfg`. Audit logs are not written on every +ZooKeeper server — they are written only on the servers to which a client is connected, as +illustrated below. + +![Audit Logs](/docs-images/zkAuditLogs.jpg) + +The audit log captures detailed information for audited operations, written as `key=value` pairs: + +| Key | Value | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `session` | Client session ID. | +| `user` | Comma-separated list of users associated with the client session. See [Who is taken as user in audit logs?](#who-is-taken-as-user-in-audit-logs) | +| `ip` | Client IP address. | +| `operation` | The audited operation. Possible values: `serverStart`, `serverStop`, `create`, `delete`, `setData`, `setAcl`, `multiOperation`, `reconfig`, `ephemeralZNodeDeleteOnSessionClose`. | +| `znode` | Path of the znode. | +| `znode type` | Type of the znode (only for `create` operations). | +| `acl` | String representation of the znode ACL, e.g. `cdrwa` (create, delete, read, write, admin). Only logged for `setAcl`. | +| `result` | Outcome of the operation: `success`, `failure`, or `invoked`. The `invoked` result is used for `serverStop` because the stop is logged before the server has confirmed it actually stopped. | + +Sample audit logs for all operations, where the client connected from `192.168.1.2`, client +principal is `zkcli@HADOOP.COM`, and server principal is `zookeeper/192.168.1.3@HADOOP.COM`: + +``` +user=zookeeper/192.168.1.3 operation=serverStart result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/a znode_type=persistent result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/a znode_type=persistent result=failure +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/a result=failure +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/a result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=failure +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/b znode_type=persistent result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=setData znode=/b result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/b result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=multiOperation result=failure +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/a result=failure +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=delete znode=/a result=success +session=0x19344730001 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=create znode=/ephemral znode_type=ephemral result=success +session=0x19344730001 user=zookeeper/192.168.1.3 operation=ephemeralZNodeDeletionOnSessionCloseOrExpire znode=/ephemral result=success +session=0x19344730000 user=192.168.1.2,zkcli@HADOOP.COM ip=192.168.1.2 operation=reconfig znode=/zookeeper/config result=success +user=zookeeper/192.168.1.3 operation=serverStop result=invoked +``` + +### Audit Log Configuration + +Audit logging is performed using Logback. The following is the default logback configuration +block in `conf/logback.xml` (the entire block is commented out by default — uncomment it to +activate audit logging): + +```xml + + +``` + +Modify this configuration to customize the audit log filename, number of backup files, +maximum file size, or to use a custom audit logger. + +### Who is Taken as User in Audit Logs? + +There are four built-in authentication providers: + +- `IPAuthenticationProvider` — the authenticated IP address is used as the user. +- `SASLAuthenticationProvider` — the client principal is used as the user. +- `X509AuthenticationProvider` — the client certificate is used as the user. +- `DigestAuthenticationProvider` — the authenticated username is used as the user. + +Custom authentication providers can override `org.apache.zookeeper.server.auth.AuthenticationProvider.getUserName(String id)` +to provide a user name. If a custom provider does not override this method, the value stored in +`org.apache.zookeeper.data.Id.id` is used as the user. Generally only the user name is stored in +this field, but it is up to the custom provider what they store there. + +Not all ZooKeeper operations are initiated by clients — some are performed by the server itself. +For example, when a client session closes, any ephemeral znodes it owned are deleted by the server +directly. These are called system operations. For system operations, the user associated with the +ZooKeeper server principal is logged as the user. For example, if the server principal is +`zookeeper/hadoop.hadoop.com@HADOOP.COM`, it becomes the system user: + +``` +user=zookeeper/hadoop.hadoop.com@HADOOP.COM operation=serverStart result=success +``` + +If there is no user associated with the ZooKeeper server, the OS user who started the server +process is used. For example, if the server was started by `root`: + +``` +user=root operation=serverStart result=success +``` + +A single client can attach multiple authentication schemes to a session. In that case all +authenticated identities are taken as the user and presented as a comma-separated list. For +example, if a client is authenticated with principal `zkcli@HADOOP.COM` and IP `127.0.0.1`, +the create operation audit log will be: + +``` +session=0x10c0bcb0000 user=zkcli@HADOOP.COM,127.0.0.1 ip=127.0.0.1 operation=create znode=/a result=success +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/observers-guide.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/observers-guide.mdx new file mode 100644 index 00000000000..a8e7ce64316 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/observers-guide.mdx @@ -0,0 +1,110 @@ +--- +title: "Observers" +description: "How ZooKeeper Observers enable scaling to large numbers of clients without hurting write performance, by using non-voting ensemble members that can be added freely without affecting quorum." +--- + +Although ZooKeeper performs very well by having clients connect directly +to voting members of the ensemble, this architecture makes it hard to +scale out to huge numbers of clients. The problem is that as we add more +voting members, write performance drops. This is because a write operation +requires the agreement of at least half the nodes in an ensemble, so the +cost of a vote grows significantly as more voters are added. + +We have introduced a new type of ZooKeeper node called an _Observer_ which +helps address this problem and further improves ZooKeeper's scalability. Observers +are non-voting members of an ensemble which only hear the results of votes, not the +agreement protocol that leads up to them. Other than this simple distinction, +Observers function exactly the same as Followers — clients may connect to +them and send read and write requests to them. Observers forward these +requests to the Leader like Followers do, but they then simply wait to +hear the result of the vote. Because of this, we can increase the number +of Observers as much as we like without harming vote performance. + +Observers have other advantages. Because they do not vote, they are not a +critical part of the ZooKeeper ensemble — they can fail or be +disconnected from the cluster without harming the availability of the +ZooKeeper service. The benefit to the user is that Observers may connect +over less reliable network links than Followers. In fact, Observers may be +used to talk to a ZooKeeper server from another data center. Clients of +an Observer will see fast reads, as all reads are served locally, and +writes result in minimal network traffic since the number of messages +required without the vote protocol is smaller. + +## How to Use Observers + +Setting up a ZooKeeper ensemble that uses Observers requires just two +changes to your config files. + +First, in the config file of every node that is to be an Observer, add: + +``` +peerType=observer +``` + +This tells ZooKeeper that the server is to be an Observer. + +Second, in every server config file, append `:observer` to the server +definition line of each Observer. For example: + +``` +server.1=localhost:2181:3181:observer +``` + +This tells every other server that `server.1` is an Observer and that they +should not expect it to vote. This is all the configuration needed to add +an Observer to your ZooKeeper cluster. You can then connect to it as you +would an ordinary Follower: + +```bash +$ bin/zkCli.sh -server localhost:2181 +``` + +where `localhost:2181` is the hostname and port of the Observer as +specified in every config file. You should see a command line prompt +through which you can issue commands like `ls` to query the ZooKeeper service. + +## How to Use Observer Masters + +Observers function simply as non-voting members of the ensemble, sharing +the Learner interface with Followers and holding only a slightly different +internal pipeline. Both maintain connections along the quorum port with the +Leader by which they learn of all new proposals on the ensemble. + +By default, Observers connect to the Leader along its quorum port to learn of +new proposals. There are benefits to allowing Observers to connect to +Followers instead as a means of plugging into the commit stream. This shifts +the burden of supporting Observers off the Leader, allowing it to focus on +coordinating the commit of writes. The result is better performance when the +Leader is under high load — particularly high network load such as after a +leader election when many Learners need to sync. It also reduces the total +number of network connections maintained on the Leader when there are many +Observers. Activating this feature allows the overall number of Observers to +scale into the hundreds, and improves Observer availability since a large +number of Observers finish syncing and start serving client traffic faster. + +This feature is activated by adding the following entry to the server config +file. It instructs Observers to connect to peers (Leaders and Followers) on +the specified port, and instructs Followers to create an ObserverMaster thread +to listen and serve on that port: + +``` +observerMasterPort=2191 +``` + +## Example Use Cases + +Wherever you wish to scale the number of clients of your ZooKeeper ensemble, +or where you wish to insulate the critical part of an ensemble from the load +of dealing with client requests, Observers are a good architectural choice. +Two example use cases are: + +- **Datacenter bridge:** Forming a ZooKeeper ensemble between two datacenters is + problematic because high variance in latency between datacenters can lead to + false-positive failure detection and partitioning. However, if the ensemble runs + entirely in one datacenter and the second datacenter runs only Observers, + partitions are not problematic — the ensemble remains connected. Clients of the + Observers may still see and issue proposals. +- **Message bus integration:** Some use cases call for ZooKeeper as a component of + a persistent reliable message bus. Observers provide a natural integration point: + a plug-in mechanism can attach the stream of proposals an Observer sees to a + publish-subscribe system, without loading the core ensemble. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quorums.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quorums.mdx new file mode 100644 index 00000000000..90767354fd1 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quorums.mdx @@ -0,0 +1,230 @@ +--- +title: "Quorums" +description: "How to configure ZooKeeper quorums: hierarchical quorums using server groups and weights, and Oracle Quorum for increasing availability in two-instance clusters." +--- + +## Hierarchical Quorums + +This document gives an example of how to use hierarchical quorums. The basic idea is +very simple. First, we split servers into groups, and add a line for each group listing +the servers that form this group. Next we have to assign a weight to each server. + +The following example shows how to configure a system with three groups of three servers +each, and we assign a weight of 1 to each server: + +``` +group.1=1:2:3 +group.2=4:5:6 +group.3=7:8:9 + +weight.1=1 +weight.2=1 +weight.3=1 +weight.4=1 +weight.5=1 +weight.6=1 +weight.7=1 +weight.8=1 +weight.9=1 +``` + +When running the system, we are able to form a quorum once we have a majority of votes from +a majority of non-zero-weight groups. Groups that have zero weight are discarded and not +considered when forming quorums. Looking at the example, we are able to form a quorum once +we have votes from at least two servers from each of two different groups. + +## Oracle Quorum + +Oracle Quorum increases the availability of a cluster of 2 ZooKeeper instances with a failure detector known as the Oracle. +The Oracle is designed to grant permission to the instance which is the only remaining instance +in a 2-instance configuration when the other instance is identified as faulty by the failure detector. + +### The Implementation of the Oracle + +Every instance accesses a file which contains either `0` or `1` to indicate whether that instance is authorized by the Oracle. +This design can be changed since failure detector algorithms vary. You can override the `askOracle()` method in _QuorumOracleMaj_ to adapt a preferred way of reading the Oracle's decision. + +### Deployment Contexts + +The Oracle is designed to increase the availability of a cluster of **2** ZooKeeper instances; thus, the size of the voting member is **2**. +In other words, the Oracle solves the consensus problem of a possible faulty instance in a two-instance ensemble. + +When the size of the voting members exceeds 2, the expected way to make the Oracle work correctly is to reconfigure the cluster size when a faulty machine is identified. +For example, with a configuration of 5 instances, when a faulty machine breaks the connection with the Leader, a _reconfig_ client request is expected to re-form the cluster as 4 instances. +Once the size of the voting member equals 2, the configuration falls into the problem domain which the Oracle is designed to address. + +### Configuring the Oracle in `zoo.cfg` + +Regardless of the cluster size, `oraclePath` must be configured at initialization time, like other static parameters. +The following shows the correct way to specify and enable the Oracle: + +``` +oraclePath=/to/some/file +``` + +`QuorumOracleMaj` reads the result of a failure detector written to a text file — the oracle file. +Suppose you have the result of the failure detector written to `/some/path/result.txt`; the correct configuration is: + +``` +oraclePath=/some/path/result.txt +``` + +The oracle file should contain `1` to authorize the instance, or `0` to deny it. An example file can be created with: + +```bash +echo 1 > /some/path/result.txt +``` + +Any equivalent file is suitable for the current implementation of `QuorumOracleMaj`. +The number of oracle files should equal the number of ZooKeeper instances configured to enable the Oracle. +Each ZooKeeper instance should have its own oracle file — files must not be shared, otherwise the issues described in the Safety section will arise. + +#### Example `zoo.cfg` + +``` +dataDir=/data +dataLogDir=/datalog +tickTime=2000 +initLimit=5 +syncLimit=2 +autopurge.snapRetainCount=3 +autopurge.purgeInterval=0 +maxClientCnxns=60 +standaloneEnabled=true +admin.enableServer=true +oraclePath=/chassis/mastership +server.1=0.0.0.0:2888:3888;2181 +server.2=hw1:2888:3888;2181 +``` + +### Behavior After Enabling the Oracle + +_QuorumPeerConfig_ will create an instance of _QuorumOracleMaj_ instead of the default `QuorumMaj` when it reads an `oraclePath` in `zoo.cfg`. +`QuorumOracleMaj` inherits from `QuorumMaj` and differs from its superclass by overriding `containsQuorum()`. +`QuorumOracleMaj` executes its version of `containsQuorum` when the Leader loses all of its followers and fails to maintain the quorum. +In all other cases, _QuorumOracleMaj_ behaves identically to _QuorumMaj_. + +### Considerations When Using the Oracle + +We consider an asynchronous distributed system which consists of **2** ZooKeeper instances and an Oracle. + +#### Liveness Issue + +When the Oracle satisfies the following property introduced by [^1]: + +> **Strong Completeness:** There is a time after which every process that crashes is permanently suspected by every correct process. + +Liveness of the system is ensured by the Oracle. +However, when the Oracle fails to maintain this property, loss of liveness is expected. For example: + +Suppose we have a Leader and a Follower running in the broadcasting state. The system will lose its liveness when: + +1. The Leader fails, but the Oracle does not detect the faulty Leader — the Oracle will not authorize the Follower to become a new Leader. +2. A Follower fails, but the Oracle does not detect the faulty Follower — the Oracle will authorize the Leader to move the system forward. + +#### Safety Issue + +**Loss of Progress** + +Progress can be lost when multiple failures occur in the system at different times. For example: + +Suppose we have a Leader (Ben) and a Follower (John) in the broadcasting state: + +- **T1** `zxid(0x1_1)`: L-Ben fails, and F-John takes over under authorization from the Oracle. +- **T2** `zxid(0x2_1)`: F-John becomes a new Leader (L-John) and starts a new epoch. +- **T3** `zxid(0x2_A)`: L-John fails. +- **T4** `zxid(0x2_A)`: Ben recovers and starts leader election. +- **T5** `zxid(0x3_1)`: Ben becomes the new Leader (L-Ben) under authorization from the Oracle. + +In this case, the system loses its progress after L-Ben initially failed. + +However, loss of progress can be prevented by making the Oracle capable of referring to the latest zxid. +When the Oracle can refer to the latest zxid, at T5 `zxid(0x2_A)`, Ben will not complete leader election because the Oracle would not authorize him while John is still known to be ahead. +This trades liveness for safety. + +**Split Brain Issue** + +We consider the Oracle satisfies the following property introduced by [^1]: + +> **Accuracy:** There is a time after which some correct process is never suspected by any process. + +The decisions the Oracle gives out must be mutually exclusive. + +Suppose we have a Leader (Ben) and a Follower (John) in the broadcasting state: + +- At any time, the Oracle will not authorize both Ben and John simultaneously, even if each failure detector suspects the other. +- Equivalently: for any two Oracle files, their values must not both be `1` at the same time. + +Split brain is expected when the Oracle fails to maintain this property during leader election, which can happen at: + +1. System start. +2. A failed instance recovering from failure. + +### Examples of Failure Detector Implementations + +A failure detector's role is to authorize the querying ZooKeeper instance whether it has the right to move the system forward without waiting for the faulty instance. + +#### Hardware-based Implementation + +Suppose two dedicated hardware nodes, `hw1` and `hw2`, host ZooKeeper instances `zk1` and `zk2` respectively, forming a cluster. +A hardware device attached to both nodes can determine whether each is powered on. +When `hw1` is not powered on, `zk1` is undoubtedly faulty. +The hardware device then updates the oracle file on `hw2` to `1`, authorizing `zk2` to move the system forward. + +#### Software-based Implementation + +Suppose two dedicated hardware nodes, `hw1` and `hw2`, host ZooKeeper instances `zk1` and `zk2` respectively. +Two services, `o1` on `hw1` and `o2` on `hw2`, detect whether the other node is alive (for example, by pinging). +When `o1` cannot ping `hw2`, it identifies `hw2` as faulty and updates the oracle file of `zk1` to `1`, authorizing `zk1` to move forward. + +#### Using a USB Device as the Oracle + +In macOS 10.15.7 (19H2), external storage devices are mounted under `/Volumes`. +A USB device containing the required oracle file can serve as the Oracle. +When the device is connected, the oracle authorizes the leader to move the system forward. + +The following 6 steps demonstrate how this works: + +1. Insert a USB device named `Oracle`. The path `/Volumes/Oracle` will be accessible. + +2. Create a file containing `1` under `/Volumes/Oracle` named `mastership`: + + ```bash + echo 1 > mastership + ``` + + The path `/Volumes/Oracle/mastership` is now accessible to ZooKeeper instances. + +3. Create a `zoo.cfg` like the following: + + ``` + dataDir=/data + dataLogDir=/datalog + tickTime=2000 + initLimit=5 + syncLimit=2 + autopurge.snapRetainCount=3 + autopurge.purgeInterval=0 + maxClientCnxns=60 + standaloneEnabled=true + admin.enableServer=true + oraclePath=/Volumes/Oracle/mastership + server.1=0.0.0.0:2888:3888;2181 + server.2=hw1:2888:3888;2181 + ``` + + > **Note:** Split brain will not occur here because there is only a single USB device. `mastership` must not be shared by multiple instances — only one ZooKeeper instance should be configured with Oracle. See the [Safety Issue](#safety-issue) section for details. + +4. Start the cluster. It should form a quorum normally. + +5. Terminate the instance that is either not attached to a USB device or whose `mastership` file contains `0`. Two scenarios are expected: + - A leader failure occurs, and the remaining instance completes leader election on its own via the Oracle. + - The quorum is maintained via the Oracle. + +6. Remove the USB device. `/Volumes/Oracle/mastership` becomes unavailable. According to the current implementation, whenever the Leader queries the oracle and the file is missing, the oracle throws an exception and returns `false`. Repeating step 5 will result in either the system being unable to recover from a leader failure, or the leader losing the quorum and service being interrupted. + +With these steps, you can observe and practice how the Oracle works with a two-instance system. + +### Reference + +[^1]: Tushar Deepak Chandra and Sam Toueg. 1991. Unreliable failure detectors for asynchronous systems (preliminary version). In _Proceedings of the tenth annual ACM symposium on Principles of distributed computing_ (_PODC '91_). Association for Computing Machinery, New York, NY, USA, 325–340. [DOI:10.1145/112600.112627](https://doi.org/10.1145/112600.112627) diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quota-guide.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quota-guide.mdx new file mode 100644 index 00000000000..b9a439c0b8e --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/quota-guide.mdx @@ -0,0 +1,51 @@ +--- +title: "Quota Guide" +description: "ZooKeeper has both namespace and bytes quotas. You can use the ZooKeeperMain class to setup quotas." +--- + +ZooKeeper prints _WARN_ messages if users exceed the quota assigned to them. The messages +are printed in the log of the ZooKeeper. + +Notice: What the `namespace` quota means is the count quota which limits the number of children +under the path (included itself). + +```bash +$ bin/zkCli.sh -server host:port +``` + +The above command gives you a command line option of using quotas. + +## Setting Quotas + +- You can use `setquota` to set a quota on a ZooKeeper node. It has an option of setting quota with + `-n` (for namespace/count) and `-b` (for bytes/data length). +- The ZooKeeper quota is stored in ZooKeeper itself in **/zookeeper/quota**. To disable other people from + changing the quotas, users can set the ACL for **/zookeeper/quota** so that only admins are able to read and write to it. +- If the quota doesn't exist in the specified path, create the quota, otherwise update the quota. +- The scope of the quota users set is all the nodes under the path specified (included itself). +- In order to simplify the calculation of quota in the current directory/hierarchy structure, a complete + tree path (from root to leaf node) can be set only one quota. In the situation when setting a quota in + a path which its parent or child node already has a quota, `setquota` will reject and tell the specified + parent or child path. Users can adjust allocations of quotas (delete/move-up/move-down the quota) + according to specific circumstances. +- Combined with the Chroot, the quota will have a better isolation effectiveness between different + applications. For example: + + ```bash + # Chroot is: + 192.168.0.1:2181,192.168.0.2:2181,192.168.0.3:2181/apps/app1 + setquota -n 100000 /apps/app1 + ``` + +- Users cannot set the quota on the path under **/zookeeper/quota**. +- The quota supports soft and hard quotas. The soft quota just logs a warning when exceeding the quota, + but the hard quota also throws a `QuotaExceededException`. When setting soft and hard quota on the same + path, the hard quota has priority. + +## Listing Quotas + +You can use _listquota_ to list a quota on a ZooKeeper node. + +## Deleting Quotas + +You can use _delquota_ to delete quota on a ZooKeeper node. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/snapshot-and-restore-guide.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/snapshot-and-restore-guide.mdx new file mode 100644 index 00000000000..ce77e61080a --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/snapshot-and-restore-guide.mdx @@ -0,0 +1,65 @@ +--- +title: "Snapshot and Restore Guide" +description: "How to use ZooKeeper's snapshot and restore APIs to recover a cluster from quorum loss or catastrophic failure." +--- + +ZooKeeper is designed to withstand machine failures. A ZooKeeper cluster can automatically recover +from temporary failures such as machine reboots, and can tolerate up to (N-1)/2 permanent failures +for a cluster of N members due to hardware failures or disk corruption. When a member permanently +fails, it loses access to the cluster. If the cluster permanently loses more than (N-1)/2 members, +it disastrously fails and loses quorum. Once quorum is lost, the cluster cannot reach consensus and +therefore cannot continue to accept updates. + +To recover from such disastrous failures, ZooKeeper provides snapshot and restore functionalities to +restore a cluster from a snapshot. + +Key characteristics of snapshot and restore: + +1. They operate on the connected server via Admin Server APIs. +2. They are rate-limited to protect the server from being overloaded. +3. They require authentication and authorization on the root path with ALL permission. The supported + auth schemes are digest, x509, and IP. + +## Snapshot + +Recovering a cluster needs a snapshot from a ZooKeeper cluster. Users can periodically take +snapshots from a live server which has the highest zxid and stream out data to local or external +storage/file system (e.g., S3). + +```bash +# Takes a snapshot from the connected server. Rate-limited to once every 5 minutes by default. +curl -H 'Authorization: digest root:root_passwd' \ + http://hostname:adminPort/commands/snapshot?streaming=true \ + --output snapshotFileName +``` + +## Restore + +Restoring a cluster needs a single snapshot as input stream. Restore can be used for recovering a +cluster after quorum loss or for building a brand-new cluster with seed data. + +All members should restore using the same snapshot. The recommended steps are: + + + Block traffic on the client port or client secure port before restore starts. + + Take a snapshot of the latest database state using the snapshot admin server command, if + applicable. + + + For each server: + - Move the files in `dataDir` and `dataLogDir` to a different location to prevent the restored + database from being overwritten when the server restarts after restore. + - Restore the server using the restore admin server command: + +```bash +# Restores the db of the connected server from a snapshot input stream. Rate-limited to once every 5 minutes by default. +curl -H 'Content-Type: application/octet-stream' \ + -H 'Authorization: digest root:root_passwd' \ + -X POST http://hostname:adminPort/commands/restore \ + --data-binary "@snapshotFileName" +``` + + + Unblock traffic on the client port or client secure port after restore completes. + diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx new file mode 100644 index 00000000000..c613a755d42 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx @@ -0,0 +1,642 @@ +--- +title: "Tools" +description: "Reference for the scripts and tools bundled with ZooKeeper — including server management scripts, snapshot and transaction log utilities, benchmark tools, and testing frameworks." +--- + +## Scripts + +### zkServer.sh + +Manage the ZooKeeper server process. + +```bash +# start the server +./zkServer.sh start + +# start the server in the foreground (useful for debugging) +./zkServer.sh start-foreground + +# stop the server +./zkServer.sh stop + +# restart the server +./zkServer.sh restart + +# show the status, mode, and role of the server +./zkServer.sh status +JMX enabled by default +Using config: /data/software/zookeeper/conf/zoo.cfg +Mode: standalone + +# print the startup parameters +./zkServer.sh print-cmd + +# show the ZooKeeper server version +./zkServer.sh version +Apache ZooKeeper, version 3.6.0-SNAPSHOT 06/11/2019 05:39 GMT +``` + +The `status` command establishes a client connection to execute diagnostic commands. +When the ZooKeeper cluster is started in TLS-only mode (by omitting `clientPort` from +`zoo.cfg`), additional SSL configuration must be provided: + +```bash +CLIENT_JVMFLAGS="-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty \ + -Dzookeeper.ssl.trustStore.location=/tmp/clienttrust.jks \ + -Dzookeeper.ssl.trustStore.password=password \ + -Dzookeeper.ssl.keyStore.location=/tmp/client.jks \ + -Dzookeeper.ssl.keyStore.password=password \ + -Dzookeeper.client.secure=true" \ + ./zkServer.sh status +``` + +### zkCli.sh + +See [ZooKeeper CLI](/docs/admin-ops/cli). + +### zkEnv.sh + +Sets environment variables for the ZooKeeper server. Key variables: + +- `ZOO_LOG_DIR` — the directory where logs are stored. + +### zkCleanup.sh + +Clean up old snapshots and transaction logs. + +```bash +# Usage: ./zkCleanup.sh dataLogDir [snapDir] -n count +# dataLogDir -- path to the transaction log directory +# snapDir -- path to the snapshot directory (optional) +# count -- number of recent snaps/logs to keep (must be >= 3) + +# Keep the latest 5 logs and snapshots +./zkCleanup.sh -n 5 +``` + +### zkTxnLogToolkit.sh + +Dump and recover transaction log files with broken CRC entries. + +```bash +$ bin/zkTxnLogToolkit.sh +usage: TxnLogToolkit [-dhrv] txn_log_file_name +-d,--dump Dump mode. Dump all entries of the log file. (this is the default) +-h,--help Print help message +-r,--recover Recovery mode. Re-calculate CRC for broken entries. +-v,--verbose Be verbose in recovery mode: print all entries, not just fixed ones. +-y,--yes Non-interactive mode: repair all CRC errors without asking +``` + +The default behavior is safe — it dumps the entries of the given transaction log file +to the screen (same as `-d,--dump`): + +```bash +$ bin/zkTxnLogToolkit.sh log.100000001 +ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 +4/5/18 2:15:58 PM CEST session 0x16295bafcc40000 cxid 0x0 zxid 0x100000001 createSession 30000 +CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null +4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null +4/5/18 2:16:12 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x100000003 createSession 30000 +4/5/18 2:17:34 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x200000001 closeSession null +4/5/18 2:17:34 PM CEST session 0x16295bd23720000 cxid 0x0 zxid 0x200000002 createSession 30000 +4/5/18 2:17:34 PM CEST session 0x16295bd23720000 cxid 0x2 zxid 0x200000003 create '/andor,#626262,v{s{31,s{'world,'anyone}}},F,1 +EOF reached after 6 txns. +``` + +In **recovery mode** (`-r,--recover`), the original file is left untouched and all transactions +are copied to a new file with a `.fixed` suffix. CRC values are recalculated; if the calculated +value does not match the original, the new value is used. By default the tool is interactive, +asking for confirmation on each CRC error: + +```bash +$ bin/zkTxnLogToolkit.sh -r log.100000001 +ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 +CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null +Would you like to fix it (Yes/No/Abort) ? +``` + +- **Yes** — write the recalculated CRC to the new file. +- **No** — copy the original CRC value. +- **Abort** — abort the operation. The `.fixed` file will not be deleted and may be in a half-complete state. + +```bash +$ bin/zkTxnLogToolkit.sh -r log.100000001 +ZooKeeper Transactional Log File with dbid 0 txnlog format version 2 +CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null +Would you like to fix it (Yes/No/Abort) ? y +EOF reached after 6 txns. +Recovery file log.100000001.fixed has been written with 1 fixed CRC error(s) +``` + +Use `-v,--verbose` to print all records (not just broken ones). Use `-y,--yes` to fix all +CRC errors automatically without prompting. + +### zkSnapShotToolkit.sh + +Dump a snapshot file to stdout, showing detailed information for each znode. + +```bash +# show usage +./zkSnapShotToolkit.sh +USAGE: SnapshotFormatter [-d|-json] snapshot_file + -d dump the data for each znode + -json dump znode info in json format + +# show each znode's metadata without data content +./zkSnapShotToolkit.sh /data/zkdata/version-2/snapshot.fa01000186d +/zk-latencies_4/session_946 + cZxid = 0x00000f0003110b + ctime = Wed Sep 19 21:58:22 CST 2018 + mZxid = 0x00000f0003110b + mtime = Wed Sep 19 21:58:22 CST 2018 + pZxid = 0x00000f0003110b + cversion = 0 + dataVersion = 0 + aclVersion = 0 + ephemeralOwner = 0x00000000000000 + dataLength = 100 + +# -d: include data content +./zkSnapShotToolkit.sh -d /data/zkdata/version-2/snapshot.fa01000186d +/zk-latencies2/session_26229 + cZxid = 0x00000900007ba0 + ctime = Wed Aug 15 20:13:52 CST 2018 + mZxid = 0x00000900007ba0 + mtime = Wed Aug 15 20:13:52 CST 2018 + pZxid = 0x00000900007ba0 + cversion = 0 + dataVersion = 0 + aclVersion = 0 + ephemeralOwner = 0x00000000000000 + data = eHh4eHh4eHh4eHh4eA== + +# -json: output in JSON format +./zkSnapShotToolkit.sh -json /data/zkdata/version-2/snapshot.fa01000186d +[[1,0,{"progname":"SnapshotFormatter.java","progver":"0.01","timestamp":1559788148637},[{"name":"\/","asize":0,"dsize":0,"dev":0,"ino":1001},[{"name":"zookeeper","asize":0,"dsize":0,"dev":0,"ino":1002},{"name":"config","asize":0,"dsize":0,"dev":0,"ino":1003},[{"name":"quota","asize":0,"dsize":0,"dev":0,"ino":1004},[{"name":"test","asize":0,"dsize":0,"dev":0,"ino":1005},{"name":"zookeeper_limits","asize":52,"dsize":52,"dev":0,"ino":1006},{"name":"zookeeper_stats","asize":15,"dsize":15,"dev":0,"ino":1007}]]],{"name":"test","asize":0,"dsize":0,"dev":0,"ino":1008}]] +``` + +### zkSnapshotRecursiveSummaryToolkit.sh + +Recursively collect and display child count and data size for a selected node. + +```bash +$ ./zkSnapshotRecursiveSummaryToolkit.sh +USAGE: +SnapshotRecursiveSummary + +snapshot_file: path to the ZooKeeper snapshot +starting_node: the path in the ZooKeeper tree where traversal begins +max_depth: depth limit for output (0 = no limit; 1 = starting node + direct children; + 2 = one more level, etc.). Only affects display, NOT the calculation. +``` + +```bash +# display stats for the root node and 2 levels of descendants +./zkSnapshotRecursiveSummaryToolkit.sh /data/zkdata/version-2/snapshot.fa01000186d / 2 + +/ + children: 1250511 + data: 1952186580 +-- /zookeeper +-- children: 1 +-- data: 0 +-- /solr +-- children: 1773 +-- data: 8419162 +---- /solr/configs +---- children: 1640 +---- data: 8407643 +---- /solr/overseer +---- children: 6 +---- data: 0 +---- /solr/live_nodes +---- children: 3 +---- data: 0 +``` + +### zkSnapshotComparer.sh + +Compare two snapshots with configurable thresholds and filters, outputting the delta — +which znodes were added, updated, or deleted. Useful for offline consistency checks and +data trend analysis. Only permanent nodes are reported; sessions and ephemeral nodes are ignored. + +Tuning parameters: + +- `--nodes` — threshold for number of descendant nodes added/removed. +- `--bytes` — threshold for bytes added/removed. + +#### Locating Snapshots + +Snapshots are stored in the [ZooKeeper data directory](/docs/admin-ops/administrators-guide/data-file-management#the-data-directory) +configured in `conf/zoo.cfg`. + +#### Supported Snapshot Formats + +Uncompressed snapshots and compressed formats (`snappy`, `gz`) are all supported. +Snapshots in different formats can be compared directly without manual decompression. + +#### Running the Tool + +Running the tool with no arguments prints the help page: + +``` +usage: java -cp org.apache.zookeeper.server.SnapshotComparer + -b,--bytes (Required) The node data delta size threshold, in bytes, for printing the node. + -d,--debug Use debug output. + -i,--interactive Enter interactive mode. + -l,--left (Required) The left snapshot file. + -n,--nodes (Required) The descendant node delta size threshold, in nodes, for printing the node. + -r,--right (Required) The right snapshot file. +``` + +Example command: + +``` +./bin/zkSnapshotComparer.sh -l /zookeeper-data/backup/snapshot.d.snappy -r /zookeeper-data/backup/snapshot.44 -b 2 -n 1 +``` + +Example output: + +``` +... +Deserialized snapshot in snapshot.44 in 0.002741 seconds +Processed data tree in 0.000361 seconds +Node count: 10 +Total size: 0 +Max depth: 4 +Count of nodes at depth 0: 1 +Count of nodes at depth 1: 2 +Count of nodes at depth 2: 4 +Count of nodes at depth 3: 3 + +Node count: 22 +Total size: 2903 +Max depth: 5 +Count of nodes at depth 0: 1 +Count of nodes at depth 1: 2 +Count of nodes at depth 2: 4 +Count of nodes at depth 3: 7 +Count of nodes at depth 4: 8 + +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Analysis for depth 0 +Node found in both trees. Delta: 2903 bytes, 12 descendants +Analysis for depth 1 +Node /zk_test found in both trees. Delta: 2903 bytes, 12 descendants +Analysis for depth 2 +Node /zk_test/gz found in both trees. Delta: 730 bytes, 3 descendants +Node /zk_test/snappy found in both trees. Delta: 2173 bytes, 9 descendants +Analysis for depth 3 +Node /zk_test/gz/12345 found in both trees. Delta: 9 bytes, 1 descendants +Node /zk_test/gz/a found only in right tree. Descendant size: 721. Descendant count: 0 +Node /zk_test/snappy/anotherTest found in both trees. Delta: 1738 bytes, 2 descendants +Node /zk_test/snappy/test_1 found only in right tree. Descendant size: 344. Descendant count: 3 +Node /zk_test/snappy/test_2 found only in right tree. Descendant size: 91. Descendant count: 2 +Analysis for depth 4 +Node /zk_test/gz/12345/abcdef found only in right tree. Descendant size: 9. Descendant count: 0 +Node /zk_test/snappy/anotherTest/abc found only in right tree. Descendant size: 1738. Descendant count: 0 +Node /zk_test/snappy/test_1/a found only in right tree. Descendant size: 93. Descendant count: 0 +Node /zk_test/snappy/test_1/b found only in right tree. Descendant size: 251. Descendant count: 0 +Node /zk_test/snappy/test_2/xyz found only in right tree. Descendant size: 33. Descendant count: 0 +Node /zk_test/snappy/test_2/y found only in right tree. Descendant size: 58. Descendant count: 0 +All layers compared. +``` + +#### Interactive Mode + +Add `-i` / `--interactive` to enter interactive mode: + +``` +./bin/zkSnapshotComparer.sh -l /zookeeper-data/backup/snapshot.d.snappy -r /zookeeper-data/backup/snapshot.44 -b 2 -n 1 -i +``` + +Three navigation options are available: + +- Press **Enter** to print the current depth layer. +- Type a **number** to jump to and print all nodes at that depth. +- Enter an **absolute path** (starting with `/`) to print the immediate subtree of that node. + +Note: only nodes passing the bytes and nodes thresholds are shown. + +Press Enter to move to the next depth layer: + +``` +Current depth is 0 +Press enter to move to print current depth layer; +... +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Analysis for depth 0 +Node found in both trees. Delta: 2903 bytes, 12 descendants +``` + +Type a number to jump forward or backward to a specific depth: + +``` +Current depth is 1 +... +Type a number to jump to and print all nodes at a given depth; +... +3 +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Analysis for depth 3 +Node /zk_test/gz/12345 found in both trees. Delta: 9 bytes, 1 descendants +Node /zk_test/gz/a found only in right tree. Descendant size: 721. Descendant count: 0 +Filtered node /zk_test/gz/anotherOne of left size 0, right size 0 +Filtered right node /zk_test/gz/b of size 0 +Node /zk_test/snappy/anotherTest found in both trees. Delta: 1738 bytes, 2 descendants +Node /zk_test/snappy/test_1 found only in right tree. Descendant size: 344. Descendant count: 3 +Node /zk_test/snappy/test_2 found only in right tree. Descendant size: 91. Descendant count: 2 + +Current depth is 3 +... +Type a number to jump to and print all nodes at a given depth; +... +0 +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Analysis for depth 0 +Node found in both trees. Delta: 2903 bytes, 12 descendants +``` + +Out-of-range depth is handled gracefully: + +``` +Current depth is 1 +... +10 +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Depth must be in range [0, 4] +``` + +Enter an absolute path to print the immediate subtree of a node: + +``` +Current depth is 3 +... +Enter an ABSOLUTE path to print the immediate subtree of a node. +/zk_test +Printing analysis for nodes difference larger than 2 bytes or node count difference larger than 1. +Analysis for node /zk_test +Node /zk_test/gz found in both trees. Delta: 730 bytes, 3 descendants +Node /zk_test/snappy found in both trees. Delta: 2173 bytes, 9 descendants +``` + +Invalid path and invalid input are handled: + +``` +Enter an ABSOLUTE path to print the immediate subtree of a node. +/non-exist-path +Analysis for node /non-exist-path +Path /non-exist-path is neither found in left tree nor right tree. + +12223999999999999999999999999999999999999 +Input 12223999999999999999999999999999999999999 is not valid. Depth must be in range [0, 4]. Path must be an absolute path which starts with '/'. +``` + +The tool exits interactive mode automatically when all layers are compared, or press `^C` to exit at any time. + +## Benchmark + +### YCSB + +[YCSB](https://github.com/brianfrankcooper/YCSB) (Yahoo Cloud Serving Benchmark) can be used to benchmark ZooKeeper. Follow the steps below to get started. + + + +**Start ZooKeeper Server(s)** + +Start your ZooKeeper ensemble before running any benchmark. + + + + +**Install Java and Maven** + +Ensure a JDK and Maven are installed on the machine running the benchmark. + + + + +**Set Up YCSB** + +Clone and build the ZooKeeper binding: + +```bash +git clone http://github.com/brianfrankcooper/YCSB.git +cd YCSB +mvn -pl site.ycsb:zookeeper-binding -am clean package -DskipTests +``` + +See the [YCSB README](https://github.com/brianfrankcooper/YCSB#getting-started) for more details. + + + + +**Configure ZooKeeper Connection Parameters** + +Set the following properties in your workload file or via the shell: + +- `zookeeper.connectString` — connection string (e.g. `127.0.0.1:2181/benchmark`) +- `zookeeper.sessionTimeout` — session timeout in milliseconds +- `zookeeper.watchFlag` — enable ZooKeeper watches (`true` or `false`, default `false`). This measures the effect of watch overhead on read/write performance, not watch notification latency. + +```bash +./bin/ycsb run zookeeper -s -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark \ + -p zookeeper.watchFlag=true +``` + +Or set properties directly on the command line (create the `/benchmark` namespace first using `create /benchmark` in the CLI): + +```bash +./bin/ycsb run zookeeper -s -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark \ + -p zookeeper.sessionTimeout=30000 +``` + + + + +**Load Data and Run Tests** + +Load data: + +```bash +# -p recordcount: number of znodes to insert +./bin/ycsb load zookeeper -s -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark \ + -p recordcount=10000 > outputLoad.txt +``` + +Run the workload (`workloadb` is recommended as the most representative read-heavy workload): + +```bash +# test the effect of value size on performance +./bin/ycsb run zookeeper -s -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark -p fieldlength=1000 + +# test with multiple fields +./bin/ycsb run zookeeper -s -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark -p fieldcount=20 + +# HDR histogram output +./bin/ycsb run zookeeper -threads 1 -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark \ + -p hdrhistogram.percentiles=10,25,50,75,90,95,99,99.9 \ + -p histogram.buckets=500 + +# multi-client test (increase maxClientCnxns in zoo.cfg as needed) +./bin/ycsb run zookeeper -threads 10 -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark + +# timeseries output +./bin/ycsb run zookeeper -threads 1 -P workloads/workloadb \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark \ + -p measurementtype=timeseries -p timeseries.granularity=50 + +# cluster test +./bin/ycsb run zookeeper -P workloads/workloadb \ + -p zookeeper.connectString=192.168.10.43:2181,192.168.10.45:2181,192.168.10.27:2181/benchmark + +# test leader performance only +./bin/ycsb run zookeeper -P workloads/workloadb \ + -p zookeeper.connectString=192.168.10.43:2181/benchmark + +# large znodes (default jute.maxbuffer = 1 MB; set the same value on all ZK servers) +./bin/ycsb run zookeeper -jvm-args="-Djute.maxbuffer=4194304" -s -P workloads/workloadc \ + -p zookeeper.connectString=127.0.0.1:2181/benchmark + +# clean up after benchmarking: CLI: deleteall /benchmark +``` + + + + +### zk-smoketest + +[zk-smoketest](https://github.com/phunt/zk-smoketest) provides a simple smoketest client +for a ZooKeeper ensemble. Useful for verifying new, updated, or existing installations. + +## Testing + +### Fault Injection Framework + +#### Byteman + +[Byteman](https://byteman.jboss.org/) is a tool for tracing, monitoring, and testing Java +application and JDK runtime code. It injects Java code into methods without requiring +recompilation, repackaging, or redeployment — and injection can be performed at JVM startup +or while the application is running. See the [Byteman tutorial](https://developer.jboss.org/wiki/ABytemanTutorial) +for a quick introduction. + +```bash +# Attach Byteman to 3 ZooKeeper servers at runtime +# (55001/55002/55003 = Byteman ports; 714/740/758 = ZK server PIDs) +./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55001 714 +./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55002 740 +./bminstall.sh -b -Dorg.jboss.byteman.transform.all -Dorg.jboss.byteman.verbose -p 55003 758 + +# load a fault injection script +./bmsubmit.sh -p 55002 -l my_zk_fault_injection.btm +# unload a fault injection script +./bmsubmit.sh -p 55002 -u my_zk_fault_injection.btm +``` + +**Example 1:** Force a leader re-election by rolling over the leader's zxid. + +```bash +cat zk_leader_zxid_roll_over.btm + +RULE trace zk_leader_zxid_roll_over +CLASS org.apache.zookeeper.server.quorum.Leader +METHOD propose +IF true +DO + traceln("*** Leader zxid has rolled over, forcing re-election ***"); + $1.zxid = 4294967295L +ENDRULE +``` + +**Example 2:** Make the leader drop ping packets to a specific follower. The leader will close +the `LearnerHandler` for that follower, and the follower will re-enter the quorum. + +```bash +cat zk_leader_drop_ping_packet.btm + +RULE trace zk_leader_drop_ping_packet +CLASS org.apache.zookeeper.server.quorum.LearnerHandler +METHOD ping +AT ENTRY +IF $0.sid == 2 +DO + traceln("*** Leader drops ping packet to sid: 2 ***"); + return; +ENDRULE +``` + +**Example 3:** Make a follower drop ACK packets. This has limited effect during broadcast since +the leader only needs a majority of ACKs to commit a proposal. + +```bash +cat zk_follower_drop_ack_packet.btm + +RULE trace zk.follower_drop_ack_packet +CLASS org.apache.zookeeper.server.quorum.SendAckRequestProcessor +METHOD processRequest +AT ENTRY +IF true +DO + traceln("*** Follower drops ACK packet ***"); + return; +ENDRULE +``` + +### Jepsen Test + +[Jepsen](https://github.com/jepsen-io/jepsen) is a framework for distributed systems +verification with fault injection. It has been used to verify eventually-consistent databases, +linearizable coordination systems, and distributed task schedulers. + +Running the [Dockerized Jepsen](https://github.com/jepsen-io/jepsen/blob/master/docker/README.md) +is the simplest way to get started. + +Installation: + +```bash +git clone git@github.com:jepsen-io/jepsen.git +cd docker +# initial setup may take a while +./up.sh +# verify one control node and five DB nodes are running +docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 8265f1d3f89c docker_control "/bin/sh -c /init.sh" 9 hours ago Up 4 hours 0.0.0.0:32769->8080/tcp jepsen-control + 8a646102da44 docker_n5 "/run.sh" 9 hours ago Up 3 hours 22/tcp jepsen-n5 + 385454d7e520 docker_n1 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n1 + a62d6a9d5f8e docker_n2 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n2 + 1485e89d0d9a docker_n3 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n3 + 27ae01e1a0c5 docker_node "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-node + 53c444b00ebd docker_n4 "/run.sh" 9 hours ago Up 9 hours 22/tcp jepsen-n4 +``` + +Running the test: + +```bash +# enter the control container +docker exec -it jepsen-control bash +# run the ZooKeeper test +cd zookeeper && lein run test --concurrency 10 +# passing output looks like: +INFO [2019-04-01 11:25:23,719] jepsen worker 8 - jepsen.util 8 :ok :read 2 +INFO [2019-04-01 11:25:23,722] jepsen worker 3 - jepsen.util 3 :invoke :cas [0 4] +INFO [2019-04-01 11:25:23,760] jepsen worker 3 - jepsen.util 3 :fail :cas [0 4] +INFO [2019-04-01 11:25:23,791] jepsen worker 1 - jepsen.util 1 :invoke :read nil +INFO [2019-04-01 11:25:23,794] jepsen worker 1 - jepsen.util 1 :ok :read 2 +INFO [2019-04-01 11:25:24,038] jepsen worker 0 - jepsen.util 0 :invoke :write 4 +INFO [2019-04-01 11:25:24,073] jepsen worker 0 - jepsen.util 0 :ok :write 4 +............................................................................... +Everything looks good! ヽ('ー`)ノ +``` + +Read [this blog post](https://aphyr.com/posts/291-call-me-maybe-zookeeper) to learn more +about the Jepsen analysis of ZooKeeper. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/basic-tutorial.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/basic-tutorial.mdx new file mode 100644 index 00000000000..c831085e08b --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/basic-tutorial.mdx @@ -0,0 +1,645 @@ +--- +title: "Basic tutorial" +description: "Step-by-step tutorial implementing ZooKeeper-based Barrier and Queue primitives in Java, demonstrating watches, ephemeral nodes, and sequential znodes for distributed coordination." +--- + +## Introduction + +In this tutorial, we show simple implementations of barriers and +producer-consumer queues using ZooKeeper. We call the respective classes Barrier and Queue. +These examples assume that you have at least one ZooKeeper server running. + +Both primitives use the following common excerpt of code: + +```java +static ZooKeeper zk = null; +static Integer mutex; + +String root; + +SyncPrimitive(String address) { + if(zk == null){ + try { + System.out.println("Starting ZK:"); + zk = new ZooKeeper(address, 3000, this); + mutex = new Integer(-1); + System.out.println("Finished starting ZK: " + zk); + } catch (IOException e) { + System.out.println(e.toString()); + zk = null; + } + } +} + +synchronized public void process(WatchedEvent event) { + synchronized (mutex) { + mutex.notify(); + } +} +``` + +Both classes extend SyncPrimitive. In this way, we execute steps that are +common to all primitives in the constructor of SyncPrimitive. To keep the examples +simple, we create a ZooKeeper object the first time we instantiate either a barrier +object or a queue object, and we declare a static variable that is a reference +to this object. The subsequent instances of Barrier and Queue check whether a +ZooKeeper object exists. Alternatively, we could have the application creating a +ZooKeeper object and passing it to the constructor of Barrier and Queue. + +We use the process() method to process notifications triggered due to watches. +In the following discussion, we present code that sets watches. A watch is internal +structure that enables ZooKeeper to notify a client of a change to a node. For example, +if a client is waiting for other clients to leave a barrier, then it can set a watch and +wait for modifications to a particular node, which can indicate that it is the end of the wait. +This point becomes clear once we go over the examples. + +## Barriers + +A barrier is a primitive that enables a group of processes to synchronize the +beginning and the end of a computation. The general idea of this implementation +is to have a barrier node that serves the purpose of being a parent for individual +process nodes. Suppose that we call the barrier node "/b1". Each process "p" then +creates a node "/b1/p". Once enough processes have created their corresponding +nodes, joined processes can start the computation. + +In this example, each process instantiates a Barrier object, and its constructor takes as parameters: + +- the address of a ZooKeeper server (e.g., "zoo1.foo.com:2181") +- the path of the barrier node on ZooKeeper (e.g., "/b1") +- the size of the group of processes + +The constructor of Barrier passes the address of the Zookeeper server to the +constructor of the parent class. The parent class creates a ZooKeeper instance if +one does not exist. The constructor of Barrier then creates a +barrier node on ZooKeeper, which is the parent node of all process nodes, and +we call root (**Note:** This is not the ZooKeeper root "/"). + +```java +/** + * Barrier constructor + * + * @param address + * @param root + * @param size + */ +Barrier(String address, String root, int size) { + super(address); + this.root = root; + this.size = size; + // Create barrier node + if (zk != null) { + try { + Stat s = zk.exists(root, false); + if (s == null) { + zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT); + } + } catch (KeeperException e) { + System.out + .println("Keeper exception when instantiating queue: " + + e.toString()); + } catch (InterruptedException e) { + System.out.println("Interrupted exception"); + } + } + + // My node name + try { + name = new String(InetAddress.getLocalHost().getCanonicalHostName().toString()); + } catch (UnknownHostException e) { + System.out.println(e.toString()); + } +} +``` + +To enter the barrier, a process calls enter(). The process creates a node under +the root to represent it, using its host name to form the node name. It then wait +until enough processes have entered the barrier. A process does it by checking +the number of children the root node has with "getChildren()", and waiting for +notifications in the case it does not have enough. To receive a notification when +there is a change to the root node, a process has to set a watch, and does it +through the call to "getChildren()". In the code, we have that "getChildren()" +has two parameters. The first one states the node to read from, and the second is +a boolean flag that enables the process to set a watch. In the code the flag is true. + +```java +/** + * Join barrier + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ + +boolean enter() throws KeeperException, InterruptedException{ + zk.create(root + "/" + name, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.EPHEMERAL); + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + + if (list.size() < size) { + mutex.wait(); + } else { + return true; + } + } + } +} +``` + +Note that enter() throws both KeeperException and InterruptedException, so it is +the responsibility of the application to catch and handle such exceptions. + +Once the computation is finished, a process calls leave() to leave the barrier. +First it deletes its corresponding node, and then it gets the children of the root +node. If there is at least one child, then it waits for a notification (obs: note +that the second parameter of the call to getChildren() is true, meaning that +ZooKeeper has to set a watch on the root node). Upon reception of a notification, +it checks once more whether the root node has any children. + +```java +/** + * Wait until all reach barrier + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ + +boolean leave() throws KeeperException, InterruptedException { + zk.delete(root + "/" + name, 0); + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + if (list.size() > 0) { + mutex.wait(); + } else { + return true; + } + } + } + } +``` + +## Producer-Consumer Queues + +A producer-consumer queue is a distributed data structure that groups of processes +use to generate and consume items. Producer processes create new elements and add +them to the queue. Consumer processes remove elements from the list, and process them. +In this implementation, the elements are simple integers. The queue is represented +by a root node, and to add an element to the queue, a producer process creates a new node, +a child of the root node. + +The following excerpt of code corresponds to the constructor of the object. As +with Barrier objects, it first calls the constructor of the parent class, SyncPrimitive, +that creates a ZooKeeper object if one doesn't exist. It then verifies if the root +node of the queue exists, and creates if it doesn't. + +```java +/** + * Constructor of producer-consumer queue + * + * @param address + * @param name + */ +Queue(String address, String name) { + super(address); + this.root = name; + // Create ZK node name + if (zk != null) { + try { + Stat s = zk.exists(root, false); + if (s == null) { + zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT); + } + } catch (KeeperException e) { + System.out + .println("Keeper exception when instantiating queue: " + + e.toString()); + } catch (InterruptedException e) { + System.out.println("Interrupted exception"); + } + } +} +``` + +A producer process calls "produce()" to add an element to the queue, and passes +an integer as an argument. To add an element to the queue, the method creates a +new node using "create()", and uses the SEQUENCE flag to instruct ZooKeeper to +append the value of the sequencer counter associated to the root node. In this way, +we impose a total order on the elements of the queue, thus guaranteeing that the +oldest element of the queue is the next one consumed. + +```java +/** + * Add element to the queue. + * + * @param i + * @return + */ + +boolean produce(int i) throws KeeperException, InterruptedException{ + ByteBuffer b = ByteBuffer.allocate(4); + byte[] value; + + // Add child with value i + b.putInt(i); + value = b.array(); + zk.create(root + "/element", value, Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT_SEQUENTIAL); + + return true; +} +``` + +To consume an element, a consumer process obtains the children of the root node, +reads the node with smallest counter value, and returns the element. Note that +if there is a conflict, then one of the two contending processes won't be able to +delete the node and the delete operation will throw an exception. + +A call to getChildren() returns the list of children in lexicographic order. +As lexicographic order does not necessarily follow the numerical order of the counter +values, we need to decide which element is the smallest. To decide which one has +the smallest counter value, we traverse the list, and remove the prefix "element" +from each one. + +```java +/** + * Remove first element from the queue. + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ +int consume() throws KeeperException, InterruptedException{ + int retvalue = -1; + Stat stat = null; + + // Get the first element available + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + if (list.size() == 0) { + System.out.println("Going to wait"); + mutex.wait(); + } else { + Integer min = new Integer(list.get(0).substring(7)); + for(String s : list){ + Integer tempValue = new Integer(s.substring(7)); + //System.out.println("Temporary value: " + tempValue); + if(tempValue < min) min = tempValue; + } + System.out.println("Temporary value: " + root + "/element" + min); + byte[] b = zk.getData(root + "/element" + min, + false, stat); + zk.delete(root + "/element" + min, 0); + ByteBuffer buffer = ByteBuffer.wrap(b); + retvalue = buffer.getInt(); + + return retvalue; + } + } + } + } +} +``` + +## Complete example + +In the following section you can find a complete command line application to demonstrate the above mentioned +recipes. Use the following command to run it. + +```bash +ZOOBINDIR="[path_to_distro]/bin" +. "$ZOOBINDIR"/zkEnv.sh +java SyncPrimitive [Test Type] [ZK server] [No of elements] [Client type] +``` + +### Queue test + +Start a producer to create 100 elements + +```bash +java SyncPrimitive qTest localhost 100 p +``` + +Start a consumer to consume 100 elements + +```bash +java SyncPrimitive qTest localhost 100 c +``` + +### Barrier test + +Start a barrier with 2 participants (start as many times as many participants you'd like to enter) + +```bash +java SyncPrimitive bTest localhost 2 +``` + +### Source Listing + +#### SyncPrimitive.Java + +```java +import java.io.IOException; +import java.net.InetAddress; +import java.net.UnknownHostException; +import java.nio.ByteBuffer; +import java.util.List; +import java.util.Random; + +import org.apache.zookeeper.CreateMode; +import org.apache.zookeeper.KeeperException; +import org.apache.zookeeper.WatchedEvent; +import org.apache.zookeeper.Watcher; +import org.apache.zookeeper.ZooKeeper; +import org.apache.zookeeper.ZooDefs.Ids; +import org.apache.zookeeper.data.Stat; + +public class SyncPrimitive implements Watcher { + + static ZooKeeper zk = null; + static Integer mutex; + String root; + + SyncPrimitive(String address) { + if(zk == null){ + try { + System.out.println("Starting ZK:"); + zk = new ZooKeeper(address, 3000, this); + mutex = new Integer(-1); + System.out.println("Finished starting ZK: " + zk); + } catch (IOException e) { + System.out.println(e.toString()); + zk = null; + } + } + //else mutex = new Integer(-1); + } + + synchronized public void process(WatchedEvent event) { + synchronized (mutex) { + //System.out.println("Process: " + event.getType()); + mutex.notify(); + } + } + + /** + * Barrier + */ + static public class Barrier extends SyncPrimitive { + int size; + String name; + + /** + * Barrier constructor + * + * @param address + * @param root + * @param size + */ + Barrier(String address, String root, int size) { + super(address); + this.root = root; + this.size = size; + + // Create barrier node + if (zk != null) { + try { + Stat s = zk.exists(root, false); + if (s == null) { + zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT); + } + } catch (KeeperException e) { + System.out + .println("Keeper exception when instantiating queue: " + + e.toString()); + } catch (InterruptedException e) { + System.out.println("Interrupted exception"); + } + } + + // My node name + try { + name = new String(InetAddress.getLocalHost().getCanonicalHostName().toString()); + } catch (UnknownHostException e) { + System.out.println(e.toString()); + } + + } + + /** + * Join barrier + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ + + boolean enter() throws KeeperException, InterruptedException{ + zk.create(root + "/" + name, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.EPHEMERAL); + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + + if (list.size() < size) { + mutex.wait(); + } else { + return true; + } + } + } + } + + /** + * Wait until all reach barrier + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ + boolean leave() throws KeeperException, InterruptedException{ + zk.delete(root + "/" + name, 0); + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + if (list.size() > 0) { + mutex.wait(); + } else { + return true; + } + } + } + } + } + + /** + * Producer-Consumer queue + */ + static public class Queue extends SyncPrimitive { + + /** + * Constructor of producer-consumer queue + * + * @param address + * @param name + */ + Queue(String address, String name) { + super(address); + this.root = name; + // Create ZK node name + if (zk != null) { + try { + Stat s = zk.exists(root, false); + if (s == null) { + zk.create(root, new byte[0], Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT); + } + } catch (KeeperException e) { + System.out + .println("Keeper exception when instantiating queue: " + + e.toString()); + } catch (InterruptedException e) { + System.out.println("Interrupted exception"); + } + } + } + + /** + * Add element to the queue. + * + * @param i + * @return + */ + + boolean produce(int i) throws KeeperException, InterruptedException{ + ByteBuffer b = ByteBuffer.allocate(4); + byte[] value; + + // Add child with value i + b.putInt(i); + value = b.array(); + zk.create(root + "/element", value, Ids.OPEN_ACL_UNSAFE, + CreateMode.PERSISTENT_SEQUENTIAL); + + return true; + } + + /** + * Remove first element from the queue. + * + * @return + * @throws KeeperException + * @throws InterruptedException + */ + int consume() throws KeeperException, InterruptedException{ + int retvalue = -1; + Stat stat = null; + + // Get the first element available + while (true) { + synchronized (mutex) { + List list = zk.getChildren(root, true); + if (list.size() == 0) { + System.out.println("Going to wait"); + mutex.wait(); + } else { + Integer min = new Integer(list.get(0).substring(7)); + String minNode = list.get(0); + for(String s : list){ + Integer tempValue = new Integer(s.substring(7)); + //System.out.println("Temporary value: " + tempValue); + if(tempValue < min) { + min = tempValue; + minNode = s; + } + } + System.out.println("Temporary value: " + root + "/" + minNode); + byte[] b = zk.getData(root + "/" + minNode, + false, stat); + zk.delete(root + "/" + minNode, 0); + ByteBuffer buffer = ByteBuffer.wrap(b); + retvalue = buffer.getInt(); + + return retvalue; + } + } + } + } + } + + public static void main(String args[]) { + if (args[0].equals("qTest")) + queueTest(args); + else + barrierTest(args); + } + + public static void queueTest(String args[]) { + Queue q = new Queue(args[1], "/app1"); + + System.out.println("Input: " + args[1]); + int i; + Integer max = new Integer(args[2]); + + if (args[3].equals("p")) { + System.out.println("Producer"); + for (i = 0; i < max; i++) + try{ + q.produce(10 + i); + } catch (KeeperException e){ + + } catch (InterruptedException e){ + + } + } else { + System.out.println("Consumer"); + + for (i = 0; i < max; i++) { + try{ + int r = q.consume(); + System.out.println("Item: " + r); + } catch (KeeperException e){ + i--; + } catch (InterruptedException e){ + } + } + } + } + + public static void barrierTest(String args[]) { + Barrier b = new Barrier(args[1], "/b1", new Integer(args[2])); + try{ + boolean flag = b.enter(); + System.out.println("Entered barrier: " + args[2]); + if(!flag) System.out.println("Error when entering the barrier"); + } catch (KeeperException e){ + } catch (InterruptedException e){ + } + + // Generate random integer + Random rand = new Random(); + int r = rand.nextInt(100); + // Loop for rand iterations + for (int i = 0; i < r; i++) { + try { + Thread.sleep(100); + } catch (InterruptedException e) { + } + } + try{ + b.leave(); + } catch (KeeperException e){ + + } catch (InterruptedException e){ + + } + System.out.println("Left barrier"); + } +} +``` diff --git a/zookeeper-docs/src/main/resources/markdown/javaExample.md b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/java-example.mdx similarity index 50% rename from zookeeper-docs/src/main/resources/markdown/javaExample.md rename to zookeeper-website/app/pages/_docs/docs/_mdx/developer/java-example.mdx index a94b083d241..970f7c03c51 100644 --- a/zookeeper-docs/src/main/resources/markdown/javaExample.md +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/java-example.mdx @@ -1,29 +1,7 @@ - - -# ZooKeeper Java Example - -* [A Simple Watch Client](#ch_Introduction) - * [Requirements](#sc_requirements) - * [Program Design](#sc_design) -* [The Executor Class](#sc_executor) -* [The DataMonitor Class](#sc_DataMonitor) -* [Complete Source Listings](#sc_completeSourceCode) - - +--- +title: "Java Example" +description: "Walks through building a complete ZooKeeper watch client in Java, covering the Executor and DataMonitor design, watcher callbacks, and handling connection state changes." +--- ## A Simple Watch Client @@ -31,81 +9,75 @@ To introduce you to the ZooKeeper Java API, we develop here a very simple watch client. This ZooKeeper client watches a znode for changes and responds to by starting or stopping a program. - - ### Requirements The client has four requirements: -* It takes as parameters: - * the address of the ZooKeeper service - * the name of a znode - the one to be watched - * the name of a file to write the output to - * an executable with arguments. -* It fetches the data associated with the znode and starts the executable. -* If the znode changes, the client re-fetches the contents and restarts the executable. -* If the znode disappears, the client kills the executable. - - +- It takes as parameters: + - the address of the ZooKeeper service + - the name of a znode - the one to be watched + - the name of a file to write the output to + - an executable with arguments. +- It fetches the data associated with the znode and starts the executable. +- If the znode changes, the client re-fetches the contents and restarts the executable. +- If the znode disappears, the client kills the executable. ### Program Design Conventionally, ZooKeeper applications are broken into two units, one which maintains the connection, -and the other which monitors data. In this application, the class called the **Executor** +and the other which monitors data. In this application, the class called the **Executor** maintains the ZooKeeper connection, and the class called the **DataMonitor** monitors the data in the ZooKeeper tree. Also, Executor contains the main thread and contains the execution logic. It is responsible for what little user interaction there is, as well as interaction with the executable program you pass in as an argument and which the sample (per the requirements) shuts down and restarts, according to the state of the znode. - - ## The Executor Class The Executor object is the primary container of the sample application. It contains both the **ZooKeeper** object, **DataMonitor**, as described above in -[Program Design](#sc_design). +[Program Design](#program-design). +```java +// from the Executor class... - // from the Executor class... - - public static void main(String[] args) { - if (args.length < 4) { - System.err - .println("USAGE: Executor hostPort znode filename program [args ...]"); - System.exit(2); - } - String hostPort = args[0]; - String znode = args[1]; - String filename = args[2]; - String exec[] = new String[args.length - 3]; - System.arraycopy(args, 3, exec, 0, exec.length); - try { - new Executor(hostPort, znode, filename, exec).run(); - } catch (Exception e) { - e.printStackTrace(); - } +public static void main(String[] args) { + if (args.length < 4) { + System.err + .println("USAGE: Executor hostPort znode filename program [args ...]"); + System.exit(2); } - - public Executor(String hostPort, String znode, String filename, - String exec[]) throws KeeperException, IOException { - this.filename = filename; - this.exec = exec; - zk = new ZooKeeper(hostPort, 3000, this); - dm = new DataMonitor(zk, znode, null, this); + String hostPort = args[0]; + String znode = args[1]; + String filename = args[2]; + String exec[] = new String[args.length - 3]; + System.arraycopy(args, 3, exec, 0, exec.length); + try { + new Executor(hostPort, znode, filename, exec).run(); + } catch (Exception e) { + e.printStackTrace(); } - - public void run() { - try { - synchronized (this) { - while (!dm.dead) { - wait(); - } +} + +public Executor(String hostPort, String znode, String filename, + String exec[]) throws KeeperException, IOException { + this.filename = filename; + this.exec = exec; + zk = new ZooKeeper(hostPort, 3000, this); + dm = new DataMonitor(zk, znode, null, this); +} + +public void run() { + try { + synchronized (this) { + while (!dm.dead) { + wait(); } - } catch (InterruptedException e) { } + } catch (InterruptedException e) { } - +} +``` Recall that the Executor's job is to start and stop the executable whose name you pass in on the command line. It does this in response to events fired by the ZooKeeper object. As you can see in the code above, the Executor passes @@ -113,9 +85,10 @@ a reference to itself as the Watcher argument in the ZooKeeper constructor. It a as DataMonitorListener argument to the DataMonitor constructor. Per the Executor's definition, it implements both these interfaces: - public class Executor implements Watcher, Runnable, DataMonitor.DataMonitorListener { - ... - +```java +public class Executor implements Watcher, Runnable, DataMonitor.DataMonitorListener { +... +``` The **Watcher** interface is defined by the ZooKeeper Java API. ZooKeeper uses it to communicate back to its container. It supports only one method, `process()`, @@ -126,33 +99,33 @@ the point that, by convention, the Executor or some Executor-like object "owns" free to delegate the events to other events to other objects. It also uses this as the default channel on which to fire watch events. (More on this later.) - - public void process(WatchedEvent event) { - dm.process(event); - } - +```java +public void process(WatchedEvent event) { + dm.process(event); +} +``` The **DataMonitorListener** interface, on the other hand, is not part of the ZooKeeper API. It is a completely custom interface, designed for this sample application. The DataMonitor object uses it to communicate back to its container, which is also the Executor object. The DataMonitorListener interface looks like this: +```java +public interface DataMonitorListener { + /** + * The existence status of the node has changed. + */ + void exists(byte data[]); - public interface DataMonitorListener { - /** - * The existence status of the node has changed. - */ - void exists(byte data[]); - - /** - * The ZooKeeper session is no longer valid. - * - * @param rc - * the ZooKeeper reason code - */ - void closing(int rc); - } - + /** + * The ZooKeeper session is no longer valid. + * + * @param rc + * the ZooKeeper reason code + */ + void closing(int rc); +} +``` This interface is defined in the DataMonitor class and implemented in the Executor class. When `Executor.exists()` is invoked, the Executor decides whether to start up or shut down per the requirements. @@ -167,134 +140,135 @@ these methods, in response to changes in ZooKeeper's state. Here are Executor's implementation of `DataMonitorListener.exists()` and `DataMonitorListener.closing`: - - public void exists( byte[] data ) { - if (data == null) { - if (child != null) { - System.out.println("Killing process"); - child.destroy(); - try { - child.waitFor(); - } catch (InterruptedException e) { - } - } - child = null; - } else { - if (child != null) { - System.out.println("Stopping child"); - child.destroy(); - try { - child.waitFor(); - } catch (InterruptedException e) { - e.printStackTrace(); - } - } +```java +public void exists( byte[] data ) { + if (data == null) { + if (child != null) { + System.out.println("Killing process"); + child.destroy(); try { - FileOutputStream fos = new FileOutputStream(filename); - fos.write(data); - fos.close(); - } catch (IOException e) { - e.printStackTrace(); - } + child.waitFor(); + } catch (InterruptedException e) { + } + } + child = null; + } else { + if (child != null) { + System.out.println("Stopping child"); + child.destroy(); try { - System.out.println("Starting child"); - child = Runtime.getRuntime().exec(exec); - new StreamWriter(child.getInputStream(), System.out); - new StreamWriter(child.getErrorStream(), System.err); - } catch (IOException e) { - e.printStackTrace(); + child.waitFor(); + } catch (InterruptedException e) { + e.printStackTrace(); } } - } - - public void closing(int rc) { - synchronized (this) { - notifyAll(); + try { + FileOutputStream fos = new FileOutputStream(filename); + fos.write(data); + fos.close(); + } catch (IOException e) { + e.printStackTrace(); + } + try { + System.out.println("Starting child"); + child = Runtime.getRuntime().exec(exec); + new StreamWriter(child.getInputStream(), System.out); + new StreamWriter(child.getErrorStream(), System.err); + } catch (IOException e) { + e.printStackTrace(); } } +} - - +public void closing(int rc) { + synchronized (this) { + notifyAll(); + } +} +``` ## The DataMonitor Class The DataMonitor class has the meat of the ZooKeeper logic. It is mostly asynchronous and event driven. DataMonitor kicks things off in the constructor with: +```java +public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher, + DataMonitorListener listener) { + this.zk = zk; + this.znode = znode; + this.chainedWatcher = chainedWatcher; + this.listener = listener; - public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher, - DataMonitorListener listener) { - this.zk = zk; - this.znode = znode; - this.chainedWatcher = chainedWatcher; - this.listener = listener; - - // Get things started by checking if the node exists. We are going - // to be completely event driven - + // Get things started by checking if the node exists. We are going + // to be completely event driven + zk.exists(znode, true, this, null); +} +``` The call to `ZooKeeper.exists()` checks for the existence of the znode, sets a watch, and passes a reference to itself (`this`) as the completion callback object. In this sense, it kicks things off, since the real processing happens when the watch is triggered. -###### Note - ->Don't confuse the completion callback with the watch callback. The `ZooKeeper.exists()` + +Don't confuse the completion callback with the watch callback. The `ZooKeeper.exists()` completion callback, which happens to be the method `StatCallback.processResult()` implemented in the DataMonitor object, is invoked when the asynchronous _setting of the watch_ operation (by `ZooKeeper.exists()`) completes on the server. ->The triggering of the watch, on the other hand, sends an event to the _Executor_ object, since +The triggering of the watch, on the other hand, sends an event to the _Executor_ object, since the Executor registered as the Watcher of the ZooKeeper object. ->As an aside, you might note that the DataMonitor could also register itself as the Watcher +As an aside, you might note that the DataMonitor could also register itself as the Watcher for this particular watch event. This is new to ZooKeeper 3.0.0 (the support of multiple Watchers). In this example, however, DataMonitor does not register as the Watcher. + + When the `ZooKeeper.exists()` operation completes on the server, the ZooKeeper API invokes this completion callback on the client: +```java +public void processResult(int rc, String path, Object ctx, Stat stat) { + boolean exists; + switch (rc) { + case Code.Ok: + exists = true; + break; + case Code.NoNode: + exists = false; + break; + case Code.SessionExpired: + case Code.NoAuth: + dead = true; + listener.closing(rc); + return; + default: + // Retry errors + zk.exists(znode, true, this, null); + return; + } - public void processResult(int rc, String path, Object ctx, Stat stat) { - boolean exists; - switch (rc) { - case Code.Ok: - exists = true; - break; - case Code.NoNode: - exists = false; - break; - case Code.SessionExpired: - case Code.NoAuth: - dead = true; - listener.closing(rc); - return; - default: - // Retry errors - zk.exists(znode, true, this, null); + byte b[] = null; + if (exists) { + try { + b = zk.getData(znode, false, null); + } catch (KeeperException e) { + // We don't need to worry about recovering now. The watch + // callbacks will kick off any exception handling + e.printStackTrace(); + } catch (InterruptedException e) { return; } - - byte b[] = null; - if (exists) { - try { - b = zk.getData(znode, false, null); - } catch (KeeperException e) { - // We don't need to worry about recovering now. The watch - // callbacks will kick off any exception handling - e.printStackTrace(); - } catch (InterruptedException e) { - return; - } - } - if ((b == null && b != prevData) - || (b != null && !Arrays.equals(prevData, b))) { - listener.exists(b); - prevData = b; - } } - + if ((b == null && b != prevData) + || (b != null && !Arrays.equals(prevData, b))) { + listener.exists(b); + prevData = b; + } +} +``` The code first checks the error codes for znode existence, fatal errors, and recoverable errors. If the file (or znode) exists, it gets the data from the znode, and @@ -308,321 +282,319 @@ the connection comes back up. Finally, notice how DataMonitor processes watch events: - - public void process(WatchedEvent event) { - String path = event.getPath(); - if (event.getType() == Event.EventType.None) { - // We are are being told that the state of the - // connection has changed - switch (event.getState()) { - case SyncConnected: - // In this particular example we don't need to do anything - // here - watches are automatically re-registered with - // server and any watches triggered while the client was - // disconnected will be delivered (in order of course) - break; - case Expired: - // It's all over - dead = true; - listener.closing(KeeperException.Code.SessionExpired); - break; - } - } else { - if (path != null && path.equals(znode)) { - // Something has changed on the node, let's find out - zk.exists(znode, true, this, null); - } +```java +public void process(WatchedEvent event) { + String path = event.getPath(); + if (event.getType() == Event.EventType.None) { + // We are are being told that the state of the + // connection has changed + switch (event.getState()) { + case SyncConnected: + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) + break; + case Expired: + // It's all over + dead = true; + listener.closing(KeeperException.Code.SessionExpired); + break; } - if (chainedWatcher != null) { - chainedWatcher.process(event); + } else { + if (path != null && path.equals(znode)) { + // Something has changed on the node, let's find out + zk.exists(znode, true, this, null); } } - + if (chainedWatcher != null) { + chainedWatcher.process(event); + } +} +``` If the client-side ZooKeeper libraries can re-establish the communication channel (SyncConnected event) to ZooKeeper before session expiration (Expired event) all of the session's watches will automatically be re-established with the server (auto-reset of watches -is new in ZooKeeper 3.0.0). See [ZooKeeper Watches](zookeeperProgrammers.html#ch_zkWatches) +is new in ZooKeeper 3.0.0). See [ZooKeeper Watches](/docs/developer/programmers-guide/watches) in the programmer guide for more on this. A bit lower down in this function, when DataMonitor gets an event for a znode, it calls`ZooKeeper.exists()` to find out what has changed. - - ## Complete Source Listings ### Executor.java +```java +/** + * A simple example program to use DataMonitor to start and + * stop executables based on a znode. The program watches the + * specified znode and saves the data that corresponds to the + * znode in the filesystem. It also starts the specified program + * with the specified arguments when the znode exists and kills + * the program if the znode goes away. + */ +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; + +import org.apache.zookeeper.KeeperException; +import org.apache.zookeeper.WatchedEvent; +import org.apache.zookeeper.Watcher; +import org.apache.zookeeper.ZooKeeper; + +public class Executor + implements Watcher, Runnable, DataMonitor.DataMonitorListener +{ + String znode; + DataMonitor dm; + ZooKeeper zk; + String filename; + String exec[]; + Process child; + + public Executor(String hostPort, String znode, String filename, + String exec[]) throws KeeperException, IOException { + this.filename = filename; + this.exec = exec; + zk = new ZooKeeper(hostPort, 3000, this); + dm = new DataMonitor(zk, znode, null, this); + } /** - * A simple example program to use DataMonitor to start and - * stop executables based on a znode. The program watches the - * specified znode and saves the data that corresponds to the - * znode in the filesystem. It also starts the specified program - * with the specified arguments when the znode exists and kills - * the program if the znode goes away. + * @param args */ - import java.io.FileOutputStream; - import java.io.IOException; - import java.io.InputStream; - import java.io.OutputStream; - - import org.apache.zookeeper.KeeperException; - import org.apache.zookeeper.WatchedEvent; - import org.apache.zookeeper.Watcher; - import org.apache.zookeeper.ZooKeeper; - - public class Executor - implements Watcher, Runnable, DataMonitor.DataMonitorListener - { - String znode; - DataMonitor dm; - ZooKeeper zk; - String filename; - String exec[]; - Process child; - - public Executor(String hostPort, String znode, String filename, - String exec[]) throws KeeperException, IOException { - this.filename = filename; - this.exec = exec; - zk = new ZooKeeper(hostPort, 3000, this); - dm = new DataMonitor(zk, znode, null, this); + public static void main(String[] args) { + if (args.length < 4) { + System.err + .println("USAGE: Executor hostPort znode filename program [args ...]"); + System.exit(2); } - - /** - * @param args - */ - public static void main(String[] args) { - if (args.length < 4) { - System.err - .println("USAGE: Executor hostPort znode filename program [args ...]"); - System.exit(2); - } - String hostPort = args[0]; - String znode = args[1]; - String filename = args[2]; - String exec[] = new String[args.length - 3]; - System.arraycopy(args, 3, exec, 0, exec.length); - try { - new Executor(hostPort, znode, filename, exec).run(); - } catch (Exception e) { - e.printStackTrace(); - } + String hostPort = args[0]; + String znode = args[1]; + String filename = args[2]; + String exec[] = new String[args.length - 3]; + System.arraycopy(args, 3, exec, 0, exec.length); + try { + new Executor(hostPort, znode, filename, exec).run(); + } catch (Exception e) { + e.printStackTrace(); } + } - /*************************************************************************** - * We do process any events ourselves, we just need to forward them on. - * - * @see org.apache.zookeeper.Watcher#process(org.apache.zookeeper.proto.WatcherEvent) - */ - public void process(WatchedEvent event) { - dm.process(event); - } + /*************************************************************************** + * We do process any events ourselves, we just need to forward them on. + * + * @see org.apache.zookeeper.Watcher#process(org.apache.zookeeper.proto.WatcherEvent) + */ + public void process(WatchedEvent event) { + dm.process(event); + } - public void run() { - try { - synchronized (this) { - while (!dm.dead) { - wait(); - } + public void run() { + try { + synchronized (this) { + while (!dm.dead) { + wait(); } - } catch (InterruptedException e) { } + } catch (InterruptedException e) { } + } - public void closing(int rc) { - synchronized (this) { - notifyAll(); - } + public void closing(int rc) { + synchronized (this) { + notifyAll(); } + } - static class StreamWriter extends Thread { - OutputStream os; + static class StreamWriter extends Thread { + OutputStream os; - InputStream is; + InputStream is; - StreamWriter(InputStream is, OutputStream os) { - this.is = is; - this.os = os; - start(); - } + StreamWriter(InputStream is, OutputStream os) { + this.is = is; + this.os = os; + start(); + } - public void run() { - byte b[] = new byte[80]; - int rc; - try { - while ((rc = is.read(b)) > 0) { - os.write(b, 0, rc); - } - } catch (IOException e) { + public void run() { + byte b[] = new byte[80]; + int rc; + try { + while ((rc = is.read(b)) > 0) { + os.write(b, 0, rc); } - + } catch (IOException e) { } + } + } - public void exists(byte[] data) { - if (data == null) { - if (child != null) { - System.out.println("Killing process"); - child.destroy(); - try { - child.waitFor(); - } catch (InterruptedException e) { - } - } - child = null; - } else { - if (child != null) { - System.out.println("Stopping child"); - child.destroy(); - try { - child.waitFor(); - } catch (InterruptedException e) { - e.printStackTrace(); - } - } + public void exists(byte[] data) { + if (data == null) { + if (child != null) { + System.out.println("Killing process"); + child.destroy(); try { - FileOutputStream fos = new FileOutputStream(filename); - fos.write(data); - fos.close(); - } catch (IOException e) { - e.printStackTrace(); + child.waitFor(); + } catch (InterruptedException e) { } + } + child = null; + } else { + if (child != null) { + System.out.println("Stopping child"); + child.destroy(); try { - System.out.println("Starting child"); - child = Runtime.getRuntime().exec(exec); - new StreamWriter(child.getInputStream(), System.out); - new StreamWriter(child.getErrorStream(), System.err); - } catch (IOException e) { + child.waitFor(); + } catch (InterruptedException e) { e.printStackTrace(); } } + try { + FileOutputStream fos = new FileOutputStream(filename); + fos.write(data); + fos.close(); + } catch (IOException e) { + e.printStackTrace(); + } + try { + System.out.println("Starting child"); + child = Runtime.getRuntime().exec(exec); + new StreamWriter(child.getInputStream(), System.out); + new StreamWriter(child.getErrorStream(), System.err); + } catch (IOException e) { + e.printStackTrace(); + } } } - +} +``` ### DataMonitor.java +```java +/** + * A simple class that monitors the data and existence of a ZooKeeper + * node. It uses asynchronous ZooKeeper APIs. + */ +import java.util.Arrays; + +import org.apache.zookeeper.KeeperException; +import org.apache.zookeeper.WatchedEvent; +import org.apache.zookeeper.Watcher; +import org.apache.zookeeper.ZooKeeper; +import org.apache.zookeeper.AsyncCallback.StatCallback; +import org.apache.zookeeper.KeeperException.Code; +import org.apache.zookeeper.data.Stat; + +public class DataMonitor implements Watcher, StatCallback { + + ZooKeeper zk; + String znode; + Watcher chainedWatcher; + boolean dead; + DataMonitorListener listener; + byte prevData[]; + + public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher, + DataMonitorListener listener) { + this.zk = zk; + this.znode = znode; + this.chainedWatcher = chainedWatcher; + this.listener = listener; + // Get things started by checking if the node exists. We are going + // to be completely event driven + zk.exists(znode, true, this, null); + } /** - * A simple class that monitors the data and existence of a ZooKeeper - * node. It uses asynchronous ZooKeeper APIs. + * Other classes use the DataMonitor by implementing this method */ - import java.util.Arrays; - - import org.apache.zookeeper.KeeperException; - import org.apache.zookeeper.WatchedEvent; - import org.apache.zookeeper.Watcher; - import org.apache.zookeeper.ZooKeeper; - import org.apache.zookeeper.AsyncCallback.StatCallback; - import org.apache.zookeeper.KeeperException.Code; - import org.apache.zookeeper.data.Stat; - - public class DataMonitor implements Watcher, StatCallback { - - ZooKeeper zk; - String znode; - Watcher chainedWatcher; - boolean dead; - DataMonitorListener listener; - byte prevData[]; - - public DataMonitor(ZooKeeper zk, String znode, Watcher chainedWatcher, - DataMonitorListener listener) { - this.zk = zk; - this.znode = znode; - this.chainedWatcher = chainedWatcher; - this.listener = listener; - // Get things started by checking if the node exists. We are going - // to be completely event driven - zk.exists(znode, true, this, null); - } - + public interface DataMonitorListener { /** - * Other classes use the DataMonitor by implementing this method + * The existence status of the node has changed. */ - public interface DataMonitorListener { - /** - * The existence status of the node has changed. - */ - void exists(byte data[]); - - /** - * The ZooKeeper session is no longer valid. - * - * @param rc - * the ZooKeeper reason code - */ - void closing(int rc); - } + void exists(byte data[]); - public void process(WatchedEvent event) { - String path = event.getPath(); - if (event.getType() == Event.EventType.None) { - // We are are being told that the state of the - // connection has changed - switch (event.getState()) { - case SyncConnected: - // In this particular example we don't need to do anything - // here - watches are automatically re-registered with - // server and any watches triggered while the client was - // disconnected will be delivered (in order of course) - break; - case Expired: - // It's all over - dead = true; - listener.closing(KeeperException.Code.SessionExpired); - break; - } - } else { - if (path != null && path.equals(znode)) { - // Something has changed on the node, let's find out - zk.exists(znode, true, this, null); - } - } - if (chainedWatcher != null) { - chainedWatcher.process(event); - } - } + /** + * The ZooKeeper session is no longer valid. + * + * @param rc + * the ZooKeeper reason code + */ + void closing(int rc); + } - public void processResult(int rc, String path, Object ctx, Stat stat) { - boolean exists; - switch (rc) { - case Code.Ok: - exists = true; - break; - case Code.NoNode: - exists = false; + public void process(WatchedEvent event) { + String path = event.getPath(); + if (event.getType() == Event.EventType.None) { + // We are are being told that the state of the + // connection has changed + switch (event.getState()) { + case SyncConnected: + // In this particular example we don't need to do anything + // here - watches are automatically re-registered with + // server and any watches triggered while the client was + // disconnected will be delivered (in order of course) break; - case Code.SessionExpired: - case Code.NoAuth: + case Expired: + // It's all over dead = true; - listener.closing(rc); - return; - default: - // Retry errors + listener.closing(KeeperException.Code.SessionExpired); + break; + } + } else { + if (path != null && path.equals(znode)) { + // Something has changed on the node, let's find out zk.exists(znode, true, this, null); - return; } + } + if (chainedWatcher != null) { + chainedWatcher.process(event); + } + } - byte b[] = null; - if (exists) { - try { - b = zk.getData(znode, false, null); - } catch (KeeperException e) { - // We don't need to worry about recovering now. The watch - // callbacks will kick off any exception handling - e.printStackTrace(); - } catch (InterruptedException e) { - return; - } - } - if ((b == null && b != prevData) - || (b != null && !Arrays.equals(prevData, b))) { - listener.exists(b); - prevData = b; + public void processResult(int rc, String path, Object ctx, Stat stat) { + boolean exists; + switch (rc) { + case Code.Ok: + exists = true; + break; + case Code.NoNode: + exists = false; + break; + case Code.SessionExpired: + case Code.NoAuth: + dead = true; + listener.closing(rc); + return; + default: + // Retry errors + zk.exists(znode, true, this, null); + return; + } + + byte b[] = null; + if (exists) { + try { + b = zk.getData(znode, false, null); + } catch (KeeperException e) { + // We don't need to worry about recovering now. The watch + // callbacks will kick off any exception handling + e.printStackTrace(); + } catch (InterruptedException e) { + return; } } + if ((b == null && b != prevData) + || (b != null && !Arrays.equals(prevData, b))) { + listener.exists(b); + prevData = b; + } } - +} +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/meta.json new file mode 100644 index 00000000000..9d7590bcca8 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Developer", + "pages": [ + "programmers-guide", + "use-cases", + "java-example", + "basic-tutorial", + "recipes", + "external:[API Docs](https://zookeeper.apache.org/doc/current/apidocs/zookeeper-server/index.html)" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/access-control-using-acls.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/access-control-using-acls.mdx new file mode 100644 index 00000000000..2a32263ee46 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/access-control-using-acls.mdx @@ -0,0 +1,283 @@ +--- +title: "Access Control using ACLs" +description: "Explains ZooKeeper's ACL-based access control for znodes, including permission types, built-in ACL schemes (world, auth, digest, host, IP), and the C client API." +--- + +ZooKeeper uses ACLs to control access to its znodes (the +data nodes of a ZooKeeper data tree). The ACL implementation is +quite similar to UNIX file access permissions: it employs +permission bits to allow/disallow various operations against a +node and the scope to which the bits apply. Unlike standard UNIX +permissions, a ZooKeeper node is not limited by the three standard +scopes for user (owner of the file), group, and world +(other). ZooKeeper does not have a notion of an owner of a +znode. Instead, an ACL specifies sets of ids and permissions that +are associated with those ids. + +Note also that an ACL pertains only to a specific znode. In +particular it does not apply to children. For example, if +_/app_ is only readable by ip:172.16.16.1 and +_/app/status_ is world readable, anyone will +be able to read _/app/status_; ACLs are not +recursive. + +ZooKeeper supports pluggable authentication schemes. Ids are +specified using the form _scheme:expression_, +where _scheme_ is the authentication scheme +that the id corresponds to. The set of valid expressions are defined +by the scheme. For example, _ip:172.16.16.1_ is +an id for a host with the address _172.16.16.1_ +using the _ip_ scheme, whereas _digest:bob:password_ +is an id for the user with the name of _bob_ using +the _digest_ scheme. + +When a client connects to ZooKeeper and authenticates +itself, ZooKeeper associates all the ids that correspond to a +client with the clients connection. These ids are checked against +the ACLs of znodes when a client tries to access a node. ACLs are +made up of pairs of _(scheme:expression, +perms)_. The format of +the _expression_ is specific to the scheme. For +example, the pair _(ip:19.22.0.0/16, READ)_ +gives the _READ_ permission to any clients with +an IP address that starts with 19.22. + +## ACL Permissions + +ZooKeeper supports the following permissions: + +- **CREATE**: you can create a child node +- **READ**: you can get data from a node and list its children. +- **WRITE**: you can set data for a node +- **DELETE**: you can delete a child node +- **ADMIN**: you can set permissions + +The _CREATE_ +and _DELETE_ permissions have been broken out +of the _WRITE_ permission for finer grained +access controls. The cases for _CREATE_ +and _DELETE_ are the following: + +You want A to be able to do a set on a ZooKeeper node, but +not be able to _CREATE_ +or _DELETE_ children. + +_CREATE_ +without _DELETE_: clients create requests by +creating ZooKeeper nodes in a parent directory. You want all +clients to be able to add, but only request processor can +delete. (This is kind of like the APPEND permission for +files.) + +Also, the _ADMIN_ permission is there +since ZooKeeper doesn’t have a notion of file owner. In some +sense the _ADMIN_ permission designates the +entity as the owner. ZooKeeper doesn’t support the LOOKUP +permission (execute permission bit on directories to allow you +to LOOKUP even though you can't list the directory). Everyone +implicitly has LOOKUP permission. This allows you to stat a +node, but nothing more. (The problem is, if you want to call +zoo_exists() on a node that doesn't exist, there is no +permission to check.) + +_ADMIN_ permission also has a special role in terms of ACLs: +in order to retrieve ACLs of a znode user has to have _READ_ or _ADMIN_ +permission, but without _ADMIN_ permission, digest hash values will be +masked out. + +As of versions **3.9.2 / 3.8.4 / 3.7.3** the exists() call will now verify ACLs +on nodes that exist and the client must have READ permission otherwise +'Insufficient permission' error will be raised. + +### Builtin ACL Schemes + +ZooKeeper has the following built in schemes: + +- **world** has a + single id, _anyone_, that represents + anyone. +- **auth** is a special + scheme which ignores any provided expression and instead uses the current user, + credentials, and scheme. Any expression (whether _user_ like with SASL + authentication or _user:password_ like with DIGEST authentication) provided is ignored + by the ZooKeeper server when persisting the ACL. However, the expression must still be + provided in the ACL because the ACL must match the form _scheme:expression:perms_. + This scheme is provided as a convenience as it is a common use-case for + a user to create a znode and then restrict access to that znode to only that user. + If there is no authenticated user, setting an ACL with the auth scheme will fail. +- **digest** uses + a _username:password_ string to generate + MD5 hash which is then used as an ACL ID + identity. Authentication is done by sending + the _username:password_ in clear text. When + used in the ACL the expression will be + the _username:base64_ + encoded _SHA1_ + password _digest_. +- **ip** uses the + client host IP as an ACL ID identity. The ACL expression is of + the form _addr/bits_ where the most + significant _bits_ + of _addr_ are matched against the most + significant _bits_ of the client host + IP. +- **x509** uses the client + X500 Principal as an ACL ID identity. The ACL expression is the exact + X500 Principal name of a client. When using the secure port, clients + are automatically authenticated and their auth info for the x509 scheme + is set. + +### ZooKeeper C client API + +The following constants are provided by the ZooKeeper C +library: + +- _const_ _int_ ZOO_PERM_READ; //can read node’s value and list its children +- _const_ _int_ ZOO_PERM_WRITE;// can set the node’s value +- _const_ _int_ ZOO_PERM_CREATE; //can create children +- _const_ _int_ ZOO_PERM_DELETE;// can delete children +- _const_ _int_ ZOO_PERM_ADMIN; //can execute set_acl() +- _const_ _int_ ZOO_PERM_ALL;// all of the above flags OR’d together + +The following are the standard ACL IDs: + +- _struct_ Id ZOO_ANYONE_ID_UNSAFE; //(‘world’,’anyone’) +- _struct_ Id ZOO_AUTH_IDS;// (‘auth’,’’) + +ZOO_AUTH_IDS empty identity string should be interpreted as “the identity of the creator”. + +ZooKeeper client comes with three standard ACLs: + +- _struct_ ACL_vector ZOO_OPEN_ACL_UNSAFE; //(ZOO_PERM_ALL,ZOO_ANYONE_ID_UNSAFE) +- _struct_ ACL_vector ZOO_READ_ACL_UNSAFE;// (ZOO_PERM_READ, ZOO_ANYONE_ID_UNSAFE) +- _struct_ ACL_vector ZOO_CREATOR_ALL_ACL; //(ZOO_PERM_ALL,ZOO_AUTH_IDS) + +The ZOO*OPEN_ACL_UNSAFE is completely open free for all +ACL: any application can execute any operation on the node and +can create, list and delete its children. The +ZOO_READ_ACL_UNSAFE is read-only access for any +application. CREATE_ALL_ACL grants all permissions to the +creator of the node. The creator must have been authenticated by +the server (for example, using “\_digest*” +scheme) before it can create nodes with this ACL. + +The following ZooKeeper operations deal with ACLs: + +- _int_ _zoo_add_auth_ + (zhandle*t \*zh,\_const* _char\_\_ + scheme,*const* *char*_ + cert, _int_ certLen, void*completion_t + completion, \_const* _void_ + \*data); + + The application uses the zoo_add_auth function to + authenticate itself to the server. The function can be called + multiple times if the application wants to authenticate using + different schemes and/or identities. + +- _int_ _zoo_create_ + (zhandle*t \*zh, \_const* _char_ + \*path, _const_ _char_ + \*value,_int_ + valuelen, _const_ _struct_ + ACL*vector \*acl, \_int* + flags,_char_ + \*realpath, _int_ + max_realpath_len); + + zoo_create(...) operation creates a new node. The acl + parameter is a list of ACLs associated with the node. The parent + node must have the CREATE permission bit set. + +- _int_ _zoo_get_acl_ + (zhandle*t \*zh, \_const* _char_ + \*path,_struct_ ACL*vector + \*acl, \_struct* Stat \*stat); + + This operation returns a node’s ACL info. The node must have READ or ADMIN + permission set. Without ADMIN permission, the digest hash values will be masked out. + +- _int_ _zoo_set_acl_ + (zhandle*t \*zh, \_const* _char_ + \*path, _int_ + version,_const_ _struct_ + ACL_vector \*acl); + + This function replaces node’s ACL list with a new one. The + node must have the ADMIN permission set. + +Here is a sample code that makes use of the above APIs to +authenticate itself using the “_foo_” scheme +and create an ephemeral node “/xyz” with create-only +permissions. + + + This is a very simple example which is intended to show how to interact with + ZooKeeper ACLs specifically. See + _.../trunk/zookeeper-client/zookeeper-client-c/src/cli.c_ for an example of a + C client implementation + + +```c +#include +#include + +#include "zookeeper.h" + +static zhandle_t *zh; + +/** + * In this example this method gets the cert for your + * environment -- you must provide + */ +char *foo_get_cert_once(char* id) { return 0; } + +/** Watcher function -- empty for this example, not something you should + * do in real code */ +void watcher(zhandle_t *zzh, int type, int state, const char *path, + void *watcherCtx) {} + +int main(int argc, char argv) { + char buffer[512]; + char p[2048]; + char *cert=0; + char appId[64]; + + strcpy(appId, "example.foo_test"); + cert = foo_get_cert_once(appId); + if(cert!=0) { + fprintf(stderr, + "Certificate for appid [%s] is [%s]\n",appId,cert); + strncpy(p,cert, sizeof(p)-1); + free(cert); + } else { + fprintf(stderr, "Certificate for appid [%s] not found\n",appId); + strcpy(p, "dummy"); + } + + zoo_set_debug_level(ZOO_LOG_LEVEL_DEBUG); + + zh = zookeeper_init("localhost:3181", watcher, 10000, 0, 0, 0); + if (!zh) { + return errno; + } + if(zoo_add_auth(zh,"foo",p,strlen(p),0,0)!=ZOK) + return 2; + + struct ACL CREATE_ONLY_ACL[] = {{ZOO_PERM_CREATE, ZOO_AUTH_IDS}}; + struct ACL_vector CREATE_ONLY = {1, CREATE_ONLY_ACL}; + int rc = zoo_create(zh,"/xyz","value", 5, &CREATE_ONLY, ZOO_EPHEMERAL, + buffer, sizeof(buffer)-1); + + /** this operation will fail with a ZNOAUTH error */ + int buflen= sizeof(buffer); + struct Stat stat; + rc = zoo_get(zh, "/xyz", 0, buffer, &buflen, &stat); + if (rc) { + fprintf(stderr, "Error %d for %s\n", rc, __LINE__); + } + + zookeeper_close(zh); + return 0; +} +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/bindings.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/bindings.mdx new file mode 100644 index 00000000000..7a6aedb68fa --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/bindings.mdx @@ -0,0 +1,260 @@ +--- +title: "Bindings" +description: "Documents the Java and C client library bindings for ZooKeeper, including the ZooKeeper class, callbacks, POSIX-style C API, multithreaded and single-threaded libraries." +--- + +The ZooKeeper client libraries come in two languages: Java and C. +The following sections describe these. + +## Java Binding + +There are two packages that make up the ZooKeeper Java binding: +**org.apache.zookeeper** and **org.apache.zookeeper.data**. The rest of the +packages that make up ZooKeeper are used internally or are part of the +server implementation. The **org.apache.zookeeper.data** package is made up of +generated classes that are used simply as containers. + +The main class used by a ZooKeeper Java client is the **ZooKeeper** class. Its two constructors differ only +by an optional session id and password. ZooKeeper supports session +recovery across instances of a process. A Java program may save its +session id and password to stable storage, restart, and recover the +session that was used by the earlier instance of the program. + +When a ZooKeeper object is created, two threads are created as +well: an IO thread and an event thread. All IO happens on the IO thread +(using Java NIO). All event callbacks happen on the event thread. +Session maintenance such as reconnecting to ZooKeeper servers and +maintaining heartbeat is done on the IO thread. Responses for +synchronous methods are also processed in the IO thread. All responses +to asynchronous methods and watch events are processed on the event +thread. There are a few things to notice that result from this +design: + +- All completions for asynchronous calls and watcher callbacks + will be made in order, one at a time. The caller can do any + processing they wish, but no other callbacks will be processed + during that time. +- Callbacks do not block the processing of the IO thread or the + processing of the synchronous calls. +- Synchronous calls may not return in the correct order. For + example, assume a client does the following processing: issues an + asynchronous read of node **/a** with + _watch_ set to true, and then in the completion + callback of the read it does a synchronous read of **/a**. (Maybe not good practice, but not illegal + either, and it makes for a simple example.) + Note that if there is a change to **/a** between the asynchronous read and the + synchronous read, the client library will receive the watch event + saying **/a** changed before the + response for the synchronous read, but because of the completion + callback blocking the event queue, the synchronous read will + return with the new value of **/a** + before the watch event is processed. + +Finally, the rules associated with shutdown are straightforward: +once a ZooKeeper object is closed or receives a fatal event +(SESSION_EXPIRED and AUTH_FAILED), the ZooKeeper object becomes invalid. +On a close, the two threads shut down and any further access on zookeeper +handle is undefined behavior and should be avoided. + +### Client Configuration Parameters + +The following list contains configuration properties for the Java client. You can set any +of these properties using Java system properties. For server properties, please check the +[Server configuration section of the Admin Guide](/docs/admin-ops/administrators-guide/configuration-parameters#advanced-configuration). +The ZooKeeper Wiki also has useful pages about +[ZooKeeper SSL support](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide), +and [SASL authentication for ZooKeeper](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+and+SASL). + +- _zookeeper.sasl.client_ : + Set the value to **false** to disable + SASL authentication. Default is **true**. + +- _zookeeper.sasl.clientconfig_ : + Specifies the context key in the JAAS login file. Default is "Client". + +- _zookeeper.server.principal_ : + Specifies the server principal to be used by the client for authentication, while connecting to the zookeeper + server, when Kerberos authentication is enabled. If this configuration is provided, then + the ZooKeeper client will NOT USE any of the following parameters to determine the server principal: + + ```properties + zookeeper.sasl.client.username, zookeeper.sasl.client.canonicalize.hostname, zookeeper.server.realm + Note: this config parameter is working only for ZooKeeper 3.5.7+, 3.6.0+ + ``` + +- _zookeeper.sasl.client.username_ : + Traditionally, a principal is divided into three parts: the primary, the instance, and the realm. + The format of a typical Kerberos V5 principal is primary/instance@REALM. + zookeeper.sasl.client.username specifies the primary part of the server principal. Default + is "zookeeper". Instance part is derived from the server IP. Finally server's principal is + username/IP@realm, where username is the value of zookeeper.sasl.client.username, IP is + the server IP, and realm is the value of zookeeper.server.realm. + +- _zookeeper.sasl.client.canonicalize.hostname_ : + Expecting the zookeeper.server.principal parameter is not provided, the ZooKeeper client will try to + determine the 'instance' (host) part of the ZooKeeper server principal. First it takes the hostname provided + as the ZooKeeper server connection string. Then it tries to 'canonicalize' the address by getting + the fully qualified domain name belonging to the address. You can disable this 'canonicalization' + by setting: zookeeper.sasl.client.canonicalize.hostname=false + +- _zookeeper.sasl.client.allowReverseDnsLookup_ : + **New in 3.9.5:** + Controls whether reverse DNS lookup is enabled when constructing the server principal for the SASL client. + Default: false + +- _zookeeper.server.realm_ : + Realm part of the server principal. By default it is the client principal realm. + +- _zookeeper.disableAutoWatchReset_ : + This switch controls whether automatic watch resetting is enabled. Clients automatically + reset watches during session reconnect by default, this option allows the client to turn off + this behavior by setting zookeeper.disableAutoWatchReset to **true**. + +- _zookeeper.client.secure_ : + **New in 3.5.5:** + If you want to connect to the server secure client port, you need to set this property to + **true** + on the client. This will connect to server using SSL with specified credentials. Note that + it requires the Netty client. + +- _zookeeper.clientCnxnSocket_ : + Specifies which ClientCnxnSocket to be used. Possible values are + **org.apache.zookeeper.ClientCnxnSocketNIO** + and + **org.apache.zookeeper.ClientCnxnSocketNetty** + . Default is + **org.apache.zookeeper.ClientCnxnSocketNIO** + . If you want to connect to server's secure client port, you need to set this property to + **org.apache.zookeeper.ClientCnxnSocketNetty** + on client. + +- _zookeeper.ssl.keyStore.location and zookeeper.ssl.keyStore.password_ : + **New in 3.5.5:** + Specifies the file path to a JKS containing the local credentials to be used for SSL connections, + and the password to unlock the file. +- _zookeeper.ssl.keyStore.passwordPath_ : + **New in 3.8.0:** + Specifies the file path which contains the keystore password + +- _zookeeper.ssl.trustStore.location and zookeeper.ssl.trustStore.password_ : + **New in 3.5.5:** + Specifies the file path to a JKS containing the remote credentials to be used for SSL connections, + and the password to unlock the file. +- _zookeeper.ssl.trustStore.passwordPath_ : + **New in 3.8.0:** + Specifies the file path which contains the truststore password + +- _zookeeper.ssl.keyStore.type_ and _zookeeper.ssl.trustStore.type_: + **New in 3.5.5:** + Specifies the file format of keys/trust store files used to establish TLS connection to the ZooKeeper server. + Values: JKS, PEM, PKCS12 or null (detect by filename). Default: null. + **New in 3.6.3, 3.7.0:** + The format BCFKS was added. + +- _jute.maxbuffer_ : + In the client side, it specifies the maximum size of the incoming data from the server. The default is 0xfffff(1048575) bytes, + or just under 1M. This is really a sanity check. The ZooKeeper server is designed to store and send + data on the order of kilobytes. If incoming data length is more than this value, an IOException + is raised. This value of client side should keep same with the server side(Setting **System.setProperty("jute.maxbuffer", "xxxx")** in the client side will work), + otherwise problems will arise. + +- _zookeeper.kinit_ : + Specifies path to kinit binary. Default is "/usr/bin/kinit". + +- _zookeeper.shuffleDnsResponse_ : + **New in 3.10.0:** + Specifies whether ZooKeeper client should randomly pick an IP address from the DNS lookup query result when resolving + server addresses or not. This is a feature flag in order to keep the old behavior of the default DNS resolver in + `StaticHostProvider`, because we disabled it by default. The reason behind that is shuffling the response of DNS queries + shadows JVM network property `java.net.preferIPv6Addresses` (default: false). This property controls whether JVM's built-in + resolver should prioritize v4 (false value) or v6 (true value) addresses when putting together the list of IP addresses + in the result. In other words the above Java system property was completely ineffective in the case of ZooKeeper server host + resolution protocol and this must have been fixed. In a dual stack environment one might want to prefer one stack over + the other which, in case of Java processes, should be controlled by JVM network properties and ZooKeeper must honor + these settings. Since the old behavior has been with us since day zero, we introduced this feature flag in case you + need it. Such case could be when you have a buggy DNS server which responds IP addresses always in the same order and + you want to randomize that. + Default: false + +- _zookeeper.hostProvider.dnsSrvRefreshIntervalSeconds_ : + **New in 3.10.0:** + Specifies the refresh interval in seconds for DNS SRV record lookups when using DnsSrvHostProvider. + A value of 0 disables periodic refresh. + Default: 60 seconds + +## C Binding + +The C binding has a single-threaded and multi-threaded library. +The multi-threaded library is easiest to use and is most similar to the +Java API. This library will create an IO thread and an event dispatch +thread for handling connection maintenance and callbacks. The +single-threaded library allows ZooKeeper to be used in event driven +applications by exposing the event loop used in the multi-threaded +library. + +The package includes two shared libraries: zookeeper*st and +zookeeper_mt. The former only provides the asynchronous APIs and +callbacks for integrating into the application's event loop. The only +reason this library exists is to support the platforms were a +\_pthread* library is not available or is unstable +(i.e. FreeBSD 4.x). In all other cases, application developers should +link with zookeeper_mt, as it includes support for both Sync and Async +API. + +### Installation + +If you're building the client from a check-out from the Apache +repository, follow the steps outlined below. If you're building from a +project source package downloaded from apache, skip to step **3**. + +1. Run `mvn compile` in zookeeper-jute directory (_.../trunk/zookeeper-jute_). + This will create a directory named "generated" under + _.../trunk/zookeeper-client/zookeeper-client-c_. +1. Change directory to the*.../trunk/zookeeper-client/zookeeper-client-c* + and run `autoreconf -if` to bootstrap **autoconf**, **automake** and **libtool**. Make sure you have **autoconf version 2.59** or greater installed. + Skip to step**4**. +1. If you are building from a project source package, + unzip/untar the source tarball and cd to the* + zookeeper-x.x.x/zookeeper-client/zookeeper-client-c* directory. +1. Run `./configure ` to + generate the makefile. Here are some of options the **configure** utility supports that can be + useful in this step: + +- `--enable-debug` + Enables optimization and enables debug info compiler + options. (Disabled by default.) +- `--without-syncapi` + Disables Sync API support; zookeeper_mt library won't be + built. (Enabled by default.) +- `--disable-static` + Do not build static libraries. (Enabled by + default.) +- `--disable-shared` + Do not build shared libraries. (Enabled by + default.) + + See INSTALL for general information about running **configure**. 1. Run + `make` or `make install` to build the libraries and install them. 1. To + generate doxygen documentation for the ZooKeeper API, run `make + doxygen-doc`. All documentation will be placed in a new subfolder named + docs. By default, this command only generates HTML. For information on other + document formats, run `./configure --help` + + +### Building Your Own C Client + +In order to be able to use the ZooKeeper C API in your application +you have to remember to + +1. Include ZooKeeper header: `#include ` +1. If you are building a multithreaded client, compile with + `-DTHREADED` compiler flag to enable the multi-threaded version of + the library, and then link against the + _zookeeper_mt_ library. If you are building a + single-threaded client, do not compile with `-DTHREADED`, and be + sure to link against the_zookeeper_st_library. + + + See *.../trunk/zookeeper-client/zookeeper-client-c/src/cli.c* for an example + of a C client implementation + diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/building-blocks-a-guide-to-zookeeper-operations.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/building-blocks-a-guide-to-zookeeper-operations.mdx new file mode 100644 index 00000000000..36d1b0a4fcd --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/building-blocks-a-guide-to-zookeeper-operations.mdx @@ -0,0 +1,96 @@ +--- +title: "Building Blocks: A Guide to ZooKeeper Operations" +description: "A practical reference for all operations a developer can perform against a ZooKeeper server, covering error handling, connecting, and the full synchronous and asynchronous API." +--- + +This section surveys all the operations a developer can perform +against a ZooKeeper server. It is lower level information than the earlier +concepts chapters in this manual, but higher level than the ZooKeeper API +Reference. + +## Handling Errors + +Both the Java and C client bindings may report errors. The Java client binding does so by throwing KeeperException, calling code() on the exception will return the specific error code. The C client binding returns an error code as defined in the enum ZOO_ERRORS. API callbacks indicate result code for both language bindings. See the API documentation (javadoc for Java, doxygen for C) for full details on the possible errors and their meaning. + +## Connecting to ZooKeeper + +Before we begin, you will have to set up a running Zookeeper server so that we can start developing the client. For C client bindings, we will be using the multithreaded library(zookeeper*mt) with a simple example written in C. To establish a connection with Zookeeper server, we make use of C API - \_zookeeper_init* with the following signature: + +int zookeeper_init(const char *host, watcher_fn fn, int recv_timeout, const clientid_t *clientid, void \*context, int flags); + +- \*_host_ : + Connection string to zookeeper server in the format of host:port. If there are multiple servers, use comma as separator after specifying the host:port pairs. Eg: "127.0.0.1:2181,127.0.0.1:3001,127.0.0.1:3002" +- _fn_ : + Watcher function to process events when a notification is triggered. +- _recv_timeout_ : + Session expiration time in milliseconds. +- \*_clientid_ : + We can specify 0 for a new session. If a session has already establish previously, we could provide that client ID and it would reconnect to that previous session. +- \*_context_ : + Context object that can be associated with the zkhandle_t handler. If it is not used, we can set it to 0. +- _flags_ : + In an initiation, we can leave it for 0. + +We will demonstrate client that outputs "Connected to Zookeeper" after successful connection or an error message otherwise. Let's call the following code _zkClient.cc_: + +```c +#include +#include +#include +using namespace std; + +// Keeping track of the connection state +static int connected = 0; +static int expired = 0; + +// *zkHandler handles the connection with Zookeeper +static zhandle_t *zkHandler; + +// watcher function would process events +void watcher(zhandle_t *zkH, int type, int state, const char *path, void *watcherCtx) +{ + if (type == ZOO_SESSION_EVENT) { + + // state refers to states of zookeeper connection. + // To keep it simple, we would demonstrate these 3: ZOO_EXPIRED_SESSION_STATE, ZOO_CONNECTED_STATE, ZOO_NOTCONNECTED_STATE + // If you are using ACL, you should be aware of an authentication failure state - ZOO_AUTH_FAILED_STATE + if (state == ZOO_CONNECTED_STATE) { + connected = 1; + } else if (state == ZOO_NOTCONNECTED_STATE ) { + connected = 0; + } else if (state == ZOO_EXPIRED_SESSION_STATE) { + expired = 1; + connected = 0; + zookeeper_close(zkH); + } + } +} + +int main(){ + zoo_set_debug_level(ZOO_LOG_LEVEL_DEBUG); + + // zookeeper_init returns the handler upon a successful connection, null otherwise + zkHandler = zookeeper_init("localhost:2181", watcher, 10000, 0, 0, 0); + + if (!zkHandler) { + return errno; + }else{ + printf("Connection established with Zookeeper. \n"); + } + + // Close Zookeeper connection + zookeeper_close(zkHandler); + + return 0; +} +``` + +Compile the code with the multithreaded library mentioned before. + +`> g++ -Iinclude/ zkClient.cpp -lzookeeper_mt -o Client` + +Run the client. + +`> ./Client` + +From the output, you should see "Connected to Zookeeper" along with Zookeeper's DEBUG messages if the connection is successful. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/consistency-guarantees.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/consistency-guarantees.mdx new file mode 100644 index 00000000000..828f902c4e6 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/consistency-guarantees.mdx @@ -0,0 +1,68 @@ +--- +title: "Consistency Guarantees" +description: "Details ZooKeeper's consistency guarantees: sequential consistency, atomicity, single system image, reliability, and timeliness, and how they compare to other distributed systems." +--- + +ZooKeeper is a high performance, scalable service. Both reads and +write operations are designed to be fast, though reads are faster than +writes. The reason for this is that in the case of reads, ZooKeeper can +serve older data, which in turn is due to ZooKeeper's consistency +guarantees: + +- _Sequential Consistency_ : + Updates from a client will be applied in the order that they + were sent. + +- _Atomicity_ : + Updates either succeed or fail — there are no partial + results. + +- _Single System Image_ : + A client will see the same view of the service regardless of + the server that it connects to. i.e., a client will never see an + older view of the system even if the client fails over to a + different server with the same session. + +- _Reliability_ : + Once an update has been applied, it will persist from that + time forward until a client overwrites the update. This guarantee + has two corollaries: + 1. If a client gets a successful return code, the update will + have been applied. On some failures (communication errors, + timeouts, etc) the client will not know if the update has + applied or not. We take steps to minimize the failures, but the + guarantee is only present with successful return codes. + (This is called the _monotonicity condition_ in Paxos.) + 1. Any updates that are seen by the client, through a read + request or successful update, will never be rolled back when + recovering from server failures. + +- _Timeliness_ : + The clients view of the system is guaranteed to be up-to-date + within a certain time bound (on the order of tens of seconds). + Either system changes will be seen by a client within this bound, or + the client will detect a service outage. + +Using these consistency guarantees it is easy to build higher level +functions such as leader election, barriers, queues, and read/write +revocable locks solely at the ZooKeeper client (no additions needed to +ZooKeeper). See [Recipes and Solutions](/docs/developer/recipes) +for more details. + + + Sometimes developers mistakenly assume one other guarantee that ZooKeeper does + _not_ in fact make. This is: *Simultaneously Consistent Cross-Client Views*: + ZooKeeper does not guarantee that at every instance in time, two different + clients will have identical views of ZooKeeper data. Due to factors like + network delays, one client may perform an update before another client gets + notified of the change. Consider the scenario of two clients, A and B. If + client A sets the value of a znode /a from 0 to 1, then tells client B to read + /a, client B may read the old value of 0, depending on which server it is + connected to. If it is important that Client A and Client B read the same + value, Client B should call the **sync()** method from the ZooKeeper API + method before it performs its read. So, ZooKeeper by itself doesn't guarantee + that changes occur synchronously across all servers, but ZooKeeper primitives + can be used to construct higher level functions that provide useful client + synchronization. (For more information, see the [ZooKeeper + Recipes](/docs/developer/recipes)). + diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/data-model.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/data-model.mdx new file mode 100644 index 00000000000..eae000252f5 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/data-model.mdx @@ -0,0 +1,208 @@ +--- +title: "Data Model" +description: "Explains ZooKeeper's hierarchical namespace of znodes, including data access rules, ephemeral and sequence nodes, container nodes, TTL nodes, and the stat structure." +--- + +ZooKeeper has a hierarchal namespace, much like a distributed file +system. The only difference is that each node in the namespace can have +data associated with it as well as children. It is like having a file +system that allows a file to also be a directory. Paths to nodes are +always expressed as canonical, absolute, slash-separated paths; there are +no relative reference. Any unicode character can be used in a path subject +to the following constraints: + +- The null character (\\u0000) cannot be part of a path name. (This + causes problems with the C binding.) +- The following characters can't be used because they don't + display well, or render in confusing ways: \\u0001 - \\u001F and \\u007F +- \\u009F. +- The following characters are not allowed: \\ud800 - uF8FF, + \\uFFF0 - uFFFF. +- The "." character can be used as part of another name, but "." + and ".." cannot alone be used to indicate a node along a path, + because ZooKeeper doesn't use relative paths. The following would be + invalid: "/a/b/./c" or "/a/b/../c". +- The token "zookeeper" is reserved. + +## ZNodes + +Every node in a ZooKeeper tree is referred to as a +_znode_. Znodes maintain a stat structure that +includes version numbers for data changes, acl changes. The stat +structure also has timestamps. The version number, together with the +timestamp, allows ZooKeeper to validate the cache and to coordinate +updates. Each time a znode's data changes, the version number increases. +For instance, whenever a client retrieves data, it also receives the +version of the data. And when a client performs an update or a delete, +it must supply the version of the data of the znode it is changing. If +the version it supplies doesn't match the actual version of the data, +the update will fail. (This behavior can be overridden.) + + + In distributed application engineering, the words _node_ can refer to a + generic host machine, a server, a member of an ensemble, a client process, + etc. In the ZooKeeper documentation, _znodes_ refer to the data nodes. + _Servers_ refers to machines that make up the ZooKeeper service; _quorum + peers_ refer to the servers that make up an ensemble; client refers to any + host or process which uses a ZooKeeper service. + + +Znodes are the main entity that a programmer access. They have +several characteristics that are worth mentioning here. + +### Watches + +Clients can set watches on znodes. Changes to that znode trigger +the watch and then clear the watch. When a watch triggers, ZooKeeper +sends the client a notification. More information about watches can be +found in the section +[ZooKeeper Watches](/docs/developer/programmers-guide/watches). + +### Data Access + +The data stored at each znode in a namespace is read and written +atomically. Reads get all the data bytes associated with a znode and a +write replaces all the data. Each node has an Access Control List +(ACL) that restricts who can do what. + +ZooKeeper was not designed to be a general database or large +object store. Instead, it manages coordination data. This data can +come in the form of configuration, status information, rendezvous, etc. +A common property of the various forms of coordination data is that +they are relatively small: measured in kilobytes. +The ZooKeeper client and the server implementations have sanity checks +to ensure that znodes have less than 1M of data, but the data should +be much less than that on average. Operating on relatively large data +sizes will cause some operations to take much more time than others and +will affect the latencies of some operations because of the extra time +needed to move more data over the network and onto storage media. If +large data storage is needed, the usual pattern of dealing with such +data is to store it on a bulk storage system, such as NFS or HDFS, and +store pointers to the storage locations in ZooKeeper. + +### Ephemeral Nodes + +ZooKeeper also has the notion of ephemeral nodes. These znodes +exists as long as the session that created the znode is active. When +the session ends the znode is deleted. Because of this behavior +ephemeral znodes are not allowed to have children. The list of ephemerals +for the session can be retrieved using **getEphemerals()** api. + +#### getEphemerals() + +Retrieves the list of ephemeral nodes created by the session for the +given path. If the path is empty, it will list all the ephemeral nodes +for the session. +**Use Case** - A sample use case might be, if the list of ephemeral +nodes for the session needs to be collected for duplicate data entry check +and the nodes are created in a sequential manner so you do not know the name +for duplicate check. In that case, getEphemerals() api could be used to +get the list of nodes for the session. This might be a typical use case +for service discovery. + +### Sequence Nodes — Unique Naming + +When creating a znode you can also request that +ZooKeeper append a monotonically increasing counter to the end +of path. This counter is unique to the parent znode. The +counter has a format of %010d — that is 10 digits with 0 +(zero) padding (the counter is formatted in this way to +simplify sorting), i.e. "`0000000001`". See +[Queue +Recipe](/docs/developer/recipes#queues) for an example use of this feature. Note: the +counter used to store the next sequence number is a signed int +(4bytes) maintained by the parent node, the counter will +overflow when incremented beyond 2147483647 (resulting in a +name "`-2147483648`"). + +### Container Nodes + +#### Added in 3.5.3 + +ZooKeeper has the notion of container znodes. Container znodes are +special purpose znodes useful for recipes such as leader, lock, etc. +When the last child of a container is deleted, the container becomes +a candidate to be deleted by the server at some point in the future. + +Given this property, you should be prepared to get +KeeperException.NoNodeException when creating children inside of +container znodes. i.e. when creating child znodes inside of container znodes +always check for KeeperException.NoNodeException and recreate the container +znode when it occurs. + +### TTL Nodes + +#### Added in 3.5.3 + +When creating PERSISTENT or PERSISTENT_SEQUENTIAL znodes, +you can optionally set a TTL in milliseconds for the znode. If the znode +is not modified within the TTL and has no children it will become a candidate +to be deleted by the server at some point in the future. + +Note: TTL Nodes must be enabled via System property as they +are disabled by default. See the [Administrator's Guide](/docs/admin-ops/administrators-guide/configuration-parameters#advanced-configuration) for +details. If you attempt to create TTL Nodes without the +proper System property set the server will throw +KeeperException.UnimplementedException. + +## Time in ZooKeeper + +ZooKeeper tracks time multiple ways: + +- **Zxid** + Every change to the ZooKeeper state receives a stamp in the + form of a _zxid_ (ZooKeeper Transaction Id). + This exposes the total ordering of all changes to ZooKeeper. Each + change will have a unique zxid and if zxid1 is smaller than zxid2 + then zxid1 happened before zxid2. +- **Version numbers** + Every change to a node will cause an increase to one of the + version numbers of that node. The three version numbers are version + (number of changes to the data of a znode), cversion (number of + changes to the children of a znode), and aversion (number of changes + to the ACL of a znode). +- **Ticks** + When using multi-server ZooKeeper, servers use ticks to define + timing of events such as status uploads, session timeouts, + connection timeouts between peers, etc. The tick time is only + indirectly exposed through the minimum session timeout (2 times the + tick time); if a client requests a session timeout less than the + minimum session timeout, the server will tell the client that the + session timeout is actually the minimum session timeout. +- **Real time** + ZooKeeper doesn't use real time, or clock time, at all except + to put timestamps into the stat structure on znode creation and + znode modification. + +## ZooKeeper Stat Structure + +The Stat structure for each znode in ZooKeeper is made up of the +following fields: + +- **czxid** + The zxid of the change that caused this znode to be + created. +- **mzxid** + The zxid of the change that last modified this znode. +- **pzxid** + The zxid of the change that last modified children of this znode. +- **ctime** + The time in milliseconds from epoch when this znode was + created. +- **mtime** + The time in milliseconds from epoch when this znode was last + modified. +- **version** + The number of changes to the data of this znode. +- **cversion** + The number of changes to the children of this znode. +- **aversion** + The number of changes to the ACL of this znode. +- **ephemeralOwner** + The session id of the owner of this znode if the znode is an + ephemeral node. If it is not an ephemeral node, it will be + zero. +- **dataLength** + The length of the data field of this znode. +- **numChildren** + The number of children of this znode. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/gotchas-common-problems-and-troubleshooting.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/gotchas-common-problems-and-troubleshooting.mdx new file mode 100644 index 00000000000..f6a868be7b5 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/gotchas-common-problems-and-troubleshooting.mdx @@ -0,0 +1,51 @@ +--- +title: "Gotchas: Common Problems and Troubleshooting" +description: "Common pitfalls and troubleshooting tips for ZooKeeper application developers, covering watches, server failures, connection loss, performance, and recoverable errors." +--- + +So now you know ZooKeeper. It's fast, simple, your application +works, but wait ... something's wrong. Here are some pitfalls that +ZooKeeper users fall into: + +1. If you are using watches, you must look for the connected watch + event. When a ZooKeeper client disconnects from a server, you will + not receive notification of changes until reconnected. If you are + watching for a znode to come into existence, you will miss the event + if the znode is created and deleted while you are disconnected. +1. You must test ZooKeeper server failures. The ZooKeeper service + can survive failures as long as a majority of servers are active. The + question to ask is: can your application handle it? In the real world + a client's connection to ZooKeeper can break. (ZooKeeper server + failures and network partitions are common reasons for connection + loss.) The ZooKeeper client library takes care of recovering your + connection and letting you know what happened, but you must make sure + that you recover your state and any outstanding requests that failed. + Find out if you got it right in the test lab, not in production - test + with a ZooKeeper service made up of a several of servers and subject + them to reboots. +1. The list of ZooKeeper servers used by the client must match the + list of ZooKeeper servers that each ZooKeeper server has. Things can + work, although not optimally, if the client list is a subset of the + real list of ZooKeeper servers, but not if the client lists ZooKeeper + servers not in the ZooKeeper cluster. +1. Be careful where you put that transaction log. The most + performance-critical part of ZooKeeper is the transaction log. + ZooKeeper must sync transactions to media before it returns a + response. A dedicated transaction log device is key to consistent good + performance. Putting the log on a busy device will adversely effect + performance. If you only have one storage device, put trace files on + NFS and increase the snapshotCount; it doesn't eliminate the problem, + but it can mitigate it. +1. Set your Java max heap size correctly. It is very important to + _avoid swapping._ Going to disk unnecessarily will + almost certainly degrade your performance unacceptably. Remember, in + ZooKeeper, everything is ordered, so if one request hits the disk, all + other queued requests hit the disk. + To avoid swapping, try to set the heapsize to the amount of + physical memory you have, minus the amount needed by the OS and cache. + The best way to determine an optimal heap size for your configurations + is to _run load tests_. If for some reason you + can't, be conservative in your estimates and choose a number well + below the limit that would cause your machine to swap. For example, on + a 4G machine, a 3G heap is a conservative estimate to start + with. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/index.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/index.mdx new file mode 100644 index 00000000000..ce1c6c9522c --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/index.mdx @@ -0,0 +1,38 @@ +--- +title: "Programmer's Guide" +description: "This document is a guide for developers wishing to create distributed applications that take advantage of ZooKeeper's coordination services. It contains conceptual and practical information." +--- + +The first four sections of this guide present a higher level +discussions of various ZooKeeper concepts. These are necessary both for an +understanding of how ZooKeeper works as well how to work with it. It does +not contain source code, but it does assume a familiarity with the +problems associated with distributed computing. + +The next four sections provide practical programming +information. + +Most of the information in this document is written to be accessible as +stand-alone reference material. However, before starting your first +ZooKeeper application, you should probably at least read the chapters on +the [ZooKeeper Data Model](/docs/developer/programmers-guide/data-model) and [ZooKeeper Basic Operations](/docs/developer/programmers-guide/building-blocks-a-guide-to-zookeeper-operations). + +## Links to Other Information + +Outside the formal documentation, there're several other sources of +information for ZooKeeper developers. + +- _[API Reference](https://zookeeper.apache.org/doc/current/apidocs/zookeeper-server/index.html)_ : + The complete reference to the ZooKeeper API +- _[ZooKeeper Talk at the Hadoop Summit 2008](https://www.youtube.com/watch?v=rXI9xiesUV8)_ : + A video introduction to ZooKeeper, by Benjamin Reed of Yahoo! + Research +- _[Barrier and Queue Tutorial](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Tutorial)_ : + The excellent Java tutorial by Flavio Junqueira, implementing + simple barriers and producer-consumer queues using ZooKeeper. +- _[ZooKeeper - A Reliable, Scalable Distributed Coordination System](https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeperArticles)_ : + An article by Todd Hoff (07/15/2008) +- _[ZooKeeper Recipes](/docs/developer/recipes)_ : + Pseudo-level discussion of the implementation of various + synchronization solutions with ZooKeeper: Event Handles, Queues, + Locks, and Two-phase Commits. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/meta.json new file mode 100644 index 00000000000..d314e3ac746 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/meta.json @@ -0,0 +1,14 @@ +{ + "title": "Programmer's Guide", + "pages": [ + "data-model", + "sessions", + "watches", + "consistency-guarantees", + "access-control-using-acls", + "pluggable-authentication", + "bindings", + "building-blocks-a-guide-to-zookeeper-operations", + "gotchas-common-problems-and-troubleshooting" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/pluggable-authentication.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/pluggable-authentication.mdx new file mode 100644 index 00000000000..8a2bb1b8b5d --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/pluggable-authentication.mdx @@ -0,0 +1,115 @@ +--- +title: "Pluggable Authentication" +description: "Describes ZooKeeper's pluggable authentication framework, how authentication plugins authenticate clients and match ACL entries, and how to add a custom scheme." +--- + +ZooKeeper runs in a variety of different environments with +various different authentication schemes, so it has a completely +pluggable authentication framework. Even the builtin authentication +schemes use the pluggable authentication framework. + +To understand how the authentication framework works, first you must +understand the two main authentication operations. The framework +first must authenticate the client. This is usually done as soon as +the client connects to a server and consists of validating information +sent from or gathered about a client and associating it with the connection. +The second operation handled by the framework is finding the entries in an +ACL that correspond to client. ACL entries are `` pairs. The _idspec_ may be +a simple string match against the authentication information associated +with the connection or it may be a expression that is evaluated against that +information. It is up to the implementation of the authentication plugin +to do the match. Here is the interface that an authentication plugin must +implement: + +```java +public interface AuthenticationProvider { + String getScheme(); + KeeperException.Code handleAuthentication(ServerCnxn cnxn, byte authData[]); + boolean isValid(String id); + boolean matches(String id, String aclExpr); + boolean isAuthenticated(); +} + +``` + +The first method _getScheme_ returns the string +that identifies the plugin. Because we support multiple methods of authentication, +an authentication credential or an _idspec_ will always be +prefixed with _scheme:_. The ZooKeeper server uses the scheme +returned by the authentication plugin to determine which ids the scheme +applies to. + +_handleAuthentication_ is called when a client +sends authentication information to be associated with a connection. The +client specifies the scheme to which the information corresponds. The +ZooKeeper server passes the information to the authentication plugin whose +_getScheme_ matches the scheme passed by the client. The +implementor of _handleAuthentication_ will usually return +an error if it determines that the information is bad, or it will associate information +with the connection using _cnxn.getAuthInfo().add(new Id(getScheme(), data))_. + +The authentication plugin is involved in both setting and using ACLs. When an +ACL is set for a znode, the ZooKeeper server will pass the id part of the entry to +the _isValid(String id)_ method. It is up to the plugin to verify +that the id has a correct form. For example, _ip:172.16.0.0/16_ +is a valid id, but _ip:host.com_ is not. If the new ACL includes +an "auth" entry, _isAuthenticated_ is used to see if the +authentication information for this scheme that is associated with the connection +should be added to the ACL. Some schemes +should not be included in auth. For example, the IP address of the client is not +considered as an id that should be added to the ACL if auth is specified. + +ZooKeeper invokes _matches(String id, String aclExpr)_ when checking an ACL. It +needs to match authentication information of the client against the relevant ACL +entries. To find the entries which apply to the client, the ZooKeeper server will +find the scheme of each entry and if there is authentication information +from that client for that scheme, _matches(String id, String aclExpr)_ +will be called with _id_ set to the authentication information +that was previously added to the connection by _handleAuthentication_ and +_aclExpr_ set to the id of the ACL entry. The authentication plugin +uses its own logic and matching scheme to determine if _id_ is included +in _aclExpr_. + +There are two built in authentication plugins: _ip_ and +_digest_. Additional plugins can adding using system properties. At +startup the ZooKeeper server will look for system properties that start with +"zookeeper.authProvider." and interpret the value of those properties as the class name +of an authentication plugin. These properties can be set using the +_-Dzookeeper.authProvider.X=com.f.MyAuth_ or adding entries such as +the following in the server configuration file: + +```properties +authProvider.1=com.f.MyAuth +authProvider.2=com.f.MyAuth2 + +``` + +Care should be taking to ensure that the suffix on the property is unique. If there are +duplicates such as _-Dzookeeper.authProvider.X=com.f.MyAuth -Dzookeeper.authProvider.X=com.f.MyAuth2_, +only one will be used. Also all servers must have the same plugins defined, otherwise clients using +the authentication schemes provided by the plugins will have problems connecting to some servers. + +**Added in 3.6.0**: An alternate abstraction is available for pluggable +authentication. It provides additional arguments. + +```java +public abstract class ServerAuthenticationProvider implements AuthenticationProvider { + public abstract KeeperException.Code handleAuthentication(ServerObjs serverObjs, byte authData[]); + public abstract boolean matches(ServerObjs serverObjs, MatchValues matchValues); +} + +``` + +Instead of implementing AuthenticationProvider you extend ServerAuthenticationProvider. Your handleAuthentication() +and matches() methods will then receive the additional parameters (via ServerObjs and MatchValues). + +- **ZooKeeperServer** + The ZooKeeperServer instance +- **ServerCnxn** + The current connection +- **path** + The ZNode path being operated on (or null if not used) +- **perm** + The operation value or 0 +- **setAcls** + When the setAcl() method is being operated on, the list of ACLs that are being set diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/sessions.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/sessions.mdx new file mode 100644 index 00000000000..20634033df7 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/sessions.mdx @@ -0,0 +1,272 @@ +--- +title: "Sessions" +description: "Covers ZooKeeper client sessions: connection states, session timeouts, expiration, password-based recovery, and how clients connect to a ZooKeeper ensemble." +--- + +A ZooKeeper client establishes a session with the ZooKeeper +service by creating a handle to the service using a language +binding. Once created, the handle starts off in the CONNECTING state +and the client library tries to connect to one of the servers that +make up the ZooKeeper service at which point it switches to the +CONNECTED state. During normal operation the client handle will be in one of these +two states. If an unrecoverable error occurs, such as session +expiration or authentication failure, or if the application explicitly +closes the handle, the handle will move to the CLOSED state. +The following figure shows the possible state transitions of a +ZooKeeper client: + +![State transitions](/docs-images/state_dia.jpg) + +To create a client session the application code must provide +a connection string containing a comma separated list of host:port pairs, +each corresponding to a ZooKeeper server (e.g. "127.0.0.1:4545" or +"127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002"). The ZooKeeper +client library will pick an arbitrary server and try to connect to +it. If this connection fails, or if the client becomes +disconnected from the server for any reason, the client will +automatically try the next server in the list, until a connection +is (re-)established. + +**Added in 3.2.0**: An +optional "chroot" suffix may also be appended to the connection +string. This will run the client commands while interpreting all +paths relative to this root (similar to the unix chroot +command). If used the example would look like: +"127.0.0.1:4545/app/a" or +"127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/app/a" where the +client would be rooted at "/app/a" and all paths would be relative +to this root - ie getting/setting/etc... "/foo/bar" would result +in operations being run on "/app/a/foo/bar" (from the server +perspective). This feature is particularly useful in multi-tenant +environments where each user of a particular ZooKeeper service +could be rooted differently. This makes re-use much simpler as +each user can code his/her application as if it were rooted at +"/", while actual location (say /app/a) could be determined at +deployment time. + +When a client gets a handle to the ZooKeeper service, +ZooKeeper creates a ZooKeeper session, represented as a 64-bit +number, that it assigns to the client. If the client connects to a +different ZooKeeper server, it will send the session id as a part +of the connection handshake. As a security measure, the server +creates a password for the session id that any ZooKeeper server +can validate.The password is sent to the client with the session +id when the client establishes the session. The client sends this +password with the session id whenever it reestablishes the session +with a new server. + +One of the parameters to the ZooKeeper client library call +to create a ZooKeeper session is the session timeout in +milliseconds. The client sends a requested timeout, the server +responds with the timeout that it can give the client. The current +implementation requires that the timeout be a minimum of 2 times +the tickTime (as set in the server configuration) and a maximum of +20 times the tickTime. The ZooKeeper client API allows access to +the negotiated timeout. + +When a client (session) becomes partitioned from the ZK +serving cluster it will begin searching the list of servers that +were specified during session creation. Eventually, when +connectivity between the client and at least one of the servers is +re-established, the session will either again transition to the +"connected" state (if reconnected within the session timeout +value) or it will transition to the "expired" state (if +reconnected after the session timeout). It is not advisable to +create a new session object (a new ZooKeeper.class or zookeeper +handle in the c binding) for disconnection. The ZK client library +will handle reconnect for you. In particular we have heuristics +built into the client library to handle things like "herd effect", +etc... Only create a new session when you are notified of session +expiration (mandatory). + +Session expiration is managed by the ZooKeeper cluster +itself, not by the client. When the ZK client establishes a +session with the cluster it provides a "timeout" value detailed +above. This value is used by the cluster to determine when the +client's session expires. Expirations happens when the cluster +does not hear from the client within the specified session timeout +period (i.e. no heartbeat). At session expiration the cluster will +delete any/all ephemeral nodes owned by that session and +immediately notify any/all connected clients of the change (anyone +watching those znodes). At this point the client of the expired +session is still disconnected from the cluster, it will not be +notified of the session expiration until/unless it is able to +re-establish a connection to the cluster. The client will stay in +disconnected state until the TCP connection is re-established with +the cluster, at which point the watcher of the expired session +will receive the "session expired" notification. + +Example state transitions for an expired session as seen by +the expired session's watcher: + +1. 'connected' : session is established and client + is communicating with cluster (client/server communication is + operating properly) +1. .... client is partitioned from the + cluster +1. 'disconnected' : client has lost connectivity + with the cluster +1. .... time elapses, after 'timeout' period the + cluster expires the session, nothing is seen by client as it is + disconnected from cluster +1. .... time elapses, the client regains network + level connectivity with the cluster +1. 'expired' : eventually the client reconnects to + the cluster, it is then notified of the + expiration + +Another parameter to the ZooKeeper session establishment +call is the default watcher. Watchers are notified when any state +change occurs in the client. For example if the client loses +connectivity to the server the client will be notified, or if the +client's session expires, etc... This watcher should consider the +initial state to be disconnected (i.e. before any state changes +events are sent to the watcher by the client lib). In the case of +a new connection, the first event sent to the watcher is typically +the session connection event. + +The session is kept alive by requests sent by the client. If +the session is idle for a period of time that would timeout the +session, the client will send a PING request to keep the session +alive. This PING request not only allows the ZooKeeper server to +know that the client is still active, but it also allows the +client to verify that its connection to the ZooKeeper server is +still active. The timing of the PING is conservative enough to +ensure reasonable time to detect a dead connection and reconnect +to a new server. + +Once a connection to the server is successfully established +(connected) there are basically two cases where the client lib generates +connectionloss (the result code in c binding, exception in Java — see +the API documentation for binding specific details) when either a synchronous or +asynchronous operation is performed and one of the following holds: + +1. The application calls an operation on a session that is no + longer alive/valid +1. The ZooKeeper client disconnects from a server when there + are pending operations to that server, i.e., there is a pending asynchronous call. + +**Added in 3.2.0 — SessionMovedException**. There is an internal +exception that is generally not seen by clients called the SessionMovedException. +This exception occurs because a request was received on a connection for a session +which has been reestablished on a different server. The normal cause of this error is +a client that sends a request to a server, but the network packet gets delayed, so +the client times out and connects to a new server. When the delayed packet arrives at +the first server, the old server detects that the session has moved, and closes the +client connection. Clients normally do not see this error since they do not read +from those old connections. (Old connections are usually closed.) One situation in which this +condition can be seen is when two clients try to reestablish the same connection using +a saved session id and password. One of the clients will reestablish the connection +and the second client will be disconnected (causing the pair to attempt to re-establish +its connection/session indefinitely). + +**Updating the list of servers**. We allow a client to +update the connection string by providing a new comma separated list of host:port pairs, +each corresponding to a ZooKeeper server. The function invokes a probabilistic load-balancing +algorithm which may cause the client to disconnect from its current host with the goal +to achieve expected uniform number of connections per server in the new list. +In case the current host to which the client is connected is not in the new list +this call will always cause the connection to be dropped. Otherwise, the decision +is based on whether the number of servers has increased or decreased and by how much. + +For example, if the previous connection string contained 3 hosts and now the list contains +these 3 hosts and 2 more hosts, 40% of clients connected to each of the 3 hosts will +move to one of the new hosts in order to balance the load. The algorithm will cause the client +to drop its connection to the current host to which it is connected with probability 0.4 and in this +case cause the client to connect to one of the 2 new hosts, chosen at random. + +Another example — suppose we have 5 hosts and now update the list to remove 2 of the hosts, +the clients connected to the 3 remaining hosts will stay connected, whereas all clients connected +to the 2 removed hosts will need to move to one of the 3 hosts, chosen at random. If the connection +is dropped, the client moves to a special mode where he chooses a new server to connect to using the +probabilistic algorithm, and not just round robin. + +In the first example, each client decides to disconnect with probability 0.4 but once the decision is +made, it will try to connect to a random new server and only if it cannot connect to any of the new +servers will it try to connect to the old ones. After finding a server, or trying all servers in the +new list and failing to connect, the client moves back to the normal mode of operation where it picks +an arbitrary server from the connectString and attempts to connect to it. If that fails, it will continue +trying different random servers in round robin. (see above the algorithm used to initially choose a server) + +**Local session**. Added in 3.5.0, mainly implemented by [ZOOKEEPER-1147](https://issues.apache.org/jira/browse/ZOOKEEPER-1147). + +- Background: The creation and closing of sessions are costly in ZooKeeper because they need quorum confirmations, + they become the bottleneck of a ZooKeeper ensemble when it needs to handle thousands of client connections. + So after 3.5.0, we introduce a new type of session: local session which doesn't have a full functionality of a normal(global) session, this feature + will be available by turning on _localSessionsEnabled_. + +when _localSessionsUpgradingEnabled_ is disable: + +- Local sessions cannot create ephemeral nodes + +- Once a local session is lost, users cannot re-establish it using the session-id/password, the session and its watches are gone for good. + Note: Losing the tcp connection does not necessarily imply that the session is lost. If the connection can be reestablished with the same zk server + before the session timeout then the client can continue (it simply cannot move to another server). + +- When a local session connects, the session info is only maintained on the zookeeper server that it is connected to. The leader is not aware of the creation of such a session and + there is no state written to disk. + +- The pings, expiration and other session state maintenance are handled by the server which current session is connected to. + +when _localSessionsUpgradingEnabled_ is enable: + +- A local session can be upgraded to the global session automatically. + +- When a new session is created it is saved locally in a wrapped _LocalSessionTracker_. It can subsequently be upgraded + to a global session as required (e.g. create ephemeral nodes). If an upgrade is requested the session is removed from local + collections while keeping the same session ID. + +- Currently, Only the operation: _create ephemeral node_ needs a session upgrade from local to global. + The reason is that the creation of ephemeral node depends heavily on a global session. If local session can create ephemeral + node without upgrading to global session, it will cause the data inconsistency between different nodes. + The leader also needs to know about the lifespan of a session in order to clean up ephemeral nodes on close/expiry. + This requires a global session as the local session is tied to its particular server. + +- A session can be both a local and global session during upgrade, but the operation of upgrade cannot be called concurrently by two thread. + +- _ZooKeeperServer_(Standalone) uses _SessionTrackerImpl_; _LeaderZookeeper_ uses _LeaderSessionTracker_ which holds + _SessionTrackerImpl_(global) and _LocalSessionTracker_(if enable); _FollowerZooKeeperServer_ and _ObserverZooKeeperServer_ + use _LearnerSessionTracker_ which holds _LocalSessionTracker_. + The UML Graph of Classes about session: + + ``` + +----------------+ +--------------------+ +---------------------+ + | | --> | | ----> | LocalSessionTracker | + | SessionTracker | | SessionTrackerImpl | +---------------------+ + | | | | +-----------------------+ + | | | | +-------------------------> | LeaderSessionTracker | + +----------------+ +--------------------+ | +-----------------------+ + | | + | | + | | + | +---------------------------+ + +---------> | | + | UpgradeableSessionTracker | + | | + | | ------------------------+ + +---------------------------+ | + | + | + v + +-----------------------+ + | LearnerSessionTracker | + +-----------------------+ + ``` + +## Q&A [!toc] + +- _What's the reason for having the config option to disable local session upgrade?_ + - In a large deployment which wants to handle a very large number of clients, we know that clients connecting via the observers + which is supposed to be local session only. So this is more like a safeguard against someone accidentally creates lots of ephemeral nodes and global sessions. + +- _When is the session created?_ + - In the current implementation, it will try to create a local session when processing _ConnectRequest_ and when + _createSession_ request reaches _FinalRequestProcessor_. + +- _What happens if the create for session is sent at server A and the client disconnects to some other server B + which ends up sending it again and then disconnects and connects back to server A?_ + - When a client reconnects to B, its sessionId won’t exist in B’s local session tracker. So B will send validation packet. + If CreateSession issued by A is committed before validation packet arrive the client will be able to connect. + Otherwise, the client will get session expired because the quorum hasn’t know about this session yet. + If the client also tries to connect back to A again, the session is already removed from local session tracker. + So A will need to send a validation packet to the leader. The outcome should be the same as B depending on the timing of the request. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/watches.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/watches.mdx new file mode 100644 index 00000000000..3d00939db0c --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/programmers-guide/watches.mdx @@ -0,0 +1,145 @@ +--- +title: "Watches" +description: "Describes ZooKeeper watches — one-time event triggers sent to clients when znode data or children change — including watch semantics, guarantees, and removal." +--- + +All of the read operations in ZooKeeper - **getData()**, **getChildren()**, and **exists()** - have the option of setting a watch as a +side effect. Here is ZooKeeper's definition of a watch: a watch event is +one-time trigger, sent to the client that set the watch, which occurs when +the data for which the watch was set changes. There are three key points +to consider in this definition of a watch: + +- **One-time trigger** + One watch event will be sent to the client when the data has changed. + For example, if a client does a getData("/znode1", true) and later the + data for /znode1 is changed or deleted, the client will get a watch + event for /znode1. If /znode1 changes again, no watch event will be + sent unless the client has done another read that sets a new + watch. +- **Sent to the client** + This implies that an event is on the way to the client, but may + not reach the client before the successful return code to the change + operation reaches the client that initiated the change. Watches are + sent asynchronously to watchers. ZooKeeper provides an ordering + guarantee: a client will never see a change for which it has set a + watch until it first sees the watch event. Network delays or other + factors may cause different clients to see watches and return codes + from updates at different times. The key point is that everything seen + by the different clients will have a consistent order. +- **The data for which the watch was + set** + This refers to the different ways a node can change. It + helps to think of ZooKeeper as maintaining two lists of + watches: data watches and child watches. getData() and + exists() set data watches. getChildren() sets child + watches. Alternatively, it may help to think of watches being + set according to the kind of data returned. getData() and + exists() return information about the data of the node, + whereas getChildren() returns a list of children. Thus, + setData() will trigger data watches for the znode being set + (assuming the set is successful). A successful create() will + trigger a data watch for the znode being created and a child + watch for the parent znode. A successful delete() will trigger + both a data watch and a child watch (since there can be no + more children) for a znode being deleted as well as a child + watch for the parent znode. + +Watches are maintained locally at the ZooKeeper server to which the +client is connected. This allows watches to be lightweight to set, +maintain, and dispatch. When a client connects to a new server, the watch +will be triggered for any session events. Watches will not be received +while disconnected from a server. When a client reconnects, any previously +registered watches will be reregistered and triggered if needed. In +general this all occurs transparently. There is one case where a watch +may be missed: a watch for the existence of a znode not yet created will +be missed if the znode is created and deleted while disconnected. + +**New in 3.6.0:** Clients can also set +permanent, recursive watches on a znode that are not removed when triggered +and that trigger for changes on the registered znode as well as any children +znodes recursively. + +## Semantics of Watches + +We can set watches with the three calls that read the state of +ZooKeeper: exists, getData, and getChildren. The following list details +the events that a watch can trigger and the calls that enable them: + +- **Created event:** + Enabled with a call to exists. +- **Deleted event:** + Enabled with a call to exists, getData, and getChildren. +- **Changed event:** + Enabled with a call to exists and getData. +- **Child event:** + Enabled with a call to getChildren. + +## Persistent, Recursive Watches + +**New in 3.6.0:** There is now a variation on the standard +watch described above whereby you can set a watch that does not get removed when triggered. +Additionally, these watches trigger the event types _NodeCreated_, _NodeDeleted_, and _NodeDataChanged_ +and, optionally, recursively for all znodes starting at the znode that the watch is registered for. Note +that _NodeChildrenChanged_ events are not triggered for persistent recursive watches as it would be redundant. + +Persistent watches are set using the method _addWatch()_. The triggering semantics and guarantees +(other than one-time triggering) are the same as standard watches. The only exception regarding events is that +recursive persistent watchers never trigger child changed events as they are redundant. +Persistent watches are removed using _removeWatches()_ with watcher type _WatcherType.Any_. + +## Remove Watches + +We can remove the watches registered on a znode with a call to +removeWatches. Also, a ZooKeeper client can remove watches locally even +if there is no server connection by setting the local flag to true. The +following list details the events which will be triggered after the +successful watch removal. + +- **Child Remove event:** + Watcher which was added with a call to getChildren. +- **Data Remove event:** + Watcher which was added with a call to exists or getData. +- **Persistent Remove event:** + Watcher which was added with a call to add a persistent watch. + +## What ZooKeeper Guarantees about Watches + +With regard to watches, ZooKeeper maintains these +guarantees: + +- Watches are ordered with respect to other events, other + watches, and asynchronous replies. The ZooKeeper client libraries + ensures that everything is dispatched in order. + +- A client will see a watch event for a znode it is watching + before seeing the new data that corresponds to that znode. + +- The order of watch events from ZooKeeper corresponds to the + order of the updates as seen by the ZooKeeper service. + +## Things to Remember about Watches + +- Standard watches are one time triggers; if you get a watch event and + you want to get notified of future changes, you must set another + watch. + +- Because standard watches are one time triggers and there is latency + between getting the event and sending a new request to get a watch + you cannot reliably see every change that happens to a node in + ZooKeeper. Be prepared to handle the case where the znode changes + multiple times between getting the event and setting the watch + again. (You may not care, but at least realize it may + happen.) + +- A watch object, or function/context pair, will only be + triggered once for a given notification. For example, if the same + watch object is registered for an exists and a getData call for the + same file and that file is then deleted, the watch object would + only be invoked once with the deletion notification for the file. + +- When you disconnect from a server (for example, when the + server fails), you will not get any watches until the connection + is reestablished. For this reason session events are sent to all + outstanding watch handlers. Use session events to go into a safe + mode: you will not be receiving events while disconnected, so your + process should act conservatively in that mode. diff --git a/zookeeper-docs/src/main/resources/markdown/recipes.md b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/recipes.mdx similarity index 69% rename from zookeeper-docs/src/main/resources/markdown/recipes.md rename to zookeeper-website/app/pages/_docs/docs/_mdx/developer/recipes.mdx index 9d3dec55c62..74d66a6b3d2 100644 --- a/zookeeper-docs/src/main/resources/markdown/recipes.md +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/recipes.mdx @@ -1,36 +1,7 @@ - - -# ZooKeeper Recipes and Solutions - -* [A Guide to Creating Higher-level Constructs with ZooKeeper](#ch_recipes) - * [Important Note About Error Handling](#sc_recipes_errorHandlingNote) - * [Out of the Box Applications: Name Service, Configuration, Group Membership](#sc_outOfTheBox) - * [Barriers](#sc_recipes_eventHandles) - * [Double Barriers](#sc_doubleBarriers) - * [Queues](#sc_recipes_Queues) - * [Priority Queues](#sc_recipes_priorityQueues) - * [Locks](#sc_recipes_Locks) - * [Recoverable Errors and the GUID](#sc_recipes_GuidNote) - * [Shared Locks](#Shared+Locks) - * [Revocable Shared Locks](#sc_revocableSharedLocks) - * [Two-phased Commit](#sc_recipes_twoPhasedCommit) - * [Leader Election](#sc_leaderElection) - - +--- +title: "Recipes and Solutions" +description: "Guidelines for using ZooKeeper to implement higher-order constructs such as barriers, queues, locks, and leader election." +--- ## A Guide to Creating Higher-level Constructs with ZooKeeper @@ -60,8 +31,6 @@ as event handles or queues, a more practical means of performing the same function. In general, the examples in this section are designed to stimulate thought. - - ### Important Note About Error Handling When implementing the recipes you must handle recoverable exceptions @@ -74,8 +43,6 @@ session is still valid and, thus, the node is not removed. The implication is that it is difficult for the client to know if its node was created or not. The recipes below include measures to handle this. - - ### Out of the Box Applications: Name Service, Configuration, Group Membership Name service and configuration are two of the primary applications @@ -88,8 +55,6 @@ group create ephemeral nodes under the group node. Nodes of the members that fail abnormally will be removed automatically when ZooKeeper detects the failure. - - ### Barriers Distributed systems use _barriers_ @@ -100,17 +65,15 @@ barrier is in place if the barrier node exists. Here's the pseudo code: 1. Client calls the ZooKeeper API's **exists()** function on the barrier node, with - _watch_ set to true. + _watch_ set to true. 1. If **exists()** returns false, the - barrier is gone and the client proceeds + barrier is gone and the client proceeds 1. Else, if **exists()** returns true, - the clients wait for a watch event from ZooKeeper for the barrier - node. + the clients wait for a watch event from ZooKeeper for the barrier + node. 1. When the watch event is triggered, the client reissues the - **exists( )** call, again waiting until - the barrier node is removed. - - + **exists( )** call, again waiting until + the barrier node is removed. #### Double Barriers @@ -128,14 +91,14 @@ _x_ client process register before proceeding with the computation. (The _x_ here is up to you to determine for your system.) -| **Enter** | **Leave** | -|-----------------------------------|-------------------------------| -| 1. Create a name __n_ = _b_+“/”+_p__ | 1. **L = getChildren(b, false)** | -| 2. Set watch: **exists(_b_ + ‘‘/ready’’, true)** | 2. if no children, exit | -| 3. Create child: **create(_n_, EPHEMERAL)** | 3. if _p_ is only process node in L, delete(n) and exit | -| 4. **L = getChildren(b, false)** | 4. if _p_ is the lowest process node in L, wait on highest process node in L | -| 5. if fewer children in L than_x_, wait for watch event | 5. else **delete(_n_)**if still exists and wait on lowest process node in L | -| 6. else **create(b + ‘‘/ready’’, REGULAR)** | 6. goto 1 | +| **Enter** | **Leave** | +| ------------------------------------------------------- | ---------------------------------------------------------------------------- | +| 1. Create a name **n* = \_b*+“/”+\_p** | 1. **L = getChildren(b, false)** | +| 2. Set watch: **exists(_b_ + ‘‘/ready’’, true)** | 2. if no children, exit | +| 3. Create child: **create(_n_, EPHEMERAL)** | 3. if _p_ is only process node in L, delete(n) and exit | +| 4. **L = getChildren(b, false)** | 4. if _p_ is the lowest process node in L, wait on highest process node in L | +| 5. if fewer children in L than*x*, wait for watch event | 5. else **delete(_n_)**if still exists and wait on lowest process node in L | +| 6. else **create(b + ‘‘/ready’’, REGULAR)** | 6. goto 1 | On entering, all processes watch on a ready node and create an ephemeral node as a child of the barrier node. Each process @@ -161,8 +124,6 @@ the owner of the lowest process watches for any other process node single process wakes up on each node deletion except for the last node, which wakes up everyone when it is removed. - - ### Queues Distributed queues are a common data structure. To implement a @@ -181,26 +142,23 @@ the list obtained from the first **getChildren( )** call. If there are no children in the queue node, the reader waits for a watch notification to check the queue again. -###### Note ->There now exists a Queue implementation in ZooKeeper -recipes directory. This is distributed with the release -- -zookeeper-recipes/zookeeper-recipes-queue directory of the release artifact. - - + + There now exists a Queue implementation in ZooKeeper recipes directory. This + is distributed with the release -- zookeeper-recipes/zookeeper-recipes-queue + directory of the release artifact. + #### Priority Queues To implement a priority queue, you need only make two simple changes to the generic [queue -recipe](#sc_recipes_Queues) . First, to add to a queue, the pathname ends with +recipe](#queues) . First, to add to a queue, the pathname ends with "queue-YY" where YY is the priority of the element with lower numbers representing higher priority (just like UNIX). Second, when removing from the queue, a client uses an up-to-date children list meaning that the client will invalidate previously obtained children lists if a watch notification triggers for the queue node. - - ### Locks Fully distributed locks that are globally synchronous, meaning at @@ -208,87 +166,79 @@ any snapshot in time no two clients think they hold the same lock. These can be implemented using ZooKeeper. As with priority queues, first define a lock node. -###### Note ->There now exists a Lock implementation in ZooKeeper -recipes directory. This is distributed with the release -- -zookeeper-recipes/zookeeper-recipes-lock directory of the release artifact. + + There now exists a Lock implementation in ZooKeeper recipes directory. This is + distributed with the release -- zookeeper-recipes/zookeeper-recipes-lock + directory of the release artifact. + Clients wishing to obtain a lock do the following: 1. Call **create( )** with a pathname - of "_locknode_/guid-lock-" and the _sequence_ and - _ephemeral_ flags set. The _guid_ - is needed in case the create() result is missed. See the note below. + of "_locknode_/guid-lock-" and the _sequence_ and + _ephemeral_ flags set. The _guid_ + is needed in case the create() result is missed. See the note below. 1. Call **getChildren( )** on the lock - node _without_ setting the watch flag (this is - important to avoid the herd effect). + node _without_ setting the watch flag (this is + important to avoid the herd effect). 1. If the pathname created in step **1** has the lowest sequence number suffix, the - client has the lock and the client exits the protocol. + client has the lock and the client exits the protocol. 1. The client calls **exists( )** with - the watch flag set on the path in the lock directory with the next - lowest sequence number. + the watch flag set on the path in the lock directory with the next + lowest sequence number. 1. if **exists( )** returns null, go - to step **2**. Otherwise, wait for a - notification for the pathname from the previous step before going to - step **2**. + to step **2**. Otherwise, wait for a + notification for the pathname from the previous step before going to + step **2**. The unlock protocol is very simple: clients wishing to release a lock simply delete the node they created in step 1. Here are a few things to notice: -* The removal of a node will only cause one client to wake up +- The removal of a node will only cause one client to wake up since each node is watched by exactly one client. In this way, you avoid the herd effect. - -* There is no polling or timeouts. - -* Because of the way you implement locking, it is easy to see the +- There is no polling or timeouts. +- Because of the way you implement locking, it is easy to see the amount of lock contention, break locks, debug locking problems, etc. - - #### Recoverable Errors and the GUID -* If a recoverable error occurs calling **create()** the +- If a recoverable error occurs calling **create()** the client should call **getChildren()** and check for a node containing the _guid_ used in the path name. - This handles the case (noted [above](#sc_recipes_errorHandlingNote)) of + This handles the case (noted [above](#important-note-about-error-handling)) of the create() succeeding on the server but the server crashing before returning the name of the new node. - - #### Shared Locks You can implement shared locks by with a few changes to the lock protocol: -| **Obtaining a read lock:** | **Obtaining a write lock:** | -|----------------------------|-----------------------------| -| 1. Call **create( )** to create a node with pathname "*guid-/read-*". This is the lock node use later in the protocol. Make sure to set both the _sequence_ and _ephemeral_ flags. | 1. Call **create( )** to create a node with pathname "*guid-/write-*". This is the lock node spoken of later in the protocol. Make sure to set both _sequence_ and _ephemeral_ flags. | -| 2. Call **getChildren( )** on the lock node _without_ setting the _watch_ flag - this is important, as it avoids the herd effect. | 2. Call **getChildren( )** on the lock node _without_ setting the _watch_ flag - this is important, as it avoids the herd effect. | -| 3. If there are no children with a pathname starting with "*write-*" and having a lower sequence number than the node created in step **1**, the client has the lock and can exit the protocol. | 3. If there are no children with a lower sequence number than the node created in step **1**, the client has the lock and the client exits the protocol. | -| 4. Otherwise, call **exists( )**, with _watch_ flag, set on the node in lock directory with pathname starting with "*write-*" having the next lowest sequence number. | 4. Call **exists( ),** with _watch_ flag set, on the node with the pathname that has the next lowest sequence number. | -| 5. If **exists( )** returns _false_, goto step **2**. | 5. If **exists( )** returns _false_, goto step **2**. Otherwise, wait for a notification for the pathname from the previous step before going to step **2**. | -| 6. Otherwise, wait for a notification for the pathname from the previous step before going to step **2** | | +| **Obtaining a read lock:** | **Obtaining a write lock:** | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1. Call **create( )** to create a node with pathname "_guid-/read-_". This is the lock node use later in the protocol. Make sure to set both the _sequence_ and _ephemeral_ flags. | 1. Call **create( )** to create a node with pathname "_guid-/write-_". This is the lock node spoken of later in the protocol. Make sure to set both _sequence_ and _ephemeral_ flags. | +| 2. Call **getChildren( )** on the lock node _without_ setting the _watch_ flag - this is important, as it avoids the herd effect. | 2. Call **getChildren( )** on the lock node _without_ setting the _watch_ flag - this is important, as it avoids the herd effect. | +| 3. If there are no children with a pathname starting with "_write-_" and having a lower sequence number than the node created in step **1**, the client has the lock and can exit the protocol. | 3. If there are no children with a lower sequence number than the node created in step **1**, the client has the lock and the client exits the protocol. | +| 4. Otherwise, call **exists( )**, with _watch_ flag, set on the node in lock directory with pathname starting with "_write-_" having the next lowest sequence number. | 4. Call **exists( ),** with _watch_ flag set, on the node with the pathname that has the next lowest sequence number. | +| 5. If **exists( )** returns _false_, goto step **2**. | 5. If **exists( )** returns _false_, goto step **2**. Otherwise, wait for a notification for the pathname from the previous step before going to step **2**. | +| 6. Otherwise, wait for a notification for the pathname from the previous step before going to step **2** | | Notes: -* It might appear that this recipe creates a herd effect: +- It might appear that this recipe creates a herd effect: when there is a large group of clients waiting for a read lock, and all getting notified more or less simultaneously - when the "*write-*" node with the lowest + when the "_write-_" node with the lowest sequence number is deleted. In fact. that's valid behavior: as all those waiting reader clients should be released since they have the lock. The herd effect refers to releasing a "herd" when in fact only a single or a small number of machines can proceed. - -* See the [note for Locks](#sc_recipes_GuidNote) on how to use the guid in the node. - - +- See the [note for Locks](#recoverable-errors-and-the-guid) on how to use the guid in the node. #### Revocable Shared Locks @@ -314,8 +264,6 @@ Laser Beams_ by stipulating in your protocol that the revoker is allowed to delete the lock node if after some length of time the lock isn't deleted by the lock holder. - - ### Two-phased Commit A two-phase commit protocol is an algorithm that lets all clients in @@ -354,14 +302,12 @@ To address the second problem, you can have the coordinator propagate the transaction to the sites, and have each site creating its own ephemeral node. - - ### Leader Election A simple way of doing leader election with ZooKeeper is to use the **SEQUENCE|EPHEMERAL** flags when creating znodes that represent "proposals" of clients. The idea is to have a znode, -say "/election", such that each znode creates a child znode "/election/guid-n_" +say "/election", such that each znode creates a child znode "/election/guid-n\_" with both flags SEQUENCE|EPHEMERAL. With the sequence flag, ZooKeeper automatically appends a sequence number that is greater than anyone previously appended to a child of "/election". The process that created @@ -389,28 +335,25 @@ Here's the pseudo code: Let ELECTION be a path of choice of the application. To volunteer to be a leader: -1. Create znode z with path "ELECTION/guid-n_" with both SEQUENCE and - EPHEMERAL flags; +1. Create znode z with path "ELECTION/guid-n\_" with both SEQUENCE and + EPHEMERAL flags; 1. Let C be the children of "ELECTION", and i is the sequence - number of z; + number of z; 1. Watch for changes on "ELECTION/guid-n_j", where j is the largest - sequence number such that j < i and n_j is a znode in C; + sequence number such that j < i and n_j is a znode in C; Upon receiving a notification of znode deletion: 1. Let C be the new set of children of ELECTION; 1. If z is the smallest node in C, then execute leader - procedure; + procedure; 1. Otherwise, watch for changes on "ELECTION/guid-n_j", where j is the - largest sequence number such that j < i and n_j is a znode in C; + largest sequence number such that j < i and n_j is a znode in C; Notes: -* Note that the znode having no preceding znode on the list of +- Note that the znode having no preceding znode on the list of children do not imply that the creator of this znode is aware that it is the current leader. Applications may consider creating a separate znode to acknowledge that the leader has executed the leader procedure. - -* See the [note for Locks](#sc_recipes_GuidNote) on how to use the guid in the node. - - +- See the [note for Locks](#recoverable-errors-and-the-guid) on how to use the guid in the node. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/developer/use-cases.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/use-cases.mdx new file mode 100644 index 00000000000..f71cb5a12c4 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/developer/use-cases.mdx @@ -0,0 +1,463 @@ +--- +title: "Use Cases" +description: "A catalog of real-world projects and organizations that use Apache ZooKeeper for distributed coordination." +--- + +- Applications and organizations using ZooKeeper include (alphabetically) [^1]. +- If your use case wants to be listed here. Please do not hesitate, submit a pull request or write an email to **dev@zookeeper.apache.org**, + and then, your use case will be included. +- If this documentation has violated your intellectual property rights or you and your company's privacy, write an email to **dev@zookeeper.apache.org**, + we will handle them in a timely manner. + +## Free Software Projects + +### [AdroitLogic UltraESB](http://adroitlogic.org/) + +- Uses ZooKeeper to implement node coordination, in clustering support. This allows the management of the complete cluster, + or any specific node - from any other node connected via JMX. A Cluster wide command framework developed on top of the + ZooKeeper coordination allows commands that fail on some nodes to be retried etc. We also support the automated graceful + round-robin-restart of a complete cluster of nodes using the same framework [^1]. + +### [Akka](http://akka.io/) + +- Akka is the platform for the next generation event-driven, scalable and fault-tolerant architectures on the JVM. + Or: Akka is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven applications on the JVM [^1]. + +### [Eclipse Communication Framework](http://www.eclipse.org/ecf) + +- The Eclipse ECF project provides an implementation of its Abstract Discovery services using Zookeeper. ECF itself + is used in many projects providing base functionality for communication, all based on OSGi [^1]. + +### [Eclipse Gyrex](http://www.eclipse.org/gyrex) + +- The Eclipse Gyrex project provides a platform for building your own Java OSGi based clouds. +- ZooKeeper is used as the core cloud component for node membership and management, coordination of jobs executing among workers, + a lock service and a simple queue service and a lot more [^1]. + +### [GoldenOrb](http://www.goldenorbos.org/) + +- massive-scale Graph analysis [^1]. + +### [Juju](https://juju.ubuntu.com/) + +- Service deployment and orchestration framework, formerly called Ensemble [^1]. + +### [Katta](http://katta.sourceforge.net/) + +- Katta serves distributed Lucene indexes in a grid environment. +- Zookeeper is used for node, master and index management in the grid [^1]. + +### [KeptCollections](https://github.com/anthonyu/KeptCollections) + +- KeptCollections is a library of drop-in replacements for the data structures in the Java Collections framework. +- KeptCollections uses Apache ZooKeeper as a backing store, thus making its data structures distributed and scalable [^1]. + +### [Neo4j](https://neo4j.com/) + +- Neo4j is a Graph Database. It's a disk based, ACID compliant transactional storage engine for big graphs and fast graph traversals, + using external indices like Lucene/Solr for global searches. +- We use ZooKeeper in the Neo4j High Availability components for write-master election, + read slave coordination and other cool stuff. ZooKeeper is a great and focused project - we like! [^1]. + +### [Norbert](http://sna-projects.com/norbert) + +- Partitioned routing and cluster management [^1]. + +### [spring-cloud-zookeeper](https://spring.io/projects/spring-cloud-zookeeper) + +- Spring Cloud Zookeeper provides Apache Zookeeper integrations for Spring Boot apps through autoconfiguration + and binding to the Spring Environment and other Spring programming model idioms. With a few simple annotations + you can quickly enable and configure the common patterns inside your application and build large distributed systems with Zookeeper. + The patterns provided include Service Discovery and Distributed Configuration [^38]. + +### [spring-statemachine](https://projects.spring.io/spring-statemachine/) + +- Spring Statemachine is a framework for application developers to use state machine concepts with Spring applications. +- Spring Statemachine can provide this feature:Distributed state machine based on a Zookeeper [31,32]. + +### [spring-xd](https://projects.spring.io/spring-xd/) + +- Spring XD is a unified, distributed, and extensible system for data ingestion, real time analytics, batch processing, and data export. + The project’s goal is to simplify the development of big data applications. +- ZooKeeper - Provides all runtime information for the XD cluster. Tracks running containers, in which containers modules + and jobs are deployed, stream definitions, deployment manifests, and the like [30,31]. + +### [Talend ESB](http://www.talend.com/products-application-integration/application-integration-esb-se.php) + +- Talend ESB is a versatile and flexible, enterprise service bus. +- It uses ZooKeeper as endpoint repository of both REST and SOAP Web services. + By using ZooKeeper Talend ESB is able to provide failover and load balancing capabilities in a very light-weight manner [^1]. + +### [redis_failover](https://github.com/ryanlecompte/redis_failover) + +- Redis Failover is a ZooKeeper-based automatic master/slave failover solution for Ruby [^1]. + +## Apache Projects + +### [Apache Accumulo](https://accumulo.apache.org/) + +- Accumulo is a distributed key/value store that provides expressive, cell-level access labels. +- Apache ZooKeeper plays a central role within the Accumulo architecture. Its quorum consistency model supports an overall + Accumulo architecture with no single points of failure. Beyond that, Accumulo leverages ZooKeeper to store and communication + configuration information for users and tables, as well as operational states of processes and tablets [^2]. + +### [Apache Atlas](http://atlas.apache.org) + +- Atlas is a scalable and extensible set of core foundational governance services – enabling enterprises to effectively and efficiently meet + their compliance requirements within Hadoop and allows integration with the whole enterprise data ecosystem. +- Atlas uses Zookeeper for coordination to provide redundancy and high availability of HBase,Kafka [31,35]. + +### [Apache BookKeeper](https://bookkeeper.apache.org/) + +- A scalable, fault-tolerant, and low-latency storage service optimized for real-time workloads. +- BookKeeper requires a metadata storage service to store information related to ledgers and available bookies. BookKeeper currently uses + ZooKeeper for this and other tasks [^3]. + +### [Apache CXF DOSGi](http://cxf.apache.org/distributed-osgi.html) + +- Apache CXF is an open source services framework. CXF helps you build and develop services using frontend programming + APIs, like JAX-WS and JAX-RS. These services can speak a variety of protocols such as SOAP, XML/HTTP, RESTful HTTP, + or CORBA and work over a variety of transports such as HTTP, JMS or JBI. +- The Distributed OSGi implementation at Apache CXF uses ZooKeeper for its Discovery functionality [^4]. + +### [Apache Drill](http://drill.apache.org/) + +- Schema-free SQL Query Engine for Hadoop, NoSQL and Cloud Storage +- ZooKeeper maintains ephemeral cluster membership information. The Drillbits use ZooKeeper to find other Drillbits in the cluster, + and the client uses ZooKeeper to find Drillbits to submit a query [^28]. + +### [Apache Druid](https://druid.apache.org/) + +- Apache Druid is a high performance real-time analytics database. +- Apache Druid uses Apache ZooKeeper (ZK) for management of current cluster state. The operations that happen over ZK are [^27]: + - Coordinator leader election + - Segment "publishing" protocol from Historical and Realtime + - Segment load/drop protocol between Coordinator and Historical + - Overlord leader election + - Overlord and MiddleManager task management + +### [Apache Dubbo](http://dubbo.apache.org) + +- Apache Dubbo is a high-performance, java based open source RPC framework. +- Zookeeper is used for service registration discovery and configuration management in Dubbo [^6]. + +### [Apache Flink](https://flink.apache.org/) + +- Apache Flink is a framework and distributed processing engine for stateful computations over unbounded and bounded data streams. + Flink has been designed to run in all common cluster environments, perform computations at in-memory speed and at any scale. +- To enable JobManager High Availability you have to set the high-availability mode to zookeeper, configure a ZooKeeper quorum and set up a masters file with all JobManagers hosts and their web UI ports. + Flink leverages ZooKeeper for distributed coordination between all running JobManager instances. ZooKeeper is a separate service from Flink, + which provides highly reliable distributed coordination via leader election and light-weight consistent state storage [^23]. + +### [Apache Flume](https://flume.apache.org/) + +- Flume is a distributed, reliable, and available service for efficiently collecting, aggregating, and moving large amounts + of log data. It has a simple and flexible architecture based on streaming data flows. It is robust and fault tolerant + with tunable reliability mechanisms and many failover and recovery mechanisms. It uses a simple extensible data model + that allows for online analytic application. + +- Flume supports Agent configurations via Zookeeper. This is an experimental feature [^5]. + +### [Apache Fluo](https://fluo.apache.org/) + +- Apache Fluo is a distributed processing system that lets users make incremental updates to large data sets. +- Apache Fluo is built on Apache Accumulo which uses Apache Zookeeper for consensus [31,37]. + +### [Apache Griffin](https://griffin.apache.org/) + +- Big Data Quality Solution For Batch and Streaming. +- Griffin uses Zookeeper for coordination to provide redundancy and high availability of Kafka [31,36]. + +### [Apache Hadoop](http://hadoop.apache.org/) + +- The Apache Hadoop software library is a framework that allows for the distributed processing of large data sets across + clusters of computers using simple programming models. It is designed to scale up from single servers to thousands of machines, + each offering local computation and storage. Rather than rely on hardware to deliver high-availability, + the library itself is designed to detect and handle failures at the application layer, so delivering a highly-available service on top of a cluster of computers, each of which may be prone to failures. + +- The implementation of automatic HDFS failover relies on ZooKeeper for the following things: + - **Failure detection** - each of the NameNode machines in the cluster maintains a persistent session in ZooKeeper. + If the machine crashes, the ZooKeeper session will expire, notifying the other NameNode that a failover should be triggered. + - **Active NameNode election** - ZooKeeper provides a simple mechanism to exclusively elect a node as active. If the current active NameNode crashes, + another node may take a special exclusive lock in ZooKeeper indicating that it should become the next active. + +- The ZKFailoverController (ZKFC) is a new component which is a ZooKeeper client which also monitors and manages the state of the NameNode. + Each of the machines which runs a NameNode also runs a ZKFC, and that ZKFC is responsible for: + - **Health monitoring** - the ZKFC pings its local NameNode on a periodic basis with a health-check command. + So long as the NameNode responds in a timely fashion with a healthy status, the ZKFC considers the node healthy. + If the node has crashed, frozen, or otherwise entered an unhealthy state, the health monitor will mark it as unhealthy. + - **ZooKeeper session management** - when the local NameNode is healthy, the ZKFC holds a session open in ZooKeeper. + If the local NameNode is active, it also holds a special “lock” znode. This lock uses ZooKeeper’s support for “ephemeral” nodes; + if the session expires, the lock node will be automatically deleted. + - **ZooKeeper-based election** - if the local NameNode is healthy, and the ZKFC sees that no other node currently holds the lock znode, + it will itself try to acquire the lock. If it succeeds, then it has “won the election”, and is responsible for running a failover to make its local NameNode active. + The failover process is similar to the manual failover described above: first, the previous active is fenced if necessary, + and then the local NameNode transitions to active state [^7]. + +### [Apache HBase](https://hbase.apache.org/) + +- HBase is the Hadoop database. It's an open-source, distributed, column-oriented store model. +- HBase uses ZooKeeper for master election, server lease management, bootstrapping, and coordination between servers. + A distributed Apache HBase installation depends on a running ZooKeeper cluster. All participating nodes and clients + need to be able to access the running ZooKeeper ensemble [^8]. +- As you can see, ZooKeeper is a fundamental part of HBase. All operations that require coordination, such as Regions + assignment, Master-Failover, replication, and snapshots, are built on ZooKeeper [^20]. + +### [Apache Helix](http://helix.apache.org/) + +- A cluster management framework for partitioned and replicated distributed resources. +- We need a distributed store to maintain the state of the cluster and a notification system to notify if there is any change in the cluster state. + Helix uses Apache ZooKeeper to achieve this functionality [^21]. + Zookeeper provides: +- A way to represent PERSISTENT state which remains until its deleted +- A way to represent TRANSIENT/EPHEMERAL state which vanishes when the process that created the state dies +- A notification mechanism when there is a change in PERSISTENT and EPHEMERAL state + +### [Apache Hive](https://hive.apache.org) + +- The Apache Hive data warehouse software facilitates reading, writing, and managing large datasets residing in distributed + storage using SQL. Structure can be projected onto data already in storage. A command line tool and JDBC driver are provided to connect users to Hive. +- Hive has been using ZooKeeper as distributed lock manager to support concurrency in HiveServer2 [25,26]. + +### [Apache Ignite](https://ignite.apache.org/) + +- Ignite is a memory-centric distributed database, caching, and processing platform for + transactional, analytical, and streaming workloads delivering in-memory speeds at petabyte scale +- Apache Ignite discovery mechanism goes with a ZooKeeper implementations which allows scaling Ignite clusters to 100s and 1000s of nodes + preserving linear scalability and performance [31,34].​ + +### [Apache James Mailbox](http://james.apache.org/mailbox/) + +- The Apache James Mailbox is a library providing a flexible Mailbox storage accessible by mail protocols + (IMAP4, POP3, SMTP,...) and other protocols. +- Uses Zookeeper and Curator Framework for generating distributed unique ID's [^31]. + +### [Apache Kafka](https://kafka.apache.org/) + +- Kafka is a distributed publish/subscribe messaging system +- Apache Kafka relies on ZooKeeper for the following things: + - **Controller election** + The controller is one of the most important broking entity in a Kafka ecosystem, and it also has the responsibility + to maintain the leader-follower relationship across all the partitions. If a node by some reason is shutting down, + it’s the controller’s responsibility to tell all the replicas to act as partition leaders in order to fulfill the + duties of the partition leaders on the node that is about to fail. So, whenever a node shuts down, a new controller + can be elected and it can also be made sure that at any given time, there is only one controller and all the follower nodes have agreed on that. + - **Configuration Of Topics** + The configuration regarding all the topics including the list of existing topics, the number of partitions for each topic, + the location of all the replicas, list of configuration overrides for all topics and which node is the preferred leader, etc. + - **Access control lists** + Access control lists or ACLs for all the topics are also maintained within Zookeeper. + - **Membership of the cluster** + Zookeeper also maintains a list of all the brokers that are functioning at any given moment and are a part of the cluster [^9]. + +### [Apache Kylin](http://kylin.apache.org/) + +- Apache Kylin is an open source Distributed Analytics Engine designed to provide SQL interface and multi-dimensional analysis (OLAP) on Hadoop/Spark supporting extremely large datasets, + original contributed from eBay Inc. +- Apache Kylin leverages Zookeeper for job coordination [31,33]. + +### [Apache Mesos](http://mesos.apache.org/) + +- Apache Mesos abstracts CPU, memory, storage, and other compute resources away from machines (physical or virtual), + enabling fault-tolerant and elastic distributed systems to easily be built and run effectively. +- Mesos has a high-availability mode that uses multiple Mesos masters: one active master (called the leader or leading master) + and several backups in case it fails. The masters elect the leader, with Apache ZooKeeper both coordinating the election + and handling leader detection by masters, agents, and scheduler drivers [^10]. + +### [Apache Oozie](https://oozie.apache.org) + +- Oozie is a workflow scheduler system to manage Apache Hadoop jobs. +- the Oozie servers use it for coordinating access to the database and communicating with each other. In order to have full HA, + there should be at least 3 ZooKeeper servers [^29]. + +### [Apache Pulsar](https://pulsar.apache.org) + +- Apache Pulsar is an open-source distributed pub-sub messaging system originally created at Yahoo and now part of the Apache Software Foundation +- Pulsar uses Apache Zookeeper for metadata storage, cluster configuration, and coordination. In a Pulsar instance: + - A configuration store quorum stores configuration for tenants, namespaces, and other entities that need to be globally consistent. + - Each cluster has its own local ZooKeeper ensemble that stores cluster-specific configuration and coordination such as ownership metadata, + broker load reports, BookKeeper ledger metadata, and more [^24]. + +### [Apache Solr](https://lucene.apache.org/solr/) + +- Solr is the popular, blazing-fast, open source enterprise search platform built on Apache Lucene. +- In the "Cloud" edition (v4.x and up) of enterprise search engine Apache Solr, ZooKeeper is used for configuration, + leader election and more [12,13]. + +### [Apache Spark](https://spark.apache.org/) + +- Apache Spark is a unified analytics engine for large-scale data processing. +- Utilizing ZooKeeper to provide leader election and some state storage, you can launch multiple Masters in your cluster connected to the same ZooKeeper instance. + One will be elected “leader” and the others will remain in standby mode. If the current leader dies, another Master will be elected, + recover the old Master’s state, and then resume scheduling [^14]. + +### [Apache Storm](http://storm.apache.org) + +- Apache Storm is a free and open source distributed realtime computation system. Apache Storm makes it easy to reliably + process unbounded streams of data, doing for realtime processing what Hadoop did for batch processing. + Apache Storm is simple, can be used with any programming language, and is a lot of fun to use! +- Storm uses Zookeeper for coordinating the cluster [^22]. + +## Companies + +### [AGETO](http://www.ageto.de/) + +- The AGETO RnD team uses ZooKeeper in a variety of internal as well as external consulting projects [^1]. + +### [Benipal Technologies](http://www.benipaltechnologies.com/) + +- ZooKeeper is used for internal application development with Solr and Hadoop with Hbase [^1]. + +### [Box](http://box.net/) + +- Box uses ZooKeeper for service discovery, service coordination, Solr and Hadoop support, etc [^1]. + +### [Deepdyve](http://www.deepdyve.com/) + +- We do search for research and provide access to high quality content using advanced search technologies Zookeeper is used to + manage server state, control index deployment and a myriad other tasks [^1]. + +### [Facebook](https://www.facebook.com/) + +- Facebook uses the Zeus ([17,18]) for configuration management which is a forked version of ZooKeeper, with many scalability + and performance en- hancements in order to work at the Facebook scale. + It runs a consensus protocol among servers distributed across mul- tiple regions for resilience. If the leader fails, + a follower is converted into a new leader. + +### [Idium Portal](http://www.idium.no/no/idium_portal/) + +- Idium Portal is a hosted web-publishing system delivered by Norwegian company, Idium AS. +- ZooKeeper is used for cluster messaging, service bootstrapping, and service coordination [^1]. + +### [Makara](http://www.makara.com/) + +- Using ZooKeeper on 2-node cluster on VMware workstation, Amazon EC2, Zen +- Using zkpython +- Looking into expanding into 100 node cluster [^1]. + +### [Midokura](http://www.midokura.com/) + +- We do virtualized networking for the cloud computing era. We use ZooKeeper for various aspects of our distributed control plane [^1]. + +### [Pinterest](https://www.pinterest.com/) + +- Pinterest uses the ZooKeeper for Service discovery and dynamic configuration.Like many large scale web sites, Pinterest’s infrastructure consists of servers that communicate with + backend services composed of a number of individual servers for managing load and fault tolerance. Ideally, we’d like the configuration to reflect only the active hosts, + so clients don’t need to deal with bad hosts as often. ZooKeeper provides a well known pattern to solve this problem [^19]. + +### [Rackspace](http://www.rackspace.com/email_hosting) + +- The Email & Apps team uses ZooKeeper to coordinate sharding and responsibility changes in a distributed e-mail client + that pulls and indexes data for search. ZooKeeper also provides distributed locking for connections to prevent a cluster from overwhelming servers [^1]. + +### [Sematext](http://sematext.com/) + +- Uses ZooKeeper in SPM (which includes ZooKeeper monitoring component, too!), Search Analytics, and Logsene [^1]. + +### [Tubemogul](http://tubemogul.com/) + +- Uses ZooKeeper for leader election, configuration management, locking, group membership [^1]. + +### [Twitter](https://twitter.com/) + +- ZooKeeper is used at Twitter as the source of truth for storing critical metadata. It serves as a coordination kernel to + provide distributed coordination services, such as leader election and distributed locking. + Some concrete examples of ZooKeeper in action include [15,16]: + - ZooKeeper is used to store service registry, which is used by Twitter’s naming service for service discovery. + - Manhattan (Twitter’s in-house key-value database), Nighthawk (sharded Redis), and Blobstore (in-house photo and video storage), + stores its cluster topology information in ZooKeeper. + - EventBus, Twitter’s pub-sub messaging system, stores critical metadata in ZooKeeper and uses ZooKeeper for leader election. + - Mesos, Twitter’s compute platform, uses ZooKeeper for leader election. + +### [Vast.com](http://www.vast.com/) + +- Used internally as a part of sharding services, distributed synchronization of data/index updates, configuration management and failover support [^1]. + +### [Wealthfront](http://wealthfront.com/) + +- Wealthfront uses ZooKeeper for service discovery, leader election and distributed locking among its many backend services. + ZK is an essential part of Wealthfront's continuous [deployment infrastructure](http://eng.wealthfront.com/2010/05/02/deployment-infrastructure-for-continuous-deployment/) [^1]. + +### [Yahoo!](http://www.yahoo.com/) + +- ZooKeeper is used for a myriad of services inside Yahoo! for doing leader election, configuration management, sharding, locking, group membership etc [^1]. + +### [Zynga](http://www.zynga.com/) + +- ZooKeeper at Zynga is used for a variety of services including configuration management, leader election, sharding and more [^1]. + +[^1]: https://cwiki.apache.org/confluence/display/ZOOKEEPER/PoweredBy + +[^2]: https://www.youtube.com/watch?v=Ew53T6h9oRw + +[^3]: https://bookkeeper.apache.org/docs/4.7.3/getting-started/concepts/#ledgers + +[^4]: http://cxf.apache.org/dosgi-discovery-demo-page.html + +[^5]: https://flume.apache.org/FlumeUserGuide.html + +[^6]: http://dubbo.apache.org/en-us/blog/dubbo-zk.html + +[^7]: https://hadoop.apache.org/docs/r2.7.1/hadoop-project-dist/hadoop-hdfs/HDFSHighAvailabilityWithQJM.html + +[^8]: https://hbase.apache.org/book.html#zookeeper + +[^9]: https://www.cloudkarafka.com/blog/2018-07-04-cloudkarafka_what_is_zookeeper.html + +[^10]: http://mesos.apache.org/documentation/latest/high-availability/ + +[^11]: http://incubator.apache.org/projects/s4.html + +[^12]: https://lucene.apache.org/solr/guide/6_6/using-zookeeper-to-manage-configuration-files.html#UsingZooKeepertoManageConfigurationFiles-StartupBootstrap + +[^13]: https://lucene.apache.org/solr/guide/6_6/setting-up-an-external-zookeeper-ensemble.html + +[^14]: https://spark.apache.org/docs/latest/spark-standalone.html#standby-masters-with-zookeeper + +[^15]: https://blog.twitter.com/engineering/en_us/topics/infrastructure/2018/zookeeper-at-twitter.html + +[^16]: https://blog.twitter.com/engineering/en_us/topics/infrastructure/2018/dynamic-configuration-at-twitter.html + +[^17]: TANG, C., KOOBURAT, T., VENKATACHALAM, P.,CHANDER, A., WEN, Z., NARAYANAN, A., DOWELL,P., AND KARL, R. Holistic Configuration Management at Facebook. In Proceedings of the 25th Symposium on Operating System Principles (SOSP’15) (Monterey, CA,USA, Oct. 2015). + +[^18]: https://www.youtube.com/watch?v=SeZV373gUZc + +[^19]: https://medium.com/@Pinterest_Engineering/zookeeper-resilience-at-pinterest-adfd8acf2a6b + +[^20]: https://blog.cloudera.com/what-are-hbase-znodes/ + +[^21]: https://helix.apache.org/Architecture.html + +[^22]: http://storm.apache.org/releases/current/Setting-up-a-Storm-cluster.html + +[^23]: https://ci.apache.org/projects/flink/flink-docs-release-1.9/ops/jobmanager_high_availability.html + +[^24]: https://pulsar.apache.org/docs/en/concepts-architecture-overview/#metadata-store + +[^25]: https://cwiki.apache.org/confluence/display/Hive/Locking + +[^26]: _ZooKeeperHiveLockManager_ implementation in the [hive](https://github.com/apache/hive/) code base + +[^27]: https://druid.apache.org/docs/latest/dependencies/zookeeper.html + +[^28]: https://mapr.com/blog/apache-drill-architecture-ultimate-guide/ + +[^29]: https://oozie.apache.org/docs/4.1.0/AG_Install.html + +[^30]: https://docs.spring.io/spring-xd/docs/current/reference/html/ + +[^31]: https://cwiki.apache.org/confluence/display/CURATOR/Powered+By + +[^32]: https://projects.spring.io/spring-statemachine/ + +[^33]: https://www.tigeranalytics.com/blog/apache-kylin-architecture/ + +[^34]: https://apacheignite.readme.io/docs/cluster-discovery + +[^35]: http://atlas.apache.org/HighAvailability.html + +[^36]: http://griffin.apache.org/docs/usecases.html + +[^37]: https://fluo.apache.org/ + +[^38]: https://spring.io/projects/spring-cloud-zookeeper diff --git a/zookeeper-docs/src/main/resources/markdown/zookeeperOver.md b/zookeeper-website/app/pages/_docs/docs/_mdx/index.mdx similarity index 73% rename from zookeeper-docs/src/main/resources/markdown/zookeeperOver.md rename to zookeeper-website/app/pages/_docs/docs/_mdx/index.mdx index 4c60a3de7e2..c93554daa99 100644 --- a/zookeeper-docs/src/main/resources/markdown/zookeeperOver.md +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/index.mdx @@ -1,35 +1,10 @@ - - -# ZooKeeper - -* [ZooKeeper: A Distributed Coordination Service for Distributed Applications](#ch_DesignOverview) - * [Design Goals](#sc_designGoals) - * [Data model and the hierarchical namespace](#sc_dataModelNameSpace) - * [Nodes and ephemeral nodes](#Nodes+and+ephemeral+nodes) - * [Conditional updates and watches](#Conditional+updates+and+watches) - * [Guarantees](#Guarantees) - * [Simple API](#Simple+API) - * [Implementation](#Implementation) - * [Uses](#Uses) - * [Performance](#Performance) - * [Reliability](#Reliability) - * [The ZooKeeper Project](#The+ZooKeeper+Project) - - +--- +title: "Overview" +description: "Official Apache ZooKeeper documentation covering installation, configuration, the data model, client APIs, administration, and operations." +--- + +export const pageTitle = `${__CURRENT_VERSION__} Overview`; +export const pageDescription = `Official Apache ZooKeeper ${__CURRENT_VERSION__} documentation covering installation, configuration, the data model, client APIs, administration, and operations.`; ## ZooKeeper: A Distributed Coordination Service for Distributed Applications @@ -46,8 +21,6 @@ especially prone to errors such as race conditions and deadlock. The motivation behind ZooKeeper is to relieve distributed applications the responsibility of implementing coordination services from scratch. - - ### Design Goals **ZooKeeper is simple.** ZooKeeper @@ -70,7 +43,7 @@ be implemented at the client. distributed processes it coordinates, ZooKeeper itself is intended to be replicated over a set of hosts called an ensemble. -![ZooKeeper Service](images/zkservice.jpg) +![ZooKeeper Service](/docs-images/zkservice.jpg) The servers that make up the ZooKeeper service must all know about each other. They maintain an in-memory image of state, along with a @@ -94,8 +67,6 @@ especially fast in "read-dominant" workloads. ZooKeeper applications run on thousands of machines, and it performs best where reads are more common than writes, at ratios of around 10:1. - - ### Data model and the hierarchical namespace The namespace provided by ZooKeeper is much like that of a @@ -105,9 +76,7 @@ path. #### ZooKeeper's Hierarchical Namespace -![ZooKeeper's Hierarchical Namespace](images/zknamespace.jpg) - - +![ZooKeeper's Hierarchical Namespace](/docs-images/zknamespace.jpg) ### Nodes and ephemeral nodes @@ -135,8 +104,6 @@ ZooKeeper also has the notion of ephemeral nodes. These znodes exists as long as the session that created the znode is active. When the session ends the znode is deleted. - - ### Conditional updates and watches ZooKeeper supports the concept of _watches_. @@ -150,8 +117,6 @@ broken, the client will receive a local notification. permanent, recursive watches on a znode that are not removed when triggered and that trigger for changes on the registered znode as well as any children znodes recursively. - - ### Guarantees @@ -159,61 +124,42 @@ ZooKeeper is very fast and very simple. Since its goal, though, is to be a basis for the construction of more complicated services, such as synchronization, it provides a set of guarantees. These are: -* Sequential Consistency - Updates from a client will be applied +- Sequential Consistency - Updates from a client will be applied in the order that they were sent. -* Atomicity - Updates either succeed or fail. No partial +- Atomicity - Updates either succeed or fail. No partial results. -* Single System Image - A client will see the same view of the +- Single System Image - A client will see the same view of the service regardless of the server that it connects to. i.e., a client will never see an older view of the system even if the client fails over to a different server with the same session. -* Reliability - Once an update has been applied, it will persist +- Reliability - Once an update has been applied, it will persist from that time forward until a client overwrites the update. -* Timeliness - The clients view of the system is guaranteed to +- Timeliness - The clients view of the system is guaranteed to be up-to-date within a certain time bound. - - ### Simple API One of the design goals of ZooKeeper is providing a very simple programming interface. As a result, it supports only these operations: -* *create* : - creates a node at a location in the tree - -* *delete* : - deletes a node - -* *exists* : - tests if a node exists at a location - -* *get data* : - reads the data from a node - -* *set data* : - writes data to a node - -* *get children* : - retrieves a list of children of a node - -* *sync* : - waits for data to be propagated - - +- _create_ : creates a node at a location in the tree +- _delete_ : deletes a node +- _exists_ : tests if a node exists at a location +- _get data_ : reads the data from a node +- _set data_ : writes data to a node +- _get children_ : retrieves a list of children of a node +- _sync_ : waits for data to be propagated ### Implementation -[ZooKeeper Components](#zkComponents) shows the high-level components +ZooKeeper Components shows the high-level components of the ZooKeeper service. With the exception of the request processor, each of the servers that make up the ZooKeeper service replicates its own copy of each of the components. - - -![ZooKeeper Components](images/zkcomponents.jpg) +![ZooKeeper Components](/docs-images/zkcomponents.jpg) The replicated database is an in-memory database containing the entire data tree. Updates are logged to disk for recoverability, and @@ -241,46 +187,42 @@ calculates what the state of the system is when the write is to be applied and transforms this into a transaction that captures this new state. - - ### Uses The programming interface to ZooKeeper is deliberately simple. With it, however, you can implement higher order operations, such as synchronizations primitives, group membership, ownership, etc. - - ### Performance ZooKeeper is designed to be highly performance. But is it? The results of the ZooKeeper's development team at Yahoo! Research indicate -that it is. (See [ZooKeeper Throughput as the Read-Write Ratio Varies](#zkPerfRW).) It is especially high +that it is. It is especially high performance in applications where reads outnumber writes, since writes involve synchronizing the state of all servers. (Reads outnumbering writes is typically the case for a coordination service.) - - -![ZooKeeper Throughput as the Read-Write Ratio Varies](images/zkperfRW-3.2.jpg) +![ZooKeeper Throughput as the Read-Write Ratio Varies](/docs-images/zkperfRW-3.2.jpg) -The [ZooKeeper Throughput as the Read-Write Ratio Varies](#zkPerfRW) is a throughput +The "ZooKeeper Throughput as the Read-Write Ratio Varies" is a throughput graph of ZooKeeper release 3.2 running on servers with dual 2Ghz -Xeon and two SATA 15K RPM drives. One drive was used as a +Xeon and two SATA 15K RPM drives. One drive was used as a dedicated ZooKeeper log device. The snapshots were written to the OS drive. Write requests were 1K writes and the reads were -1K reads. "Servers" indicate the size of the ZooKeeper +1K reads. "Servers" indicate the size of the ZooKeeper ensemble, the number of servers that make up the service. Approximately 30 other servers were used to simulate the clients. The ZooKeeper ensemble was configured such that leaders do not allow connections from clients. -######Note ->In version 3.2 r/w performance improved by ~2x compared to - the [previous 3.1 release](http://zookeeper.apache.org/docs/r3.1.1/zookeeperOver.html#Performance). + + In version 3.2 r/w performance improved by ~2x compared to + + +the [previous 3.1 release](http://zookeeper.apache.org/docs/r3.1.1/zookeeperOver.html#Performance). Benchmarks also indicate that it is reliable, too. -[Reliability in the Presence of Errors](#zkPerfReliability) shows how a deployment responds to +[Reliability in the Presence of Errors](#reliability) shows how a deployment responds to various failures. The events marked in the figure are the following: 1. Failure and recovery of a follower @@ -289,8 +231,6 @@ various failures. The events marked in the figure are the following: 1. Failure and recovery of two followers 1. Failure of another leader - - ### Reliability To show the behavior of the system over time as @@ -300,9 +240,7 @@ but this time we kept the write percentage at a constant 30%, which is a conservative ratio of our expected workloads. - - -![Reliability in the Presence of Errors](images/zkperfreliability.jpg) +![Reliability in the Presence of Errors](/docs-images/zkperfreliability.jpg) There are a few important observations from this graph. First, if followers fail and recover quickly, then ZooKeeper is able to sustain a @@ -313,24 +251,20 @@ ZooKeeper takes less than 200ms to elect a new leader. Third, as followers recover, ZooKeeper is able to raise throughput again once they start processing requests. - - ### The ZooKeeper Project ZooKeeper has been [successfully used](https://cwiki.apache.org/confluence/display/ZOOKEEPER/PoweredBy) -in many industrial applications. It is used at Yahoo! as the +in many industrial applications. It is used at Yahoo! as the coordination and failure recovery service for Yahoo! Message Broker, which is a highly scalable publish-subscribe system managing thousands of topics for replication and data -delivery. It is used by the Fetching Service for Yahoo! +delivery. It is used by the Fetching Service for Yahoo! crawler, where it also manages failure recovery. A number of Yahoo! advertising systems also use ZooKeeper to implement reliable services. All users and developers are encouraged to join the community and contribute their expertise. See the -[Zookeeper Project on Apache](http://zookeeper.apache.org/) +[Zookeeper Project on Apache](/) for more information. - - diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/meta.json new file mode 100644 index 00000000000..21c73ca5038 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/meta.json @@ -0,0 +1,17 @@ +{ + "title": "Multi-Page Documentation", + "description": "Apache ZooKeeper multi-page reference", + "root": true, + "pages": [ + "---Getting Started---", + "index", + "...overview", + "---Developer---", + "programmers-guide", + "...developer", + "---Admin & Ops---", + "...admin-ops", + "---Miscellaneous---", + "...miscellaneous" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/internals.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/internals.mdx new file mode 100644 index 00000000000..4281e1ac275 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/internals.mdx @@ -0,0 +1,310 @@ +--- +title: "Internals" +description: "This document covers the inner workings of ZooKeeper, including the atomic broadcast protocol, consistency guarantees, quorum design, and logging conventions." +--- + +## Atomic Broadcast + +At the heart of ZooKeeper is an atomic messaging system that keeps all of the servers in sync. + +### Guarantees, Properties, and Definitions + +The specific guarantees provided by the ZooKeeper messaging system are: + +- **Reliable delivery:** If a message `m` is delivered by one server, message `m` will eventually be delivered by all servers. +- **Total order:** If a message `a` is delivered before message `b` by one server, message `a` will be delivered before `b` by all servers. +- **Causal order:** If a message `b` is sent after a message `a` has been delivered by the sender of `b`, message `a` must be ordered before `b`. If a sender sends `c` after sending `b`, `c` must be ordered after `b`. + +The ZooKeeper messaging system also needs to be efficient, reliable, and easy to +implement and maintain. We make heavy use of messaging, so we need the system to +be able to handle thousands of requests per second. Although we can require at +least k+1 correct servers to send new messages, we must be able to recover from +correlated failures such as power outages. When we implemented the system we had +little time and few engineering resources, so we needed a protocol that is +accessible to engineers and is easy to implement. We found that our protocol +satisfied all of these goals. + +Our protocol assumes that we can construct point-to-point FIFO channels between +the servers. While similar services usually assume message delivery that can +lose or reorder messages, our assumption of FIFO channels is very practical +given that we use TCP for communication. Specifically we rely on the following property of TCP: + +- **Ordered delivery:** Data is delivered in the same order it is sent and a message `m` is delivered only after all messages sent before `m` have been delivered. (The corollary is that if message `m` is lost, all messages after `m` will also be lost.) +- **No message after close:** Once a FIFO channel is closed, no messages will be received from it. + +FLP proved that consensus cannot be achieved in asynchronous distributed systems +if failures are possible. To ensure that we achieve consensus in the presence of failures +we use timeouts. However, we rely on time for liveness, not for correctness. So, +if timeouts stop working (e.g., skewed clocks) the messaging system may +hang, but it will not violate its guarantees. + +When describing the ZooKeeper messaging protocol we will talk of packets, +proposals, and messages: + +- **Packet:** A sequence of bytes sent through a FIFO channel. +- **Proposal:** A unit of agreement. Proposals are agreed upon by exchanging packets with a quorum of ZooKeeper servers. Most proposals contain messages; however, the NEW_LEADER proposal is an example of a proposal that does not contain a message. +- **Message:** A sequence of bytes to be atomically broadcast to all ZooKeeper servers. A message is put into a proposal and agreed upon before it is delivered. + +As stated above, ZooKeeper guarantees a total order of messages, and it also +guarantees a total order of proposals. ZooKeeper exposes the total ordering using +a ZooKeeper transaction id (_zxid_). All proposals will be stamped with a zxid when +proposed and exactly reflect the total ordering. Proposals are sent to all +ZooKeeper servers and committed when a quorum of them acknowledge the proposal. +If a proposal contains a message, the message will be delivered when the proposal +is committed. Acknowledgement means the server has recorded the proposal to persistent storage. +Our quorums have the requirement that any pair of quorums must have at least one server +in common. We ensure this by requiring that all quorums have size (_n/2+1_) where +n is the number of servers that make up a ZooKeeper service. + +The zxid has two parts: the epoch and a counter. In our implementation the zxid +is a 64-bit number. We use the high order 32-bits for the epoch and the low order +32-bits for the counter. Because a zxid consists of two parts, it can be represented both as a +number and as a pair of integers, (_epoch, count_). The epoch number represents a +change in leadership. Each time a new leader comes into power it will have its +own epoch number. We have a simple algorithm to assign a unique zxid to a proposal: +the leader simply increments the zxid to obtain a unique zxid for each proposal. +_Leadership activation will ensure that only one leader uses a given epoch, so our +simple algorithm guarantees that every proposal will have a unique id._ + +ZooKeeper messaging consists of two phases: + +- **Leader activation:** In this phase a leader establishes the correct state of the system and gets ready to start making proposals. +- **Active messaging:** In this phase a leader accepts messages to propose and coordinates message delivery. + +ZooKeeper is a holistic protocol. We do not focus on individual proposals, rather +we look at the stream of proposals as a whole. Our strict ordering allows us to do this +efficiently and greatly simplifies our protocol. Leadership activation embodies +this holistic concept. A leader becomes active only when a quorum of followers +(the leader counts as a follower as well — you can always vote for yourself) has synced +up with the leader: they have the same state. This state consists of all of the +proposals that the leader believes have been committed and the proposal to follow +the leader, the `NEW_LEADER` proposal. (Hopefully you are thinking: +_Does the set of proposals that the leader believes has been committed +include all the proposals that really have been committed?_ The answer is _yes_. +Below, we make clear why.) + +### Leader Activation + +Leader activation includes leader election (`FastLeaderElection`). +ZooKeeper messaging doesn't care about the exact method of electing a leader as long as the following holds: + +- The leader has seen the highest zxid of all the followers. +- A quorum of servers have committed to following the leader. + +Of these two requirements, only the first — the highest zxid among the followers — +needs to hold for correct operation. The second requirement, a quorum of followers, +just needs to hold with high probability. We are going to recheck the second requirement, +so if a failure happens during or after the leader election and quorum is lost, +we will recover by abandoning leader activation and running another election. + +After leader election a single server will be designated as a leader and start +waiting for followers to connect. The rest of the servers will try to connect to +the leader. The leader will sync up with the followers by sending any proposals they +are missing, or if a follower is missing too many proposals, it will send a full +snapshot of the state to the follower. + +There is a corner case in which a follower that has proposals, `U`, not seen +by a leader arrives. Proposals are seen in order, so the proposals of `U` will have zxids +higher than zxids seen by the leader. The follower must have arrived after the +leader election, otherwise the follower would have been elected leader given that +it has seen a higher zxid. Since committed proposals must be seen by a quorum of +servers, and a quorum of servers that elected the leader did not see `U`, the proposals +of `U` have not been committed, so they can be discarded. When the follower connects +to the leader, the leader will tell the follower to discard `U`. + +A new leader establishes a zxid to start using for new proposals by getting the +epoch, `e`, of the highest zxid it has seen and setting the next zxid to use to be +`(e+1, 0)`. After the leader syncs with a follower, it will propose a NEW_LEADER +proposal. Once the NEW_LEADER proposal has been committed, the leader will activate +and start receiving and issuing proposals. + +The basic rules of operation during leader activation are: + +- A follower will ACK the NEW_LEADER proposal after it has synced with the leader. +- A follower will only ACK a NEW_LEADER proposal with a given zxid from a single server. +- A new leader will COMMIT the NEW_LEADER proposal when a quorum of followers has ACKed it. +- A follower will commit any state it received from the leader when the NEW_LEADER proposal is COMMITted. +- A new leader will not accept new proposals until the NEW_LEADER proposal has been COMMITted. + +If leader election terminates erroneously, we don't have a problem since the +NEW_LEADER proposal will not be committed because the leader will not have quorum. +When this happens, the leader and any remaining followers will timeout and go back +to leader election. + +### Active Messaging + +Leader Activation does all the heavy lifting. Once the leader is coronated it can +start blasting out proposals. As long as it remains the leader no other leader can +emerge since no other leader will be able to get a quorum of followers. If a new +leader does emerge, it means that the current leader has lost quorum, and the new +leader will clean up any mess left over during its activation. + +ZooKeeper messaging operates similar to a classic two-phase commit. + +![Two phase commit](/docs-images/2pc.jpg) + +All communication channels are FIFO, so everything is done in order. Specifically +the following operating constraints are observed: + +- The leader sends proposals to all followers using the same order. Moreover, this order follows the order in which requests were received. Because we use FIFO channels this means that followers also receive proposals in order. +- Followers process messages in the order they are received. This means that messages will be ACKed in order and the leader will receive ACKs from followers in order, due to the FIFO channels. It also means that if message `m` has been written to non-volatile storage, all messages that were proposed before `m` have been written to non-volatile storage. +- The leader will issue a COMMIT to all followers as soon as a quorum of followers have ACKed a message. Since messages are ACKed in order, COMMITs will be sent by the leader and received by the followers in order. +- COMMITs are processed in order. Followers deliver a proposal message when that proposal is committed. + +### Summary + +Why does it work? Specifically, why does a set of proposals believed by a new leader +always contain any proposal that has actually been committed? First, all proposals have +a unique zxid, so unlike other protocols, we never have to worry about two different +values being proposed for the same zxid; followers (a leader is also a follower) see +and record proposals in order; proposals are committed in order; there is only one active +leader at a time since followers only follow a single leader at a time; a new leader has +seen all committed proposals from the previous epoch since it has seen the highest zxid +from a quorum of servers; any uncommitted proposals from a previous epoch seen by a new +leader will be committed by that leader before it becomes active. + +### Comparisons + +**Isn't this just Multi-Paxos?** No. Multi-Paxos requires some way of assuring that +there is only a single coordinator. We do not count on such assurances. Instead +we use leader activation to recover from leadership changes or old leaders +believing they are still active. + +**Isn't this just Paxos? The active messaging phase looks just like phase 2 of Paxos.** +Actually, to us active messaging looks just like 2-phase commit without the need to +handle aborts. Active messaging is different from both in the sense that it has +cross-proposal ordering requirements. If we do not maintain strict FIFO ordering of +all packets, it all falls apart. Also, our leader activation phase is different from +both of them. In particular, our use of epochs allows us to skip blocks of uncommitted +proposals and to not worry about duplicate proposals for a given zxid. + +## Consistency Guarantees + +The [consistency](https://jepsen.io/consistency) guarantees of ZooKeeper lie between +sequential consistency and linearizability. + +Write operations in ZooKeeper are _linearizable_. Each `write` will appear to take effect +atomically at some point between when the client issues the request and receives the +corresponding response. This means that the writes performed by all clients can be totally +ordered in a way that respects their real-time ordering. However, merely stating that writes +are linearizable is meaningless unless we also talk about reads. + +Read operations in ZooKeeper are _not linearizable_ since they can return stale data. A `read` +in ZooKeeper is not a quorum operation — a server will respond immediately to a client +performing a `read`. ZooKeeper prioritizes performance over consistency for reads. However, +reads are _sequentially consistent_, because `read` operations appear to take effect in some +sequential order that respects each client's operation order. A common workaround is to issue +a `sync` before a `read`. This too does **not** strictly guarantee up-to-date data because +`sync` is [not currently a quorum operation](https://issues.apache.org/jira/browse/ZOOKEEPER-1675). + +To illustrate: consider a scenario where two servers simultaneously think they are the leader, +which could occur if the TCP connection timeout is smaller than `syncLimit * tickTime`. Note +that this is [unlikely](https://www.amazon.com/ZooKeeper-Distributed-Coordination-Flavio-Junqueira/dp/1449361307) +to occur in practice, but is worth keeping in mind. Under this scenario, the `sync` may be +served by the "leader" with stale data, allowing the following `read` to be stale as well. +The stronger guarantee of linearizability is provided if an actual quorum operation (e.g., a +`write`) is performed before a `read`. + +Overall, the consistency guarantees of ZooKeeper are formally captured by the notion of +[ordered sequential consistency](http://webee.technion.ac.il/people/idish/ftp/OSC-IPL17.pdf) +(`OSC(U)`), which lies between sequential consistency and linearizability. + +## Quorums + +Atomic broadcast and leader election use the notion of quorums to guarantee a consistent +view of the system. By default, ZooKeeper uses majority quorums, which means that every +voting operation requires a majority to vote. One example is acknowledging a leader proposal: +the leader can only commit once it receives an acknowledgement from a quorum of servers. + +If we extract the properties that we really need from our use of majorities, we have that we only +need to guarantee that groups of processes used to validate an operation by voting pairwise +intersect in at least one server. Using majorities guarantees such a property. +However, there are other ways of constructing quorums. For example, we can assign +weights to the votes of servers, and say that the votes of some servers are more important. +To obtain a quorum, we get enough votes so that the sum of weights of all votes is larger +than half of the total sum of all weights. + +A different construction that uses weights and is useful in wide-area deployments is a +hierarchical one. With this construction, we split the servers into disjoint groups and +assign weights to processes. To form a quorum, we have to get enough servers from a majority +of groups G, such that for each group g in G, the sum of votes from g is larger than half of +the sum of weights in g. Interestingly, this construction enables smaller quorums. If we have +9 servers split into 3 groups with a weight of 1 each, we are able to form quorums of size 4. +Note that two subsets of processes each composed of a majority of servers from a majority of +groups necessarily have a non-empty intersection. It is reasonable to expect that a majority +of co-locations will have a majority of servers available with high probability. + +ZooKeeper provides users with the ability to configure servers to use majority quorums, +weighted quorums, or a hierarchy of groups. + +## Logging + +ZooKeeper uses [slf4j](http://www.slf4j.org/index.html) as an abstraction layer for logging. +[Logback](https://logback.qos.ch/) has been chosen as the logging backend since ZooKeeper 3.8.0. +For better embedding support, it is planned in the future to leave the choice of logging +implementation to the end user. Therefore, always use the slf4j API for log statements in code, +but configure Logback for runtime logging behavior. +Note that slf4j has no FATAL level; former FATAL-level messages have been moved to ERROR. +For information on configuring Logback for ZooKeeper, see the +[Logging](/docs/admin-ops/administrators-guide/administration#logging) section of the +[ZooKeeper Administrator's Guide](/docs/admin-ops/administrators-guide). + +### Developer Guidelines + +Follow the [slf4j manual](http://www.slf4j.org/manual.html) when creating log statements in +code. Also read the [FAQ on logging performance](http://www.slf4j.org/faq.html#logging_performance). +Patch reviewers will look for the following: + +#### Logging at the Right Level + +There are several log levels in slf4j, in order of decreasing severity: + +1. **ERROR** — error events that might still allow the application to continue running. +1. **WARN** — potentially harmful situations. +1. **INFO** — informational messages that highlight the progress of the application at a coarse-grained level. +1. **DEBUG** — fine-grained informational events most useful for debugging. +1. **TRACE** — finer-grained informational events than DEBUG. + +ZooKeeper is typically run in production such that INFO and above are output to the log. + +#### Use of Standard slf4j Idioms + +**Static message logging:** + +```java +LOG.debug("process completed successfully!"); +``` + +For parameterized messages, use formatting anchors: + +```java +LOG.debug("got {} messages in {} minutes", new Object[]{count, time}); +``` + +**Naming:** Loggers should be named after the class in which they are used. + +```java +public class Foo { + private static final Logger LOG = LoggerFactory.getLogger(Foo.class); + + public Foo() { + LOG.info("constructing Foo"); + } +} +``` + +**Exception handling:** + +```java +try { + // code +} catch (XYZException e) { + // do this + LOG.error("Something bad happened", e); + // don't do this (generally): + // LOG.error(e); + // the above hides the stack trace + + // continue, recover, or rethrow as appropriate +} +``` diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/meta.json new file mode 100644 index 00000000000..af488677858 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/miscellaneous/meta.json @@ -0,0 +1,10 @@ +{ + "title": "Miscellaneous", + "pages": [ + "internals", + "[Mailing Lists](/mailing-lists)", + "external:[Wiki](https://cwiki.apache.org/confluence/display/ZOOKEEPER)", + "external:[FAQ](https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ)", + "external:[All docs for LLMs](/llms-full.txt)" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/overview/meta.json b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/meta.json new file mode 100644 index 00000000000..fab24c1cab3 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/meta.json @@ -0,0 +1,8 @@ +{ + "title": "Overview", + "pages": [ + "overview", + "quick-start", + "release-notes" + ] +} diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/overview/quick-start.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/quick-start.mdx new file mode 100644 index 00000000000..3bc41c97342 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/quick-start.mdx @@ -0,0 +1,338 @@ +--- +title: "Quick Start" +description: "This document contains information to get you started quickly with ZooKeeper." +--- + +## Coordinating Distributed Applications with ZooKeeper + +The document is aimed primarily at developers hoping to try it out, and +contains simple installation instructions for a single ZooKeeper server, a +few commands to verify that it is running, and a simple programming +example. Finally, as a convenience, there are a few sections regarding +more complicated installations, for example running replicated +deployments, and optimizing the transaction log. However for the complete +instructions for commercial deployments, please refer to the [ZooKeeper +Administrator's Guide](/docs/admin-ops/administrators-guide). + +### Pre-requisites + +See [System Requirements](/docs/admin-ops/administrators-guide/deployment#system-requirements) in the Admin guide. + +### Download + +To get a ZooKeeper distribution, download a recent +[stable](/releases) release from one of the Apache Download +Mirrors. + +### Standalone Operation + +Setting up a ZooKeeper server in standalone mode is +straightforward. The server is contained in a single JAR file, +so installation consists of creating a configuration. + +Once you've downloaded a stable ZooKeeper release unpack +it and cd to the root + +To start ZooKeeper you need a configuration file. Here is a sample, +create it in **conf/zoo.cfg**: + +``` +tickTime=2000 +dataDir=/var/lib/zookeeper +clientPort=2181 +``` + +This file can be called anything, but for the sake of this +discussion call +it **conf/zoo.cfg**. Change the +value of **dataDir** to specify an +existing (empty to start with) directory. Here are the meanings +for each of the fields: + +- **_tickTime_** : + the basic time unit in milliseconds used by ZooKeeper. It is + used to do heartbeats and the minimum session timeout will be + twice the tickTime. +- **_dataDir_** : + the location to store the in-memory database snapshots and, + unless specified otherwise, the transaction log of updates to the + database. +- **_clientPort_** : + the port to listen for client connections + +Now that you created the configuration file, you can start +ZooKeeper: + +```bash +bin/zkServer.sh start +``` + +ZooKeeper logs messages using _logback_ — more detail +available in the +[Logging](/docs/admin-ops/administrators-guide/administration#logging) +section of the Administrator's Guide. You will see log messages +coming to the console (default) and/or a log file depending on +the logback configuration. + +The steps outlined here run ZooKeeper in standalone mode. There is +no replication, so if ZooKeeper process fails, the service will go down. +This is fine for most development situations, but to run ZooKeeper in +replicated mode, please see [Running Replicated +ZooKeeper](#running-replicated-zookeeper). + +### Managing ZooKeeper Storage + +For long running production systems ZooKeeper storage must +be managed externally (dataDir and logs). See the section on +[maintenance](/docs/admin-ops/administrators-guide/administration#maintenance) for +more details. + +### Connecting to ZooKeeper + + + + Start `zkCli.sh` and connect to your ZooKeeper server. `bin/zkCli.sh -server + 127.0.0.1:2181` + + Run `help` to list commands and verify client connectivity. + + Create, inspect, update, and delete a test znode to validate end-to-end + operation. + + + +This lets you perform simple, file-like operations. + +Once you have connected, you should see something like: + +``` +Connecting to localhost:2181 +... +Welcome to ZooKeeper! +JLine support is enabled +[zkshell: 0] +``` + +From the shell, type `help` to get a listing of commands that can be executed from the client, as in: + +``` +[zkshell: 0] help +ZooKeeper -server host:port cmd args +addauth scheme auth +close +config [-c] [-w] [-s] +connect host:port +create [-s] [-e] [-c] [-t ttl] path [data] [acl] +delete [-v version] path +deleteall path +delquota [-n|-b] path +get [-s] [-w] path +getAcl [-s] path +getAllChildrenNumber path +getEphemerals path +history +listquota path +ls [-s] [-w] [-R] path +printwatches on|off +quit +reconfig [-s] [-v version] [[-file path] | [-members serverID=host:port1:port2;port3[,...]*]] | [-add serverId=host:port1:port2;port3[,...]]* [-remove serverId[,...]*] +redo cmdno +removewatches path [-c|-d|-a] [-l] +set [-s] [-v version] path data +setAcl [-s] [-v version] [-R] path acl +setquota -n|-b val path +stat [-w] path +sync path +``` + +From here, you can try a few simple commands to get a feel for this simple command line interface. First, start by issuing the list command, as +in `ls`, yielding: + +``` +[zkshell: 8] ls / +[zookeeper] +``` + +Next, create a new znode by running `create /zk_test my_data`. This creates a new znode and associates the string "my_data" with the node. +You should see: + +``` +[zkshell: 9] create /zk_test my_data +Created /zk_test +``` + +Issue another `ls /` command to see what the directory looks like: + +``` +[zkshell: 11] ls / +[zookeeper, zk_test] +``` + +Notice that the zk_test directory has now been created. + +Next, verify that the data was associated with the znode by running the `get` command, as in: + +``` +[zkshell: 12] get /zk_test +my_data +cZxid = 5 +ctime = Fri Jun 05 13:57:06 PDT 2009 +mZxid = 5 +mtime = Fri Jun 05 13:57:06 PDT 2009 +pZxid = 5 +cversion = 0 +dataVersion = 0 +aclVersion = 0 +ephemeralOwner = 0 +dataLength = 7 +numChildren = 0 +``` + +We can change the data associated with zk_test by issuing the `set` command, as in: + +``` +[zkshell: 14] set /zk_test junk +cZxid = 5 +ctime = Fri Jun 05 13:57:06 PDT 2009 +mZxid = 6 +mtime = Fri Jun 05 14:01:52 PDT 2009 +pZxid = 5 +cversion = 0 +dataVersion = 1 +aclVersion = 0 +ephemeralOwner = 0 +dataLength = 4 +numChildren = 0 +[zkshell: 15] get /zk_test +junk +cZxid = 5 +ctime = Fri Jun 05 13:57:06 PDT 2009 +mZxid = 6 +mtime = Fri Jun 05 14:01:52 PDT 2009 +pZxid = 5 +cversion = 0 +dataVersion = 1 +aclVersion = 0 +ephemeralOwner = 0 +dataLength = 4 +numChildren = 0 +``` + +(Notice we did a `get` after setting the data and it did, indeed, change. + +Finally, let's `delete` the node by issuing: + +``` +[zkshell: 16] delete /zk_test +[zkshell: 17] ls / +[zookeeper] +[zkshell: 18] +``` + +That's it for now. To explore more, see the [Zookeeper CLI](/docs/admin-ops/cli). + +### Programming to ZooKeeper + +ZooKeeper has a Java bindings and C bindings. They are +functionally equivalent. The C bindings exist in two variants: single +threaded and multi-threaded. These differ only in how the messaging loop +is done. For more information, see the [Programming +Examples in the ZooKeeper Programmer's Guide](/docs/developer/java-example#program-design) for +sample code using the different APIs. + +### Running Replicated ZooKeeper + +Running ZooKeeper in standalone mode is convenient for evaluation, +some development, and testing. But in production, you should run +ZooKeeper in replicated mode. A replicated group of servers in the same +application is called a _quorum_, and in replicated +mode, all servers in the quorum have copies of the same configuration +file. + + + For replicated mode, a minimum of three servers are required, + + +and it is strongly recommended that you have an odd number of +servers. If you only have two servers, then you are in a +situation where if one of them fails, there are not enough +machines to form a majority quorum. Two servers are inherently +**less** stable than a single server, because there are two single +points of failure. + +The required +**conf/zoo.cfg** +file for replicated mode is similar to the one used in standalone +mode, but with a few differences. Here is an example: + +``` +tickTime=2000 +dataDir=/var/lib/zookeeper +clientPort=2181 +initLimit=5 +syncLimit=2 +server.1=zoo1:2888:3888 +server.2=zoo2:2888:3888 +server.3=zoo3:2888:3888 +``` + +The new entry, **initLimit** is +timeouts ZooKeeper uses to limit the length of time the ZooKeeper +servers in quorum have to connect to a leader. The entry **syncLimit** limits how far out of date a server can +be from a leader. + +With both of these timeouts, you specify the unit of time using +**tickTime**. In this example, the timeout +for initLimit is 5 ticks at 2000 milliseconds a tick, or 10 +seconds. + +The entries of the form _server.X_ list the +servers that make up the ZooKeeper service. When the server starts up, +it knows which server it is by looking for the file +_myid_ in the data directory. That file has the +contains the server number, in ASCII. + +Finally, note the two port numbers after each server +name: " 2888" and "3888". Peers use the former port to connect +to other peers. Such a connection is necessary so that peers +can communicate, for example, to agree upon the order of +updates. More specifically, a ZooKeeper server uses this port +to connect followers to the leader. When a new leader arises, a +follower opens a TCP connection to the leader using this +port. Because the default leader election also uses TCP, we +currently require another port for leader election. This is the +second port in the server entry. + + + If you want to test multiple servers on a single machine, specify the + servername as _localhost_ with unique quorum & leader election ports (i.e. + 2888:3888, 2889:3889, 2890:3890 in the example above) for each server.X in + that server's config file. Of course separate _dataDir_s and distinct + _clientPort_s are also necessary (in the above replicated example, running on + a single _localhost_, you would still have three config files). + + +> Please be aware that setting up multiple servers on a single +> machine will not create any redundancy. If something were to +> happen which caused the machine to die, all of the zookeeper +> servers would be offline. Full redundancy requires that each +> server have its own machine. It must be a completely separate +> physical server. Multiple virtual machines on the same physical +> host are still vulnerable to the complete failure of that host. + +> If you have multiple network interfaces in your ZooKeeper machines, +> you can also instruct ZooKeeper to bind on all of your interfaces and +> automatically switch to a healthy interface in case of a network failure. +> For details, see the [Configuration Parameters](/docs/admin-ops/administrators-guide/configuration-parameters#cluster-options). + +### Other Optimizations + +There are a couple of other configuration parameters that can +greatly increase performance: + +- To get low latencies on updates it is important to + have a dedicated transaction log directory. By default + transaction logs are put in the same directory as the data + snapshots and _myid_ file. The dataLogDir + parameters indicates a different directory to use for the + transaction logs. diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/overview/release-notes.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/release-notes.mdx new file mode 100644 index 00000000000..c6e0932fcf2 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/overview/release-notes.mdx @@ -0,0 +1,289 @@ +--- +title: "Release Notes" +description: "Release notes for ZooKeeper 3.9.x, including new features, bug fixes, improvements, and breaking changes." +--- + +# Release Notes - ZooKeeper - Version 3.9.5 + +## Sub-task + +- [ZOOKEEPER-842](https://issues.apache.org/jira/browse/ZOOKEEPER-842) - stat calls static method on org.apache.zookeeper.server.DataTree + +## Bug + +- [ZOOKEEPER-4736](https://issues.apache.org/jira/browse/ZOOKEEPER-4736) - socket fd leak +- [ZOOKEEPER-4871](https://issues.apache.org/jira/browse/ZOOKEEPER-4871) - ZooKeeper python module (zkpython) is incompatible with Python 3.12 +- [ZOOKEEPER-4958](https://issues.apache.org/jira/browse/ZOOKEEPER-4958) - "ssl.clientHostnameVerification" is ignored if "ssl.authProvider" is configured to "x509" +- [ZOOKEEPER-4974](https://issues.apache.org/jira/browse/ZOOKEEPER-4974) - Remove enforced JDK 17 compilation warnings +- [ZOOKEEPER-4984](https://issues.apache.org/jira/browse/ZOOKEEPER-4984) - Upgrade OWASP plugin to 12.1.6 due to breaking changes in the API +- [ZOOKEEPER-4986](https://issues.apache.org/jira/browse/ZOOKEEPER-4986) - Disable reverse DNS lookup in TLS client and server +- [ZOOKEEPER-4989](https://issues.apache.org/jira/browse/ZOOKEEPER-4989) - Compilation of client on Windows with MSVC is broken + +## Improvement + +- [ZOOKEEPER-3938](https://issues.apache.org/jira/browse/ZOOKEEPER-3938) - Upgrade jline to version 3.x. +- [ZOOKEEPER-4955](https://issues.apache.org/jira/browse/ZOOKEEPER-4955) - Fix interference with jvm ssl properties for ssl.crl and ssl.ocsp +- [ZOOKEEPER-4962](https://issues.apache.org/jira/browse/ZOOKEEPER-4962) - Add getPort and getSecurePort for ZooKeeperServerEmbedded +- [ZOOKEEPER-4965](https://issues.apache.org/jira/browse/ZOOKEEPER-4965) - Drop unnecessary `@SuppressWarnings("deprecation")` +- [ZOOKEEPER-4970](https://issues.apache.org/jira/browse/ZOOKEEPER-4970) - Deprecate methods of ZKConfig which throw QuorumPeerConfig.ConfigException + +## Test + +- [ZOOKEEPER-4780](https://issues.apache.org/jira/browse/ZOOKEEPER-4780) - Avoid creating temporary files in source directory. + +## Task + +- [ZOOKEEPER-4976](https://issues.apache.org/jira/browse/ZOOKEEPER-4976) - Update Netty to fix CVE-2025-58057 +- [ZOOKEEPER-5017](https://issues.apache.org/jira/browse/ZOOKEEPER-5017) - Upgrade Netty to 4.1.130.Final to address CVE-2025-67735 +- [ZOOKEEPER-5018](https://issues.apache.org/jira/browse/ZOOKEEPER-5018) - Upgrade Jetty to 9.4.58.v20250814 in order to fix CVE-2025-5115 + +--- + +# Release Notes - ZooKeeper - Version 3.9.4 + +## Breaking Changes + +[ZOOKEEPER-4891](https://issues.apache.org/jira/browse/ZOOKEEPER-4891) updates `logback-classic` to `1.3.15` to solve CVE issues and `slf4j-api` to `2.0.13` to meet the compatibility requirement of logback. + +This could cause slf4j to complain "No SLF4J providers were found" and output no further logs in certain conditions: + +1. For library or client usage, this could happen if you specify and inherit incompatible slf4j and logback versions, say, `slf4j-api:2.0.13` from `org.apache.zookeeper:zookeeper` and `logback-classic:1.2.13` from customized project dependencies. +2. For application or deployment usage, this could happen if you custom and inherit incompatible slf4j and logback versions in classpath, say, `slf4j-api:2.0.13` from zookeeper distribution and `logback-classic:1.2.13` from customization. + +This can be resolved by specifying compatible slf4j and logback versions in classpath, say, `slf4j-api:2.0.13` and `logback-classic:1.3.15`. + +## Bug + +- [ZOOKEEPER-4020](https://issues.apache.org/jira/browse/ZOOKEEPER-4020) - Memory leak in Zookeeper C Client +- [ZOOKEEPER-4240](https://issues.apache.org/jira/browse/ZOOKEEPER-4240) - IPV6 support in ZooKeeper ACL +- [ZOOKEEPER-4604](https://issues.apache.org/jira/browse/ZOOKEEPER-4604) - Creating a COMPLETION_STRING_STAT would set acl_result completion +- [ZOOKEEPER-4699](https://issues.apache.org/jira/browse/ZOOKEEPER-4699) - zh->hostname heap-use-after-free in zookeeper_interest +- [ZOOKEEPER-4725](https://issues.apache.org/jira/browse/ZOOKEEPER-4725) - TTL node creations do not appear in audit log +- [ZOOKEEPER-4787](https://issues.apache.org/jira/browse/ZOOKEEPER-4787) - Failed to establish connection between zookeeper +- [ZOOKEEPER-4810](https://issues.apache.org/jira/browse/ZOOKEEPER-4810) - Fix data race in format_endpoint_info() +- [ZOOKEEPER-4819](https://issues.apache.org/jira/browse/ZOOKEEPER-4819) - Can't seek for writable tls server if connected to readonly server +- [ZOOKEEPER-4846](https://issues.apache.org/jira/browse/ZOOKEEPER-4846) - Failure to reload database due to missing ACL +- [ZOOKEEPER-4848](https://issues.apache.org/jira/browse/ZOOKEEPER-4848) - Possible stack overflow in setup_random +- [ZOOKEEPER-4858](https://issues.apache.org/jira/browse/ZOOKEEPER-4858) - Remove the lock contention between snapshotting and the sync operation +- [ZOOKEEPER-4872](https://issues.apache.org/jira/browse/ZOOKEEPER-4872) - SnapshotCommand should not perform fastForwardFromEdits +- [ZOOKEEPER-4886](https://issues.apache.org/jira/browse/ZOOKEEPER-4886) - observer with small myid can't join SASL quorum +- [ZOOKEEPER-4889](https://issues.apache.org/jira/browse/ZOOKEEPER-4889) - Fallback to DIGEST-MD5 auth mech should be disabled in Fips mode +- [ZOOKEEPER-4900](https://issues.apache.org/jira/browse/ZOOKEEPER-4900) - Bump patch release of jetty to include CVE fix for CVE-2024-6763 +- [ZOOKEEPER-4907](https://issues.apache.org/jira/browse/ZOOKEEPER-4907) - Shouldn't throw "Len error" when server closing cause confusion +- [ZOOKEEPER-4909](https://issues.apache.org/jira/browse/ZOOKEEPER-4909) - When a spurious wakeup occurs, the client's waiting time may exceed requestTimeout. +- [ZOOKEEPER-4919](https://issues.apache.org/jira/browse/ZOOKEEPER-4919) - ResponseCache supposed to be a LRU cache +- [ZOOKEEPER-4921](https://issues.apache.org/jira/browse/ZOOKEEPER-4921) - Zookeeper Client 3.9.3 Fails to Reconnect After Network Failures +- [ZOOKEEPER-4925](https://issues.apache.org/jira/browse/ZOOKEEPER-4925) - Diff sync introduce hole in stale follower's committedLog which cause data loss in leading +- [ZOOKEEPER-4928](https://issues.apache.org/jira/browse/ZOOKEEPER-4928) - Version in zookeeper_version.h is not updated +- [ZOOKEEPER-4933](https://issues.apache.org/jira/browse/ZOOKEEPER-4933) - Connection throttle exception causing all connections to be rejected +- [ZOOKEEPER-4940](https://issues.apache.org/jira/browse/ZOOKEEPER-4940) - Enabling zookeeper.ssl.ocsp with JRE TLS provider errors out +- [ZOOKEEPER-4953](https://issues.apache.org/jira/browse/ZOOKEEPER-4953) - Fixing Typo In ZooKeeper Programmer's Guide +- [ZOOKEEPER-4960](https://issues.apache.org/jira/browse/ZOOKEEPER-4960) - Upgrade OWASP plugin to 12.1.3 due to recent parsing errors + +## New Feature + +- [ZOOKEEPER-4895](https://issues.apache.org/jira/browse/ZOOKEEPER-4895) - Introduce a helper function for C client to generate password for SASL authentication + +## Improvement + +- [ZOOKEEPER-4790](https://issues.apache.org/jira/browse/ZOOKEEPER-4790) - TLS Quorum hostname verification breaks in some scenarios +- [ZOOKEEPER-4852](https://issues.apache.org/jira/browse/ZOOKEEPER-4852) - Fix the bad "\*uuuuu" mark in the ASF license +- [ZOOKEEPER-4891](https://issues.apache.org/jira/browse/ZOOKEEPER-4891) - Update logback to 1.3.15 to fix CVE-2024-12798. +- [ZOOKEEPER-4902](https://issues.apache.org/jira/browse/ZOOKEEPER-4902) - Document that read-only mode also enables isro 4lw +- [ZOOKEEPER-4906](https://issues.apache.org/jira/browse/ZOOKEEPER-4906) - Log full exception details for server JAAS config failure +- [ZOOKEEPER-4944](https://issues.apache.org/jira/browse/ZOOKEEPER-4944) - Cache zookeeper dists for end to end compatibility tests +- [ZOOKEEPER-4954](https://issues.apache.org/jira/browse/ZOOKEEPER-4954) - Use FIPS style hostname verification when no custom truststore is specified +- [ZOOKEEPER-4964](https://issues.apache.org/jira/browse/ZOOKEEPER-4964) - Check permissions individually during admin server auth + +## Task + +- [ZOOKEEPER-4897](https://issues.apache.org/jira/browse/ZOOKEEPER-4897) - Upgrade Netty to fix CVE-2025-24970 in ZooKeeper 3.9.3 +- [ZOOKEEPER-4959](https://issues.apache.org/jira/browse/ZOOKEEPER-4959) - Fix license files after logback/slf4j upgrade + +--- + +# Release Notes - ZooKeeper - Version 3.9.3 + +## Bug + +- [ZOOKEEPER-2332](https://issues.apache.org/jira/browse/ZOOKEEPER-2332) - Zookeeper failed to start for empty txn log +- [ZOOKEEPER-2623](https://issues.apache.org/jira/browse/ZOOKEEPER-2623) - CheckVersion outside of Multi causes NullPointerException +- [ZOOKEEPER-4293](https://issues.apache.org/jira/browse/ZOOKEEPER-4293) - Lock Contention in ClientCnxnSocketNetty (possible deadlock) +- [ZOOKEEPER-4394](https://issues.apache.org/jira/browse/ZOOKEEPER-4394) - Learner.syncWithLeader got NullPointerException +- [ZOOKEEPER-4409](https://issues.apache.org/jira/browse/ZOOKEEPER-4409) - NullPointerException in SendAckRequestProcessor +- [ZOOKEEPER-4508](https://issues.apache.org/jira/browse/ZOOKEEPER-4508) - ZooKeeper client run to endless loop in ClientCnxn.SendThread.run if all server down +- [ZOOKEEPER-4712](https://issues.apache.org/jira/browse/ZOOKEEPER-4712) - Follower.shutdown() and Observer.shutdown() do not correctly shutdown the syncProcessor, which may lead to data inconsistency +- [ZOOKEEPER-4733](https://issues.apache.org/jira/browse/ZOOKEEPER-4733) - non-return function error and asan error in CPPUNIT TESTs +- [ZOOKEEPER-4752](https://issues.apache.org/jira/browse/ZOOKEEPER-4752) - Remove version files in zookeeper-server/src/main from .gitignore +- [ZOOKEEPER-4804](https://issues.apache.org/jira/browse/ZOOKEEPER-4804) - Use daemon threads for Netty client +- [ZOOKEEPER-4814](https://issues.apache.org/jira/browse/ZOOKEEPER-4814) - Protocol desynchronization after Connect for (some) old clients +- [ZOOKEEPER-4839](https://issues.apache.org/jira/browse/ZOOKEEPER-4839) - When DigestMD5 is used to enable mandatory client authentication, users that do not exist can log in +- [ZOOKEEPER-4843](https://issues.apache.org/jira/browse/ZOOKEEPER-4843) - Encountering an 'Unreasonable Length' error when configuring jute.maxbuffer to 1GB or more +- [ZOOKEEPER-4876](https://issues.apache.org/jira/browse/ZOOKEEPER-4876) - jetty-http-9.4.53.v20231009.jar: CVE-2024-6763(3.7) + +## New Feature + +- [ZOOKEEPER-4747](https://issues.apache.org/jira/browse/ZOOKEEPER-4747) - Java api lacks synchronous version of sync() call + +## Improvement + +- [ZOOKEEPER-4850](https://issues.apache.org/jira/browse/ZOOKEEPER-4850) - Enhance zkCli Tool to Support Reading and Writing Binary Data +- [ZOOKEEPER-4851](https://issues.apache.org/jira/browse/ZOOKEEPER-4851) - Honor X-Forwarded-For optionally in IPAuthenticationProvider +- [ZOOKEEPER-4860](https://issues.apache.org/jira/browse/ZOOKEEPER-4860) - Disable X-Forwarded-For in IPAuthenticationProvider by default + +## Test + +- [ZOOKEEPER-4859](https://issues.apache.org/jira/browse/ZOOKEEPER-4859) - C client tests hang to be cancelled quite often + +## Task + +- [ZOOKEEPER-4820](https://issues.apache.org/jira/browse/ZOOKEEPER-4820) - zookeeper pom leaks logback dependency +- [ZOOKEEPER-4868](https://issues.apache.org/jira/browse/ZOOKEEPER-4868) - Bump commons-io library to 2.14.0 + +--- + +# Release Notes - ZooKeeper - Version 3.9.2 + +## Sub-task + +- [ZOOKEEPER-910](https://issues.apache.org/jira/browse/ZOOKEEPER-910) - Use SelectionKey.isXYZ() methods instead of complicated binary logic +- [ZOOKEEPER-4728](https://issues.apache.org/jira/browse/ZOOKEEPER-4728) - Zookeeper cannot bind to itself forever if DNS is not ready when startup + +## Bug + +- [ZOOKEEPER-2590](https://issues.apache.org/jira/browse/ZOOKEEPER-2590) - exists() should check read ACL permission +- [ZOOKEEPER-4236](https://issues.apache.org/jira/browse/ZOOKEEPER-4236) - Java Client SendThread create many unnecessary Login objects +- [ZOOKEEPER-4415](https://issues.apache.org/jira/browse/ZOOKEEPER-4415) - Zookeeper 3.7.0 : The client supported protocol versions [TLSv1.3] are not accepted by server preferences +- [ZOOKEEPER-4730](https://issues.apache.org/jira/browse/ZOOKEEPER-4730) - Incorrect datadir and logdir size reported from admin and 4lw dirs command +- [ZOOKEEPER-4785](https://issues.apache.org/jira/browse/ZOOKEEPER-4785) - Txn loss due to race condition in Learner.syncWithLeader() during DIFF sync + +## Improvement + +- [ZOOKEEPER-3486](https://issues.apache.org/jira/browse/ZOOKEEPER-3486) - add the doc about how to configure SSL/TLS for the admin server +- [ZOOKEEPER-4756](https://issues.apache.org/jira/browse/ZOOKEEPER-4756) - Merge script should use GitHub api to merge pull requests +- [ZOOKEEPER-4778](https://issues.apache.org/jira/browse/ZOOKEEPER-4778) - Patch jetty, netty, and logback to remove high severity vulnerabilities +- [ZOOKEEPER-4794](https://issues.apache.org/jira/browse/ZOOKEEPER-4794) - Reduce the ZKDatabase#committedLog memory usage +- [ZOOKEEPER-4799](https://issues.apache.org/jira/browse/ZOOKEEPER-4799) - Refactor ACL check in addWatch command +- [ZOOKEEPER-4801](https://issues.apache.org/jira/browse/ZOOKEEPER-4801) - Add memory size limitation policy for ZkDataBase#committedLog + +## Wish + +- [ZOOKEEPER-4807](https://issues.apache.org/jira/browse/ZOOKEEPER-4807) - Add sid for the leader goodbye log + +--- + +# Release Notes - ZooKeeper - Version 3.9.1 + +## Improvement + +- [ZOOKEEPER-4732](https://issues.apache.org/jira/browse/ZOOKEEPER-4732) - improve Reproducible Builds +- [ZOOKEEPER-4753](https://issues.apache.org/jira/browse/ZOOKEEPER-4753) - Explicit handling of DIGEST-MD5 vs GSSAPI in quorum auth + +## Task + +- [ZOOKEEPER-4751](https://issues.apache.org/jira/browse/ZOOKEEPER-4751) - Update snappy-java to 1.1.10.5 to address CVE-2023-43642 +- [ZOOKEEPER-4754](https://issues.apache.org/jira/browse/ZOOKEEPER-4754) - Update Jetty to avoid CVE-2023-36479, CVE-2023-40167, and CVE-2023-41900 +- [ZOOKEEPER-4755](https://issues.apache.org/jira/browse/ZOOKEEPER-4755) - Handle Netty CVE-2023-4586 + +--- + +# Release Notes - ZooKeeper - Version 3.9.0 + +## Sub-task + +- [ZOOKEEPER-4327](https://issues.apache.org/jira/browse/ZOOKEEPER-4327) - Flaky test: RequestThrottlerTest + +## Bug + +- [ZOOKEEPER-2108](https://issues.apache.org/jira/browse/ZOOKEEPER-2108) - Compilation error in ZkAdaptor.cc with GCC 4.7 or later +- [ZOOKEEPER-3652](https://issues.apache.org/jira/browse/ZOOKEEPER-3652) - Improper synchronization in ClientCnxn +- [ZOOKEEPER-3908](https://issues.apache.org/jira/browse/ZOOKEEPER-3908) - zktreeutil multiple issues +- [ZOOKEEPER-3996](https://issues.apache.org/jira/browse/ZOOKEEPER-3996) - Flaky test: ReadOnlyModeTest.testConnectionEvents +- [ZOOKEEPER-4026](https://issues.apache.org/jira/browse/ZOOKEEPER-4026) - CREATE2 requests embedded in a MULTI request only get a regular CREATE response +- [ZOOKEEPER-4296](https://issues.apache.org/jira/browse/ZOOKEEPER-4296) - NullPointerException when ClientCnxnSocketNetty is closed without being opened +- [ZOOKEEPER-4308](https://issues.apache.org/jira/browse/ZOOKEEPER-4308) - Flaky test: EagerACLFilterTest.testSetDataFail +- [ZOOKEEPER-4393](https://issues.apache.org/jira/browse/ZOOKEEPER-4393) - Problem to connect to zookeeper in FIPS mode +- [ZOOKEEPER-4466](https://issues.apache.org/jira/browse/ZOOKEEPER-4466) - Support different watch modes on same path +- [ZOOKEEPER-4471](https://issues.apache.org/jira/browse/ZOOKEEPER-4471) - Remove WatcherType.Children break persistent watcher's child events +- [ZOOKEEPER-4473](https://issues.apache.org/jira/browse/ZOOKEEPER-4473) - zooInspector create root node fail with path validate +- [ZOOKEEPER-4475](https://issues.apache.org/jira/browse/ZOOKEEPER-4475) - Persistent recursive watcher got NodeChildrenChanged event +- [ZOOKEEPER-4477](https://issues.apache.org/jira/browse/ZOOKEEPER-4477) - Single Kerberos ticket renewal failure can prevent all future renewals since Java 9 +- [ZOOKEEPER-4504](https://issues.apache.org/jira/browse/ZOOKEEPER-4504) - ZKUtil#deleteRecursive causing deadlock in HDFS HA functionality +- [ZOOKEEPER-4505](https://issues.apache.org/jira/browse/ZOOKEEPER-4505) - CVE-2020-36518 - Upgrade jackson databind to 2.13.2.1 +- [ZOOKEEPER-4511](https://issues.apache.org/jira/browse/ZOOKEEPER-4511) - Flaky test: FileTxnSnapLogMetricsTest.testFileTxnSnapLogMetrics +- [ZOOKEEPER-4514](https://issues.apache.org/jira/browse/ZOOKEEPER-4514) - ClientCnxnSocketNetty throwing NPE +- [ZOOKEEPER-4515](https://issues.apache.org/jira/browse/ZOOKEEPER-4515) - ZK Cli quit command always logs error +- [ZOOKEEPER-4537](https://issues.apache.org/jira/browse/ZOOKEEPER-4537) - Race between SyncThread and CommitProcessor thread +- [ZOOKEEPER-4549](https://issues.apache.org/jira/browse/ZOOKEEPER-4549) - ProviderRegistry may be repeatedly initialized +- [ZOOKEEPER-4565](https://issues.apache.org/jira/browse/ZOOKEEPER-4565) - Config watch path get truncated abnormally and fail chroot zookeeper client +- [ZOOKEEPER-4647](https://issues.apache.org/jira/browse/ZOOKEEPER-4647) - Tests don't pass on JDK20 because we try to mock InetAddress +- [ZOOKEEPER-4654](https://issues.apache.org/jira/browse/ZOOKEEPER-4654) - Fix C client test compilation error in Util.cc. +- [ZOOKEEPER-4674](https://issues.apache.org/jira/browse/ZOOKEEPER-4674) - C client tests don't pass on CI +- [ZOOKEEPER-4719](https://issues.apache.org/jira/browse/ZOOKEEPER-4719) - Use bouncycastle jdk18on instead of jdk15on +- [ZOOKEEPER-4721](https://issues.apache.org/jira/browse/ZOOKEEPER-4721) - Upgrade OWASP Dependency Check to 8.3.1 + +## New Feature + +- [ZOOKEEPER-4570](https://issues.apache.org/jira/browse/ZOOKEEPER-4570) - Admin server API for taking snapshot and stream out the data +- [ZOOKEEPER-4655](https://issues.apache.org/jira/browse/ZOOKEEPER-4655) - Communicate the Zxid that triggered a WatchEvent to fire + +## Improvement + +- [ZOOKEEPER-3731](https://issues.apache.org/jira/browse/ZOOKEEPER-3731) - Disable HTTP TRACE Method +- [ZOOKEEPER-3806](https://issues.apache.org/jira/browse/ZOOKEEPER-3806) - TLS - dynamic loading for client trust/key store +- [ZOOKEEPER-3860](https://issues.apache.org/jira/browse/ZOOKEEPER-3860) - Avoid reverse DNS lookup for hostname verification when hostnames are provided in the connection url +- [ZOOKEEPER-4289](https://issues.apache.org/jira/browse/ZOOKEEPER-4289) - Reduce the performance impact of Prometheus metrics +- [ZOOKEEPER-4303](https://issues.apache.org/jira/browse/ZOOKEEPER-4303) - ZooKeeperServerEmbedded could auto-assign and expose ports +- [ZOOKEEPER-4464](https://issues.apache.org/jira/browse/ZOOKEEPER-4464) - zooinspector display "Ephemeral Owner" in hex for easy match to jmx session +- [ZOOKEEPER-4467](https://issues.apache.org/jira/browse/ZOOKEEPER-4467) - Missing op code (addWatch) in Request.op2String +- [ZOOKEEPER-4472](https://issues.apache.org/jira/browse/ZOOKEEPER-4472) - Support persistent watchers removing individually +- [ZOOKEEPER-4474](https://issues.apache.org/jira/browse/ZOOKEEPER-4474) - ZooDefs.opNames is unused +- [ZOOKEEPER-4490](https://issues.apache.org/jira/browse/ZOOKEEPER-4490) - Publish Clover results to SonarQube +- [ZOOKEEPER-4491](https://issues.apache.org/jira/browse/ZOOKEEPER-4491) - Adding SSL support to Zktreeutil +- [ZOOKEEPER-4492](https://issues.apache.org/jira/browse/ZOOKEEPER-4492) - Merge readOnly field into ConnectRequest and Response +- [ZOOKEEPER-4494](https://issues.apache.org/jira/browse/ZOOKEEPER-4494) - Fix error message format +- [ZOOKEEPER-4518](https://issues.apache.org/jira/browse/ZOOKEEPER-4518) - remove useless log in the PrepRequestProcessor#pRequest method +- [ZOOKEEPER-4519](https://issues.apache.org/jira/browse/ZOOKEEPER-4519) - Testable interface should have a testableCloseSocket() method +- [ZOOKEEPER-4529](https://issues.apache.org/jira/browse/ZOOKEEPER-4529) - Upgrade netty to 4.1.76.Final +- [ZOOKEEPER-4531](https://issues.apache.org/jira/browse/ZOOKEEPER-4531) - Revert Netty TCNative change +- [ZOOKEEPER-4551](https://issues.apache.org/jira/browse/ZOOKEEPER-4551) - Do not log spammy stacktrace when a client closes its connection +- [ZOOKEEPER-4566](https://issues.apache.org/jira/browse/ZOOKEEPER-4566) - Create tool for recursive snapshot analysis +- [ZOOKEEPER-4573](https://issues.apache.org/jira/browse/ZOOKEEPER-4573) - Encapsulate request bytebuffer in Request +- [ZOOKEEPER-4575](https://issues.apache.org/jira/browse/ZOOKEEPER-4575) - ZooKeeperServer#processPacket take record instead of bytes +- [ZOOKEEPER-4616](https://issues.apache.org/jira/browse/ZOOKEEPER-4616) - Upgrade docker image for the dev environment to resolve CVEs +- [ZOOKEEPER-4622](https://issues.apache.org/jira/browse/ZOOKEEPER-4622) - Add Netty-TcNative OpenSSL Support +- [ZOOKEEPER-4636](https://issues.apache.org/jira/browse/ZOOKEEPER-4636) - Fix zkServer.sh for AIX +- [ZOOKEEPER-4657](https://issues.apache.org/jira/browse/ZOOKEEPER-4657) - Publish SBOM artifacts +- [ZOOKEEPER-4659](https://issues.apache.org/jira/browse/ZOOKEEPER-4659) - Upgrade Commons CLI to 1.5.0 due to OWASP failing on 1.4 CVE-2021-37533 +- [ZOOKEEPER-4660](https://issues.apache.org/jira/browse/ZOOKEEPER-4660) - Suppress false positive OWASP failure for CVE-2021-37533 +- [ZOOKEEPER-4661](https://issues.apache.org/jira/browse/ZOOKEEPER-4661) - Upgrade Jackson Databind to 2.13.4.2 for CVE-2022-42003 CVE-2022-42004 +- [ZOOKEEPER-4705](https://issues.apache.org/jira/browse/ZOOKEEPER-4705) - Restrict GitHub merge button to allow squash commit only +- [ZOOKEEPER-4717](https://issues.apache.org/jira/browse/ZOOKEEPER-4717) - Cache serialize data in the request to avoid repeat serialize. +- [ZOOKEEPER-4718](https://issues.apache.org/jira/browse/ZOOKEEPER-4718) - Removing unnecessary heap memory allocation in serialization can help reduce GC pressure. + +## Test + +- [ZOOKEEPER-4630](https://issues.apache.org/jira/browse/ZOOKEEPER-4630) - Fix the NPE from ConnectionMetricsTest.testRevalidateCount +- [ZOOKEEPER-4676](https://issues.apache.org/jira/browse/ZOOKEEPER-4676) - ReadOnlyModeTest doesn't compile on JDK20 (Thread.suspend has been removed) + +## Wish + +- [ZOOKEEPER-3615](https://issues.apache.org/jira/browse/ZOOKEEPER-3615) - write a TLA+ specification to verify Zab protocol +- [ZOOKEEPER-4710](https://issues.apache.org/jira/browse/ZOOKEEPER-4710) - Fix ZkUtil deleteInBatch() by releasing semaphore after set flag +- [ZOOKEEPER-4714](https://issues.apache.org/jira/browse/ZOOKEEPER-4714) - Improve syncRequestProcessor performance +- [ZOOKEEPER-4715](https://issues.apache.org/jira/browse/ZOOKEEPER-4715) - Verify file size and position in testGetCurrentLogSize. + +## Task + +- [ZOOKEEPER-4479](https://issues.apache.org/jira/browse/ZOOKEEPER-4479) - Tests: C client test TestOperations.cc testTimeoutCausedByWatches1 is very flaky on CI +- [ZOOKEEPER-4482](https://issues.apache.org/jira/browse/ZOOKEEPER-4482) - Fix LICENSE FILES for commons-io and commons-cli +- [ZOOKEEPER-4599](https://issues.apache.org/jira/browse/ZOOKEEPER-4599) - Upgrade Jetty to avoid CVE-2022-2048 +- [ZOOKEEPER-4641](https://issues.apache.org/jira/browse/ZOOKEEPER-4641) - GH CI fails with error: implicit declaration of function FIPS_mode +- [ZOOKEEPER-4642](https://issues.apache.org/jira/browse/ZOOKEEPER-4642) - Remove Travis CI +- [ZOOKEEPER-4649](https://issues.apache.org/jira/browse/ZOOKEEPER-4649) - Upgrade netty to 4.1.86 because of CVE-2022-41915 +- [ZOOKEEPER-4669](https://issues.apache.org/jira/browse/ZOOKEEPER-4669) - Upgrade snappy-java to 1.1.9.1 (in order to support M1 macs) +- [ZOOKEEPER-4688](https://issues.apache.org/jira/browse/ZOOKEEPER-4688) - Upgrade `cyclonedx-maven-plugin` to 2.7.6 +- [ZOOKEEPER-4700](https://issues.apache.org/jira/browse/ZOOKEEPER-4700) - Update Jetty for fixing CVE-2023-26048 and CVE-2023-26049 +- [ZOOKEEPER-4707](https://issues.apache.org/jira/browse/ZOOKEEPER-4707) - Update snappy-java to address multiple CVEs +- [ZOOKEEPER-4709](https://issues.apache.org/jira/browse/ZOOKEEPER-4709) - Upgrade Netty to 4.1.94.Final +- [ZOOKEEPER-4716](https://issues.apache.org/jira/browse/ZOOKEEPER-4716) - Upgrade jackson to 2.15.2, suppress two false positive CVE errors diff --git a/zookeeper-website/app/pages/_docs/docs/index.tsx b/zookeeper-website/app/pages/_docs/docs/index.tsx new file mode 100644 index 00000000000..4c645ce23a0 --- /dev/null +++ b/zookeeper-website/app/pages/_docs/docs/index.tsx @@ -0,0 +1,172 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { docs } from "@/.source"; +import { toClientRenderer } from "fumadocs-mdx/runtime/vite"; +import { DocsLayout } from "@/components/docs/layout/docs"; +import { + DocsBody as FumaDocsBody, + DocsDescription as FumaDocsDescription, + DocsPage as FumaDocsPage, + DocsTitle as FumaDocsTitle +} from "@/components/docs/layout/docs/page"; +import defaultMdxComponents from "fumadocs-ui/mdx"; +import type * as PageTree from "fumadocs-core/page-tree"; +import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared"; +import { useParams } from "react-router"; +import { getPageTreePeers } from "fumadocs-core/page-tree"; +import { Card, Cards } from "fumadocs-ui/components/card"; +import { Callout } from "fumadocs-ui/components/callout"; +import { Step, Steps } from "fumadocs-ui/components/steps"; +import { Link } from "@/components/link"; +import { OlderDocsPicker } from "@/components/docs/older-docs-picker"; +import type { MDXComponents } from "mdx/types"; + +// Extend default MDX components to include shared UI blocks globally. +// Note: We'll override the 'a' component in the renderer to handle route-specific logic +const baseMdxComponents: MDXComponents = { + ...defaultMdxComponents, + p: (props) =>

      , + h1: (props) =>

      , + Callout, + Step, + Steps +}; + +export function baseOptions(): BaseLayoutProps { + return { + nav: { + title: ( +
      + ZooKeeper favicon +

      Apache ZooKeeper

      +
      + ) + }, + githubUrl: "https://github.com/apache/zookeeper/" + }; +} + +type DocsLoaderData = { path: string; url: string; tree: unknown }; + +const renderer = toClientRenderer( + docs.doc, + ( + { + toc, + default: Mdx, + frontmatter, + pageTitle, + pageDescription + }: { + toc: any; + default: any; + frontmatter: { title?: string; description?: string }; + pageTitle?: string; + pageDescription?: string; + }, + { tree }: { tree: PageTree.Root } + ) => { + const route = useParams()["*"]; + const baseGithubPath = "zookeeper-docs/app/pages/_docs/docs/_mdx/"; + + const grouppedRoutes = [ + "developer/programmers-guide", + "admin-ops/administrators-guide" + ]; + const trimmedRoute = route?.endsWith("/") ? route?.slice(0, -1) : route; + const mdxFileRoute = `${trimmedRoute === "" ? "index" : trimmedRoute}.mdx`; + const isGrouppedRoute = + !!trimmedRoute && grouppedRoutes.includes(trimmedRoute); + const displayTitle = pageTitle ?? frontmatter.title; + const displayDescription = pageDescription ?? frontmatter.description; + + // Use default Link component for all links (external links are handled by Link component) + const CustomLink = ({ href, children, ...rest }: any) => { + return ( + + {children} + + ); + }; + + const mdxComponents = { + ...baseMdxComponents, + a: CustomLink + }; + + return ( + + {displayTitle + " | Zookeeper"} + + + {displayTitle} + {displayDescription} + + + {route !== undefined && isGrouppedRoute && ( + // table of content for groupped routes +
      +

      In this section:

      + + {getPageTreePeers(tree, `/docs/${trimmedRoute}`).map((peer) => ( + + {peer.description} + + ))} + +
      + )} +       + + {route !== undefined && ( + + Edit on GitHub + + )} +       + ); + } +); + +export function DocsPage({ loaderData }: { loaderData: DocsLoaderData }) { + const { tree, path } = loaderData; + const Content = renderer[path]; + + const layoutOptions = baseOptions(); + + return ( + }} + > + + + ); +} diff --git a/zookeeper-website/app/pages/_landing/bylaws/content.md b/zookeeper-website/app/pages/_landing/bylaws/content.md new file mode 100644 index 00000000000..30ecd46c0c1 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/bylaws/content.md @@ -0,0 +1,126 @@ + + +# Apache ZooKeeper Project Bylaws + +This is version 1 of the bylaws. + +## Introduction + +This document defines the bylaws under which the Apache ZooKeeper project operates. It defines the roles and responsibilities of the project, who may vote, how voting works, how conflicts are resolved, etc. + +ZooKeeper is a project of the [Apache Software Foundation](https://www.apache.org/foundation/). The foundation holds the copyright on Apache code including the code in the ZooKeeper codebase. The [foundation FAQ](https://www.apache.org/foundation/faq.html) explains the operation and background of the foundation. + +ZooKeeper is typical of Apache projects in that it operates under a set of principles, known collectively as the Apache Way. If you are new to Apache development, please refer to the [Incubator project](https://incubator.apache.org/) for more information on how Apache projects operate. + +## Roles and Responsibilities + +Apache projects define a set of roles with associated rights and responsibilities. These roles govern what tasks an individual may perform within the project. The roles are defined in the following sections. + +## Users + +The most important participants in the project are people who use our software. The majority of our contributors start out as users and guide their development efforts from the user's perspective. + +Users contribute to the Apache projects by providing feedback to contributors in the form of bug reports and feature suggestions. As well, users participate in the Apache community by helping other users on mailing lists and user support forums. + +## Contributors + +All of the volunteers who are contributing time, code, documentation, or resources to the ZooKeeper Project. A contributor that makes sustained, welcome contributions to the project may be invited to become a committer, though the exact timing of such invitations depends on many factors. + +## Committers + +The project's committers are responsible for the project's technical management. Committers have access to a specified set of subproject's repositories. Committers on subprojects may cast binding votes on any technical discussion regarding that subproject. + +Committer access is by invitation only and must be approved by lazy consensus of the active PMC members. A Committer is considered emeritus by his or her own declaration or by not reviewing patches or commiting patches to the project for over six months. An emeritus committer may request reinstatement of commit access from the PMC which must be approved by lazy consensus of the active PMC members. + +Commit access can be revoked by a unanimous vote of all the active PMC members (except the committer in question if he or she is also a PMC member). + +All Apache committers are required to have a signed [Contributor License Agreement (CLA)](https://www.apache.org/licenses/icla.txt) on file with the Apache Software Foundation. There is a [Committer FAQ](https://www.apache.org/dev/committers.html) which provides more details on the requirements for committers. + +A committer who makes a sustained contribution to the project may be invited to become a member of the PMC. The form of contribution is not limited to code. It can also include code review, helping out users on the mailing lists, documentation, etc. + +## Project Management Committee + +The PMC is responsible to the board and the ASF for the management and oversight of the Apache ZooKeeper codebase. The responsibilities of the PMC include: + +- Deciding what is distributed as products of the Apache ZooKeeper project. In particular all releases must be approved by the PMC. +- Maintaining the project's shared resources, including the codebase repository, mailing lists, websites. +- Speaking on behalf of the project. +- Resolving license disputes regarding products of the project. +- Nominating new PMC members and committers. +- Maintaining these bylaws and other guidelines of the project. +- Membership of the PMC is by invitation only and must be approved by a lazy consensus of active PMC members. A PMC member is considered emeritus by his or her own declaration or by not contributing in any form to the project for over six months. An emeritus member may request reinstatement to the PMC, which must be approved by a lazy consensus of active PMC members. + +Membership of the PMC can be revoked by an unanimous vote of all the active PMC members other than the member in question. + +The chair of the PMC is appointed by the ASF board. The chair is an office holder of the Apache Software Foundation (Vice President, Apache ZooKeeper) and has primary responsibility to the board for the management of the projects within the scope of the ZooKeeper PMC. The chair reports to the board quarterly on developments within the ZooKeeper project. + +When the current chair of the PMC resigns, the PMC votes to recommend a new chair using lazy consensus, but the decision must be ratified by the Apache board. + +## Decision Making + +Within the ZooKeeper project, different types of decisions require different forms of approval. For example, the previous section describes several decisions which require 'lazy consensus' approval. This section defines how voting is performed, the types of approvals, and which types of decision require which type of approval. + +## Voting + +Decisions regarding the project are made by votes on the primary project development mailing list [dev@zookeeper.apache.org](mailto:dev@zookeeper.apache.org). Where necessary, PMC voting may take place on the private ZooKeeper PMC mailing list [private@zookeeper.apache.org](mailto:private@zookeeper.apache.org). Votes are clearly indicated by subject line starting with `[VOTE]`. Votes may contain multiple items for approval and these should be clearly separated. Voting is carried out by replying to the vote mail. Voting may take four flavors. + +| Vote | Meaning | +| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| +1 | 'Yes,' 'Agree,' or 'the action should be performed.' In general, this vote also indicates a willingness on the behalf of the voter in 'making it happen'. | +| +0 | This vote indicates a willingness for the action under consideration to go ahead. The voter, however will not be able to help. | +| -0 | This vote indicates that the voter does not, in general, agree with the proposed action but is not concerned enough to prevent the action going ahead. | +| -1 | This is a negative vote. On issues where consensus is required, this vote counts as a veto. All vetoes must contain an explanation of why the veto is appropriate. Vetoes with no explanation are void. It may also be appropriate for a -1 vote to include an alternative course of action. | + +All participants in the ZooKeeper project are encouraged to show their agreement with or against a particular action by voting. For technical decisions, only the votes of active committers are binding. Non binding votes are still useful for those with binding votes to understand the perception of an action in the wider ZooKeeper community. For PMC decisions, only the votes of PMC members are binding. + +Voting can also be applied to changes already made to the ZooKeeper codebase. These typically take the form of a veto (-1) in reply to the commit message sent when the commit is made. Note that this should be a rare occurrence. All efforts should be made to discuss issues when they are still patches before the code is committed. + +## Approvals + +There are the types of approvals that can be sought. Different actions require different types of approvals. + +| Approval Type | Definition | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Consensus | For this to pass, all voters with binding votes must vote and there can be no binding vetoes (-1). Consensus votes are rarely required due to the impracticality of getting all eligible voters to cast a vote. | +| Lazy Consensus | Lazy consensus requires 3 binding +1 votes and no binding vetoes. | +| Lazy Majority | A lazy majority vote requires 3 binding +1 votes and more binding +1 votes that -1 votes. | +| Lazy Approval | An action with lazy approval is implicitly allowed unless a -1 vote is received, at which time, depending on the type of action, either lazy majority or lazy consensus approval must be obtained. | +| 2/3 Majority | Some actions require a 2/3 majority of active committers or PMC members to pass. Such actions typically affect the foundation of the project (e.g. adopting a new codebase to replace an existing product). The higher threshold is designed to ensure such changes are strongly supported. To pass this vote requires at least 2/3 of binding vote holders to vote +1. | + +## Vetoes + +A valid, binding veto cannot be overruled. If a veto is cast, it must be accompanied by a valid reason explaining the reasons for the veto. The validity of a veto, if challenged, can be confirmed by anyone who has a binding vote. This does not necessarily signify agreement with the veto — merely that the veto is valid. + +If you disagree with a valid veto, you must lobby the person casting the veto to withdraw his or her veto. If a veto is not withdrawn, the action that has been vetoed must be reversed in a timely manner. + +## Actions + +This section describes the various actions which are undertaken within the project, the corresponding approval required for that action and those who have binding votes over the action. It also specifies the minimum length of time that a vote must remain open, measured in business days. In general votes should not be called at times when it is known that interested members of the project will be unavailable. + +| Action | Description | Approval | Binding Votes | Min. Days | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------- | +| Code Change | A change made to a codebase of the project and committed by a committer. This includes source code, documentation, website content, etc. | Lazy approval (not counting the vote of the contributor), moving to lazy majority if a -1 is received | Active committers | 1 | +| Release Plan | Defines the timetable and actions for a release. The plan also nominates a Release Manager. | Lazy majority | Active committers | 3 | +| Product Release | When a release of one of the project's products is ready, a vote is required to accept the release as an official release of the project. | Lazy Majority | Active PMC members | 3 | +| Adoption of New Codebase | When the codebase for an existing, released product is to be replaced with an alternative codebase. If such a vote fails to gain approval, the existing code base will continue. This also covers the creation of new sub-projects within the project. | 2/3 majority | Active PMC members | 6 | +| New Committer or reinstatement | When a new committer is proposed for the project. | Lazy consensus | Active PMC members | 3 | +| New PMC Member or reinstatement | When a committer is proposed for the PMC. | Lazy consensus | Active PMC members | 3 | +| Committer Removal | When removal of commit privileges is sought. Note: Such actions will also be referred to the ASF board by the PMC chair. | Consensus | Active PMC members (excluding the committer in question if a member of the PMC). | 6 | +| PMC Member Removal | When removal of a PMC member is sought. Note: Such actions will also be referred to the ASF board by the PMC chair. | Consensus | Active PMC members (excluding the member in question). | 6 | +| Modifying Bylaws | Modifying this document. | 2/3 majority | Active PMC members | 6 | diff --git a/zookeeper-website/app/pages/_landing/bylaws/index.tsx b/zookeeper-website/app/pages/_landing/bylaws/index.tsx new file mode 100644 index 00000000000..c222b7c92dd --- /dev/null +++ b/zookeeper-website/app/pages/_landing/bylaws/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function BylawsPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/credits/developers.json b/zookeeper-website/app/pages/_landing/credits/developers.json new file mode 100644 index 00000000000..f4a77670e8c --- /dev/null +++ b/zookeeper-website/app/pages/_landing/credits/developers.json @@ -0,0 +1,47 @@ +{ + "pmc": [ + { "id": "tdunning", "name": "Ted Dunning", "organization": "MapR Technologies", "timezone": "-8" }, + { "id": "camille", "name": "Camille Fournier", "organization": "RentTheRunway", "timezone": "-5" }, + { "id": "phunt", "name": "Patrick Hunt", "organization": "Cloudera Inc.", "timezone": "-8" }, + { "id": "fpj", "name": "Flavio Junqueira", "organization": "Confluent", "timezone": "+0" }, + { "id": "ivank", "name": "Ivan Kelly", "organization": "Midokura", "timezone": "+2" }, + { "id": "mahadev", "name": "Mahadev Konar", "organization": "Hortonworks Inc.", "timezone": "-8" }, + { "id": "michim", "name": "Michi Mutsuzaki", "organization": "Nicira", "timezone": "-8" }, + { "id": "cnauroth", "name": "Chris Nauroth", "organization": "Hortonworks Inc.", "timezone": "-8" }, + { "id": "breed", "name": "Benjamin Reed", "organization": "Facebook", "timezone": "-8" }, + { "id": "henry", "name": "Henry Robinson", "organization": "Cloudera Inc.", "timezone": "-8" }, + { "id": "rgs", "name": "Raul Gutierrez Segales", "organization": "Pinterest", "timezone": "-8" }, + { "id": "rakeshr", "name": "Rakesh Radhakrishnan", "organization": "Intel", "timezone": "+5:30" }, + { "id": "hanm", "name": "Michael Han", "organization": "Twitter", "timezone": "-8" }, + { "id": "andor", "name": "Andor Molnar", "organization": "Cloudera Inc.", "timezone": "+1" }, + { "id": "eolivelli", "name": "Enrico Olivelli", "organization": "Diennea", "timezone": "+1" }, + { "id": "symat", "name": "Mate Szalay-Beko", "organization": "Cloudera Inc.", "timezone": "+1" } + ], + "committers": [ + { "id": "camille", "name": "Camille Fournier", "organization": "RentTheRunway", "timezone": "-5" }, + { "id": "phunt", "name": "Patrick Hunt", "organization": "Cloudera Inc.", "timezone": "-8" }, + { "id": "fpj", "name": "Flavio Junqueira", "organization": "Confluent", "timezone": "+1" }, + { "id": "cnauroth", "name": "Chris Nauroth", "organization": "Hortonworks Inc.", "timezone": "-8" }, + { "id": "mahadev", "name": "Mahadev Konar", "organization": "Hortonworks Inc.", "timezone": "-8" }, + { "id": "gkesavan", "name": "Giridharan Kesavan", "organization": "Hortonworks Inc.", "timezone": "-8" }, + { "id": "akornev", "name": "Andrew Kornev", "organization": "", "timezone": "" }, + { "id": "michim", "name": "Michi Mutsuzaki", "organization": "Nicira", "timezone": "-8" }, + { "id": "breed", "name": "Benjamin Reed", "organization": "Facebook", "timezone": "-8" }, + { "id": "henry", "name": "Henry Robinson", "organization": "Cloudera Inc.", "timezone": "-8" }, + { "id": "shralex", "name": "Alex Shraer", "organization": "Apple", "timezone": "-8" }, + { "id": "thawan", "name": "Thawan Kooburat", "organization": "Facebook", "timezone": "-8" }, + { "id": "rakeshr", "name": "Rakesh Radhakrishnan", "organization": "Intel", "timezone": "+5:30" }, + { "id": "hdeng", "name": "Hongchao Deng", "organization": "CoreOS", "timezone": "-8" }, + { "id": "rgs", "name": "Raul Gutierrez Segales", "organization": "Pinterest", "timezone": "-8" }, + { "id": "hanm", "name": "Michael Han", "organization": "Twitter", "timezone": "-8" }, + { "id": "arshad", "name": "Mohammad Arshad", "organization": "Huawei", "timezone": "+5:30" }, + { "id": "afine", "name": "Abraham Fine", "organization": "IFTTT", "timezone": "-8" }, + { "id": "andor", "name": "Andor Molnar", "organization": "Cloudera Inc.", "timezone": "+1" }, + { "id": "fangmin", "name": "Fangmin Lyu", "organization": "Facebook", "timezone": "-8" }, + { "id": "eolivelli", "name": "Enrico Olivelli", "organization": "Diennea", "timezone": "+1" }, + { "id": "nkalmar", "name": "Norbert Kalmar", "organization": "Cloudera", "timezone": "+1" }, + { "id": "enixon", "name": "Brian Nixon", "organization": "Facebook", "timezone": "-8" }, + { "id": "symat", "name": "Mate Szalay-Beko", "organization": "Cloudera Inc.", "timezone": "+1" }, + { "id": "ddiederen", "name": "Damien Diederen", "organization": "Crosstwine Labs", "timezone": "+1" } + ] +} diff --git a/zookeeper-website/app/pages/_landing/credits/developers.json.d.ts b/zookeeper-website/app/pages/_landing/credits/developers.json.d.ts new file mode 100644 index 00000000000..ffc848ddc91 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/credits/developers.json.d.ts @@ -0,0 +1,27 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +interface Developer { + id: string; + name: string; + email: string; + timezone: string; +} + +declare const developers: Developer[]; +export default developers; diff --git a/zookeeper-website/app/pages/_landing/credits/index.tsx b/zookeeper-website/app/pages/_landing/credits/index.tsx new file mode 100644 index 00000000000..50d15ee9066 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/credits/index.tsx @@ -0,0 +1,121 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import data from "./developers.json"; + +interface Member { + id: string; + name: string; + organization: string; + timezone: string; +} + +interface Credits { + pmc: Member[]; + committers: Member[]; +} + +function MemberTable({ members }: { members: Member[] }) { + return ( +
      + + + + + + + + + + + {members.map((member) => ( + + + + + + + ))} + +
      UsernameNameOrganizationTime Zone
      {member.id}{member.name || "-"} + {member.organization || "-"} + {member.timezone || "-"}
      +
      + ); +} + +export function CreditsPage() { + const credits = data as Credits; + + return ( +
      +
      +

      + ZooKeeper Credits +

      + +

      + A successful project requires many people to play many roles. Some + members write code or documentation, while others are valuable as + testers, submitting patches and suggestions. +

      + +

      + PMC Members +

      + +

      + ZooKeeper's active PMC members are listed below. +

      + + + +

      + Committers +

      + +

      + ZooKeeper's active committers are listed below. +

      + + + +

      + Contributors +

      + +

      + A list of ZooKeeper contributors and their contributions is available + from{" "} + + Jira + + . +

      +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/events/content.md b/zookeeper-website/app/pages/_landing/events/content.md new file mode 100644 index 00000000000..af5434e03c9 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/events/content.md @@ -0,0 +1,68 @@ + + +# Events + +## Upcoming Events + +[![Current Apache Event](https://www.apache.org/events/current-event-234x60.png)](https://www.apache.org/events/) + +## Past Events + +### Facebook ZooKeeper Meetup + +Your ZooKeeper friends @ Facebook would like to invite you to share and learn what's new with ZooKeeper. + +We will not only share what we at Facebook have been up to, but we have exciting talks from speakers from the ZooKeeper community lined up who are eager to share what they've been working on as well. And of course, we've got some cool swag for you :-) + +**When:** November 8th 2018, 5pm – 8pm (Talks: 5pm - 7pm; Networking & Happy Hour: 7pm - 8pm) + +**Where:** Facebook HQ — MPK 16, 1 Hacker Way, Menlo Park, CA + +**Agenda:** + +- 5:00pm – 5:15pm — Welcome/Registration +- 5:15pm – 6:10pm — ZooKeeper @ Facebook +- 6:15pm – 6:35pm — What's new in ZooKeeper 3.5 (Andor Molnar) +- 6:40pm – 7:00pm — ZooKeeper @ Twitter (Michael Han) + +We will have remote viewing locations in our Facebook Seattle office, and the event will also be live streamed. You can indicate how you'd like to attend on the registration page. + +**Recording:** [https://www.facebook.com/zkmeetup](https://www.facebook.com/zkmeetup) + +--- + +### 10 years at Apache | ZooKeeper Meetup with Patrick Hunt + +**When:** June 6th 2018, 6pm – 8pm CEST + +**Where:** Cloudera Budapest Office, Széchenyi István tér 7-8, Budapest, Hungary + +**Agenda:** + +**"Apache ZooKeeper — a short history"** (Patrick Hunt) + +_Ten years at Apache — a short history of the Apache ZooKeeper project including insights on how to use it, when to use it, when not to use it, and experiences from running in production._ + +Interestingly ZooKeeper will be hitting its 10 year anniversary at Apache while in Budapest — see [ZOOKEEPER-1](https://issues.apache.org/jira/browse/ZOOKEEPER-1). + +**"What it feels like working on an Open Source project"** (Andor Molnar) + +_Experiences of a Hungarian software engineer moved to the Open Source world recently from the traditional closed-source proprietary product development. The ladder of Apache: committer, PMC members, etc. Challenges in prioritization. Does scrum work with open source? Importance of socialization: how networking helps you to be successful._ + +**Recording:** no recording diff --git a/zookeeper-website/app/pages/_landing/events/index.tsx b/zookeeper-website/app/pages/_landing/events/index.tsx new file mode 100644 index 00000000000..1a5acf3d46b --- /dev/null +++ b/zookeeper-website/app/pages/_landing/events/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function EventsPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/home/community.tsx b/zookeeper-website/app/pages/_landing/home/community.tsx new file mode 100644 index 00000000000..32113878002 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/community.tsx @@ -0,0 +1,100 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Button } from "@/ui/button"; +import { ArrowUpRight } from "lucide-react"; +import { Link } from "@/components/link"; + +export function CommunitySection() { + return ( +
      +
      +
      +
      +
      +

      + A Vibrant Community +

      +

      + ZooKeeper is a top-level Apache project with an active community + of users and contributors. Join discussions, read the + documentation, and help shape the roadmap. +

      +
      + + + +
      +
      +
        +
      • + + + News + +

        + ZooKeeper release announcements and project news. +

        + + +
        • +
      • + + + IRC Channel + +

        + Chat with the community on #zookeeper at irc.libera.chat. +

        + + +
        • +
      • + + + Security + +

        + Report vulnerabilities and review known CVEs. +

        + + +
        • +
      +
      +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/feature-card.tsx b/zookeeper-website/app/pages/_landing/home/feature-card.tsx new file mode 100644 index 00000000000..28a4df5e54a --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/feature-card.tsx @@ -0,0 +1,52 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type React from "react"; +import { cn } from "@/lib/utils"; +import type { LucideIcon } from "lucide-react"; + +export function FeatureCard({ + title, + children, + icon: Icon, + className +}: { + title: string; + children: React.ReactNode; + icon?: LucideIcon; + className?: string; +}) { + return ( +
      + {Icon && ( +
      + +
      + )} +

      {title}

      +

      + {children} +

      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/features.tsx b/zookeeper-website/app/pages/_landing/home/features.tsx new file mode 100644 index 00000000000..dc3cefa3142 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/features.tsx @@ -0,0 +1,65 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { FeatureCard } from "@/pages/_landing/home/feature-card"; +import { Zap, ShieldCheck, ListOrdered, ServerCrash } from "lucide-react"; + +export function FeaturesSection() { + const features = [ + { + title: "High Performance", + desc: "In-memory messaging with sub-millisecond latency; handles tens of thousands of requests per second.", + Icon: Zap + }, + { + title: "Simple & Reliable", + desc: "A clean hierarchical namespace modeled after a file system makes coordination logic easy to reason about.", + Icon: ShieldCheck + }, + { + title: "Ordered Operations", + desc: "Every update is stamped with a monotonically increasing zxid, giving clients a total ordering guarantee.", + Icon: ListOrdered + }, + { + title: "Fault-Tolerant", + desc: "Replicated across an ensemble of servers; survives node failures automatically with no data loss.", + Icon: ServerCrash + } + ]; + return ( +
      +
      +

      + Why ZooKeeper +

      +

      + A proven coordination kernel trusted by Kafka, Hadoop, HBase, and many + other distributed systems. +

      +
      +
      + {features.map((f) => ( + + {f.desc} + + ))} +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/hero.tsx b/zookeeper-website/app/pages/_landing/home/hero.tsx new file mode 100644 index 00000000000..de6b2d3de82 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/hero.tsx @@ -0,0 +1,111 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Button } from "@/ui/button"; +import { Link } from "@/components/link"; +import { Terminal } from "lucide-react"; + +export function Hero() { + return ( +
      + {/* Background pattern */} +
      + +
      +
      +
      + Apache ZooKeeper logo + Apache ZooKeeper logo + +

      + The standard for{" "} + distributed coordination +

      +

      + Naming, configuration management, synchronization, and group + services — battle-tested coordination primitives in a simple, + highly reliable interface. +

      + +
      + + +
      +
      + +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      + + zkCli.sh +
      +
      +
      +
      + $ bin/zkCli.sh -server 127.0.0.1:2181 +
      +
      Connecting to 127.0.0.1:2181
      +
      Welcome to ZooKeeper!
      +
      JLine support is enabled
      +
      + [zk: 127.0.0.1:2181(CONNECTED) 0] create /myapp "config_data" +
      +
      Created /myapp
      +
      + [zk: 127.0.0.1:2181(CONNECTED) 1] get /myapp +
      +
      config_data
      +
      + [zk: 127.0.0.1:2181(CONNECTED) 2] ls / +
      +
      [myapp, zookeeper]
      +
      + [zk: 127.0.0.1:2181(CONNECTED) 3]{" "} + +
      +
      +
      +
      +
      +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/index.tsx b/zookeeper-website/app/pages/_landing/home/index.tsx new file mode 100644 index 00000000000..4727e14e75a --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/index.tsx @@ -0,0 +1,33 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { Hero } from "@/pages/_landing/home/hero"; +import { FeaturesSection } from "@/pages/_landing/home/features"; +import { CommunitySection } from "@/pages/_landing/home/community"; +import { UseCasesSection } from "@/pages/_landing/home/use-cases"; + +export function HomePage() { + return ( + <> + + + + + + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/integrations.tsx b/zookeeper-website/app/pages/_landing/home/integrations.tsx new file mode 100644 index 00000000000..0f7aa61b62b --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/integrations.tsx @@ -0,0 +1,64 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +export function IntegrationsSection() { + const items = [ + { + title: "Hadoop Ecosystem", + desc: "Runs on HDFS and integrates with MapReduce, Spark, and other ecosystem tools." + }, + { + title: "Observability", + desc: "Metrics via Hadoop metrics subsystem, JMX export, and production-ready operations." + }, + { + title: "Access Layers", + desc: "Client access via Java API, REST, and Thrift gateways for flexible integration." + } + ]; + return ( +
      +
      +

      + Built to Integrate +

      +

      + Designed to fit naturally within your Hadoop-based data platform. +

      +
      +
      + {items.map((item) => ( +
      +

      + {item.title} +

      +

      + {item.desc} +

      +
      + ))} +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/home/use-cases.tsx b/zookeeper-website/app/pages/_landing/home/use-cases.tsx new file mode 100644 index 00000000000..908faba47a2 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/home/use-cases.tsx @@ -0,0 +1,98 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + Crown, + Database, + GitBranch, + Lock, + Network, + Waypoints +} from "lucide-react"; + +export function UseCasesSection() { + const items = [ + { + title: "Leader Election", + desc: "Elect a single master among distributed workers reliably using ephemeral znodes and watches.", + Icon: Crown + }, + { + title: "Distributed Locking", + desc: "Implement mutexes and read/write locks across cluster nodes without a single point of failure.", + Icon: Lock + }, + { + title: "Service Discovery", + desc: "Register and look up live service instances dynamically as nodes join or leave the cluster.", + Icon: Network + }, + { + title: "Configuration Management", + desc: "Propagate config changes to all nodes instantly with watches — no polling required.", + Icon: Database + }, + { + title: "Cluster Membership", + desc: "Track which nodes are alive in real time using ephemeral nodes and group membership recipes.", + Icon: Waypoints + }, + { + title: "Barrier Synchronization", + desc: "Coordinate phased computations so all workers start and finish a phase together.", + Icon: GitBranch + } + ]; + return ( +
      +
      +
      +

      + Use Cases +

      +

      + Common patterns and distributed systems problems where ZooKeeper + excels. +

      +
      +
      + {items.map(({ title, desc, Icon }) => ( +
      +
      +
      + +
      +
      +

      + {title} +

      +

      + {desc} +

      +
      +
      +
      + ))} +
      +
      +
      + ); +} diff --git a/zookeeper-website/app/pages/_landing/irc/content.md b/zookeeper-website/app/pages/_landing/irc/content.md new file mode 100644 index 00000000000..abc652be2f0 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/irc/content.md @@ -0,0 +1,30 @@ + + +# IRC Channel + +The Apache ZooKeeper community uses IRC for real-time chat and informal discussion. + +## Channel + +**Server:** `irc.libera.chat` +**Channel:** `#zookeeper` + +## Connecting + +The IRC channel can be used for online discussion about zookeeper related stuff, but developers should be careful to transfer all the official decisions or useful discussions to the issue tracking system. diff --git a/zookeeper-website/app/pages/_landing/irc/index.tsx b/zookeeper-website/app/pages/_landing/irc/index.tsx new file mode 100644 index 00000000000..e20bde1ad2b --- /dev/null +++ b/zookeeper-website/app/pages/_landing/irc/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function IrcPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/landing-layout.tsx b/zookeeper-website/app/pages/_landing/landing-layout.tsx new file mode 100644 index 00000000000..1fd10fe89de --- /dev/null +++ b/zookeeper-website/app/pages/_landing/landing-layout.tsx @@ -0,0 +1,33 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { GettingStartedSection } from "@/components/getting-started"; +import { SiteFooter } from "@/components/site-footer"; +import { SiteNavbar } from "@/components/site-navbar"; +import { Outlet } from "react-router"; + +export default function LandingLayout() { + return ( + <> + + + + + + ); +} diff --git a/zookeeper-website/app/pages/_landing/mailing-lists/content.md b/zookeeper-website/app/pages/_landing/mailing-lists/content.md new file mode 100644 index 00000000000..3c08266e552 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/mailing-lists/content.md @@ -0,0 +1,79 @@ + + +# ZooKeeper Mailing Lists + +## Users + +If you use ZooKeeper, please subscribe to the ZooKeeper user mailing list. + +The ZooKeeper user mailing list is: [user@zookeeper.apache.org](mailto:user@zookeeper.apache.org) + +- [Archives](https://mail-archives.apache.org/mod_mbox/zookeeper-user/) +- [Alternative Archives](https://lists.apache.org/list.html?user@zookeeper.apache.org) +- [Older Archives (Hadoop, pre-TLP)](https://mail-archives.apache.org/mod_mbox/hadoop-zookeeper-user/) +- [Subscribe to List](mailto:user-subscribe@zookeeper.apache.org) +- [Unsubscribe from List](mailto:user-unsubscribe@zookeeper.apache.org) + +> In order to post to the list, it is necessary to first subscribe to it. + +## Developers + +If you'd like to contribute to ZooKeeper, please subscribe to the ZooKeeper developer mailing list. + +This mailing list is for general developer chat and announcements. All notifications are sent to other mailing lists (see below). The only exception are new Jira issues which will still be sent to this list. + +The ZooKeeper developer mailing list is: [dev@zookeeper.apache.org](mailto:dev@zookeeper.apache.org) + +- [Archives](https://mail-archives.apache.org/mod_mbox/zookeeper-dev/) +- [Alternative Archives](https://lists.apache.org/list.html?dev@zookeeper.apache.org) +- [Older Archives (Hadoop, pre-TLP)](https://mail-archives.apache.org/mod_mbox/hadoop-zookeeper-dev/) +- [Subscribe to List](mailto:dev-subscribe@zookeeper.apache.org) +- [Unsubscribe from List](mailto:dev-unsubscribe@zookeeper.apache.org) + +> In order to post to the list, it is necessary to first subscribe to it. + +## Commits + +If you'd like to see changes made in ZooKeeper's version control system then subscribe to the ZooKeeper commit mailing list. + +- [Archives](https://mail-archives.apache.org/mod_mbox/zookeeper-commits/) +- [Alternative Archives](https://lists.apache.org/list.html?commits@zookeeper.apache.org) +- [Older Archives (Hadoop, pre-TLP)](https://mail-archives.apache.org/mod_mbox/hadoop-zookeeper-commits/) +- [Subscribe to List](mailto:commits-subscribe@zookeeper.apache.org) +- [Unsubscribe from List](mailto:commits-unsubscribe@zookeeper.apache.org) + +## Jira Notifications + +If you'd like to see notification mails for all changes made to Jira tickets then subscribe to the ZooKeeper issues mailing list. + +> Notifications for the creation of new issues will also be sent to the `dev` mailing list. + +- [Archives](https://lists.apache.org/list.html?issues@zookeeper.apache.org) +- [Alternative Archives](https://mail-archives.apache.org/mod_mbox/zookeeper-issues/) +- [Subscribe to List](mailto:issues-subscribe@zookeeper.apache.org) +- [Unsubscribe from List](mailto:issues-unsubscribe@zookeeper.apache.org) + +## Git Notifications + +If you'd like to see notification mails for all non-commit related Git things (e.g. Pull Request comments) then subscribe to the ZooKeeper notifications mailing list. + +- [Archives](https://lists.apache.org/list.html?notifications@zookeeper.apache.org) +- [Alternative Archives](https://mail-archives.apache.org/mod_mbox/zookeeper-notifications/) +- [Subscribe to List](mailto:notifications-subscribe@zookeeper.apache.org) +- [Unsubscribe from List](mailto:notifications-unsubscribe@zookeeper.apache.org) diff --git a/zookeeper-website/app/pages/_landing/mailing-lists/index.tsx b/zookeeper-website/app/pages/_landing/mailing-lists/index.tsx new file mode 100644 index 00000000000..ca15bf806f0 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/mailing-lists/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function MailingListsPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/news/content.md b/zookeeper-website/app/pages/_landing/news/content.md new file mode 100644 index 00000000000..e58805f01ee --- /dev/null +++ b/zookeeper-website/app/pages/_landing/news/content.md @@ -0,0 +1,647 @@ + + +# News + +--- + +**6 Mar, 2026: release 3.9.5 available** + +This is a bugfix release for 3.9 branch. + +See [ZooKeeper 3.9.5 Release Notes](https://zookeeper.apache.org/doc/r3.9.5/releasenotes.html) for details. + +--- + +**12 Feb, 2026: release 3.8.6 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.6 Release Notes](https://zookeeper.apache.org/doc/r3.8.6/releasenotes.html) for details. + +--- + +**18 Sep, 2025: release 3.8.5 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.5 Release Notes](https://zookeeper.apache.org/doc/r3.8.5/releasenotes.html) for details. + +--- + +**29 Aug, 2025: release 3.9.4 available** + +This is a bugfix release for 3.9 branch. + +See [ZooKeeper 3.9.4 Release Notes](https://zookeeper.apache.org/doc/r3.9.4/releasenotes.html) for details. + +--- + +**24 Oct, 2024: release 3.9.3 available** + +This is a bugfix release for 3.9 branch. + +See [ZooKeeper 3.9.3 Release Notes](https://zookeeper.apache.org/doc/r3.9.3/releasenotes.html) for details. + +--- + +**12 Mar, 2024: release 3.9.2 available** + +This is a bugfix release for 3.9 branch. + +See [ZooKeeper 3.9.2 Release Notes](https://zookeeper.apache.org/doc/r3.9.2/releasenotes.html) for details. + +--- + +**5 Mar, 2024: release 3.8.4 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.4 Release Notes](https://zookeeper.apache.org/doc/r3.8.4/releasenotes.html) for details. + +--- + +**2 February, 2024: Apache ZooKeeper 3.7 End-of-Life** + +The Apache ZooKeeper community would like to make the official announcement of 3.7 release line End-of-Life. It will be effective on 2nd of February, 2024 00:01 AM (PDT). From that day forward the 3.7 version of Apache ZooKeeper won't be supported by the community which means we won't: + +- accept patches on the 3.7.x branch, +- run automated tests on any JDK version, +- create new releases from 3.7.x branch, +- resolve security issues, CVEs or critical bugs. + +Latest released version of Apache ZooKeeper 3.7 (currently 3.7.2) will be available on the download page for another year (until 2nd of February, 2025), after that it will be accessible among other historical versions from Apache Archives. + +**Upgrade** + +We recommend users of Apache ZooKeeper 3.7 to plan your production upgrades according to the following supported upgrade path: + +1. Upgrade to latest 3.8.x version +2. (Optional) Upgrade to latest 3.9.x version. + +Please find known upgrade issues and workarounds on the following wiki page: [Upgrade FAQ](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Upgrade+FAQ). + +In addition to that the user@ mailing list is open 24/7 to help and answer your questions as usual. + +**Compatibility** + +Our backward compatibility rules still apply and can be found here: [Backward compatibility rules](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Backward+compatibility+rules). + +Following the recommended upgrade path with rolling upgrade process ZooKeeper quorum will be available at all times as long as clients are not starting to use new features. + +--- + +**9 Oct, 2023: release 3.9.1 available** + +This is a bugfix release for 3.9 branch. + +See [ZooKeeper 3.9.1 Release Notes](https://zookeeper.apache.org/doc/r3.9.1/releasenotes.html) for details. + +--- + +**9 Oct, 2023: release 3.8.3 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.3 Release Notes](https://zookeeper.apache.org/doc/r3.8.3/releasenotes.html) for details. + +--- + +**9 Oct, 2023: release 3.7.2 available** + +This is a bugfix release for 3.7 branch. + +See [ZooKeeper 3.7.2 Release Notes](https://zookeeper.apache.org/doc/r3.7.2/releasenotes.html) for details. + +--- + +**3 Aug, 2023: release 3.9.0 available** + +This is the first release for the 3.9 branch. It is a major release and it introduces a lot of new features, most notably: + +- Admin server API for taking snapshot and stream out the data +- Communicate the Zxid that triggered a WatchEvent to fire +- TLS — dynamic loading for client trust/key store +- Add Netty-TcNative OpenSSL Support +- Adding SSL support to Zktreeutil +- Improve syncRequestProcessor performance +- Updates to all the third party dependencies to get rid of every known CVE. + +ZooKeeper clients from 3.5.x onwards are fully compatible with 3.9.x servers. The upgrade from 3.7.x and 3.8.x can be executed as usual, no particular additional upgrade procedure is needed. ZooKeeper 3.9.x clients are compatible with 3.5.x, 3.6.x, 3.7.x and 3.8.x servers as long as you are not using new APIs not present in these versions. + +See [ZooKeeper 3.9.0 Release Notes](https://zookeeper.apache.org/doc/r3.9.0/releasenotes.html) for details. + +Latest stable version of ZooKeeper is now 3.8.2. + +--- + +**18 Jul, 2023: release 3.8.2 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.2 Release Notes](https://zookeeper.apache.org/doc/r3.8.2/releasenotes.html) for details. + +--- + +**30 Jan, 2023: release 3.8.1 available** + +This is a bugfix release for 3.8 branch. + +See [ZooKeeper 3.8.1 Release Notes](https://zookeeper.apache.org/doc/r3.8.1/releasenotes.html) for details. + +--- + +**30 December, 2022: release 3.6.4 available** + +This is the last bugfix release for 3.6 branch, as 3.6 is EoL since 30th December, 2022. It fixes 42 issues, including CVE fixes, log4j1 removal (using reload4j from now) and various other bug fixes (e.g. snapshotting, SASL and C client related fixes). + +See [ZooKeeper 3.6.4 Release Notes](https://zookeeper.apache.org/doc/r3.6.4/releasenotes.html) for details. + +--- + +**30 December, 2022: Apache ZooKeeper 3.6 End-of-Life** + +The Apache ZooKeeper community would like to make the official announcement of 3.6 release line End-of-Life. It will be effective on 30th of December, 2022 00:01 AM (PDT). From that day forward the 3.6 version of Apache ZooKeeper won't be supported by the community which means we won't: + +- accept patches on the 3.6.x branch, +- run automated tests on any JDK version, +- create new releases from 3.6.x branch, +- resolve security issues, CVEs or critical bugs. + +Latest released version of Apache ZooKeeper 3.6 (currently 3.6.4) will be available on the download page for another year (until 30th of December, 2023), after that it will be accessible among other historical versions from Apache Archives. + +**Upgrade** + +We recommend users of Apache ZooKeeper 3.6 to plan your production upgrades according to the following supported upgrade path: + +1. Upgrade to latest 3.7.x version +2. Upgrade to latest 3.8.x version +3. (Optional) Upgrade to latest 3.9.x version. + +Please find known upgrade issues and workarounds on the following wiki page: [Upgrade FAQ](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Upgrade+FAQ). + +In addition to that the user@ mailing list is open 24/7 to help and answer your questions as usual. + +**Compatibility** + +Our backward compatibility rules still apply and can be found here: [Backward compatibility rules](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Backward+compatibility+rules). + +Following the recommended upgrade path with rolling upgrade process ZooKeeper quorum will be available at all times as long as clients are not starting to use new features. + +--- + +**4 June, 2022: release 3.5.10 available** + +This is the last bugfix release for 3.5 branch, as 3.5 is EoL since 1st June, 2022. It fixes 44 issues, including CVE fixes, log4j1 removal (using reload4j from now) and various other bug fixes (thread leaks, data corruption, snapshotting and SASL related fixes). + +See [ZooKeeper 3.5.10 Release Notes](https://zookeeper.apache.org/doc/r3.5.10/releasenotes.html) for details. + +--- + +**1 June, 2022: Apache ZooKeeper 3.5 End-of-Life** + +The Apache ZooKeeper community would like to make the official announcement of 3.5 release line End-of-Life. It will be effective on 1st of June, 2022 00:01 AM (PDT). From that day forward the 3.5 version of Apache ZooKeeper won't be supported by the community which means we won't: + +- accept patches on the 3.5.x branch, +- run automated tests on any JDK version, +- create new releases from 3.5.x branch, +- resolve security issues, CVEs or critical bugs. + +Latest released version of Apache ZooKeeper 3.5 (currently 3.5.9) will be available on the download page for another year (until 1st of June, 2023), after that it will be accessible among other historical versions from Apache Archives. + +**Upgrade** + +We recommend users of Apache ZooKeeper 3.5 to plan your production upgrades according to the following supported upgrade path: + +1. Upgrade to latest 3.5.x version +2. Upgrade to latest 3.6.x version +3. (Optional) Upgrade to latest 3.7.x version. + +Please find known upgrade issues and workarounds on the following wiki page: [Upgrade FAQ](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Upgrade+FAQ). + +In addition to that the user@ mailing list is open 24/7 to help and answer your questions as usual. + +**Compatibility** + +Our backward compatibility rules still apply and can be found here: [Backward compatibility rules](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Backward+compatibility+rules). + +Following the recommended upgrade path with rolling upgrade process ZooKeeper quorum will be available at all times as long as clients are not starting to use new features. + +--- + +**12 May, 2022: release 3.7.1 available** + +This is a bugfix release for 3.7 branch. It fixes 64 issues, including multiple CVE fixes. + +See [ZooKeeper 3.7.1 Release Notes](https://zookeeper.apache.org/doc/r3.7.1/releasenotes.html) for details. + +--- + +**7 March, 2022: release 3.8.0 available** + +This is the first release for the 3.8 branch. It is a major release and it introduces a lot of new features, most notably: + +- Migration of the logging framework from Apache Log4j1 to LogBack +- Read Key/Trust store password from file (and other security related improvements) +- Restored support for OSGI +- Reduced the performance impact of Prometheus metrics +- Official support for JDK17 (all tests are passing) +- Updates to all the third party dependencies to get rid of every known CVE. + +ZooKeeper clients from 3.5.x onwards are fully compatible with 3.8.x servers. The upgrade from 3.6.x and 3.7.x can be executed as usual, no particular additional upgrade procedure is needed. ZooKeeper 3.8.x clients are compatible with 3.5.x, 3.6.x and 3.7.x servers as long as you are not using new APIs not present in these versions. + +See [ZooKeeper 3.8.0 Release Notes](https://zookeeper.apache.org/doc/r3.8.0/releasenotes.html) for details. + +--- + +**13 April, 2021: release 3.6.3 available** + +This is a bugfix release for 3.6 branch. It fixes 52 issues, including multiple CVE fixes. + +See [ZooKeeper 3.6.3 Release Notes](https://zookeeper.apache.org/doc/r3.6.3/releasenotes.html) for details. + +--- + +**27 March, 2021: release 3.7.0 available** + +This is the first release for the 3.7 branch. It introduces a number of new features, notably: + +- An API to start a ZooKeeper server from Java ([ZOOKEEPER-3874](https://issues.apache.org/jira/browse/ZOOKEEPER-3874)) +- Quota enforcement ([ZOOKEEPER-3301](https://issues.apache.org/jira/browse/ZOOKEEPER-3301)) +- Host name canonicalization in quorum SASL authentication ([ZOOKEEPER-4030](https://issues.apache.org/jira/browse/ZOOKEEPER-4030)) +- Support for BCFKS key/trust store format ([ZOOKEEPER-3950](https://issues.apache.org/jira/browse/ZOOKEEPER-3950)) +- A choice of mandatory authentication scheme(s) ([ZOOKEEPER-3561](https://issues.apache.org/jira/browse/ZOOKEEPER-3561)) +- A "whoami" API and CLI command ([ZOOKEEPER-3969](https://issues.apache.org/jira/browse/ZOOKEEPER-3969)) +- The possibility of disabling digest authentication ([ZOOKEEPER-3979](https://issues.apache.org/jira/browse/ZOOKEEPER-3979)) +- Multiple SASL "superUsers" ([ZOOKEEPER-3959](https://issues.apache.org/jira/browse/ZOOKEEPER-3959)) +- Fast-tracking of throttled requests ([ZOOKEEPER-3683](https://issues.apache.org/jira/browse/ZOOKEEPER-3683)) +- Additional security metrics ([ZOOKEEPER-3978](https://issues.apache.org/jira/browse/ZOOKEEPER-3978)) +- SASL support in the C and Perl clients ([ZOOKEEPER-1112](https://issues.apache.org/jira/browse/ZOOKEEPER-1112), [ZOOKEEPER-3714](https://issues.apache.org/jira/browse/ZOOKEEPER-3714)) +- A new zkSnapshotComparer.sh tool ([ZOOKEEPER-3427](https://issues.apache.org/jira/browse/ZOOKEEPER-3427)) +- Notes on how to benchmark ZooKeeper with the YCSB tool ([ZOOKEEPER-3264](https://issues.apache.org/jira/browse/ZOOKEEPER-3264)) + +ZooKeeper clients from the 3.5 and 3.6 branches are fully compatible with 3.7 servers. The upgrade from 3.6.x to 3.7.0 can be executed as usual, no particular additional upgrade procedure is needed. ZooKeeper 3.7.0 clients are compatible with 3.5 and 3.6 servers as long as you are not using new APIs not present in these versions. + +See [ZooKeeper 3.7.0 Release Notes](https://zookeeper.apache.org/doc/r3.7.0/releasenotes.html) for details. + +--- + +**15 January, 2021: release 3.5.9 available** + +This is a bugfix release for 3.5 branch. It fixes 25 issues, including multiple CVE fixes. + +See [ZooKeeper 3.5.9 Release Notes](https://zookeeper.apache.org/doc/r3.5.9/releasenotes.html) for details. + +--- + +**9 September, 2020: release 3.6.2 available** + +This is a bugfix release for 3.6 branch. It is a minor release and it fixes a few critical issues and brings a few dependencies upgrades. + +See [ZooKeeper 3.6.2 Release Notes](https://zookeeper.apache.org/doc/r3.6.2/releasenotes.html) for details. + +--- + +**11 May, 2020: release 3.5.8 available** + +This is a bugfix release for 3.5 branch. It fixes 24 issues, including third party CVE fixes, several leader-election related fixes and a compatibility issue with applications built against earlier 3.5 client libraries (by restoring a few non public APIs). + +See [ZooKeeper 3.5.8 Release Notes](https://zookeeper.apache.org/doc/r3.5.8/releasenotes.html) for details. + +--- + +**30 April, 2020: release 3.6.1 available** + +This is the second release for 3.6 branch. It is a bugfix release and it fixes a few compatibility issues with applications built for ZooKeeper 3.5. The upgrade from 3.5.7 to 3.6.1 can be executed as usual, no particular additional upgrade procedure is needed. ZooKeeper 3.6.1 clients are compatible with 3.5 servers as long as you are not using new APIs not present in 3.5. + +See [ZooKeeper 3.6.1 Release Notes](https://zookeeper.apache.org/doc/r3.6.1/releasenotes.html) for details. + +--- + +**4 March, 2020: release 3.6.0 available** + +This is the first release for 3.6 branch. It comes with lots of new features and improvements around performance and security. It is also introducing new APIs on the client side. ZooKeeper clients from 3.4 and 3.5 branch are fully compatible with 3.6 servers. The upgrade from 3.5.7 to 3.6.0 can be executed as usual, no particular additional upgrade procedure is needed. ZooKeeper 3.6.0 clients are compatible with 3.5 servers as long as you are not using new APIs not present in 3.5. + +See [ZooKeeper 3.6.0 Release Notes](https://zookeeper.apache.org/doc/r3.6.0/releasenotes.html) for details. + +--- + +**14 February, 2020: release 3.5.7 available** + +This is a bugfix release for 3.5 branch. It fixes 25 issues, including third party CVE fixes, potential data loss and potential split brain if some rare conditions exist. + +See [ZooKeeper 3.5.7 Release Notes](https://zookeeper.apache.org/doc/r3.5.7/releasenotes.html) for details. + +--- + +**19 October, 2019: release 3.5.6 available** + +This is a bugfix release for 3.5 branch. It fixes 29 issues, including CVE fixes, hostname resolve issue and possible memory leak. + +See [ZooKeeper 3.5.6 Release Notes](https://zookeeper.apache.org/doc/r3.5.6/releasenotes.html) for details. + +--- + +**20 May, 2019: release 3.5.5 available** + +First stable version of 3.5 branch. This release is considered to be the successor of 3.4 stable branch and recommended for production use. It contains 950 commits, resolves 744 issues, fixes 470 bugs and includes the following new features: + +- Dynamic reconfiguration +- Local sessions +- New node types: Container, TTL +- SSL support for Atomic Broadcast Protocol +- Ability to remove watchers +- Multi-threaded commit processor +- Upgraded to Netty 4.1 +- Maven build +- Various performance and stability improvements. + +Please also note: + +- Minimum recommended JDK version is now 1.8 +- Release artifacts have been changed considerably: `apache-zookeeper-X.Y.Z.tar.gz` is standard source-only release; `apache-zookeeper-X.Y.Z-bin.tar.gz` is the convenience tarball which contains the binaries. + +See [ZooKeeper 3.5.5 Release Notes](https://zookeeper.apache.org/doc/r3.5.5/releasenotes.html) for details. + +--- + +**2 April, 2019: release 3.4.14 available** + +This is a bugfix release. It fixes 8 issues, mostly build / unit tests issues, dependency updates flagged by OWASP, NPE and a name resolution problem. Among these it also supports experimental Maven build and Markdown based documentation generation. + +See [ZooKeeper 3.4.14 Release Notes](https://zookeeper.apache.org/doc/r3.4.14/releasenotes.html) for details. + +--- + +**15 July, 2018: release 3.4.13 available** + +This is a bugfix release. It fixes 17 issues, including issues such as ZOOKEEPER-2959 that could cause data loss when observer is used, and ZOOKEEPER-2184 that prevents ZooKeeper Java clients working in dynamic IP (container / cloud) environment. + +See [ZooKeeper 3.4.13 Release Notes](https://zookeeper.apache.org/doc/r3.4.13/releasenotes.html) for details. + +--- + +**17 May, 2018: release 3.5.4-beta available** + +3.5.4-beta is the second beta in the planned 3.5 release line leading up to a stable 3.5 release. It comprises 113 bug fixes and improvements. + +Release 3.5.3 added a new feature ZOOKEEPER-2169 "Enable creation of nodes with TTLs". There was a major oversight when TTL nodes were implemented. The session ID generator for each server is seeded with the configured Server ID in the high byte. TTL Nodes were using the highest bit to denote a TTL node when used in the ephemeral owner. This meant that Server IDs > 127 that created ephemeral nodes would have those nodes always considered TTL nodes (with the TTL being essentially a random number). ZOOKEEPER-2901 fixes the issue. By default TTL is disabled and must now be enabled in `zoo.cfg`. When TTL Nodes are enabled, the max Server ID changes from 255 to 254. + +--- + +**1 May, 2018: release 3.4.12 available** + +This release fixes 22 issues, including issues that affect incorrect handling of the `dataDir` and the `dataLogDir`. + +See [ZooKeeper 3.4.12 Release Notes](https://zookeeper.apache.org/doc/r3.4.12/releasenotes.html) for details. + +--- + +**9 November, 2017: release 3.4.11 available** + +This release fixes 53 issues, it includes support for Java 9 and other critical bug fixes. + +> **WARNING:** ZOOKEEPER-2960 was recently identified as a regression in 3.4.11 affecting the specification of separate `dataDir` and `dataLogDir` configuration parameters. It will be addressed in 3.4.12. + +See [ZooKeeper 3.4.11 Release Notes](https://zookeeper.apache.org/doc/r3.4.11/releasenotes.html) for details. + +--- + +**17 April, 2017: release 3.5.3-beta available** + +3.5.3-beta is the first beta in the planned 3.5 release line leading up to a stable 3.5 release. It comprises 76 bug fixes and improvements. This release includes important security fix around dynamic reconfigure API, improvements on test infrastructure, and new features such as TTL node. + +--- + +**30 March, 2017: release 3.4.10 available** + +This release fixes 43 issues, including security feature QuorumPeer mutual authentication via SASL and other critical bugs. + +See [ZooKeeper 3.4.10 Release Notes](https://zookeeper.apache.org/doc/r3.4.10/releasenotes.html) for details. + +--- + +**3 September, 2016: release 3.4.9 available** + +This release fixes many critical bugs and improvements. + +See [ZooKeeper 3.4.9 Release Notes](https://zookeeper.apache.org/doc/r3.4.9/releasenotes.html) for details. + +--- + +**20 July, 2016: release 3.5.2-alpha available** + +This is an alpha quality release that contains many bug fixes and improvements. + +--- + +**20 February, 2016: release 3.4.8 available** + +This release fixes 9 issues, most notably a deadlock when shutting down ZooKeeper. + +See [ZooKeeper 3.4.8 Release Notes](https://zookeeper.apache.org/doc/r3.4.8/releasenotes.html) for details. + +--- + +**31 August, 2015: release 3.5.1-alpha available** + +This is an alpha quality release that contains many bug fixes and improvements. It also introduces a few new features, including container znodes and SSL support for client-server communication. + +See [ZooKeeper 3.5.1-alpha Release Notes](https://zookeeper.apache.org/doc/r3.5.1-alpha/releasenotes.html) for details. + +--- + +**6 August, 2014: release 3.5.0-alpha available** + +This release is alpha quality and contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.5.0-alpha Release Notes](https://zookeeper.apache.org/doc/r3.5.0-alpha/releasenotes.html) for details. + +--- + +**10 March, 2014: release 3.4.6 available** + +The release fixes a critical bug that could prevent a server from joining an established ensemble. + +See [ZooKeeper 3.4.6 Release Notes](https://zookeeper.apache.org/doc/r3.4.6/releasenotes.html) for details. + +--- + +**18 November, 2012: release 3.4.5 available** + +The release fixes a critical bug that could cause client connection issues. + +See [ZooKeeper 3.4.5 Release Notes](https://zookeeper.apache.org/doc/r3.4.5/releasenotes.html) for details. + +--- + +**23 September, 2012: release 3.4.4 available** + +The release fixes a critical bug that could cause data inconsistency. + +See [ZooKeeper 3.4.4 Release Notes](https://zookeeper.apache.org/doc/r3.4.4/releasenotes.html) for details. + +--- + +**2 August, 2012: release 3.3.6 available** + +The release fixes a critical bug that could cause data loss. + +See [ZooKeeper 3.3.6 Release Notes](https://zookeeper.apache.org/doc/r3.3.6/releasenotes.html) for details. + +--- + +**20 March, 2012: release 3.3.5 available** + +The release fixes a critical bug that could cause data corruption. + +See [ZooKeeper 3.3.5 Release Notes](https://zookeeper.apache.org/doc/r3.3.5/releasenotes.html) for details. + +--- + +**13 Feb, 2012: release 3.4.3 available** + +This release fixes critical bugs in 3.4.2. + +See [ZooKeeper 3.4.3 Release Notes](https://zookeeper.apache.org/doc/r3.4.3/releasenotes.html) for details. + +--- + +**29 Dec, 2011: release 3.4.2 available** + +This release fixes a critical bug in 3.4.1. + +See [ZooKeeper 3.4.2 Release Notes](https://zookeeper.apache.org/doc/r3.4.2/releasenotes.html) for details. + +--- + +**16 Dec, 2011: release 3.4.1 available** + +This release fixes a critical bug with data loss in 3.4.0. + +See [ZooKeeper 3.4.1 Release Notes](https://zookeeper.apache.org/doc/r3.4.1/releasenotes.html) for details. + +--- + +**26 Nov, 2011: release 3.3.4 available** + +The release fixes a number of critical bugs that could cause data corruption. + +See [ZooKeeper 3.3.4 Release Notes](https://zookeeper.apache.org/doc/r3.3.4/releasenotes.html) for details. + +--- + +**22 Nov, 2011: release 3.4.0 available** + +Due to data loss issues, this release has been removed from the downloads page. Release 3.4.1 is now available. + +--- + +**27 Feb, 2011: release 3.3.3 available** + +The release fixes two critical bugs that could cause data corruption. It also addresses 12 other issues. + +See [ZooKeeper 3.3.3 Release Notes](https://zookeeper.apache.org/doc/r3.3.3/releasenotes.html) for details. + +--- + +**11 Nov, 2010: release 3.3.2 available** + +This release contains a number of critical bug fixes. + +See [ZooKeeper 3.3.2 Release Notes](https://zookeeper.apache.org/doc/r3.3.2/releasenotes.html) for details. + +--- + +**17 May, 2010: release 3.3.1 available** + +This release contains a number of critical bug fixes. + +See [ZooKeeper 3.3.1 Release Notes](https://zookeeper.apache.org/doc/r3.3.1/releasenotes.html) for details. + +--- + +**25 March, 2010: release 3.3.0 available** + +This release contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.3.0 Release Notes](https://zookeeper.apache.org/doc/r3.3.0/releasenotes.html) for details. + +--- + +**14 December, 2009: release 3.2.2 available** + +This release contains a number of critical bug fixes. + +See [ZooKeeper 3.2.2 Release Notes](https://zookeeper.apache.org/doc/r3.2.2/releasenotes.html) for details. + +--- + +**14 December, 2009: release 3.1.2 available** + +This release contains a number of critical bug fixes. + +See [ZooKeeper 3.1.2 Release Notes](https://zookeeper.apache.org/doc/r3.1.2/releasenotes.html) for details. + +--- + +**4 September, 2009: release 3.2.1 available** + +This release contains a number of critical bug fixes. + +See [ZooKeeper 3.2.1 Release Notes](https://zookeeper.apache.org/doc/r3.2.1/releasenotes.html) for details. + +--- + +**8 July, 2009: release 3.2.0 available** + +This release contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.2.0 Release Notes](https://zookeeper.apache.org/doc/r3.2.0/releasenotes.html) for details. + +--- + +**27 March, 2009: release 3.1.1 available** + +This release contains a small number of bug fixes. + +See [ZooKeeper 3.1.1 Release Notes](https://zookeeper.apache.org/doc/r3.1.1/releasenotes.html) for details. + +--- + +**13 February, 2009: release 3.1.0 available** + +This release contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.1.0 Release Notes](https://zookeeper.apache.org/doc/r3.1.0/releasenotes.html) for details. + +--- + +**4 December, 2008: release 3.0.1 available** + +This release contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.0.1 Release Notes](https://zookeeper.apache.org/doc/r3.0.1/releasenotes.html) for details. + +--- + +**27 October, 2008: release 3.0.0 available** + +This release contains many improvements, new features, bug fixes and optimizations. + +See [ZooKeeper 3.0.0 Release Notes](https://zookeeper.apache.org/doc/r3.0.0/releasenotes.html) for details. diff --git a/zookeeper-website/app/pages/_landing/news/index.tsx b/zookeeper-website/app/pages/_landing/news/index.tsx new file mode 100644 index 00000000000..dcb9164efbe --- /dev/null +++ b/zookeeper-website/app/pages/_landing/news/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function NewsPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/releases/content.md b/zookeeper-website/app/pages/_landing/releases/content.md new file mode 100644 index 00000000000..f9b045141e8 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/releases/content.md @@ -0,0 +1,67 @@ + + +# Apache ZooKeeper™ Releases + +The Apache ZooKeeper system for distributed coordination is a high-performance service for building distributed applications. + +## Release Strategy + +The Apache ZooKeeper community supports two release branches at a time: **stable** and **current**. + +- The **current** version is **3.9.x** +- The **stable** version is **3.8.x** + +Once a new minor version is released, the previous stable version is expected to be decommissioned within approximately six months, during which only security and critical fixes are provided. After End-of-Life is announced, no further patches are provided by the community. All ZooKeeper releases remain accessible from the [official Apache Archives](https://archive.apache.org/dist/zookeeper/). + +## Download + +Apache ZooKeeper **3.9.5** is our current release, and **3.8.6** our latest stable release. + +The keys used to sign releases can be found in our published [KEYS](https://downloads.apache.org/zookeeper/KEYS) file. See [Verifying Apache Software Foundation Releases](https://www.apache.org/info/verification.html) for how to verify your downloads. + +### Apache ZooKeeper 3.9.5 (Current) + +- [apache-zookeeper-3.9.5-bin.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5-bin.tar.gz) + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5-bin.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5-bin.tar.gz.sha512)) +- [apache-zookeeper-3.9.5.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5.tar.gz) _(source)_ + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.9.5/apache-zookeeper-3.9.5.tar.gz.sha512)) + +### Apache ZooKeeper 3.8.6 (Latest Stable) + +- [apache-zookeeper-3.8.6-bin.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz) + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6-bin.tar.gz.sha512)) +- [apache-zookeeper-3.8.6.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6.tar.gz) _(source)_ + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.8.6/apache-zookeeper-3.8.6.tar.gz.sha512)) + +### Apache ZooKeeper 3.7.2 (End-of-Life since 2 Feb 2024) + +- [apache-zookeeper-3.7.2-bin.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2-bin.tar.gz) + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2-bin.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2-bin.tar.gz.sha512)) +- [apache-zookeeper-3.7.2.tar.gz](https://www.apache.org/dyn/closer.lua/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2.tar.gz) _(source)_ + ([asc](https://downloads.apache.org/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2.tar.gz.asc), + [sha512](https://downloads.apache.org/zookeeper/zookeeper-3.7.2/apache-zookeeper-3.7.2.tar.gz.sha512)) + +--- + +Older releases are available in the [Apache Archive](https://archive.apache.org/dist/zookeeper/). diff --git a/zookeeper-website/app/pages/_landing/releases/index.tsx b/zookeeper-website/app/pages/_landing/releases/index.tsx new file mode 100644 index 00000000000..6da4399adc3 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/releases/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function ReleasesPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/security/content.md b/zookeeper-website/app/pages/_landing/security/content.md new file mode 100644 index 00000000000..6b5e9680635 --- /dev/null +++ b/zookeeper-website/app/pages/_landing/security/content.md @@ -0,0 +1,265 @@ + + +# ZooKeeper Security + +The Apache Software Foundation takes security issues very seriously. Due to the infrastructure nature of the Apache ZooKeeper project specifically, we haven't had many reports over time, but it doesn't mean that we haven't had concerns over some bugs and vulnerabilities. If you have any concern or believe you have uncovered a vulnerability, we suggest that you get in touch via the e-mail address [security@zookeeper.apache.org](mailto:security@zookeeper.apache.org?Subject=[SECURITY]%20My%20security%20issue). In the message, try to provide a description of the issue and ideally a way of reproducing it. Note that this security address should be used only for undisclosed vulnerabilities. Dealing with known issues should be handled regularly via jira and the mailing lists. **Please report any security problems to the project security address before disclosing it publicly.** + +The ASF Security team maintains a page with a description of how vulnerabilities are handled, check their [Web page](https://www.apache.org/security/) for more information. + +## Vulnerability reports + +- [CVE-2026-24308](#cve-2026-24308) +- [CVE-2026-24281](#cve-2026-24281) +- [CVE-2025-58457](#cve-2025-58457) +- [CVE-2024-51504](#cve-2024-51504) +- [CVE-2024-23944](#cve-2024-23944) +- [CVE-2023-44981](#cve-2023-44981) +- [CVE-2019-0201](#cve-2019-0201) +- [CVE-2018-8012](#cve-2018-8012) +- [CVE-2017-5637](#cve-2017-5637) +- [CVE-2016-5017](#cve-2016-5017) + +--- + +### CVE-2026-24308 + +**Sensitive information disclosure in client configuration handling** + +**Severity:** important + +**Affected versions:** + +- Apache ZooKeeper (org.apache.zookeeper:zookeeper) 3.9.0 through 3.9.4 +- Apache ZooKeeper (org.apache.zookeeper:zookeeper) 3.8.0 through 3.8.5 + +**Description:** + +Improper handling of configuration values in ZKConfig in Apache ZooKeeper 3.8.5 and 3.9.4 on all platforms allows an attacker to expose sensitive information stored in client configuration in the client's logfile. Configuration values are exposed at INFO level logging rendering potential production systems affected by the issue. Users are recommended to upgrade to version 3.8.6 or 3.9.5 which fixes this issue. + +**Credit:** Youlong Chen (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2026-24308](https://www.cve.org/CVERecord?id=CVE-2026-24308) + +--- + +### CVE-2026-24281 + +**Reverse-DNS fallback enables hostname verification bypass in ZooKeeper ZKTrustManager** + +**Severity:** important + +**Affected versions:** + +- Apache ZooKeeper (org.apache.zookeeper:zookeeper) 3.9.0 through 3.9.4 +- Apache ZooKeeper (org.apache.zookeeper:zookeeper) 3.8.0 through 3.8.5 + +**Description:** + +Hostname verification in Apache ZooKeeper ZKTrustManager falls back to reverse DNS (PTR) when IP SAN validation fails, allowing attackers who control or spoof PTR records to impersonate ZooKeeper servers or clients with a valid certificate for the PTR name. It's important to note that attacker must present a certificate which is trusted by ZKTrustManager which makes the attack vector harder to exploit. Users are recommended to upgrade to version 3.8.6 or 3.9.5, which fixes this issue by introducing a new configuration option to disable reverse DNS lookup in client and quorum protocols. + +This issue is being tracked as [ZOOKEEPER-4986](https://issues.apache.org/jira/browse/ZOOKEEPER-4986). + +**Credit:** Nikita Markevich (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2026-24281](https://www.cve.org/CVERecord?id=CVE-2026-24281) · [ZOOKEEPER-4986](https://issues.apache.org/jira/browse/ZOOKEEPER-4986) + +--- + +### CVE-2025-58457 + +**Insufficient Permission Check in AdminServer Snapshot/Restore Commands** + +**Severity:** moderate + +**Affected versions:** + +- Apache ZooKeeper (org.apache.zookeeper:zookeeper) 3.9.0 before 3.9.4 + +**Description:** + +Improper permission check in ZooKeeper AdminServer lets authorized clients to run `snapshot` and `restore` command with insufficient permissions. + +This issue affects Apache ZooKeeper: from 3.9.0 before 3.9.4. Users are recommended to upgrade to version 3.9.4, which fixes the issue. + +The issue can be mitigated by disabling both commands (via `admin.snapshot.enabled` and `admin.restore.enabled`), disabling the whole AdminServer interface (via `admin.enableServer`), or ensuring that the root ACL does not provide open permissions. (Note that ZooKeeper ACLs are not recursive, so this does not impact operations on child nodes besides notifications from recursive watches.) + +**Credit:** Damien Diederen (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2025-58457](https://www.cve.org/CVERecord?id=CVE-2025-58457) + +--- + +### CVE-2024-51504 + +**Authentication bypass with IP-based authentication in Admin Server** + +**Severity:** important + +**Affected versions:** + +- Apache ZooKeeper 3.9.0 before 3.9.3 + +**Description:** + +When using IPAuthenticationProvider in ZooKeeper Admin Server there is a possibility of Authentication Bypass by Spoofing — this only impacts IP based authentication implemented in ZooKeeper Admin Server. Default configuration of client's IP address detection in IPAuthenticationProvider, which uses HTTP request headers, is weak and allows an attacker to bypass authentication via spoofing client's IP address in request headers. Default configuration honors `X-Forwarded-For` HTTP header to read client's IP address. `X-Forwarded-For` request header is mainly used by proxy servers to identify the client and can be easily spoofed by an attacker pretending that the request comes from a different IP address. Admin Server commands, such as snapshot and restore arbitrarily can be executed on successful exploitation which could potentially lead to information leakage or service availability issues. Users are recommended to upgrade to version 3.9.3, which fixes this issue. + +**Credit:** 4ra1n (reporter), Y4tacker (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2024-51504](https://www.cve.org/CVERecord?id=CVE-2024-51504) + +--- + +### CVE-2024-23944 + +**Information disclosure in persistent watcher handling** + +**Severity:** critical + +**Affected versions:** + +- Apache ZooKeeper 3.9.0 through 3.9.1 +- Apache ZooKeeper 3.8.0 through 3.8.3 +- Apache ZooKeeper 3.6.0 through 3.7.2 + +**Description:** + +Information disclosure in persistent watchers handling in Apache ZooKeeper due to missing ACL check. It allows an attacker to monitor child znodes by attaching a persistent watcher (`addWatch` command) to a parent which the attacker has already access to. ZooKeeper server doesn't do ACL check when the persistent watcher is triggered and as a consequence, the full path of znodes that a watch event gets triggered upon is exposed to the owner of the watcher. It's important to note that only the path is exposed by this vulnerability, not the data of znode, but since znode path can contain sensitive information like user name or login ID, this issue is potentially critical. + +Users are recommended to upgrade to version 3.9.2 or 3.8.4 which fixes the issue. + +**Credit:** 周吉安(寒泉) (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2024-23944](https://www.cve.org/CVERecord?id=CVE-2024-23944) + +--- + +### CVE-2023-44981 + +**Authorization bypass in SASL Quorum Peer Authentication** + +**Severity:** critical + +**Affected versions:** + +- Apache ZooKeeper 3.9.0 +- Apache ZooKeeper 3.8.0 through 3.8.2 +- Apache ZooKeeper 3.7.0 through 3.7.1 +- Apache ZooKeeper before 3.7.0 + +**Description:** + +Authorization Bypass Through User-Controlled Key vulnerability in Apache ZooKeeper. If SASL Quorum Peer authentication is enabled in ZooKeeper (`quorum.auth.enableSasl=true`), the authorization is done by verifying that the instance part in SASL authentication ID is listed in `zoo.cfg` server list. The instance part in SASL auth ID is optional and if it's missing, like `eve@EXAMPLE.COM`, the authorization check will be skipped. As a result an arbitrary endpoint could join the cluster and begin propagating counterfeit changes to the leader, essentially giving it complete read-write access to the data tree. Quorum Peer authentication is not enabled by default. + +Users are recommended to upgrade to version 3.9.1, 3.8.3, or 3.7.2, which fixes the issue. + +Alternately ensure the ensemble election/quorum communication is protected by a firewall as this will mitigate the issue. + +See the documentation for more details on correct cluster administration. + +**Credit:** Damien Diederen (reporter) + +**References:** [https://www.cve.org/CVERecord?id=CVE-2023-44981](https://www.cve.org/CVERecord?id=CVE-2023-44981) + +--- + +### CVE-2019-0201 + +**Information disclosure vulnerability in Apache ZooKeeper** + +**Severity:** Critical + +**Vendor:** The Apache Software Foundation + +**Versions Affected:** ZooKeeper prior to 3.4.14; ZooKeeper 3.5.0-alpha through 3.5.4-beta. The unsupported ZooKeeper 1.x through 3.3.x versions may be also affected. + +**Description:** ZooKeeper's `getACL()` command doesn't check any permission when retrieves the ACLs of the requested node and returns all information contained in the ACL Id field as plaintext string. DigestAuthenticationProvider overloads the Id field with the hash value that is used for user authentication. As a consequence, if Digest Authentication is in use, the unsalted hash value will be disclosed by `getACL()` request for unauthenticated or unprivileged users. + +**Mitigation:** Use an authentication method other than Digest (e.g. Kerberos) or upgrade to 3.4.14 or later (3.5.5 or later if on the 3.5 branch). + +**Credit:** This issue was identified by Harrison Neal, PatchAdvisor, Inc. + +**References:** [https://issues.apache.org/jira/browse/ZOOKEEPER-1392](https://issues.apache.org/jira/browse/ZOOKEEPER-1392) + +--- + +### CVE-2018-8012 + +**Apache ZooKeeper Quorum Peer mutual authentication** + +**Severity:** Critical + +**Vendor:** The Apache Software Foundation + +**Versions Affected:** ZooKeeper prior to 3.4.10; ZooKeeper 3.5.0-alpha through 3.5.3-beta. The unsupported ZooKeeper 1.x through 3.3.x versions may be also affected. + +**Description:** No authentication/authorization is enforced when a server attempts to join a quorum. As a result an arbitrary end point could join the cluster and begin propagating counterfeit changes to the leader. + +**Mitigation:** Upgrade to 3.4.10 or later (3.5.4-beta or later if on the 3.5 branch) and enable Quorum Peer mutual authentication. + +Alternately ensure the ensemble election/quorum communication is protected by a firewall as this will mitigate the issue. + +See the documentation for more details on correct cluster administration. + +**Credit:** This issue was identified by Földi Tamás and Eugene Koontz. + +**References:** [ZOOKEEPER-1045](https://issues.apache.org/jira/browse/ZOOKEEPER-1045) · [Server-Server mutual authentication](https://cwiki.apache.org/confluence/display/ZOOKEEPER/Server-Server+mutual+authentication) · [ZooKeeper Admin Guide](https://zookeeper.apache.org/doc/current/zookeeperAdmin.html) + +--- + +### CVE-2017-5637 + +**DOS attack on wchp/wchc four letter words (4lw)** + +**Severity:** moderate + +**Vendor:** The Apache Software Foundation + +**Versions Affected:** ZooKeeper 3.4.0 to 3.4.9; ZooKeeper 3.5.0 to 3.5.2. The unsupported ZooKeeper 1.x through 3.3.x versions may be also affected. Note: The 3.5 branch was still beta at this time. + +**Description:** Two four letter word commands "wchp/wchc" are CPU intensive and could cause spike of CPU utilization on ZooKeeper server if abused, which leads to the server unable to serve legitimate client requests. There is no known compromise which takes advantage of this vulnerability. + +**Mitigation:** This affects ZooKeeper ensembles whose client port is publicly accessible, so it is recommended to protect ZooKeeper ensemble with firewall. Documentation has also been updated to clarify on this point. In addition, a patch ([ZOOKEEPER-2693](https://issues.apache.org/jira/browse/ZOOKEEPER-2693)) is provided to disable "wchp/wchc" commands by default. + +- ZooKeeper 3.4.x users should upgrade to 3.4.10 or apply the patch. +- ZooKeeper 3.5.x users should upgrade to 3.5.3 or apply the patch. + +**References:** [ZOOKEEPER-2693](https://issues.apache.org/jira/browse/ZOOKEEPER-2693) + +--- + +### CVE-2016-5017 + +**Buffer overflow vulnerability in ZooKeeper C cli shell** + +**Severity:** moderate + +**Vendor:** The Apache Software Foundation + +**Versions Affected:** ZooKeeper 3.4.0 to 3.4.8; ZooKeeper 3.5.0 to 3.5.2. The unsupported ZooKeeper 1.x through 3.3.x versions may be also affected. Note: The 3.5 branch was still alpha at this time. + +**Description:** The ZooKeeper C client shells "cli_st" and "cli_mt" have a buffer overflow vulnerability associated with parsing of the input command when using the `cmd:` batch mode syntax. If the command string exceeds 1024 characters a buffer overflow will occur. There is no known compromise which takes advantage of this vulnerability, and if security is enabled the attacker would be limited by client level security constraints. The C cli shell is intended as a sample/example of how to use the C client interface, not as a production tool — the documentation has also been clarified on this point. + +**Mitigation:** It is important to use the fully featured/supported Java cli shell rather than the C cli shell independent of version. + +- ZooKeeper 3.4.x users should upgrade to 3.4.9 or apply this [patch](https://gitbox.apache.org/repos/asf?p=zookeeper.git;a=commitdiff;h=27ecf981a15554dc8e64a28630af7a5c9e2bdf4f). +- ZooKeeper 3.5.x users should upgrade to 3.5.3 when released or apply this [patch](https://gitbox.apache.org/repos/asf?p=zookeeper.git;a=commitdiff;h=f09154d6648eeb4ec5e1ac8a2bacbd2f8c87c14a). + +The patch solves the problem reported here, but it does not make the client ready for production use. The community has no plan to make this client production ready at this time, and strongly recommends that users move to the Java cli and use the C cli for illustration purposes only. + +**Credit:** This issue was discovered by Lyon Yang (@l0Op3r). diff --git a/zookeeper-website/app/pages/_landing/security/index.tsx b/zookeeper-website/app/pages/_landing/security/index.tsx new file mode 100644 index 00000000000..1de04933ace --- /dev/null +++ b/zookeeper-website/app/pages/_landing/security/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function SecurityPage() { + return ; +} diff --git a/zookeeper-website/app/pages/_landing/version-control/content.md b/zookeeper-website/app/pages/_landing/version-control/content.md new file mode 100644 index 00000000000..0a15a4ba98b --- /dev/null +++ b/zookeeper-website/app/pages/_landing/version-control/content.md @@ -0,0 +1,33 @@ + + +# Version Control + +Apache ZooKeeper™ uses [Git](https://git-scm.com/) to manage its source code. + +## Web Browser Access + +All commits and releases are done on this repository. + +``` +https://gitbox.apache.org/repos/asf?p=zookeeper.git +``` + +[Browse the repository](https://gitbox.apache.org/repos/asf?p=zookeeper.git) + +A GitHub mirror is also available at [https://github.com/apache/zookeeper](https://github.com/apache/zookeeper). diff --git a/zookeeper-website/app/pages/_landing/version-control/index.tsx b/zookeeper-website/app/pages/_landing/version-control/index.tsx new file mode 100644 index 00000000000..fc6bfaff61d --- /dev/null +++ b/zookeeper-website/app/pages/_landing/version-control/index.tsx @@ -0,0 +1,24 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { MdLayout } from "@/components/mdx-components"; +import Content from "./content.md"; + +export function VersionControlPage() { + return ; +} diff --git a/zookeeper-website/app/root.tsx b/zookeeper-website/app/root.tsx new file mode 100644 index 00000000000..49b8877dbfd --- /dev/null +++ b/zookeeper-website/app/root.tsx @@ -0,0 +1,127 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { + isRouteErrorResponse, + Links, + Meta, + Outlet, + Scripts, + ScrollRestoration +} from "react-router"; + +import type { Route } from "./+types/root"; +import appStyles from "./app.css?url"; +import "katex/dist/katex.css"; +import { ThemeProvider } from "./lib/theme-provider"; + +export const links: Route.LinksFunction = () => [ + { + rel: "preload", + as: "font", + href: "/fonts/inter-latin-wght-normal.woff2", + type: "font/woff2", + crossOrigin: "anonymous" + }, + { + rel: "prefetch", + as: "font", + href: "/fonts/inter-latin-wght-italic.woff2", + type: "font/woff2", + crossOrigin: "anonymous" + }, + { rel: "stylesheet", href: appStyles }, + { rel: "icon", href: "/images/logo.svg", type: "image/svg+xml" }, + { rel: "icon", href: "/favicon.ico", sizes: "any" } +]; + +export function Layout({ children }: { children: React.ReactNode }) { + return ( + + + + + + +

      404

      Page not found

      The page you are looking for doesn't exist. The website was updated recently, so the route you were trying to visit might have changed.

      Go back home
      \ No newline at end of file diff --git a/zookeeper-docs/src/main/resources/markdown/images/2pc.jpg b/zookeeper-website/public/docs-images/2pc.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/2pc.jpg rename to zookeeper-website/public/docs-images/2pc.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/bk-overview.jpg b/zookeeper-website/public/docs-images/bk-overview.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/bk-overview.jpg rename to zookeeper-website/public/docs-images/bk-overview.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/favicon.ico b/zookeeper-website/public/docs-images/favicon.ico similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/favicon.ico rename to zookeeper-website/public/docs-images/favicon.ico diff --git a/zookeeper-docs/src/main/resources/markdown/images/state_dia.dia b/zookeeper-website/public/docs-images/state_dia.dia similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/state_dia.dia rename to zookeeper-website/public/docs-images/state_dia.dia diff --git a/zookeeper-docs/src/main/resources/markdown/images/state_dia.jpg b/zookeeper-website/public/docs-images/state_dia.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/state_dia.jpg rename to zookeeper-website/public/docs-images/state_dia.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkAuditLogs.jpg b/zookeeper-website/public/docs-images/zkAuditLogs.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkAuditLogs.jpg rename to zookeeper-website/public/docs-images/zkAuditLogs.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkarch.jpg b/zookeeper-website/public/docs-images/zkarch.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkarch.jpg rename to zookeeper-website/public/docs-images/zkarch.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkcomponents.jpg b/zookeeper-website/public/docs-images/zkcomponents.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkcomponents.jpg rename to zookeeper-website/public/docs-images/zkcomponents.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zknamespace.jpg b/zookeeper-website/public/docs-images/zknamespace.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zknamespace.jpg rename to zookeeper-website/public/docs-images/zknamespace.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkperfRW-3.2.jpg b/zookeeper-website/public/docs-images/zkperfRW-3.2.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkperfRW-3.2.jpg rename to zookeeper-website/public/docs-images/zkperfRW-3.2.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkperfRW.jpg b/zookeeper-website/public/docs-images/zkperfRW.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkperfRW.jpg rename to zookeeper-website/public/docs-images/zkperfRW.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkperfreliability.jpg b/zookeeper-website/public/docs-images/zkperfreliability.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkperfreliability.jpg rename to zookeeper-website/public/docs-images/zkperfreliability.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zkservice.jpg b/zookeeper-website/public/docs-images/zkservice.jpg similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zkservice.jpg rename to zookeeper-website/public/docs-images/zkservice.jpg diff --git a/zookeeper-docs/src/main/resources/markdown/images/zookeeper_small.gif b/zookeeper-website/public/docs-images/zookeeper_small.gif similarity index 100% rename from zookeeper-docs/src/main/resources/markdown/images/zookeeper_small.gif rename to zookeeper-website/public/docs-images/zookeeper_small.gif diff --git a/zookeeper-website/public/favicon.ico b/zookeeper-website/public/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..a19f0471504f5a8322540927f58eea36df5c5260 GIT binary patch literal 32038 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
      bJve#&c?4vRB6dur+Goe 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 F{{U2~?qC1_ literal 0 HcmV?d00001 diff --git a/zookeeper-website/public/fonts/inter-latin-wght-italic.woff2 b/zookeeper-website/public/fonts/inter-latin-wght-italic.woff2 new file mode 100644 index 0000000000000000000000000000000000000000..2f06c65192b03b43e343717cc24fafb0e36e87a1 GIT binary patch literal 51832 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∾Na#*TBTU(!jF?9zmR-!C*+RdvGrd0&{`| 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Apache ZooKeeper logo + + + + image/svg+xml + + Apache ZooKeeper logo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/zookeeper-website/public/images/large-logo.svg b/zookeeper-website/public/images/large-logo.svg new file mode 100644 index 00000000000..cc09f5786a9 --- /dev/null +++ b/zookeeper-website/public/images/large-logo.svg @@ -0,0 +1,182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Apache ZooKeeper logo + + + + image/svg+xml + + Apache ZooKeeper logo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/zookeeper-website/public/images/logo.svg b/zookeeper-website/public/images/logo.svg new file mode 100644 index 00000000000..a281babc319 --- /dev/null +++ b/zookeeper-website/public/images/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/zookeeper-website/react-router.config.ts b/zookeeper-website/react-router.config.ts new file mode 100644 index 00000000000..32cc487b5b2 --- /dev/null +++ b/zookeeper-website/react-router.config.ts @@ -0,0 +1,36 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { Config } from '@react-router/dev/config'; +import { glob } from 'node:fs/promises'; +import { createGetUrl, getSlugs } from 'fumadocs-core/source'; + +const getUrl = createGetUrl('/docs'); + +export default { + // Config options... + // Server-side render by default, to enable SPA mode set this to `false` + ssr: false, + async prerender({ getStaticPaths }) { + const paths: string[] = [...getStaticPaths()]; + for await (const entry of glob("**/*.mdx", { cwd: "app/pages/_docs/docs/_mdx" })) { + paths.push(getUrl(getSlugs(entry))); + } + return paths; + } +} satisfies Config; diff --git a/zookeeper-website/source.config.ts b/zookeeper-website/source.config.ts new file mode 100644 index 00000000000..45b5f7c6990 --- /dev/null +++ b/zookeeper-website/source.config.ts @@ -0,0 +1,42 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { defineConfig, defineDocs } from "fumadocs-mdx/config"; +import remarkGfm from "remark-gfm"; +import rehypeKatex from "rehype-katex"; +import remarkMath from "remark-math"; + +export const docs = defineDocs({ + dir: "app/pages/_docs/docs/_mdx", + docs: { + files: ["**/*.mdx"], // ← only index .mdx + postprocess: { + includeProcessedMarkdown: true + } + }, + meta: { + files: ["**/*.{json,yaml}"] + } +}); + +export default defineConfig({ + mdxOptions: { + remarkPlugins: (v) => [remarkMath, remarkGfm, ...v], + rehypePlugins: (v) => [rehypeKatex, ...v] + } +}); diff --git a/zookeeper-website/tsconfig.json b/zookeeper-website/tsconfig.json new file mode 100644 index 00000000000..d2587b9b194 --- /dev/null +++ b/zookeeper-website/tsconfig.json @@ -0,0 +1,27 @@ +{ + "include": ["**/*", "**/.server/**/*", "**/.client/**/*", ".react-router/types/**/*", "**/*.d.ts"], + "compilerOptions": { + "lib": ["DOM", "DOM.Iterable", "ES2023"], + "types": ["node", "vite/client"], + "target": "ES2022", + "module": "ES2022", + "moduleResolution": "bundler", + "jsx": "react-jsx", + "rootDirs": [".", "./.react-router/types"], + "baseUrl": ".", + "paths": { + "@/.source": [".source"], + "@/*": ["app/*"] + }, + "esModuleInterop": true, + "verbatimModuleSyntax": true, + "noEmit": true, + "resolveJsonModule": true, + "skipLibCheck": true, + "strict": true, + + /* Linting */ + "noUnusedLocals": false, + "noUnusedParameters": false + } +} diff --git a/zookeeper-website/unit-tests/home.test.tsx b/zookeeper-website/unit-tests/home.test.tsx new file mode 100644 index 00000000000..5937960e2ca --- /dev/null +++ b/zookeeper-website/unit-tests/home.test.tsx @@ -0,0 +1,93 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, it, expect } from "vitest"; +import { screen } from "@testing-library/react"; +import { renderWithProviders } from "./utils"; +import { HomePage } from "@/pages/_landing/home"; + +describe("HomePage", () => { + it("renders the hero section with main heading", () => { + renderWithProviders(); + + const heading = screen.getByRole("heading", { + name: /The standard for distributed coordination/i + }); + expect(heading).toBeInTheDocument(); + }); + + it("displays the Apache ZooKeeper logo", () => { + renderWithProviders(); + + const logos = screen.getAllByAltText(/Apache ZooKeeper logo/i); + expect(logos.length).toBeGreaterThan(0); + }); + + it("shows the main description text", () => { + renderWithProviders(); + + const description = screen.getByText( + /Naming, configuration management, synchronization/i + ); + expect(description).toBeInTheDocument(); + }); + + it("displays Download button", () => { + renderWithProviders(); + + const downloadButton = screen.getByRole("link", { + name: /^Download$/i + }); + expect(downloadButton).toBeInTheDocument(); + expect(downloadButton).toHaveAttribute("href", "/releases"); + }); + + it("displays Read Documentation button", () => { + renderWithProviders(); + + const docsButton = screen.getByRole("link", { + name: /Read Documentation/i + }); + expect(docsButton).toBeInTheDocument(); + }); + + it("renders the features section", () => { + renderWithProviders(); + + // Check for key feature headings + expect(screen.getByText("High Performance")).toBeInTheDocument(); + expect(screen.getByText("Simple & Reliable")).toBeInTheDocument(); + }); + + it("renders use cases section", () => { + renderWithProviders(); + + // Check for use cases section by ID + const useCases = document.querySelector("#use-cases"); + expect(useCases).toBeInTheDocument(); + }); + + it("renders community section", () => { + renderWithProviders(); + + // Look for a heading specific to the community section + expect( + screen.getByRole("heading", { name: /Vibrant Community/i }) + ).toBeInTheDocument(); + }); +}); diff --git a/zookeeper-website/unit-tests/markdown.test.tsx b/zookeeper-website/unit-tests/markdown.test.tsx new file mode 100644 index 00000000000..ec2276c06fc --- /dev/null +++ b/zookeeper-website/unit-tests/markdown.test.tsx @@ -0,0 +1,184 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import React from "react"; +import { describe, it, expect } from "vitest"; +import { screen } from "@testing-library/react"; +import { renderWithProviders } from "./utils"; +import { getMDXComponents, MdLayout } from "@/components/mdx-components"; + +describe("MDX Components", () => { + describe("getMDXComponents", () => { + it("returns MDX components configuration", () => { + const components = getMDXComponents(); + + expect(components).toHaveProperty("h1"); + expect(components).toHaveProperty("h2"); + expect(components).toHaveProperty("h3"); + expect(components).toHaveProperty("p"); + expect(components).toHaveProperty("a"); + expect(components).toHaveProperty("ul"); + expect(components).toHaveProperty("ol"); + expect(components).toHaveProperty("li"); + expect(components).toHaveProperty("blockquote"); + expect(components).toHaveProperty("table"); + }); + + it("accepts overrides", () => { + const customH1 = () =>

      Custom

      ; + const components = getMDXComponents({ h1: customH1 }); + + expect(components.h1).toBe(customH1); + }); + }); + + describe("Heading Components", () => { + it("renders h1 with correct styling", () => { + const components = getMDXComponents(); + const H1 = components.h1 as React.ComponentType; + + renderWithProviders(

      Heading 1

      ); + + const heading = screen.getByRole("heading", { level: 1 }); + expect(heading).toHaveTextContent("Heading 1"); + expect(heading).toBeInTheDocument(); + }); + + it("renders h2 with correct styling", () => { + const components = getMDXComponents(); + const H2 = components.h2 as React.ComponentType; + + renderWithProviders(

      Heading 2

      ); + + const heading = screen.getByRole("heading", { level: 2 }); + expect(heading).toHaveTextContent("Heading 2"); + expect(heading).toBeInTheDocument(); + }); + + it("renders h3 with correct styling", () => { + const components = getMDXComponents(); + const H3 = components.h3 as React.ComponentType; + + renderWithProviders(

      Heading 3

      ); + + const heading = screen.getByRole("heading", { level: 3 }); + expect(heading).toHaveTextContent("Heading 3"); + expect(heading).toBeInTheDocument(); + }); + }); + + describe("Link Component", () => { + it("renders internal links without target blank", () => { + const components = getMDXComponents(); + const A = components.a as React.ComponentType; + + renderWithProviders(      Internal Link); + + const link = screen.getByRole("link", { name: "Internal Link" }); + expect(link).toHaveAttribute("href", "/docs/test"); + expect(link).not.toHaveAttribute("target", "_blank"); + }); + + it("renders external links with target blank and icon", () => { + const components = getMDXComponents(); + const A = components.a as React.ComponentType; + + renderWithProviders(External Link); + + const link = screen.getByRole("link", { name: /External Link/i }); + expect(link).toHaveAttribute("href", "https://example.com"); + expect(link).toHaveAttribute("target", "_blank"); + expect(link).toHaveAttribute("rel", "noopener noreferrer"); + }); + + it("treats zookeeper.apache.org links as internal", () => { + const components = getMDXComponents(); + const A = components.a as React.ComponentType; + + renderWithProviders( + Apache Link + ); + + const link = screen.getByRole("link", { name: "Apache Link" }); + expect(link).not.toHaveAttribute("target", "_blank"); + }); + }); + + describe("Image Component", () => { + it("renders images with lazy loading", () => { + const components = getMDXComponents(); + const Img = components.img as React.ComponentType; + + renderWithProviders(Test image); + + const img = screen.getByAltText("Test image"); + expect(img).toHaveAttribute("src", "/test.png"); + expect(img).toHaveAttribute("loading", "lazy"); + }); + }); + + describe("MdLayout", () => { + it("renders MDX content with layout wrapper", () => { + const MockContent = ({ components }: any) => { + const H1 = components.h1 as React.ComponentType; + const P = components.p as React.ComponentType; + return ( + <> +

      Test Title

      +

      Test content

      + + ); + }; + + renderWithProviders(); + + expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent( + "Test Title" + ); + expect(screen.getByText("Test content")).toBeInTheDocument(); + }); + + it("applies custom className", () => { + const MockContent = () =>
      Content
      ; + + const { container } = renderWithProviders( + + ); + + expect(container.querySelector(".custom-class")).toBeInTheDocument(); + }); + + it("passes overrides to getMDXComponents", () => { + const CustomH1 = ({ children }: any) => ( +

      {children}

      + ); + const MockContent = ({ components }: any) => { + const H1 = components.h1 as React.ComponentType; + return

      Custom Heading

      ; + }; + + renderWithProviders( + + ); + + expect(screen.getByTestId("custom-h1")).toHaveTextContent( + "Custom Heading" + ); + }); + }); +}); diff --git a/zookeeper-website/unit-tests/navigation.test.tsx b/zookeeper-website/unit-tests/navigation.test.tsx new file mode 100644 index 00000000000..f8da8455c74 --- /dev/null +++ b/zookeeper-website/unit-tests/navigation.test.tsx @@ -0,0 +1,138 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, it, expect, beforeEach } from "vitest"; +import { screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { renderWithProviders } from "./utils"; +import { SiteNavbar } from "@/components/site-navbar"; +import { projectLinks, asfLinks } from "@/components/links"; + +describe("SiteNavbar", () => { + beforeEach(() => { + // Add js class to enable JavaScript-specific menus + document.documentElement.classList.add("js"); + }); + + it("renders the navbar with logo", () => { + renderWithProviders(); + + const logo = screen.getByAltText(/Apache ZooKeeper logo/i); + expect(logo).toBeInTheDocument(); + }); + + it("logo links to home", () => { + renderWithProviders(); + + const logo = screen.getByAltText(/Apache ZooKeeper logo/i); + const logoLink = logo.closest("a"); + expect(logoLink).toHaveAttribute("href", "/"); + }); + + it("displays project menu trigger", () => { + renderWithProviders(); + + // There are multiple buttons (JS and no-JS), so use getAllByRole + const projectMenus = screen.getAllByRole("button", { + name: /Apache ZooKeeper Project/i + }); + expect(projectMenus.length).toBeGreaterThan(0); + }); + + it("displays documentation menu trigger", () => { + renderWithProviders(); + + // There are multiple buttons (JS and no-JS), so use getAllByRole + const docsMenus = screen.getAllByRole("button", { + name: /^Documentation$/i + }); + expect(docsMenus.length).toBeGreaterThan(0); + }); + + it("displays ASF menu trigger", () => { + renderWithProviders(); + + // There are multiple buttons (JS and no-JS), so use getAllByRole + const asfMenus = screen.getAllByRole("button", { name: /ASF/i }); + expect(asfMenus.length).toBeGreaterThan(0); + }); + + it("opens project dropdown menu and shows links", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + // Get the first project menu button (for desktop JS version) + const projectMenus = screen.getAllByRole("button", { + name: /Apache ZooKeeper Project/i + }); + await user.click(projectMenus[0]); + + // Check that first few project links from links.ts are present + expect( + screen.getByRole("menuitem", { name: projectLinks[0].label }) + ).toBeInTheDocument(); + expect( + screen.getByRole("menuitem", { name: projectLinks[1].label }) + ).toBeInTheDocument(); + expect( + screen.getByRole("menuitem", { name: projectLinks[3].label }) + ).toBeInTheDocument(); + }); + + it("opens documentation dropdown menu", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + const docsMenus = screen.getAllByRole("button", { + name: /^Documentation$/i + }); + await user.click(docsMenus[0]); + + // Check for documentation links + const docLinks = screen.getAllByRole("menuitem", { + name: /Issue Tracking/i + }); + expect(docLinks.length).toBeGreaterThan(0); + }); + + it("opens ASF dropdown menu and shows links", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + const asfMenus = screen.getAllByRole("button", { name: /ASF/i }); + await user.click(asfMenus[0]); + + // Check first two ASF links from asfLinks + expect( + screen.getByRole("menuitem", { name: asfLinks[0].label }) + ).toBeInTheDocument(); + expect( + screen.getByRole("menuitem", { name: asfLinks[1].label }) + ).toBeInTheDocument(); + }); + + it("includes theme toggle", () => { + renderWithProviders(); + + // Multiple theme toggles (desktop and mobile), so use getAllByRole + const themeToggles = screen.getAllByRole("button", { + name: /Toggle theme/i + }); + expect(themeToggles.length).toBeGreaterThan(0); + }); +}); diff --git a/zookeeper-website/unit-tests/older-docs-picker.test.tsx b/zookeeper-website/unit-tests/older-docs-picker.test.tsx new file mode 100644 index 00000000000..1da6fa23e65 --- /dev/null +++ b/zookeeper-website/unit-tests/older-docs-picker.test.tsx @@ -0,0 +1,187 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, it, expect } from "vitest"; +import { screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { renderWithProviders } from "./utils"; +import { OlderDocsPicker } from "@/components/docs/older-docs-picker"; +import { + RELEASED_DOC_VERSIONS, + sortVersionsDesc +} from "@/lib/released-docs-versions"; + +describe("sortVersionsDesc", () => { + it("sorts stable versions newest first", () => { + const result = sortVersionsDesc(["3.7.0", "3.9.0", "3.8.0"]); + expect(result).toEqual(["3.9.0", "3.8.0", "3.7.0"]); + }); + + it("sorts patch versions correctly", () => { + const result = sortVersionsDesc(["3.8.1", "3.8.10", "3.8.2"]); + expect(result).toEqual(["3.8.10", "3.8.2", "3.8.1"]); + }); + + it("places stable releases above pre-releases of the same base", () => { + const result = sortVersionsDesc([ + "3.5.0-alpha", + "3.5.0-beta" as string, + "3.5.0" + ]); + // stable > beta > alpha for the same version + expect(result[0]).toBe("3.5.0"); + expect(result[2]).toBe("3.5.0-alpha"); + }); + + it("sorts alpha before beta for same base version", () => { + const result = sortVersionsDesc(["3.5.4-beta", "3.5.0-alpha"]); + expect(result[0]).toBe("3.5.4-beta"); + expect(result[1]).toBe("3.5.0-alpha"); + }); +}); + +describe("RELEASED_DOC_VERSIONS", () => { + it("is a non-empty array of strings", () => { + expect(Array.isArray(RELEASED_DOC_VERSIONS)).toBe(true); + expect(RELEASED_DOC_VERSIONS.length).toBeGreaterThan(0); + }); + + it("starts with the highest version", () => { + const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); + expect(RELEASED_DOC_VERSIONS[0]).toBe(sorted[0]); + }); + + it("ends with the lowest version", () => { + const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); + expect(RELEASED_DOC_VERSIONS[RELEASED_DOC_VERSIONS.length - 1]).toBe( + sorted[sorted.length - 1] + ); + }); + + it("is already sorted newest to oldest", () => { + const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); + expect(RELEASED_DOC_VERSIONS).toEqual(sorted); + }); +}); + +describe("OlderDocsPicker", () => { + it("renders the trigger button", () => { + renderWithProviders(); + expect( + screen.getByRole("button", { name: /older docs/i }) + ).toBeInTheDocument(); + }); + + it("does not show the version list before the button is clicked", () => { + renderWithProviders(); + expect(screen.queryByRole("listbox")).not.toBeInTheDocument(); + }); + + it("opens the popover and shows a search combobox on trigger click", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + await waitFor(() => { + expect(screen.getByRole("combobox")).toBeInTheDocument(); + }); + }); + + it("shows all versions when popover is open", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + await waitFor(() => { + expect(screen.getByRole("listbox")).toBeInTheDocument(); + }); + + const items = screen.getAllByRole("option"); + expect(items.length).toBe(RELEASED_DOC_VERSIONS.length); + }); + + it("filters versions by search query", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + const input = await screen.findByRole("combobox"); + await user.type(input, "3.9"); + + await waitFor(() => { + const items = screen.getAllByRole("option"); + // Every visible option must match the search term + items.forEach((item) => { + expect(item.textContent?.trim()).toContain("3.9"); + }); + }); + }); + + it("shows 'No versions found' when search has no matches", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + const input = await screen.findByRole("combobox"); + await user.type(input, "99.99.99"); + + await waitFor(() => { + expect(screen.getByText(/no versions found/i)).toBeInTheDocument(); + }); + }); + + it("each version links to the correct /released-docs/ path", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + await waitFor(() => { + const items = screen.getAllByRole("option"); + expect(items.length).toBeGreaterThan(0); + items.forEach((item) => { + // With asChild, the IS the option element + expect(item.getAttribute("href")).toMatch( + /^\/released-docs\/r[\d.].+\/index\.html$/ + ); + }); + }); + }); + + it("clears search when popover is reopened", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + const trigger = screen.getByRole("button", { name: /older docs/i }); + + await user.click(trigger); + const input = await screen.findByRole("combobox"); + await user.type(input, "3.9"); + + // Close and reopen — Radix unmounts the popover content, resetting Command state + await user.keyboard("{Escape}"); + await user.click(trigger); + + const newInput = await screen.findByRole("combobox"); + expect(newInput).toHaveValue(""); + }); +}); diff --git a/zookeeper-website/unit-tests/released-docs-versions.test.ts b/zookeeper-website/unit-tests/released-docs-versions.test.ts new file mode 100644 index 00000000000..88f03b386c1 --- /dev/null +++ b/zookeeper-website/unit-tests/released-docs-versions.test.ts @@ -0,0 +1,104 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, it, expect } from "vitest"; +import { readdirSync } from "fs"; +import { resolve } from "path"; +import { RAW_RELEASED_DOC_VERSIONS } from "virtual:released-docs-versions"; +import { + RELEASED_DOC_VERSIONS, + sortVersionsDesc +} from "@/lib/released-docs-versions"; + +// Read the real filesystem so we can cross-check the virtual module output. +const RELEASED_DOCS_DIR = resolve(__dirname, "../public/released-docs"); +const ACTUAL_FOLDERS = readdirSync(RELEASED_DOCS_DIR, { withFileTypes: true }) + .filter((d) => d.isDirectory() && d.name.startsWith("r")) + .map((d) => d.name.slice(1)); // strip leading "r" + +describe("virtual:released-docs-versions plugin", () => { + it("exposes a non-empty array", () => { + expect(Array.isArray(RAW_RELEASED_DOC_VERSIONS)).toBe(true); + expect(RAW_RELEASED_DOC_VERSIONS.length).toBeGreaterThan(0); + }); + + it("matches exactly the directories present in public/released-docs/", () => { + expect(RAW_RELEASED_DOC_VERSIONS.slice().sort()).toEqual( + ACTUAL_FOLDERS.slice().sort() + ); + }); + + it("strips the leading 'r' prefix from every folder name", () => { + RAW_RELEASED_DOC_VERSIONS.forEach((v) => { + expect(v).not.toMatch(/^r/); + }); + }); + + it("contains no empty strings", () => { + RAW_RELEASED_DOC_VERSIONS.forEach((v) => { + expect(v.length).toBeGreaterThan(0); + }); + }); + + it("only includes directory entries, not loose files", () => { + // Every raw entry must correspond to a directory named r{version} + const folderSet = new Set(ACTUAL_FOLDERS); + RAW_RELEASED_DOC_VERSIONS.forEach((v) => { + expect(folderSet.has(v)).toBe(true); + }); + }); + + it("every entry looks like a valid version string", () => { + RAW_RELEASED_DOC_VERSIONS.forEach((v) => { + expect(v).toMatch(/^\d+\.\d+\.\d+/); + }); + }); +}); + +describe("RELEASED_DOC_VERSIONS (sorted output)", () => { + it("equals sortVersionsDesc applied to the raw virtual-module data", () => { + expect(RELEASED_DOC_VERSIONS).toEqual( + sortVersionsDesc(RAW_RELEASED_DOC_VERSIONS) + ); + }); + + it("contains the same entries as RAW_RELEASED_DOC_VERSIONS, just reordered", () => { + expect(RELEASED_DOC_VERSIONS.slice().sort()).toEqual( + RAW_RELEASED_DOC_VERSIONS.slice().sort() + ); + }); + + it("first entry is the numerically highest version", () => { + const [first, ...rest] = RELEASED_DOC_VERSIONS; + const refirst = sortVersionsDesc([first, ...rest])[0]; + expect(first).toBe(refirst); + }); + + it("last entry is the numerically lowest version", () => { + const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); + expect(RELEASED_DOC_VERSIONS.at(-1)).toBe(sorted.at(-1)); + }); + + it("each consecutive pair is in descending order", () => { + for (let i = 0; i < RELEASED_DOC_VERSIONS.length - 1; i++) { + const [a, b] = [RELEASED_DOC_VERSIONS[i], RELEASED_DOC_VERSIONS[i + 1]]; + const [first] = sortVersionsDesc([a, b]); + expect(first).toBe(a); + } + }); +}); diff --git a/zookeeper-website/unit-tests/setup.ts b/zookeeper-website/unit-tests/setup.ts new file mode 100644 index 00000000000..0be244d699b --- /dev/null +++ b/zookeeper-website/unit-tests/setup.ts @@ -0,0 +1,25 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import "@testing-library/jest-dom"; +import { cleanup } from "@testing-library/react"; +import { afterEach } from "vitest"; + +afterEach(() => { + cleanup(); +}); diff --git a/zookeeper-website/unit-tests/theme-toggle.test.tsx b/zookeeper-website/unit-tests/theme-toggle.test.tsx new file mode 100644 index 00000000000..fd6ac12fe18 --- /dev/null +++ b/zookeeper-website/unit-tests/theme-toggle.test.tsx @@ -0,0 +1,66 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, it, expect, beforeEach } from "vitest"; +import { screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { renderWithProviders } from "./utils"; +import { ThemeToggle } from "@/components/theme-toggle"; + +describe("ThemeToggle", () => { + beforeEach(() => { + localStorage.clear(); + }); + + it("renders the theme toggle button", () => { + renderWithProviders(); + + const button = screen.getByRole("button", { name: /Toggle theme/i }); + expect(button).toBeInTheDocument(); + }); + + it("toggles theme when clicked", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + const button = screen.getByRole("button", { name: /Toggle theme/i }); + + // Initially should be light theme (default) + expect(document.documentElement.classList.contains("dark")).toBe(false); + + // Click to toggle to dark + await user.click(button); + expect(document.documentElement.classList.contains("dark")).toBe(true); + + // Click to toggle back to light + await user.click(button); + expect(document.documentElement.classList.contains("dark")).toBe(false); + }); + + it("has sun and moon icons", () => { + renderWithProviders(); + + // Both icons should be in the DOM (one visible, one hidden based on theme) + const button = screen.getByRole("button", { name: /Toggle theme/i }); + expect(button).toBeInTheDocument(); + + // Check SVG elements exist (lucide-react renders as svg) + const svgs = button.querySelectorAll("svg"); + expect(svgs.length).toBe(2); // Sun and Moon icons + }); +}); diff --git a/zookeeper-website/unit-tests/utils.tsx b/zookeeper-website/unit-tests/utils.tsx new file mode 100644 index 00000000000..18b01fcf46d --- /dev/null +++ b/zookeeper-website/unit-tests/utils.tsx @@ -0,0 +1,34 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { render } from "@testing-library/react"; +import { BrowserRouter } from "react-router"; +import { ThemeProvider } from "@/lib/theme-provider"; +import type { ReactElement } from "react"; + +export function renderWithProviders(ui: ReactElement) { + return render( + + + {ui} + + + ); +} + +export * from "@testing-library/react"; diff --git a/zookeeper-website/vite.config.ts b/zookeeper-website/vite.config.ts new file mode 100644 index 00000000000..edbb1e011bf --- /dev/null +++ b/zookeeper-website/vite.config.ts @@ -0,0 +1,66 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { reactRouter } from "@react-router/dev/vite"; +import tailwindcss from "@tailwindcss/vite"; +import { defineConfig, createLogger } from "vite"; +import tsconfigPaths from "vite-tsconfig-paths"; +import { resolve } from "path"; +import mdx from "fumadocs-mdx/vite"; +import * as MdxConfig from "./source.config"; +import { releasedDocsVersionsPlugin } from "./plugins/released-docs-versions"; +import { CURRENT_VERSION } from "./app/lib/current-version"; + +// Create custom logger to filter out benign warnings +const logger = createLogger(); +const originalWarn = logger.warn; +logger.warn = (msg, options) => { + // Suppress public directory warnings - these are informational only + if (msg.includes("Files in the public directory are served at the root path")) + return; + if ( + msg.includes( + "Assets in public directory cannot be imported from JavaScript" + ) + ) + return; + // Suppress Babel deoptimization warnings for large MDX files + if (msg.includes("deoptimised the styling")) return; + // Log all other warnings + originalWarn(msg, options); +}; + +export default defineConfig({ + plugins: [ + releasedDocsVersionsPlugin(), + mdx(MdxConfig), + tailwindcss(), + reactRouter(), + tsconfigPaths() + ], + resolve: { + alias: { + "@/.source": resolve(__dirname, ".source"), + "@": resolve(__dirname, "app") + } + }, + define: { + __CURRENT_VERSION__: JSON.stringify(CURRENT_VERSION) + }, + customLogger: logger +}); diff --git a/zookeeper-website/vitest.config.ts b/zookeeper-website/vitest.config.ts new file mode 100644 index 00000000000..bec249ae583 --- /dev/null +++ b/zookeeper-website/vitest.config.ts @@ -0,0 +1,58 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { defineConfig } from "vitest/config"; +import react from "@vitejs/plugin-react"; +import tsconfigPaths from "vite-tsconfig-paths"; +import { resolve } from "path"; +import mdx from "fumadocs-mdx/vite"; +import * as MdxConfig from "./source.config"; +import { releasedDocsVersionsPlugin } from "./plugins/released-docs-versions"; +import { CURRENT_VERSION } from "./app/lib/current-version"; + +export default defineConfig({ + plugins: [ + releasedDocsVersionsPlugin(), + mdx(MdxConfig), + react(), + tsconfigPaths() + ], + define: { + __CURRENT_VERSION__: JSON.stringify(CURRENT_VERSION) + }, + test: { + globals: true, + environment: "happy-dom", + setupFiles: ["./unit-tests/setup.ts"], + css: true, + pool: "threads", + exclude: [ + "**/node_modules/**", + "**/dist/**", + "**/e2e-tests/**", + "**/playwright-report/**", + "**/test-results/**" + ] + }, + resolve: { + alias: { + "@/.source": resolve(__dirname, ".source"), + "@": resolve(__dirname, "app") + } + } +}); From 06217d0302b70f8c6e3323a63e497481d4e1583d Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Mon, 20 Apr 2026 16:54:15 +0200 Subject: [PATCH 2/9] Fix build --- pom.xml | 2 +- zookeeper-website/README.md | 29 +++- .../app/components/docs/older-docs-picker.tsx | 16 +- .../app/lib/released-docs-versions.ts | 23 +++ .../e2e-tests/older-docs-picker.spec.ts | 68 +++++--- zookeeper-website/package-lock.json | 38 +++-- .../plugins/released-docs-versions.ts | 31 +++- zookeeper-website/pom.xml | 150 ++++++++++++++++++ .../unit-tests/older-docs-picker.test.tsx | 65 +++++--- .../unit-tests/released-docs-versions.test.ts | 120 +++++++++----- 10 files changed, 423 insertions(+), 119 deletions(-) create mode 100644 zookeeper-website/pom.xml diff --git a/pom.xml b/pom.xml index 2811e0dfa06..2e14fe6abd3 100644 --- a/pom.xml +++ b/pom.xml @@ -57,7 +57,7 @@ - zookeeper-docs + zookeeper-website zookeeper-jute zookeeper-server zookeeper-metrics-providers diff --git a/zookeeper-website/README.md b/zookeeper-website/README.md index 157c4b2ec5f..52923421212 100644 --- a/zookeeper-website/README.md +++ b/zookeeper-website/README.md @@ -386,7 +386,17 @@ Generated files are located under the `build/` directory. ### Maven Integration -The website is integrated with the Apache ZooKeeper Maven build system using the `frontend-maven-plugin`. The website is configured to build **only during site generation** (`mvn site`) and will not build during regular Maven lifecycle phases like `mvn clean install`. +The website is integrated into the Apache ZooKeeper Maven build through two POMs: + +- The repository root `pom.xml` includes `zookeeper-website` as a Maven module. +- `zookeeper-website/pom.xml` owns the website-specific build and configures `frontend-maven-plugin`. + +The frontend plugin is intentionally bound only to the Maven `site` lifecycle: + +- `pre-site` installs Node.js/npm and runs `npm install` +- `site` runs the website CI command + +Because of that, the website is built **only during site generation** (`mvn site`) and is skipped during regular Maven lifecycle phases such as `mvn clean install`. #### When the Website Builds @@ -404,7 +414,7 @@ The website will **NOT** build during regular commands like: This keeps regular ZooKeeper builds fast while still allowing the website to be generated when needed. -#### What Gets Executed During `mvn site` +#### What the Website POM Does During `mvn site` When you run `mvn site`, the website module automatically: @@ -452,7 +462,7 @@ mvn clean install **Build the Website:** ```bash -# From ZooKeeper root or zookeeper-website directory +# From ZooKeeper root directory mvn site ``` @@ -470,18 +480,21 @@ This runs `npm run ci-skip-tests` for the website module. **Build Website Only:** ```bash -# From zookeeper-website directory +# From ZooKeeper root directory +mvn -pl zookeeper-website site + +# Or from the website module directory cd zookeeper-website -mvn clean install +mvn site ``` **Skip Website Build:** -If you want to build ZooKeeper but skip the website: +If you are running the Maven `site` lifecycle but want to disable the website frontend build: ```bash -# From ZooKeeper root directory -mvn clean install -DskipSite +# From ZooKeeper root or zookeeper-website directory +mvn site -DskipSite ``` ### Deployment diff --git a/zookeeper-website/app/components/docs/older-docs-picker.tsx b/zookeeper-website/app/components/docs/older-docs-picker.tsx index 178a81cf416..645cb773762 100644 --- a/zookeeper-website/app/components/docs/older-docs-picker.tsx +++ b/zookeeper-website/app/components/docs/older-docs-picker.tsx @@ -26,18 +26,24 @@ import { CommandItem, CommandList } from "@/ui/command"; -import { RELEASED_DOC_VERSIONS } from "@/lib/released-docs-versions"; +import { getReleasedDocVersions } from "@/lib/released-docs-versions"; + +interface OlderDocsVersionsProps { + versions?: string[]; +} /** Shared Command palette (search + list), used in both the * sidebar popover and the navbar sub-menu. */ -export function OlderDocsVersionList() { +export function OlderDocsVersionList({ + versions = getReleasedDocVersions() +}: OlderDocsVersionsProps) { return ( (value.includes(search) ? 1 : 0)}> No versions found - {RELEASED_DOC_VERSIONS.map((version) => ( + {versions.map((version) => ( {version} @@ -49,7 +55,7 @@ export function OlderDocsVersionList() { } /** Sidebar variant — Popover that opens to the right of the trigger button. */ -export function OlderDocsPicker() { +export function OlderDocsPicker({ versions }: OlderDocsVersionsProps) { return ( @@ -66,7 +72,7 @@ export function OlderDocsPicker() { className="w-56 p-0" aria-label="Older documentation versions" > - + ); diff --git a/zookeeper-website/app/lib/released-docs-versions.ts b/zookeeper-website/app/lib/released-docs-versions.ts index e252bd197ea..9889187b14f 100644 --- a/zookeeper-website/app/lib/released-docs-versions.ts +++ b/zookeeper-website/app/lib/released-docs-versions.ts @@ -67,3 +67,26 @@ import { RAW_RELEASED_DOC_VERSIONS } from "virtual:released-docs-versions"; export const RELEASED_DOC_VERSIONS: string[] = sortVersionsDesc( RAW_RELEASED_DOC_VERSIONS ); + +export function getReleasedDocVersions(): string[] { + if (typeof window !== "undefined") { + const override = window.localStorage.getItem( + "__released_doc_versions_override__" + ); + if (override) { + try { + const parsed = JSON.parse(override); + if ( + Array.isArray(parsed) && + parsed.every((value) => typeof value === "string") + ) { + return sortVersionsDesc(parsed); + } + } catch { + // Ignore invalid test overrides and fall back to build-time data. + } + } + } + + return RELEASED_DOC_VERSIONS; +} diff --git a/zookeeper-website/e2e-tests/older-docs-picker.spec.ts b/zookeeper-website/e2e-tests/older-docs-picker.spec.ts index 1b1d33d9fc6..962b436f72b 100644 --- a/zookeeper-website/e2e-tests/older-docs-picker.spec.ts +++ b/zookeeper-website/e2e-tests/older-docs-picker.spec.ts @@ -18,8 +18,20 @@ import { test, expect } from "@playwright/test"; +const MOCK_RELEASED_DOC_VERSIONS = ["3.10.0", "3.9.4", "3.9.0-beta"]; +const RELEASED_DOC_VERSIONS_OVERRIDE_KEY = "__released_doc_versions_override__"; + test.describe("Older Docs Picker – sidebar", () => { test.beforeEach(async ({ page }) => { + await page.addInitScript( + ({ key, versions }) => { + window.localStorage.setItem(key, JSON.stringify(versions)); + }, + { + key: RELEASED_DOC_VERSIONS_OVERRIDE_KEY, + versions: MOCK_RELEASED_DOC_VERSIONS + } + ); await page.goto("/docs"); await page.waitForLoadState("networkidle"); }); @@ -48,8 +60,7 @@ test.describe("Older Docs Picker – sidebar", () => { const options = list.getByRole("option"); await expect(options.first()).toBeVisible(); - const count = await options.count(); - expect(count).toBeGreaterThan(0); + await expect(options).toHaveCount(MOCK_RELEASED_DOC_VERSIONS.length); }); test("versions are displayed in descending order", async ({ page }) => { @@ -57,16 +68,11 @@ test.describe("Older Docs Picker – sidebar", () => { const options = page.getByRole("option"); await expect(options.first()).toBeVisible(); - const count = await options.count(); - expect(count).toBeGreaterThan(1); - - const firstText = (await options.first().textContent()) ?? ""; - const lastText = (await options.last().textContent()) ?? ""; - // Simple sanity check: the first item should sort higher than the last - expect(firstText.trim()).not.toBe(""); - expect(lastText.trim()).not.toBe(""); - expect(firstText.trim() > lastText.trim()).toBe(true); + const texts = await options.allTextContents(); + expect(texts.map((text) => text.trim())).toEqual( + MOCK_RELEASED_DOC_VERSIONS + ); }); test("each version item is a link to /released-docs/r{version}/index.html", async ({ @@ -75,13 +81,12 @@ test.describe("Older Docs Picker – sidebar", () => { await page.getByRole("button", { name: /older docs/i }).click(); const options = page.getByRole("option"); - await expect(options.first()).toBeVisible(); - - // With asChild, the IS the option element — check href directly - const count = Math.min(await options.count(), 5); - for (let i = 0; i < count; i++) { + await expect(options).toHaveCount(MOCK_RELEASED_DOC_VERSIONS.length); + for (let i = 0; i < MOCK_RELEASED_DOC_VERSIONS.length; i++) { const href = await options.nth(i).getAttribute("href"); - expect(href).toMatch(/^\/released-docs\/r[\d.].+\/index\.html$/); + expect(href).toBe( + `/released-docs/r${MOCK_RELEASED_DOC_VERSIONS[i]}/index.html` + ); } }); @@ -103,8 +108,8 @@ test.describe("Older Docs Picker – sidebar", () => { const filtered = page.getByRole("option"); const totalAfter = await filtered.count(); - // The list should be smaller after filtering - expect(totalAfter).toBeLessThan(totalBefore); + expect(totalBefore).toBe(MOCK_RELEASED_DOC_VERSIONS.length); + expect(totalAfter).toBe(2); // Every remaining option must contain the search term for (let i = 0; i < totalAfter; i++) { @@ -145,6 +150,15 @@ test.describe("Older Docs Picker – sidebar", () => { test.describe("Older Docs Picker – navbar Documentation menu", () => { test.beforeEach(async ({ page }) => { + await page.addInitScript( + ({ key, versions }) => { + window.localStorage.setItem(key, JSON.stringify(versions)); + }, + { + key: RELEASED_DOC_VERSIONS_OVERRIDE_KEY, + versions: MOCK_RELEASED_DOC_VERSIONS + } + ); await page.goto("/"); await page.waitForLoadState("networkidle"); }); @@ -180,8 +194,9 @@ test.describe("Older Docs Picker – navbar Documentation menu", () => { await expect(page.getByRole("menu")).toHaveCount(2, { timeout: 10000 }); const subMenu = page.getByRole("menu").last(); - const options = subMenu.getByRole("option"); - await expect(options.first()).toBeVisible(); + const versionLinks = subMenu.locator('a[href^="/released-docs/r"]'); + await expect(versionLinks.first()).toBeVisible(); + await expect(versionLinks).toHaveCount(MOCK_RELEASED_DOC_VERSIONS.length); }); test("navbar older-docs links point to /released-docs/", async ({ page }) => { @@ -192,15 +207,18 @@ test.describe("Older Docs Picker – navbar Documentation menu", () => { const olderDocs = page.getByRole("menuitem", { name: /older docs/i }); await olderDocs.hover(); + await olderDocs.press("ArrowRight"); const subMenu = page.getByRole("menu").last(); await expect(subMenu).toBeVisible(); - const links = subMenu.getByRole("link"); - const count = Math.min(await links.count(), 3); - for (let i = 0; i < count; i++) { + const links = subMenu.locator('a[href^="/released-docs/r"]'); + await expect(links).toHaveCount(MOCK_RELEASED_DOC_VERSIONS.length); + for (let i = 0; i < MOCK_RELEASED_DOC_VERSIONS.length; i++) { const href = await links.nth(i).getAttribute("href"); - expect(href).toMatch(/^\/released-docs\/r[\d.].+\/index\.html$/); + expect(href).toBe( + `/released-docs/r${MOCK_RELEASED_DOC_VERSIONS[i]}/index.html` + ); } }); }); diff --git a/zookeeper-website/package-lock.json b/zookeeper-website/package-lock.json index d3c9a1fcb77..dc3ddb7aa9b 100644 --- a/zookeeper-website/package-lock.json +++ b/zookeeper-website/package-lock.json @@ -186,6 +186,7 @@ "integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@babel/code-frame": "^7.27.1", "@babel/generator": "^7.28.3", @@ -784,6 +785,7 @@ "url": "https://opencollective.com/csstools" } ], + "peer": true, "engines": { "node": ">=18" }, @@ -828,6 +830,7 @@ "url": "https://opencollective.com/csstools" } ], + "peer": true, "engines": { "node": ">=18" } @@ -3535,6 +3538,7 @@ "resolved": "https://registry.npmjs.org/@react-router/serve/-/serve-7.12.0.tgz", "integrity": "sha512-j1ltgU7s3wAwOosZ5oxgHSsmVyK706gY/yIs8qVmC239wQ3zr3eqaXk3TVVLMeRy+eDgPNmgc6oNJv2o328VgA==", "license": "MIT", + "peer": true, "dependencies": { "@mjackson/node-fetch-server": "^0.2.0", "@react-router/express": "7.12.0", @@ -4471,8 +4475,7 @@ "version": "5.0.4", "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==", - "dev": true, - "peer": true + "dev": true }, "node_modules/@types/babel__core": { "version": "7.20.5", @@ -4611,6 +4614,7 @@ "integrity": "sha512-Gd33J2XIrXurb+eT2ktze3rJAfAp9ZNjlBdh4SVgyrKEOADwCbdUDaK7QgJno8Ue4kcajscsKqu6n8OBG3hhCQ==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "undici-types": "~6.21.0" } @@ -4620,6 +4624,7 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz", "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==", "license": "MIT", + "peer": true, "dependencies": { "csstype": "^3.0.2" } @@ -4630,6 +4635,7 @@ "integrity": "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==", "devOptional": true, "license": "MIT", + "peer": true, "peerDependencies": { "@types/react": "^19.2.0" } @@ -4691,6 +4697,7 @@ "integrity": "sha512-IgSWvLobTDOjnaxAfDTIHaECbkNlAlKv2j5SjpB2v7QHKv1FIfjwMy8FsDbVfDX/KjmCmYICcw7uGaXLhtsLNg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/types": "8.56.0", @@ -5369,6 +5376,7 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -5917,6 +5925,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.8.9", "caniuse-lite": "^1.0.30001746", @@ -7106,8 +7115,7 @@ "version": "0.5.16", "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz", "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==", - "dev": true, - "peer": true + "dev": true }, "node_modules/dunder-proto": { "version": "1.0.1", @@ -7444,6 +7452,7 @@ "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", @@ -7624,6 +7633,7 @@ "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@rtsao/scc": "^1.1.0", "array-includes": "^3.1.9", @@ -7988,6 +7998,7 @@ "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz", "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==", "license": "MIT", + "peer": true, "dependencies": { "accepts": "~1.3.8", "array-flatten": "1.1.1", @@ -8261,6 +8272,7 @@ "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-16.0.10.tgz", "integrity": "sha512-6DQLpJ7ETvSuGZ4TnK6z1wGwnbqht0lK8BcKc3ergWjc8u2XTsPZP3i3tMgOUsKCG0cr9s8fLYz3FGEMOkDuFw==", "license": "MIT", + "peer": true, "dependencies": { "@formatjs/intl-localematcher": "^0.6.2", "@orama/orama": "^3.1.16", @@ -10966,6 +10978,7 @@ "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.454.0.tgz", "integrity": "sha512-hw7zMDwykCLnEzgncEEjHeA6+45aeEzRYuKHuyRSOPkhko+J3ySGjGIzu+mmMfDFG1vazHepMaYFYHbTFAZAAQ==", "license": "ISC", + "peer": true, "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc" } @@ -10975,7 +10988,6 @@ "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz", "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", "dev": true, - "peer": true, "bin": { "lz-string": "bin/bin.js" } @@ -12848,6 +12860,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -12893,6 +12906,7 @@ "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==", "dev": true, "license": "MIT", + "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -13008,7 +13022,6 @@ "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz", "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==", "dev": true, - "peer": true, "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", @@ -13023,7 +13036,6 @@ "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "dev": true, - "peer": true, "engines": { "node": ">=10" }, @@ -13134,6 +13146,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.0.tgz", "integrity": "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10.0" } @@ -13143,6 +13156,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.0.tgz", "integrity": "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ==", "license": "MIT", + "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -13171,8 +13185,7 @@ "version": "17.0.2", "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", - "dev": true, - "peer": true + "dev": true }, "node_modules/react-markdown": { "version": "10.1.0", @@ -13279,6 +13292,7 @@ "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.12.0.tgz", "integrity": "sha512-kTPDYPFzDVGIIGNLS5VJykK0HfHLY5MF3b+xj0/tTyNYL1gF1qs7u67Z9jEhQk2sQ98SUaHxlG31g1JtF7IfVw==", "license": "MIT", + "peer": true, "dependencies": { "cookie": "^1.0.1", "set-cookie-parser": "^2.6.0" @@ -14687,7 +14701,8 @@ "version": "4.1.14", "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.14.tgz", "integrity": "sha512-b7pCxjGO98LnxVkKjaZSDeNuljC4ueKUddjENJOADtubtdo8llTaJy7HwBMeLNSSo2N5QIAgklslK1+Ir8r6CA==", - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/tailwindcss-animate": { "version": "1.0.7", @@ -15527,6 +15542,7 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", + "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -15729,6 +15745,7 @@ "dev": true, "hasInstallScript": true, "license": "MIT", + "peer": true, "dependencies": { "napi-postinstall": "^0.3.0" }, @@ -15938,6 +15955,7 @@ "integrity": "sha512-tI2l/nFHC5rLh7+5+o7QjKjSR04ivXDF4jcgV0f/bTQ+OJiITy5S6gaynVsEM+7RqzufMnVbIon6Sr5x1SDYaQ==", "devOptional": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.5.0", diff --git a/zookeeper-website/plugins/released-docs-versions.ts b/zookeeper-website/plugins/released-docs-versions.ts index 3d64c82e17b..f4504594523 100644 --- a/zookeeper-website/plugins/released-docs-versions.ts +++ b/zookeeper-website/plugins/released-docs-versions.ts @@ -16,12 +16,36 @@ // limitations under the License. // -import { readdirSync } from "fs"; +import { readdirSync, type Dirent } from "fs"; import { resolve } from "path"; import type { Plugin } from "vite"; const VIRTUAL_ID = "virtual:released-docs-versions"; const RESOLVED_ID = "\0" + VIRTUAL_ID; +const RELEASED_DOCS_DIR = resolve(__dirname, "../public/released-docs"); + +type ReleasedDocsDirEntry = Pick; + +export function extractReleasedDocsVersions( + entries: ReleasedDocsDirEntry[] +): string[] { + return entries + .filter((entry) => entry.isDirectory() && entry.name.startsWith("r")) + .map((entry) => entry.name.slice(1)); +} + +export function getReleasedDocsVersions(dir = RELEASED_DOCS_DIR): string[] { + try { + const entries = readdirSync(dir, { withFileTypes: true }); + return extractReleasedDocsVersions(entries); + } catch (error) { + const maybeFsError = error as NodeJS.ErrnoException; + if (maybeFsError.code === "ENOENT") { + return []; + } + throw error; + } +} export function releasedDocsVersionsPlugin(): Plugin { return { @@ -31,10 +55,7 @@ export function releasedDocsVersionsPlugin(): Plugin { }, load(id) { if (id !== RESOLVED_ID) return; - const dir = resolve(__dirname, "../public/released-docs"); - const folders = readdirSync(dir, { withFileTypes: true }) - .filter((d) => d.isDirectory() && d.name.startsWith("r")) - .map((d) => d.name.slice(1)); // strip leading "r" + const folders = getReleasedDocsVersions(); return `export const RAW_RELEASED_DOC_VERSIONS = ${JSON.stringify(folders)};`; } }; diff --git a/zookeeper-website/pom.xml b/zookeeper-website/pom.xml new file mode 100644 index 00000000000..3215e54dcad --- /dev/null +++ b/zookeeper-website/pom.xml @@ -0,0 +1,150 @@ + + + + 4.0.0 + + + org.apache.zookeeper + parent + 3.10.0-SNAPSHOT + .. + + + zookeeper-website + pom + Apache ZooKeeper - Website + Apache ZooKeeper Website built with React and TypeScript + + + v22.20.0 + 11.6.2 + ci + + + + + + org.apache.maven.plugins + maven-clean-plugin + + + + ${project.basedir}/build + false + + + ${project.basedir}/node_modules + false + + + + + + com.github.eirslett + frontend-maven-plugin + 1.15.1 + + ${project.build.directory} + ${project.basedir} + + + + install-node-and-npm + + install-node-and-npm + + pre-site + + ${node.version} + ${npm.version} + + + + npm-install + + npm + + pre-site + + install + + + + npm-run-ci + + npm + + site + + run ${website.ci.command} + + + + + + + + + + skip-site + + + skipSite + + + + + + com.github.eirslett + frontend-maven-plugin + + + install-node-and-npm + none + + + npm-install + none + + + npm-run-ci + none + + + + + + + + skip-tests + + + skipTests + + + + ci-skip-tests + + + + diff --git a/zookeeper-website/unit-tests/older-docs-picker.test.tsx b/zookeeper-website/unit-tests/older-docs-picker.test.tsx index 1da6fa23e65..262616558e7 100644 --- a/zookeeper-website/unit-tests/older-docs-picker.test.tsx +++ b/zookeeper-website/unit-tests/older-docs-picker.test.tsx @@ -26,6 +26,8 @@ import { sortVersionsDesc } from "@/lib/released-docs-versions"; +const MOCK_RELEASED_DOC_VERSIONS = ["3.10.0", "3.9.4", "3.9.0-beta"]; + describe("sortVersionsDesc", () => { it("sorts stable versions newest first", () => { const result = sortVersionsDesc(["3.7.0", "3.9.0", "3.8.0"]); @@ -56,21 +58,11 @@ describe("sortVersionsDesc", () => { }); describe("RELEASED_DOC_VERSIONS", () => { - it("is a non-empty array of strings", () => { + it("is an array of strings", () => { expect(Array.isArray(RELEASED_DOC_VERSIONS)).toBe(true); - expect(RELEASED_DOC_VERSIONS.length).toBeGreaterThan(0); - }); - - it("starts with the highest version", () => { - const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); - expect(RELEASED_DOC_VERSIONS[0]).toBe(sorted[0]); - }); - - it("ends with the lowest version", () => { - const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); - expect(RELEASED_DOC_VERSIONS[RELEASED_DOC_VERSIONS.length - 1]).toBe( - sorted[sorted.length - 1] - ); + RELEASED_DOC_VERSIONS.forEach((version) => { + expect(typeof version).toBe("string"); + }); }); it("is already sorted newest to oldest", () => { @@ -81,20 +73,26 @@ describe("RELEASED_DOC_VERSIONS", () => { describe("OlderDocsPicker", () => { it("renders the trigger button", () => { - renderWithProviders(); + renderWithProviders( + + ); expect( screen.getByRole("button", { name: /older docs/i }) ).toBeInTheDocument(); }); it("does not show the version list before the button is clicked", () => { - renderWithProviders(); + renderWithProviders( + + ); expect(screen.queryByRole("listbox")).not.toBeInTheDocument(); }); it("opens the popover and shows a search combobox on trigger click", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); await user.click(screen.getByRole("button", { name: /older docs/i })); @@ -105,7 +103,9 @@ describe("OlderDocsPicker", () => { it("shows all versions when popover is open", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); await user.click(screen.getByRole("button", { name: /older docs/i })); @@ -114,12 +114,14 @@ describe("OlderDocsPicker", () => { }); const items = screen.getAllByRole("option"); - expect(items.length).toBe(RELEASED_DOC_VERSIONS.length); + expect(items.length).toBe(MOCK_RELEASED_DOC_VERSIONS.length); }); it("filters versions by search query", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); await user.click(screen.getByRole("button", { name: /older docs/i })); @@ -137,7 +139,9 @@ describe("OlderDocsPicker", () => { it("shows 'No versions found' when search has no matches", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); await user.click(screen.getByRole("button", { name: /older docs/i })); @@ -151,7 +155,9 @@ describe("OlderDocsPicker", () => { it("each version links to the correct /released-docs/ path", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); await user.click(screen.getByRole("button", { name: /older docs/i })); @@ -167,9 +173,22 @@ describe("OlderDocsPicker", () => { }); }); + it("shows an empty state when no older docs are available", async () => { + const user = userEvent.setup(); + renderWithProviders(); + + await user.click(screen.getByRole("button", { name: /older docs/i })); + + await waitFor(() => { + expect(screen.getByText(/no versions found/i)).toBeInTheDocument(); + }); + }); + it("clears search when popover is reopened", async () => { const user = userEvent.setup(); - renderWithProviders(); + renderWithProviders( + + ); const trigger = screen.getByRole("button", { name: /older docs/i }); diff --git a/zookeeper-website/unit-tests/released-docs-versions.test.ts b/zookeeper-website/unit-tests/released-docs-versions.test.ts index 88f03b386c1..376bf5ffe35 100644 --- a/zookeeper-website/unit-tests/released-docs-versions.test.ts +++ b/zookeeper-website/unit-tests/released-docs-versions.test.ts @@ -17,30 +17,93 @@ // import { describe, it, expect } from "vitest"; -import { readdirSync } from "fs"; -import { resolve } from "path"; +import { mkdtempSync, rmSync } from "fs"; +import { join } from "path"; +import { tmpdir } from "os"; import { RAW_RELEASED_DOC_VERSIONS } from "virtual:released-docs-versions"; import { RELEASED_DOC_VERSIONS, sortVersionsDesc } from "@/lib/released-docs-versions"; +import { + extractReleasedDocsVersions, + getReleasedDocsVersions +} from "../plugins/released-docs-versions"; -// Read the real filesystem so we can cross-check the virtual module output. -const RELEASED_DOCS_DIR = resolve(__dirname, "../public/released-docs"); -const ACTUAL_FOLDERS = readdirSync(RELEASED_DOCS_DIR, { withFileTypes: true }) - .filter((d) => d.isDirectory() && d.name.startsWith("r")) - .map((d) => d.name.slice(1)); // strip leading "r" +const MOCK_RELEASED_DOC_VERSIONS = ["3.9.4", "3.10.0", "3.9.0-beta", "3.8.12"]; -describe("virtual:released-docs-versions plugin", () => { - it("exposes a non-empty array", () => { - expect(Array.isArray(RAW_RELEASED_DOC_VERSIONS)).toBe(true); - expect(RAW_RELEASED_DOC_VERSIONS.length).toBeGreaterThan(0); +function mockDirEntry(name: string, isDirectory: boolean) { + return { + name, + isDirectory: () => isDirectory + }; +} + +describe("extractReleasedDocsVersions", () => { + it("strips the leading 'r' prefix from mocked release directories", () => { + const versions = extractReleasedDocsVersions([ + mockDirEntry("r3.9.4", true), + mockDirEntry("r3.10.0-beta", true) + ]); + + expect(versions).toEqual(["3.9.4", "3.10.0-beta"]); }); - it("matches exactly the directories present in public/released-docs/", () => { - expect(RAW_RELEASED_DOC_VERSIONS.slice().sort()).toEqual( - ACTUAL_FOLDERS.slice().sort() - ); + it("ignores non-release folders and loose files from mocked entries", () => { + const versions = extractReleasedDocsVersions([ + mockDirEntry("r3.9.4", true), + mockDirEntry("draft-docs", true), + mockDirEntry("r3.8.0", false), + mockDirEntry("README.md", false) + ]); + + expect(versions).toEqual(["3.9.4"]); + }); +}); + +describe("getReleasedDocsVersions", () => { + it("returns an empty array when the released-docs directory is missing", () => { + const missingDir = join(tmpdir(), `released-docs-missing-${Date.now()}`); + + expect(getReleasedDocsVersions(missingDir)).toEqual([]); + }); + + it("returns an empty array for an empty released-docs directory", () => { + const emptyDir = mkdtempSync(join(tmpdir(), "released-docs-empty-")); + + try { + expect(getReleasedDocsVersions(emptyDir)).toEqual([]); + } finally { + rmSync(emptyDir, { recursive: true, force: true }); + } + }); +}); + +describe("sortVersionsDesc with mocked released-docs versions", () => { + it("places the numerically highest version first", () => { + const sorted = sortVersionsDesc(MOCK_RELEASED_DOC_VERSIONS); + expect(sorted[0]).toBe("3.10.0"); + }); + + it("places the numerically lowest version last", () => { + const sorted = sortVersionsDesc(MOCK_RELEASED_DOC_VERSIONS); + expect(sorted.at(-1)).toBe("3.8.12"); + }); + + it("keeps each consecutive pair in descending order", () => { + const sorted = sortVersionsDesc(MOCK_RELEASED_DOC_VERSIONS); + + for (let i = 0; i < sorted.length - 1; i++) { + const [a, b] = [sorted[i], sorted[i + 1]]; + const [first] = sortVersionsDesc([a, b]); + expect(first).toBe(a); + } + }); +}); + +describe("virtual:released-docs-versions plugin", () => { + it("exposes an array", () => { + expect(Array.isArray(RAW_RELEASED_DOC_VERSIONS)).toBe(true); }); it("strips the leading 'r' prefix from every folder name", () => { @@ -55,14 +118,6 @@ describe("virtual:released-docs-versions plugin", () => { }); }); - it("only includes directory entries, not loose files", () => { - // Every raw entry must correspond to a directory named r{version} - const folderSet = new Set(ACTUAL_FOLDERS); - RAW_RELEASED_DOC_VERSIONS.forEach((v) => { - expect(folderSet.has(v)).toBe(true); - }); - }); - it("every entry looks like a valid version string", () => { RAW_RELEASED_DOC_VERSIONS.forEach((v) => { expect(v).toMatch(/^\d+\.\d+\.\d+/); @@ -82,23 +137,4 @@ describe("RELEASED_DOC_VERSIONS (sorted output)", () => { RAW_RELEASED_DOC_VERSIONS.slice().sort() ); }); - - it("first entry is the numerically highest version", () => { - const [first, ...rest] = RELEASED_DOC_VERSIONS; - const refirst = sortVersionsDesc([first, ...rest])[0]; - expect(first).toBe(refirst); - }); - - it("last entry is the numerically lowest version", () => { - const sorted = sortVersionsDesc([...RELEASED_DOC_VERSIONS]); - expect(RELEASED_DOC_VERSIONS.at(-1)).toBe(sorted.at(-1)); - }); - - it("each consecutive pair is in descending order", () => { - for (let i = 0; i < RELEASED_DOC_VERSIONS.length - 1; i++) { - const [a, b] = [RELEASED_DOC_VERSIONS[i], RELEASED_DOC_VERSIONS[i + 1]]; - const [first] = sortVersionsDesc([a, b]); - expect(first).toBe(a); - } - }); }); From 37a6f198769d4f509e11cd90826af97acb4838af Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Tue, 21 Apr 2026 11:49:31 +0200 Subject: [PATCH 3/9] WIP --- zookeeper-assembly/pom.xml | 2 +- zookeeper-assembly/src/main/assembly/bin-package.xml | 9 +-------- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/zookeeper-assembly/pom.xml b/zookeeper-assembly/pom.xml index 317233d6f3b..5049c6b2fa6 100644 --- a/zookeeper-assembly/pom.xml +++ b/zookeeper-assembly/pom.xml @@ -50,7 +50,7 @@ org.apache.zookeeper - zookeeper-docs + zookeeper-website ${project.version} pom diff --git a/zookeeper-assembly/src/main/assembly/bin-package.xml b/zookeeper-assembly/src/main/assembly/bin-package.xml index 1fa81d0bb22..2e2f57c7ebe 100644 --- a/zookeeper-assembly/src/main/assembly/bin-package.xml +++ b/zookeeper-assembly/src/main/assembly/bin-package.xml @@ -37,7 +37,7 @@ org.apache.zookeeper:zookeeper-recipes org.apache.zookeeper:zookeeper-client - org.apache.zookeeper:zookeeper-docs + org.apache.zookeeper:zookeeper-website false true @@ -49,13 +49,6 @@ - - - ${project.basedir}/../zookeeper-docs/target/html - docs - ${rw.file.permission} - ${rwx.file.permission} - ${project.basedir}/../zookeeper-jute/target/apidocs From 78d5f71298d9652c2c78a801d39bc6e3123d0d91 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 14:33:18 +0200 Subject: [PATCH 4/9] Fix CI issues --- pom.xml | 1 + zookeeper-website/README.md | 4 +- .../app/pages/_docs/docs/index.tsx | 10 ++-- .../app/pages/_landing/bylaws/content.md | 2 +- zookeeper-website/app/routes.ts | 1 + zookeeper-website/app/routes/_landing/404.tsx | 57 +++++++++++++++++++ zookeeper-website/public/.htaccess | 19 ++++++- zookeeper-website/public/404.html | 37 ------------ .../public/images/dark-theme-large-logo.svg | 18 ++++++ .../public/images/large-logo.svg | 18 ++++++ zookeeper-website/public/images/logo.svg | 18 ++++++ 11 files changed, 139 insertions(+), 46 deletions(-) create mode 100644 zookeeper-website/app/routes/_landing/404.tsx delete mode 100644 zookeeper-website/public/404.html diff --git a/pom.xml b/pom.xml index 2e14fe6abd3..50b8a77849f 100644 --- a/pom.xml +++ b/pom.xml @@ -1073,6 +1073,7 @@ **/README.md + **/*.mdx **/findbugsExcludeFile.xml **/checkstyle-noframes-sorted.xsl **/configure.ac diff --git a/zookeeper-website/README.md b/zookeeper-website/README.md index 52923421212..794f4f8e01f 100644 --- a/zookeeper-website/README.md +++ b/zookeeper-website/README.md @@ -305,8 +305,8 @@ This starts a local development server with: **Update the 404 page:** -- Edit the content in `app/routes/404.tsx`. -- Apache 404 handling lives in `public/.htaccess` (uses `ErrorDocument 404 /404`). +- Edit the content in `app/routes/_landing/404.tsx`. +- Apache 404 handling lives in `public/.htaccess` (uses `ErrorDocument 404 /404/index.html`). **Check code quality:** diff --git a/zookeeper-website/app/pages/_docs/docs/index.tsx b/zookeeper-website/app/pages/_docs/docs/index.tsx index 4c645ce23a0..817fa30bb0b 100644 --- a/zookeeper-website/app/pages/_docs/docs/index.tsx +++ b/zookeeper-website/app/pages/_docs/docs/index.tsx @@ -90,14 +90,14 @@ const renderer = toClientRenderer( const route = useParams()["*"]; const baseGithubPath = "zookeeper-docs/app/pages/_docs/docs/_mdx/"; - const grouppedRoutes = [ + const groupedRoutes = [ "developer/programmers-guide", "admin-ops/administrators-guide" ]; const trimmedRoute = route?.endsWith("/") ? route?.slice(0, -1) : route; const mdxFileRoute = `${trimmedRoute === "" ? "index" : trimmedRoute}.mdx`; - const isGrouppedRoute = - !!trimmedRoute && grouppedRoutes.includes(trimmedRoute); + const isGroupedRoute = + !!trimmedRoute && groupedRoutes.includes(trimmedRoute); const displayTitle = pageTitle ?? frontmatter.title; const displayDescription = pageDescription ?? frontmatter.description; @@ -124,8 +124,8 @@ const renderer = toClientRenderer( {displayDescription} - {route !== undefined && isGrouppedRoute && ( - // table of content for groupped routes + {route !== undefined && isGroupedRoute && ( + // table of content for grouped routes

      In this section:

      diff --git a/zookeeper-website/app/pages/_landing/bylaws/content.md b/zookeeper-website/app/pages/_landing/bylaws/content.md index 30ecd46c0c1..387d3066009 100644 --- a/zookeeper-website/app/pages/_landing/bylaws/content.md +++ b/zookeeper-website/app/pages/_landing/bylaws/content.md @@ -46,7 +46,7 @@ All of the volunteers who are contributing time, code, documentation, or resourc The project's committers are responsible for the project's technical management. Committers have access to a specified set of subproject's repositories. Committers on subprojects may cast binding votes on any technical discussion regarding that subproject. -Committer access is by invitation only and must be approved by lazy consensus of the active PMC members. A Committer is considered emeritus by his or her own declaration or by not reviewing patches or commiting patches to the project for over six months. An emeritus committer may request reinstatement of commit access from the PMC which must be approved by lazy consensus of the active PMC members. +Committer access is by invitation only and must be approved by lazy consensus of the active PMC members. A Committer is considered emeritus by his or her own declaration or by not reviewing patches or committing patches to the project for over six months. An emeritus committer may request reinstatement of commit access from the PMC which must be approved by lazy consensus of the active PMC members. Commit access can be revoked by a unanimous vote of all the active PMC members (except the committer in question if he or she is also a PMC member). diff --git a/zookeeper-website/app/routes.ts b/zookeeper-website/app/routes.ts index e25312a6dea..9f43e33af66 100644 --- a/zookeeper-website/app/routes.ts +++ b/zookeeper-website/app/routes.ts @@ -27,6 +27,7 @@ export default [ // Landing layout("./pages/_landing/landing-layout.tsx", [ index("routes/_landing/home.tsx"), + route("404", "routes/_landing/404.tsx"), route("releases", "routes/_landing/releases.tsx"), route("events", "routes/_landing/events.tsx"), route("news", "routes/_landing/news.tsx"), diff --git a/zookeeper-website/app/routes/_landing/404.tsx b/zookeeper-website/app/routes/_landing/404.tsx new file mode 100644 index 00000000000..496555ed7b1 --- /dev/null +++ b/zookeeper-website/app/routes/_landing/404.tsx @@ -0,0 +1,57 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import type { Route } from "./+types/404"; +import { Link } from "@/components/link"; +import { Button } from "@/ui/button"; + +export function meta({}: Route.MetaArgs) { + return [ + { title: "Page Not Found - Apache ZooKeeper" }, + { + name: "description", + content: + "The page you are looking for doesn't exist. The website was updated recently, so the route you were trying to visit might have changed." + } + ]; +} + +export default function NotFoundPage() { + return ( +
      +
      +

      + 404 +

      +

      + Page not found +

      +

      + The page you are looking for doesn't exist. The website was + updated recently, so the route you were trying to visit might have + changed. +

      +
      + +
      +
      +
      + ); +} diff --git a/zookeeper-website/public/.htaccess b/zookeeper-website/public/.htaccess index de377bfe450..4f37d8f5974 100644 --- a/zookeeper-website/public/.htaccess +++ b/zookeeper-website/public/.htaccess @@ -1 +1,18 @@ -ErrorDocument 404 /404.html +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +ErrorDocument 404 /404/index.html diff --git a/zookeeper-website/public/404.html b/zookeeper-website/public/404.html deleted file mode 100644 index 2d36a60bbfb..00000000000 --- a/zookeeper-website/public/404.html +++ /dev/null @@ -1,37 +0,0 @@ -Page Not Found - Apache ZooKeeper

      404

      Page not found

      The page you are looking for doesn't exist. The website was updated recently, so the route you were trying to visit might have changed.

      Go back home
      \ No newline at end of file diff --git a/zookeeper-website/public/images/dark-theme-large-logo.svg b/zookeeper-website/public/images/dark-theme-large-logo.svg index 1fe31b7557b..fe0c9e4bf6c 100644 --- a/zookeeper-website/public/images/dark-theme-large-logo.svg +++ b/zookeeper-website/public/images/dark-theme-large-logo.svg @@ -1,4 +1,22 @@ + diff --git a/zookeeper-website/public/images/large-logo.svg b/zookeeper-website/public/images/large-logo.svg index cc09f5786a9..695f31dfc29 100644 --- a/zookeeper-website/public/images/large-logo.svg +++ b/zookeeper-website/public/images/large-logo.svg @@ -1,4 +1,22 @@ + diff --git a/zookeeper-website/public/images/logo.svg b/zookeeper-website/public/images/logo.svg index a281babc319..7d0da946df0 100644 --- a/zookeeper-website/public/images/logo.svg +++ b/zookeeper-website/public/images/logo.svg @@ -1 +1,19 @@ + \ No newline at end of file From ebc8b5cc9bbf90d1922ac60c047843d5df764af6 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 14:46:26 +0200 Subject: [PATCH 5/9] Add GitHub Actions workflow for website build --- .github/workflows/website.yaml | 61 ++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 .github/workflows/website.yaml diff --git a/.github/workflows/website.yaml b/.github/workflows/website.yaml new file mode 100644 index 00000000000..6baf8796546 --- /dev/null +++ b/.github/workflows/website.yaml @@ -0,0 +1,61 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +name: Website + +on: + push: + branches: [ '*' ] + pull_request: + branches: [ '*' ] + +permissions: + contents: read + +jobs: + site: + name: website-site + timeout-minutes: 120 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + - name: Set up JDK 11 + uses: actions/setup-java@v5 + with: + java-version: 11 + distribution: temurin + cache: 'maven' + - name: Show the first log message + run: git log -n1 + - name: Build website with Maven site + run: mvn -B -V -e -ntp "-Dstyle.color=always" -pl zookeeper-website site + env: + MAVEN_OPTS: -Djansi.force=true + - name: Upload website Playwright report + if: ${{ failure() }} + uses: actions/upload-artifact@v7 + with: + name: website-playwright-report + path: zookeeper-website/playwright-report/ + if-no-files-found: ignore + - name: Upload website test results + if: ${{ failure() }} + uses: actions/upload-artifact@v7 + with: + name: website-test-results + path: zookeeper-website/test-results/ + if-no-files-found: ignore From a0729bc78f329c1b25ad878fea0012dfc24ed6f7 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 14:55:09 +0200 Subject: [PATCH 6/9] Add sitemap generation, robots.txt, and HTTP cache headers --- zookeeper-website/README.md | 6 + zookeeper-website/package-lock.json | 94 ++++++++----- zookeeper-website/package.json | 4 +- zookeeper-website/public/.htaccess | 8 ++ zookeeper-website/public/robots.txt | 5 + .../scripts/generate-sitemap.test.ts | 107 +++++++++++++++ zookeeper-website/scripts/generate-sitemap.ts | 125 ++++++++++++++++++ 7 files changed, 317 insertions(+), 32 deletions(-) create mode 100644 zookeeper-website/public/robots.txt create mode 100644 zookeeper-website/scripts/generate-sitemap.test.ts create mode 100644 zookeeper-website/scripts/generate-sitemap.ts diff --git a/zookeeper-website/README.md b/zookeeper-website/README.md index 794f4f8e01f..bd4588e9ee1 100644 --- a/zookeeper-website/README.md +++ b/zookeeper-website/README.md @@ -307,6 +307,12 @@ This starts a local development server with: - Edit the content in `app/routes/_landing/404.tsx`. - Apache 404 handling lives in `public/.htaccess` (uses `ErrorDocument 404 /404/index.html`). +- Keep `public/robots.txt` disallowing `/404/` so the error page is not indexed. + +**Update sitemap generation:** + +- Edit `scripts/generate-sitemap.ts` and its tests in `scripts/generate-sitemap.test.ts`. +- `npm run build` generates `build/client/sitemap.xml`, and `public/robots.txt` should keep pointing at the production sitemap URL. **Check code quality:** diff --git a/zookeeper-website/package-lock.json b/zookeeper-website/package-lock.json index dc3ddb7aa9b..d36b1c096ad 100644 --- a/zookeeper-website/package-lock.json +++ b/zookeeper-website/package-lock.json @@ -51,6 +51,7 @@ "remark-heading-id": "^1.0.1", "remark-math": "^6.0.0", "scroll-into-view-if-needed": "^3.1.0", + "sitemap": "^9.0.1", "tailwind-merge": "^2.5.5", "tailwindcss-animate": "^1.0.7" }, @@ -186,7 +187,6 @@ "integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@babel/code-frame": "^7.27.1", "@babel/generator": "^7.28.3", @@ -785,7 +785,6 @@ "url": "https://opencollective.com/csstools" } ], - "peer": true, "engines": { "node": ">=18" }, @@ -830,7 +829,6 @@ "url": "https://opencollective.com/csstools" } ], - "peer": true, "engines": { "node": ">=18" } @@ -3538,7 +3536,6 @@ "resolved": "https://registry.npmjs.org/@react-router/serve/-/serve-7.12.0.tgz", "integrity": "sha512-j1ltgU7s3wAwOosZ5oxgHSsmVyK706gY/yIs8qVmC239wQ3zr3eqaXk3TVVLMeRy+eDgPNmgc6oNJv2o328VgA==", "license": "MIT", - "peer": true, "dependencies": { "@mjackson/node-fetch-server": "^0.2.0", "@react-router/express": "7.12.0", @@ -4475,7 +4472,8 @@ "version": "5.0.4", "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==", - "dev": true + "dev": true, + "peer": true }, "node_modules/@types/babel__core": { "version": "7.20.5", @@ -4612,9 +4610,7 @@ "version": "22.18.11", "resolved": "https://registry.npmjs.org/@types/node/-/node-22.18.11.tgz", "integrity": "sha512-Gd33J2XIrXurb+eT2ktze3rJAfAp9ZNjlBdh4SVgyrKEOADwCbdUDaK7QgJno8Ue4kcajscsKqu6n8OBG3hhCQ==", - "dev": true, "license": "MIT", - "peer": true, "dependencies": { "undici-types": "~6.21.0" } @@ -4624,7 +4620,6 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz", "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==", "license": "MIT", - "peer": true, "dependencies": { "csstype": "^3.0.2" } @@ -4635,11 +4630,19 @@ "integrity": "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==", "devOptional": true, "license": "MIT", - "peer": true, "peerDependencies": { "@types/react": "^19.2.0" } }, + "node_modules/@types/sax": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz", + "integrity": "sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==", + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, "node_modules/@types/unist": { "version": "3.0.3", "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", @@ -4697,7 +4700,6 @@ "integrity": "sha512-IgSWvLobTDOjnaxAfDTIHaECbkNlAlKv2j5SjpB2v7QHKv1FIfjwMy8FsDbVfDX/KjmCmYICcw7uGaXLhtsLNg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.56.0", "@typescript-eslint/types": "8.56.0", @@ -5376,7 +5378,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -5515,7 +5516,6 @@ "version": "5.0.2", "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz", "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==", - "dev": true, "license": "MIT" }, "node_modules/argparse": { @@ -5925,7 +5925,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "baseline-browser-mapping": "^2.8.9", "caniuse-lite": "^1.0.30001746", @@ -7115,7 +7114,8 @@ "version": "0.5.16", "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz", "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==", - "dev": true + "dev": true, + "peer": true }, "node_modules/dunder-proto": { "version": "1.0.1", @@ -7452,7 +7452,6 @@ "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.1", @@ -7633,7 +7632,6 @@ "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@rtsao/scc": "^1.1.0", "array-includes": "^3.1.9", @@ -7998,7 +7996,6 @@ "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz", "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==", "license": "MIT", - "peer": true, "dependencies": { "accepts": "~1.3.8", "array-flatten": "1.1.1", @@ -8272,7 +8269,6 @@ "resolved": "https://registry.npmjs.org/fumadocs-core/-/fumadocs-core-16.0.10.tgz", "integrity": "sha512-6DQLpJ7ETvSuGZ4TnK6z1wGwnbqht0lK8BcKc3ergWjc8u2XTsPZP3i3tMgOUsKCG0cr9s8fLYz3FGEMOkDuFw==", "license": "MIT", - "peer": true, "dependencies": { "@formatjs/intl-localematcher": "^0.6.2", "@orama/orama": "^3.1.16", @@ -10978,7 +10974,6 @@ "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.454.0.tgz", "integrity": "sha512-hw7zMDwykCLnEzgncEEjHeA6+45aeEzRYuKHuyRSOPkhko+J3ySGjGIzu+mmMfDFG1vazHepMaYFYHbTFAZAAQ==", "license": "ISC", - "peer": true, "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0-rc" } @@ -10988,6 +10983,7 @@ "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz", "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", "dev": true, + "peer": true, "bin": { "lz-string": "bin/bin.js" } @@ -12860,7 +12856,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -12906,7 +12901,6 @@ "integrity": "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==", "dev": true, "license": "MIT", - "peer": true, "bin": { "prettier": "bin/prettier.cjs" }, @@ -13022,6 +13016,7 @@ "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz", "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==", "dev": true, + "peer": true, "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", @@ -13036,6 +13031,7 @@ "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz", "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "dev": true, + "peer": true, "engines": { "node": ">=10" }, @@ -13146,7 +13142,6 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.0.tgz", "integrity": "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -13156,7 +13151,6 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.0.tgz", "integrity": "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ==", "license": "MIT", - "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -13185,7 +13179,8 @@ "version": "17.0.2", "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", - "dev": true + "dev": true, + "peer": true }, "node_modules/react-markdown": { "version": "10.1.0", @@ -13292,7 +13287,6 @@ "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.12.0.tgz", "integrity": "sha512-kTPDYPFzDVGIIGNLS5VJykK0HfHLY5MF3b+xj0/tTyNYL1gF1qs7u67Z9jEhQk2sQ98SUaHxlG31g1JtF7IfVw==", "license": "MIT", - "peer": true, "dependencies": { "cookie": "^1.0.1", "set-cookie-parser": "^2.6.0" @@ -13949,6 +13943,15 @@ "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", "license": "MIT" }, + "node_modules/sax": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz", + "integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==", + "license": "BlueOak-1.0.0", + "engines": { + "node": ">=11.0.0" + } + }, "node_modules/saxes": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz", @@ -14373,6 +14376,40 @@ "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==", "dev": true }, + "node_modules/sitemap": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/sitemap/-/sitemap-9.0.1.tgz", + "integrity": "sha512-S6hzjGJSG3d6if0YoF5kTyeRJvia6FSTBroE5fQ0bu1QNxyJqhhinfUsXi9fH3MgtXODWvwo2BDyQSnhPQ88uQ==", + "license": "MIT", + "dependencies": { + "@types/node": "^24.9.2", + "@types/sax": "^1.2.1", + "arg": "^5.0.0", + "sax": "^1.4.1" + }, + "bin": { + "sitemap": "dist/esm/cli.js" + }, + "engines": { + "node": ">=20.19.5", + "npm": ">=10.8.2" + } + }, + "node_modules/sitemap/node_modules/@types/node": { + "version": "24.12.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.2.tgz", + "integrity": "sha512-A1sre26ke7HDIuY/M23nd9gfB+nrmhtYyMINbjI1zHJxYteKR6qSMX56FsmjMcDb3SMcjJg5BiRRgOCC/yBD0g==", + "license": "MIT", + "dependencies": { + "undici-types": "~7.16.0" + } + }, + "node_modules/sitemap/node_modules/undici-types": { + "version": "7.16.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz", + "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==", + "license": "MIT" + }, "node_modules/source-map": { "version": "0.6.1", "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", @@ -14701,8 +14738,7 @@ "version": "4.1.14", "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.14.tgz", "integrity": "sha512-b7pCxjGO98LnxVkKjaZSDeNuljC4ueKUddjENJOADtubtdo8llTaJy7HwBMeLNSSo2N5QIAgklslK1+Ir8r6CA==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/tailwindcss-animate": { "version": "1.0.7", @@ -15542,7 +15578,6 @@ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -15598,7 +15633,6 @@ "version": "6.21.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", - "dev": true, "license": "MIT" }, "node_modules/unified": { @@ -15745,7 +15779,6 @@ "dev": true, "hasInstallScript": true, "license": "MIT", - "peer": true, "dependencies": { "napi-postinstall": "^0.3.0" }, @@ -15955,7 +15988,6 @@ "integrity": "sha512-tI2l/nFHC5rLh7+5+o7QjKjSR04ivXDF4jcgV0f/bTQ+OJiITy5S6gaynVsEM+7RqzufMnVbIon6Sr5x1SDYaQ==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.5.0", diff --git a/zookeeper-website/package.json b/zookeeper-website/package.json index 9a5f915d4fa..01b46951ffd 100644 --- a/zookeeper-website/package.json +++ b/zookeeper-website/package.json @@ -6,7 +6,7 @@ "node": ">=22.12.0" }, "scripts": { - "build": "react-router build", + "build": "react-router build && npm run generate-sitemap", "dev": "react-router dev", "start": "serve -s build/client -l 5173", "typecheck": "react-router typegen && tsc", @@ -22,6 +22,7 @@ "test:e2e:headed": "playwright test --headed", "test:e2e:debug": "playwright test --debug", "fumadocs-init": "fumadocs-mdx", + "generate-sitemap": "tsx scripts/generate-sitemap.ts", "ci": "npm run fumadocs-init && npm run lint && npm run typecheck && npm run test:unit:run && npm run build && npx playwright install && npm run test:e2e", "ci-skip-tests": "npm run fumadocs-init && npm run build" }, @@ -71,6 +72,7 @@ "remark-heading-id": "^1.0.1", "remark-math": "^6.0.0", "scroll-into-view-if-needed": "^3.1.0", + "sitemap": "^9.0.1", "tailwind-merge": "^2.5.5", "tailwindcss-animate": "^1.0.7" }, diff --git a/zookeeper-website/public/.htaccess b/zookeeper-website/public/.htaccess index 4f37d8f5974..07b3fb7c150 100644 --- a/zookeeper-website/public/.htaccess +++ b/zookeeper-website/public/.htaccess @@ -16,3 +16,11 @@ # under the License. ErrorDocument 404 /404/index.html + + + Header always set Cache-Control "no-cache, must-revalidate" + + + Header always set Cache-Control "public, max-age=2592000, immutable" + + diff --git a/zookeeper-website/public/robots.txt b/zookeeper-website/public/robots.txt new file mode 100644 index 00000000000..0fd09dba1f2 --- /dev/null +++ b/zookeeper-website/public/robots.txt @@ -0,0 +1,5 @@ +User-agent: * +Allow: / +Disallow: /404/ + +Sitemap: https://zookeeper.apache.org/sitemap.xml diff --git a/zookeeper-website/scripts/generate-sitemap.test.ts b/zookeeper-website/scripts/generate-sitemap.test.ts new file mode 100644 index 00000000000..0373d53dd5c --- /dev/null +++ b/zookeeper-website/scripts/generate-sitemap.test.ts @@ -0,0 +1,107 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { describe, expect, it } from "vitest"; +import { + isRedirectOnlyPage, + normalizePath, + shouldIncludeInSitemap, + toSiteUrl +} from "../scripts/generate-sitemap"; + +describe("normalizePath", () => { + it("preserves forward-slash paths", () => { + expect(normalizePath("docs/index.html")).toBe("docs/index.html"); + }); + + it("converts windows separators to forward slashes", () => { + expect(normalizePath("docs\\features\\metrics\\index.html")).toBe( + "docs/features/metrics/index.html" + ); + }); +}); + +describe("toSiteUrl", () => { + it("maps the root index file to slash", () => { + expect(toSiteUrl("index.html")).toBe("/"); + }); + + it("maps nested index files to trailing-slash URLs", () => { + expect(toSiteUrl("docs/features/metrics/index.html")).toBe( + "/docs/features/metrics/" + ); + }); + + it("preserves non-index html filenames", () => { + expect(toSiteUrl("news/archive.html")).toBe("/news/archive.html"); + }); +}); + +describe("isRedirectOnlyPage", () => { + it("detects javascript redirect pages", () => { + expect( + isRedirectOnlyPage( + '' + ) + ).toBe(true); + }); + + it("detects meta refresh redirects", () => { + expect( + isRedirectOnlyPage( + '' + ) + ).toBe(true); + }); + + it("does not flag ordinary html pages", () => { + expect( + isRedirectOnlyPage("

      Apache ZooKeeper

      ") + ).toBe(false); + }); +}); + +describe("shouldIncludeInSitemap", () => { + it("excludes explicitly ignored html paths", () => { + expect(shouldIncludeInSitemap("404.html", "")).toBe(false); + expect(shouldIncludeInSitemap("404/index.html", "")).toBe( + false + ); + expect(shouldIncludeInSitemap("__spa-fallback.html", "")).toBe( + false + ); + }); + + it("excludes redirect-only pages even if the path is not prelisted", () => { + expect( + shouldIncludeInSitemap( + "downloads/latest/index.html", + '' + ) + ).toBe(false); + }); + + it("includes normal prerendered pages", () => { + expect( + shouldIncludeInSitemap( + "docs/features/metrics/index.html", + "

      Metrics

      " + ) + ).toBe(true); + }); +}); diff --git a/zookeeper-website/scripts/generate-sitemap.ts b/zookeeper-website/scripts/generate-sitemap.ts new file mode 100644 index 00000000000..97bcdc7ca55 --- /dev/null +++ b/zookeeper-website/scripts/generate-sitemap.ts @@ -0,0 +1,125 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +import { access, glob, readFile, stat, writeFile } from "node:fs/promises"; +import { fileURLToPath } from "node:url"; +import { join } from "node:path"; +import { SitemapStream, streamToPromise } from "sitemap"; + +const ROOT = join(import.meta.dirname, ".."); +const BUILD_DIR = join(ROOT, "build", "client"); +const SITEMAP_PATH = join(BUILD_DIR, "sitemap.xml"); +const SITE_URL = "https://zookeeper.apache.org"; + +const EXCLUDED_HTML_PATHS = new Set([ + "404.html", + "404/index.html", + "__spa-fallback.html", +]); + +const REDIRECT_PAGE_PATTERNS = [ + /window\.location\.replace\(/i, + /http-equiv=["']refresh/i, + />Redirecting to .*?If it does not happen automatically,/is +]; + +interface SitemapEntry { + url: string; + lastmod: string; +} + +export function normalizePath(relativePath: string): string { + return relativePath.replaceAll("\\", "/"); +} + +export function toSiteUrl(relativePath: string): string { + if (relativePath === "index.html") { + return "/"; + } + + if (relativePath.endsWith("/index.html")) { + return `/${relativePath.slice(0, -"/index.html".length)}/`; + } + + return `/${relativePath}`; +} + +export function isRedirectOnlyPage(html: string): boolean { + return REDIRECT_PAGE_PATTERNS.some((pattern) => pattern.test(html)); +} + +export function shouldIncludeInSitemap( + relativePath: string, + html: string +): boolean { + if (EXCLUDED_HTML_PATHS.has(relativePath)) { + return false; + } + + return !isRedirectOnlyPage(html); +} + +export async function collectSitemapEntries(): Promise { + const entries: SitemapEntry[] = []; + + for await (const htmlPath of glob("**/*.html", { cwd: BUILD_DIR })) { + const relativePath = normalizePath(htmlPath); + const filePath = join(BUILD_DIR, relativePath); + const html = await readFile(filePath, "utf8"); + + if (!shouldIncludeInSitemap(relativePath, html)) { + continue; + } + + const { mtime } = await stat(filePath); + + entries.push({ + url: toSiteUrl(relativePath), + lastmod: mtime.toISOString() + }); + } + + entries.sort((left, right) => left.url.localeCompare(right.url)); + return entries; +} + +export async function main() { + await access(BUILD_DIR); + + const entries = await collectSitemapEntries(); + const sitemap = new SitemapStream({ hostname: SITE_URL }); + + for (const entry of entries) { + sitemap.write(entry); + } + + sitemap.end(); + + const xml = (await streamToPromise(sitemap)).toString(); + await writeFile(SITEMAP_PATH, xml); + + console.log( + `Generated sitemap with ${entries.length} URLs at ${SITEMAP_PATH}` + ); +} + +const isDirectRun = process.argv[1] === fileURLToPath(import.meta.url); + +if (isDirectRun) { + await main(); +} From 0e0ecb2533b329d7e8551c924dc4aa7df93cf8de Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 14:56:16 +0200 Subject: [PATCH 7/9] Fix CVEs --- zookeeper-website/package-lock.json | 640 +++++++++++++++++++++++++--- 1 file changed, 573 insertions(+), 67 deletions(-) diff --git a/zookeeper-website/package-lock.json b/zookeeper-website/package-lock.json index d36b1c096ad..c68303ca35a 100644 --- a/zookeeper-website/package-lock.json +++ b/zookeeper-website/package-lock.json @@ -4655,6 +4655,16 @@ "integrity": "sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA==", "dev": true }, + "node_modules/@types/ws": { + "version": "8.18.1", + "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz", + "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, "node_modules/@typescript-eslint/eslint-plugin": { "version": "8.56.0", "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.56.0.tgz", @@ -4844,9 +4854,9 @@ } }, "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", - "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz", + "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==", "dev": true, "license": "MIT", "dependencies": { @@ -5896,9 +5906,9 @@ } }, "node_modules/brace-expansion": { - "version": "1.1.12", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", - "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", + "version": "1.1.14", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz", + "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==", "dev": true, "license": "MIT", "dependencies": { @@ -8102,6 +8112,23 @@ "dev": true, "license": "MIT" }, + "node_modules/fast-uri": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", + "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, "node_modules/fdir": { "version": "6.5.0", "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", @@ -8197,9 +8224,9 @@ } }, "node_modules/flatted": { - "version": "3.3.3", - "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz", - "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==", + "version": "3.4.2", + "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.2.tgz", + "integrity": "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==", "dev": true, "license": "ISC" }, @@ -8348,9 +8375,9 @@ } }, "node_modules/fumadocs-core/node_modules/path-to-regexp": { - "version": "8.3.0", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz", - "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==", + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", "license": "MIT", "funding": { "type": "opencollective", @@ -9346,26 +9373,34 @@ "license": "ISC" }, "node_modules/happy-dom": { - "version": "20.0.8", - "resolved": "https://registry.npmjs.org/happy-dom/-/happy-dom-20.0.8.tgz", - "integrity": "sha512-TlYaNQNtzsZ97rNMBAm8U+e2cUQXNithgfCizkDgc11lgmN4j9CKMhO3FPGKWQYPwwkFcPpoXYF/CqEPLgzfOg==", + "version": "20.9.0", + "resolved": "https://registry.npmjs.org/happy-dom/-/happy-dom-20.9.0.tgz", + "integrity": "sha512-GZZ9mKe8r646NUAf/zemnGbjYh4Bt8/MqASJY+pSm5ZDtc3YQox+4gsLI7yi1hba6o+eCsGxpHn5+iEVn31/FQ==", "dev": true, + "license": "MIT", "dependencies": { - "@types/node": "^20.0.0", + "@types/node": ">=20.0.0", "@types/whatwg-mimetype": "^3.0.2", - "whatwg-mimetype": "^3.0.0" + "@types/ws": "^8.18.1", + "entities": "^7.0.1", + "whatwg-mimetype": "^3.0.0", + "ws": "^8.18.3" }, "engines": { "node": ">=20.0.0" } }, - "node_modules/happy-dom/node_modules/@types/node": { - "version": "20.19.23", - "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.23.tgz", - "integrity": "sha512-yIdlVVVHXpmqRhtyovZAcSy0MiPcYWGkoO4CGe/+jpP0hmNuihm4XhHbADpK++MsiLHP5MVlv+bcgdF99kSiFQ==", + "node_modules/happy-dom/node_modules/entities": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz", + "integrity": "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==", "dev": true, - "dependencies": { - "undici-types": "~6.21.0" + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" } }, "node_modules/has-bigints": { @@ -10933,9 +10968,9 @@ } }, "node_modules/lodash": { - "version": "4.17.23", - "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz", - "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==", + "version": "4.18.1", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz", + "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==", "license": "MIT" }, "node_modules/lodash.merge": { @@ -12711,9 +12746,9 @@ "license": "MIT" }, "node_modules/path-to-regexp": { - "version": "0.1.12", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.12.tgz", - "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==", + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz", + "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==", "license": "MIT" }, "node_modules/pathe": { @@ -12750,9 +12785,9 @@ "license": "ISC" }, "node_modules/picomatch": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", - "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz", + "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "license": "MIT", "engines": { "node": ">=12" @@ -14032,14 +14067,14 @@ "license": "MIT" }, "node_modules/serve": { - "version": "14.2.5", - "resolved": "https://registry.npmjs.org/serve/-/serve-14.2.5.tgz", - "integrity": "sha512-Qn/qMkzCcMFVPb60E/hQy+iRLpiU8PamOfOSYoAHmmF+fFFmpPpqa6Oci2iWYpTdOUM3VF+TINud7CfbQnsZbA==", + "version": "14.2.6", + "resolved": "https://registry.npmjs.org/serve/-/serve-14.2.6.tgz", + "integrity": "sha512-QEjUSA+sD4Rotm1znR8s50YqA3kYpRGPmtd5GlFxbaL9n/FdUNbqMhxClqdditSk0LlZyA/dhud6XNRTOC9x2Q==", "dev": true, "license": "MIT", "dependencies": { "@zeit/schemas": "2.36.0", - "ajv": "8.12.0", + "ajv": "8.18.0", "arg": "5.0.2", "boxen": "7.0.0", "chalk": "5.0.1", @@ -14047,7 +14082,7 @@ "clipboardy": "3.0.0", "compression": "1.8.1", "is-port-reachable": "4.0.0", - "serve-handler": "6.1.6", + "serve-handler": "6.1.7", "update-check": "1.5.4" }, "bin": { @@ -14058,16 +14093,16 @@ } }, "node_modules/serve-handler": { - "version": "6.1.6", - "resolved": "https://registry.npmjs.org/serve-handler/-/serve-handler-6.1.6.tgz", - "integrity": "sha512-x5RL9Y2p5+Sh3D38Fh9i/iQ5ZK+e4xuXRd/pGbM4D13tgo/MGwbttUk8emytcr1YYzBYs+apnUngBDFYfpjPuQ==", + "version": "6.1.7", + "resolved": "https://registry.npmjs.org/serve-handler/-/serve-handler-6.1.7.tgz", + "integrity": "sha512-CinAq1xWb0vR3twAv9evEU8cNWkXCb9kd5ePAHUKJBkOsUpR1wt/CvGdeca7vqumL1U5cSaeVQ6zZMxiJ3yWsg==", "dev": true, "license": "MIT", "dependencies": { "bytes": "3.0.0", "content-disposition": "0.5.2", "mime-types": "2.1.18", - "minimatch": "3.1.2", + "minimatch": "3.1.5", "path-is-inside": "1.0.2", "path-to-regexp": "3.3.0", "range-parser": "1.2.0" @@ -14116,19 +14151,6 @@ "node": ">= 0.6" } }, - "node_modules/serve-handler/node_modules/minimatch": { - "version": "3.1.2", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz", - "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==", - "dev": true, - "license": "ISC", - "dependencies": { - "brace-expansion": "^1.1.7" - }, - "engines": { - "node": "*" - } - }, "node_modules/serve-handler/node_modules/path-to-regexp": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-3.3.0.tgz", @@ -14162,16 +14184,16 @@ } }, "node_modules/serve/node_modules/ajv": { - "version": "8.12.0", - "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.12.0.tgz", - "integrity": "sha512-sRu1kpcO9yLtYxBKvqfTeh9KzZEwO3STyX1HT+4CaDzC6HpTGYhIhPIzj9XuKU7KYDwnaeh5hcOwjy1QuJzBPA==", + "version": "8.18.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", + "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", "dev": true, "license": "MIT", "dependencies": { - "fast-deep-equal": "^3.1.1", + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", - "require-from-string": "^2.0.2", - "uri-js": "^4.2.2" + "require-from-string": "^2.0.2" }, "funding": { "type": "github", @@ -14764,9 +14786,9 @@ } }, "node_modules/tar": { - "version": "7.5.9", - "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.9.tgz", - "integrity": "sha512-BTLcK0xsDh2+PUe9F6c2TlRp4zOOBMTkoQHQIWSIzI0R7KG46uEwq4OPk2W7bZcprBMsuaeFsqwYr7pjh6CuHg==", + "version": "7.5.13", + "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.13.tgz", + "integrity": "sha512-tOG/7GyXpFevhXVh8jOPJrmtRpOTsYqUIkVdVooZYJS/z8WhfQUX8RJILmeuJNinGAMSu1veBr4asSHFt5/hng==", "dev": true, "license": "BlueOak-1.0.0", "dependencies": { @@ -15983,13 +16005,13 @@ } }, "node_modules/vite": { - "version": "7.2.6", - "resolved": "https://registry.npmjs.org/vite/-/vite-7.2.6.tgz", - "integrity": "sha512-tI2l/nFHC5rLh7+5+o7QjKjSR04ivXDF4jcgV0f/bTQ+OJiITy5S6gaynVsEM+7RqzufMnVbIon6Sr5x1SDYaQ==", + "version": "7.3.2", + "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.2.tgz", + "integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==", "devOptional": true, "license": "MIT", "dependencies": { - "esbuild": "^0.25.0", + "esbuild": "^0.27.0", "fdir": "^6.5.0", "picomatch": "^4.0.3", "postcss": "^8.5.6", @@ -16107,6 +16129,490 @@ } } }, + "node_modules/vite/node_modules/@esbuild/aix-ppc64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz", + "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/android-arm": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz", + "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/android-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz", + "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/android-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz", + "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/darwin-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz", + "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/darwin-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz", + "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/freebsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz", + "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/freebsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz", + "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-arm": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz", + "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz", + "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-ia32": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz", + "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-loong64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz", + "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-mips64el": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz", + "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-ppc64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz", + "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-riscv64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz", + "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-s390x": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz", + "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/linux-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz", + "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/netbsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz", + "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/netbsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz", + "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/openbsd-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz", + "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/openbsd-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz", + "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/openharmony-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz", + "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/sunos-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz", + "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/win32-arm64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz", + "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/win32-ia32": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz", + "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/@esbuild/win32-x64": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz", + "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/vite/node_modules/esbuild": { + "version": "0.27.7", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz", + "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==", + "devOptional": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.27.7", + "@esbuild/android-arm": "0.27.7", + "@esbuild/android-arm64": "0.27.7", + "@esbuild/android-x64": "0.27.7", + "@esbuild/darwin-arm64": "0.27.7", + "@esbuild/darwin-x64": "0.27.7", + "@esbuild/freebsd-arm64": "0.27.7", + "@esbuild/freebsd-x64": "0.27.7", + "@esbuild/linux-arm": "0.27.7", + "@esbuild/linux-arm64": "0.27.7", + "@esbuild/linux-ia32": "0.27.7", + "@esbuild/linux-loong64": "0.27.7", + "@esbuild/linux-mips64el": "0.27.7", + "@esbuild/linux-ppc64": "0.27.7", + "@esbuild/linux-riscv64": "0.27.7", + "@esbuild/linux-s390x": "0.27.7", + "@esbuild/linux-x64": "0.27.7", + "@esbuild/netbsd-arm64": "0.27.7", + "@esbuild/netbsd-x64": "0.27.7", + "@esbuild/openbsd-arm64": "0.27.7", + "@esbuild/openbsd-x64": "0.27.7", + "@esbuild/openharmony-arm64": "0.27.7", + "@esbuild/sunos-x64": "0.27.7", + "@esbuild/win32-arm64": "0.27.7", + "@esbuild/win32-ia32": "0.27.7", + "@esbuild/win32-x64": "0.27.7" + } + }, "node_modules/vitest": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.0.4.tgz", From f9f5a8c29931c66a8059087b068d276b3cb56751 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 14:56:20 +0200 Subject: [PATCH 8/9] Fix lint --- zookeeper-website/scripts/generate-sitemap.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zookeeper-website/scripts/generate-sitemap.ts b/zookeeper-website/scripts/generate-sitemap.ts index 97bcdc7ca55..97c7d29b72c 100644 --- a/zookeeper-website/scripts/generate-sitemap.ts +++ b/zookeeper-website/scripts/generate-sitemap.ts @@ -29,7 +29,7 @@ const SITE_URL = "https://zookeeper.apache.org"; const EXCLUDED_HTML_PATHS = new Set([ "404.html", "404/index.html", - "__spa-fallback.html", + "__spa-fallback.html" ]); const REDIRECT_PAGE_PATTERNS = [ From ff2606e5a05e0284d23d52bba9646dc789bf9e11 Mon Sep 17 00:00:00 2001 From: Yurii Palamarchuk Date: Thu, 23 Apr 2026 15:37:07 +0200 Subject: [PATCH 9/9] Move RAT plugin exclusions for .mdx files and robots.txt to zookeeper-website module --- pom.xml | 1 - zookeeper-website/pom.xml | 12 +++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/pom.xml b/pom.xml index 50b8a77849f..2e14fe6abd3 100644 --- a/pom.xml +++ b/pom.xml @@ -1073,7 +1073,6 @@ **/README.md - **/*.mdx **/findbugsExcludeFile.xml **/checkstyle-noframes-sorted.xsl **/configure.ac diff --git a/zookeeper-website/pom.xml b/zookeeper-website/pom.xml index 3215e54dcad..a0bb20009d3 100644 --- a/zookeeper-website/pom.xml +++ b/zookeeper-website/pom.xml @@ -43,6 +43,16 @@ + + org.apache.rat + apache-rat-plugin + + + **/*.mdx + public/robots.txt + + + org.apache.maven.plugins maven-clean-plugin @@ -63,7 +73,7 @@ com.github.eirslett frontend-maven-plugin 1.15.1 - + ${project.build.directory} ${project.basedir}