From 697e52a07ca577437b85a8a7696a1020d6d2d147 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Wed, 11 Oct 2023 12:55:33 +0100 Subject: [PATCH 1/8] feat(docs/concepts): add details around resource definitions --- docs/site/pages/concepts/_meta.json | 1 + docs/site/pages/concepts/definitions.mdx | 45 +++++++++++++++++++ .../{concepts.mdx => concepts/overview.mdx} | 0 3 files changed, 46 insertions(+) rename docs/site/pages/{concepts.mdx => concepts/overview.mdx} (100%) diff --git a/docs/site/pages/concepts/_meta.json b/docs/site/pages/concepts/_meta.json index 2b8d3f1..43588f0 100644 --- a/docs/site/pages/concepts/_meta.json +++ b/docs/site/pages/concepts/_meta.json @@ -1,4 +1,5 @@ { + "overview": "Overview", "definitions": "Resource Definitions", "controllers": "Controllers", "bindings": "Bindings" diff --git a/docs/site/pages/concepts/definitions.mdx b/docs/site/pages/concepts/definitions.mdx index 76934d0..e636c56 100644 --- a/docs/site/pages/concepts/definitions.mdx +++ b/docs/site/pages/concepts/definitions.mdx @@ -9,3 +9,48 @@ to learn how they can be configured. Resource definitions describe the schema for the different resource kinds available in a Cup instance. +When you interact with the Cup API, you do so through the various resource definition configured. + +A Cup resource is comprised of a few components to build the entire definition. +These components and concepts are taken directly from Kubernetes and its custom resource definitions (CRD). +Each definition consists of: + +- A group +- A set of kind names +- Multiple versioned JSON schema definitions +- Some extra user defined arbitrary metadata + +## Groups + +Groups are a top-level construct for grouping related kinds of resource definitions together. +Usually a group name identifies an organization or domain for a set of related resource types. + +For example, `flipt.io` is the group for Flipt feature flag related resources. + +## Kind names + +Kinds are the the unique name identifier for a resource scoped within a particular group. +As with Kubernetes CRDs, Cup's resource definitions required you to declare a few variations on the kinds name. + +These variations are: + +- `Kind` (canonical kind name in Title-case) +- `singular` (lowercase term referring to a single instance of the kind) +- `plural` (lowercase term referring to two or more instances of the kind) + +For example, for a Flipt feature flag we have the names: + +- `Kind` is `Flag` +- `singular` is `flag` +- `plural` is `flags` + +These different forms can be used by downstream tools to provide meaningful and readable interfaces when interacting with these resource kinds. + +## Versioned JSON Schema + +At their core, the resource definitions are comprised of schemas for the fields the resource kinds contain. +Cup uses [JSON Schema](https://json-schema.org/) as the schema definition language. + +Cup organizes schemas into separate versions. +This is important, because over time resources can and will change. +Versions allow definition authors to provide guarantees to downstream consumers regarding the shape of resources. diff --git a/docs/site/pages/concepts.mdx b/docs/site/pages/concepts/overview.mdx similarity index 100% rename from docs/site/pages/concepts.mdx rename to docs/site/pages/concepts/overview.mdx From 41e74e97230ed7d7d05cf68138aabeb9f706af82 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Wed, 11 Oct 2023 13:30:50 +0100 Subject: [PATCH 2/8] chore: upgrade nextra --- docs/site/package.json | 6 +- docs/site/pnpm-lock.yaml | 426 ++++++++++++++++++++++++++------------- 2 files changed, 291 insertions(+), 141 deletions(-) diff --git a/docs/site/package.json b/docs/site/package.json index d3bfe43..01c2a35 100644 --- a/docs/site/package.json +++ b/docs/site/package.json @@ -1,9 +1,9 @@ { "dependencies": { "next": "^13.4.16", + "nextra": "^2.13.2", + "nextra-theme-docs": "^2.11.0", "react": "^18.2.0", - "react-dom": "^18.2.0", - "nextra": "^2.11.0", - "nextra-theme-docs": "^2.11.0" + "react-dom": "^18.2.0" } } diff --git a/docs/site/pnpm-lock.yaml b/docs/site/pnpm-lock.yaml index ec1a891..bf4304d 100644 --- a/docs/site/pnpm-lock.yaml +++ b/docs/site/pnpm-lock.yaml @@ -9,11 +9,11 @@ dependencies: specifier: ^13.4.16 version: 13.4.16(react-dom@18.2.0)(react@18.2.0) nextra: - specifier: ^2.11.0 - version: 2.11.0(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) + specifier: ^2.13.2 + version: 2.13.2(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) nextra-theme-docs: specifier: ^2.11.0 - version: 2.11.0(next@13.4.16)(nextra@2.11.0)(react-dom@18.2.0)(react@18.2.0) + version: 2.11.0(next@13.4.16)(nextra@2.13.2)(react-dom@18.2.0)(react@18.2.0) react: specifier: ^18.2.0 version: 18.2.0 @@ -80,8 +80,8 @@ packages: react: 18.2.0 dev: false - /@napi-rs/simple-git-android-arm-eabi@0.1.8: - resolution: {integrity: sha512-JJCejHBB1G6O8nxjQLT4quWCcvLpC3oRdJJ9G3MFYSCoYS8i1bWCWeU+K7Br+xT+D6s1t9q8kNJAwJv9Ygpi0g==} + /@napi-rs/simple-git-android-arm-eabi@0.1.9: + resolution: {integrity: sha512-9D4JnfePMpgL4pg9aMUX7/TIWEUQ+Tgx8n3Pf8TNCMGjUbImJyYsDSLJzbcv9wH7srgn4GRjSizXFJHAPjzEug==} engines: {node: '>= 10'} cpu: [arm] os: [android] @@ -89,8 +89,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-android-arm64@0.1.8: - resolution: {integrity: sha512-mraHzwWBw3tdRetNOS5KnFSjvdAbNBnjFLA8I4PwTCPJj3Q4txrigcPp2d59cJ0TC51xpnPXnZjYdNwwSI9g6g==} + /@napi-rs/simple-git-android-arm64@0.1.9: + resolution: {integrity: sha512-Krilsw0gPrrASZzudNEl9pdLuNbhoTK0j7pUbfB8FRifpPdFB/zouwuEm0aSnsDXN4ftGrmGG82kuiR/2MeoPg==} engines: {node: '>= 10'} cpu: [arm64] os: [android] @@ -98,8 +98,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-darwin-arm64@0.1.8: - resolution: {integrity: sha512-ufy/36eI/j4UskEuvqSH7uXtp3oXeLDmjQCfKJz3u5Vx98KmOMKrqAm2H81AB2WOtCo5mqS6PbBeUXR8BJX8lQ==} + /@napi-rs/simple-git-darwin-arm64@0.1.9: + resolution: {integrity: sha512-H/F09nDgYjv4gcFrZBgdTKkZEepqt0KLYcCJuUADuxkKupmjLdecMhypXLk13AzvLW4UQI7NlLTLDXUFLyr2BA==} engines: {node: '>= 10'} cpu: [arm64] os: [darwin] @@ -107,8 +107,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-darwin-x64@0.1.8: - resolution: {integrity: sha512-Vb21U+v3tPJNl+8JtIHHT8HGe6WZ8o1Tq3f6p+Jx9Cz71zEbcIiB9FCEMY1knS/jwQEOuhhlI9Qk7d4HY+rprA==} + /@napi-rs/simple-git-darwin-x64@0.1.9: + resolution: {integrity: sha512-jBR2xS9nVPqmHv0TWz874W0m/d453MGrMeLjB+boK5IPPLhg3AWIZj0aN9jy2Je1BGVAa0w3INIQJtBBeB6kFA==} engines: {node: '>= 10'} cpu: [x64] os: [darwin] @@ -116,8 +116,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-linux-arm-gnueabihf@0.1.8: - resolution: {integrity: sha512-6BPTJ7CzpSm2t54mRLVaUr3S7ORJfVJoCk2rQ8v8oDg0XAMKvmQQxOsAgqKBo9gYNHJnqrOx3AEuEgvB586BuQ==} + /@napi-rs/simple-git-linux-arm-gnueabihf@0.1.9: + resolution: {integrity: sha512-3n0+VpO4YfZxndZ0sCvsHIvsazd+JmbSjrlTRBCnJeAU1/sfos3skNZtKGZksZhjvd+3o+/GFM8L7Xnv01yggA==} engines: {node: '>= 10'} cpu: [arm] os: [linux] @@ -125,8 +125,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-linux-arm64-gnu@0.1.8: - resolution: {integrity: sha512-qfESqUCAA/XoQpRXHptSQ8gIFnETCQt1zY9VOkplx6tgYk9PCeaX4B1Xuzrh3eZamSCMJFn+1YB9Ut8NwyGgAA==} + /@napi-rs/simple-git-linux-arm64-gnu@0.1.9: + resolution: {integrity: sha512-lIzf0KHU2SKC12vMrWwCtysG2Sdt31VHRPMUiz9lD9t3xwVn8qhFSTn5yDkTeG3rgX6o0p5EKalfQN5BXsJq2w==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] @@ -134,8 +134,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-linux-arm64-musl@0.1.8: - resolution: {integrity: sha512-G80BQPpaRmQpn8dJGHp4I2/YVhWDUNJwcCrJAtAdbKFDCMyCHJBln2ERL/+IEUlIAT05zK/c1Z5WEprvXEdXow==} + /@napi-rs/simple-git-linux-arm64-musl@0.1.9: + resolution: {integrity: sha512-KQozUoNXrxrB8k741ncWXSiMbjl1AGBGfZV21PANzUM8wH4Yem2bg3kfglYS/QIx3udspsT35I9abu49n7D1/w==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] @@ -143,8 +143,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-linux-x64-gnu@0.1.8: - resolution: {integrity: sha512-NI6o1sZYEf6vPtNWJAm9w8BxJt+LlSFW0liSjYe3lc3e4dhMfV240f0ALeqlwdIldRPaDFwZSJX5/QbS7nMzhw==} + /@napi-rs/simple-git-linux-x64-gnu@0.1.9: + resolution: {integrity: sha512-O/Niui5mnHPcK3iYC3ui8wgERtJWsQ3Y74W/09t0bL/3dgzGMl4oQt0qTj9dWCsnoGsIEYHPzwCBp/2vqYp/pw==} engines: {node: '>= 10'} cpu: [x64] os: [linux] @@ -152,8 +152,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-linux-x64-musl@0.1.8: - resolution: {integrity: sha512-wljGAEOW41er45VTiU8kXJmO480pQKzsgRCvPlJJSCaEVBbmo6XXbFIXnZy1a2J3Zyy2IOsRB4PVkUZaNuPkZQ==} + /@napi-rs/simple-git-linux-x64-musl@0.1.9: + resolution: {integrity: sha512-L9n+e8Wn3hKr3RsIdY8GaB+ry4xZ4BaGwyKExgoB8nDGQuRUY9oP6p0WA4hWfJvJnU1H6hvo36a5UFPReyBO7A==} engines: {node: '>= 10'} cpu: [x64] os: [linux] @@ -161,8 +161,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-win32-arm64-msvc@0.1.8: - resolution: {integrity: sha512-QuV4QILyKPfbWHoQKrhXqjiCClx0SxbCTVogkR89BwivekqJMd9UlMxZdoCmwLWutRx4z9KmzQqokvYI5QeepA==} + /@napi-rs/simple-git-win32-arm64-msvc@0.1.9: + resolution: {integrity: sha512-Z6Ja/SZK+lMvRWaxj7wjnvSbAsGrH006sqZo8P8nxKUdZfkVvoCaAWr1r0cfkk2Z3aijLLtD+vKeXGlUPH6gGQ==} engines: {node: '>= 10'} cpu: [arm64] os: [win32] @@ -170,8 +170,8 @@ packages: dev: false optional: true - /@napi-rs/simple-git-win32-x64-msvc@0.1.8: - resolution: {integrity: sha512-UzNS4JtjhZhZ5hRLq7BIUq+4JOwt1ThIKv11CsF1ag2l99f0123XvfEpjczKTaa94nHtjXYc2Mv9TjccBqYOew==} + /@napi-rs/simple-git-win32-x64-msvc@0.1.9: + resolution: {integrity: sha512-VAZj1UvC+R2MjKOD3I/Y7dmQlHWAYy4omhReQJRpbCf+oGCBi9CWiIduGqeYEq723nLIKdxP7XjaO0wl1NnUww==} engines: {node: '>= 10'} cpu: [x64] os: [win32] @@ -179,21 +179,21 @@ packages: dev: false optional: true - /@napi-rs/simple-git@0.1.8: - resolution: {integrity: sha512-BvOMdkkofTz6lEE35itJ/laUokPhr/5ToMGlOH25YnhLD2yN1KpRAT4blW9tT8281/1aZjW3xyi73bs//IrDKA==} + /@napi-rs/simple-git@0.1.9: + resolution: {integrity: sha512-qKzDS0+VjMvVyU28px+C6zlD1HKy83NIdYzfMQWa/g/V1iG/Ic8uwrS2ihHfm7mp7X0PPrmINLiTTi6ieUIKfw==} engines: {node: '>= 10'} optionalDependencies: - '@napi-rs/simple-git-android-arm-eabi': 0.1.8 - '@napi-rs/simple-git-android-arm64': 0.1.8 - '@napi-rs/simple-git-darwin-arm64': 0.1.8 - '@napi-rs/simple-git-darwin-x64': 0.1.8 - '@napi-rs/simple-git-linux-arm-gnueabihf': 0.1.8 - '@napi-rs/simple-git-linux-arm64-gnu': 0.1.8 - '@napi-rs/simple-git-linux-arm64-musl': 0.1.8 - '@napi-rs/simple-git-linux-x64-gnu': 0.1.8 - '@napi-rs/simple-git-linux-x64-musl': 0.1.8 - '@napi-rs/simple-git-win32-arm64-msvc': 0.1.8 - '@napi-rs/simple-git-win32-x64-msvc': 0.1.8 + '@napi-rs/simple-git-android-arm-eabi': 0.1.9 + '@napi-rs/simple-git-android-arm64': 0.1.9 + '@napi-rs/simple-git-darwin-arm64': 0.1.9 + '@napi-rs/simple-git-darwin-x64': 0.1.9 + '@napi-rs/simple-git-linux-arm-gnueabihf': 0.1.9 + '@napi-rs/simple-git-linux-arm64-gnu': 0.1.9 + '@napi-rs/simple-git-linux-arm64-musl': 0.1.9 + '@napi-rs/simple-git-linux-x64-gnu': 0.1.9 + '@napi-rs/simple-git-linux-x64-musl': 0.1.9 + '@napi-rs/simple-git-win32-arm64-msvc': 0.1.9 + '@napi-rs/simple-git-win32-x64-msvc': 0.1.9 dev: false /@next/env@13.4.16: @@ -291,22 +291,22 @@ packages: tslib: 2.6.1 dev: false - /@theguild/remark-mermaid@0.0.4(react@18.2.0): - resolution: {integrity: sha512-C1gssw07eURtCwzXqZZdvyV/eawQ/cXfARaXIgBU9orffox+/YQ+exxmNu9v16NSGzAVsGF4qEVHvCOcCR/FpQ==} + /@theguild/remark-mermaid@0.0.5(react@18.2.0): + resolution: {integrity: sha512-e+ZIyJkEv9jabI4m7q29wZtZv+2iwPGsXJ2d46Zi7e+QcFudiyuqhLhHG/3gX3ZEB+hxTch+fpItyMS8jwbIcw==} peerDependencies: react: ^18.2.0 dependencies: - mermaid: 10.3.1 + mermaid: 10.5.0 react: 18.2.0 unist-util-visit: 5.0.0 transitivePeerDependencies: - supports-color dev: false - /@theguild/remark-npm2yarn@0.1.1: - resolution: {integrity: sha512-ZKwd/bjQ9V+pESLnu8+q8jqn15alXzJOuVckraebsXwqVBTw53Gmupiw9zCdLNHU829KTYNycJYea6m9HRLuOg==} + /@theguild/remark-npm2yarn@0.2.1: + resolution: {integrity: sha512-jUTFWwDxtLEFtGZh/TW/w30ySaDJ8atKWH8dq2/IiQF61dPrGfETpl0WxD0VdBfuLOeU14/kop466oBSRO/5CA==} dependencies: - npm-to-yarn: 2.0.0 + npm-to-yarn: 2.1.0 unist-util-visit: 5.0.0 dev: false @@ -320,14 +320,14 @@ packages: resolution: {integrity: sha512-dsoJGEIShosKVRBZB0Vo3C8nqSDqVGujJU6tPznsBJxNJNwMF8utmS83nvCBKQYPpjCzaaHcrf66iTRpZosLPw==} dev: false - /@types/d3-scale@4.0.3: - resolution: {integrity: sha512-PATBiMCpvHJSMtZAMEhc2WyL+hnzarKzI6wAHYjhsonjWJYGq5BXTzQjv4l8m2jO183/4wZ90rKvSeT7o72xNQ==} + /@types/d3-scale@4.0.5: + resolution: {integrity: sha512-w/C++3W394MHzcLKO2kdsIn5KKNTOqeQVzyPSGPLzQbkPw/jpeaGtSRlakcKevGgGsjJxGsbqS0fPrVFDbHrDA==} dependencies: - '@types/d3-time': 3.0.0 + '@types/d3-time': 3.0.1 dev: false - /@types/d3-time@3.0.0: - resolution: {integrity: sha512-sZLCdHvBUcNby1cB6Fd3ZBrABbjz3v1Vm90nysCQ6Vt7vd6e/h9Lt7SiJUoEX0l4Dzc7P5llKyhqSi1ycSf1Hg==} + /@types/d3-time@3.0.1: + resolution: {integrity: sha512-5j/AnefKAhCw4HpITmLDTPlf4vhi8o/dES+zbegfPb7LaGfNyqkLxBR6E+4yvTAgnJLmhe80EXFMzUs38fw4oA==} dev: false /@types/debug@4.1.8: @@ -352,24 +352,36 @@ packages: '@types/unist': 2.0.7 dev: false - /@types/js-yaml@4.0.5: - resolution: {integrity: sha512-FhpRzf927MNQdRZP0J5DLIdTXhjLYzeUTmLAu69mnVksLH9CJY3IuSeEgbKUki7GQZm0WqDkGzyxju2EZGD2wA==} + /@types/hast@3.0.1: + resolution: {integrity: sha512-hs/iBJx2aydugBQx5ETV3ZgeSS0oIreQrFJ4bjBl0XvM4wAmDjFEALY7p0rTSLt2eL+ibjRAAs9dTPiCLtmbqQ==} + dependencies: + '@types/unist': 3.0.0 dev: false - /@types/katex@0.14.0: - resolution: {integrity: sha512-+2FW2CcT0K3P+JMR8YG846bmDwplKUTsWgT2ENwdQ1UdVfRk3GQrh6Mi4sTopy30gI8Uau5CEqHTDZ6YvWIUPA==} + /@types/js-yaml@4.0.5: + resolution: {integrity: sha512-FhpRzf927MNQdRZP0J5DLIdTXhjLYzeUTmLAu69mnVksLH9CJY3IuSeEgbKUki7GQZm0WqDkGzyxju2EZGD2wA==} dev: false /@types/katex@0.16.2: resolution: {integrity: sha512-dHsSjSlU/EWEEbeNADr3FtZZOAXPkFPUO457QCnoNqcZQXNqNEu/svQd0Nritvd3wNff4vvC/f4e6xgX3Llt8A==} dev: false + /@types/katex@0.16.3: + resolution: {integrity: sha512-CeVMX9EhVUW8MWnei05eIRks4D5Wscw/W9Byz1s3PA+yJvcdvq9SaDjiUKvRvEgjpdTyJMjQA43ae4KTwsvOPg==} + dev: false + /@types/mdast@3.0.12: resolution: {integrity: sha512-DT+iNIRNX884cx0/Q1ja7NyUPpZuv0KPyL5rGNxm1WC1OtHstl7n4Jb7nk+xacNShQMbczJjt8uFzznpp6kYBg==} dependencies: '@types/unist': 2.0.7 dev: false + /@types/mdast@4.0.1: + resolution: {integrity: sha512-IlKct1rUTJ1T81d8OHzyop15kGv9A/ff7Gz7IJgrk6jDb4Udw77pCJ+vq8oxZf4Ghpm+616+i1s/LNg/Vh7d+g==} + dependencies: + '@types/unist': 3.0.0 + dev: false + /@types/mdx@2.0.6: resolution: {integrity: sha512-sVcwEG10aFU2KcM7cIA0M410UPv/DesOPyG8zMVk0QUDexHA3lYmGucpEpZ2dtWWhi2ip3CG+5g/iH0PwoW4Fw==} dev: false @@ -402,6 +414,10 @@ packages: resolution: {integrity: sha512-MFETx3tbTjE7Uk6vvnWINA/1iJ7LuMdO4fcq8UfF0pRbj01aGLduVvQcRyswuACJdpnHgg8E3rQLhaRdNEJS0w==} dev: false + /@ungap/structured-clone@1.2.0: + resolution: {integrity: sha512-zuVdFrMJiuCDQUMCzQaD6KL28MjnqqN8XnAqiEq9PNm/hCPTSGfrXCOfwj1ow4LFb/tNymJPwsNbVePc1xFqrQ==} + dev: false + /acorn-jsx@5.3.2(acorn@8.10.0): resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==} peerDependencies: @@ -867,8 +883,8 @@ packages: lodash-es: 4.17.21 dev: false - /dayjs@1.11.9: - resolution: {integrity: sha512-QvzAURSbQ0pKdIye2txOzNaHmxtUBXerpY0FJsFXUMKbIZeFm5ht1LS/jFsrncjnmtv8HsG0W2g6c0zUjZWmpA==} + /dayjs@1.11.10: + resolution: {integrity: sha512-vjAczensTgRcqDERK0SR2XMwsF/tSvnvlv6VcF2GIhg6Sx4yOIt/irsr1RDJsKiIyBzJDpCoXiWWq28MqH2cnQ==} dev: false /debug@4.3.4: @@ -900,13 +916,19 @@ packages: engines: {node: '>=6'} dev: false + /devlop@1.1.0: + resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} + dependencies: + dequal: 2.0.3 + dev: false + /diff@5.1.0: resolution: {integrity: sha512-D+mk+qE8VC/PAUrlAU34N+VfXev0ghe5ywmpqrawphmVZc1bEfn56uo9qpyGp1p4xpzOHkSW4ztBd6L7Xx4ACw==} engines: {node: '>=0.3.1'} dev: false - /dompurify@3.0.5: - resolution: {integrity: sha512-F9e6wPGtY+8KNMRAVfxeCOHU0/NPWMSENNq4pQctuXRqqdEPW7q3CrLbR5Nse044WwacyjHGOMlvNsBe1y6z9A==} + /dompurify@3.0.6: + resolution: {integrity: sha512-ilkD8YEnnGh1zJ240uJsW7AzE+2qpbOUYjacomn3AvJ6J4JhKGSZ2nh4wUIXPZrEPppaCLx5jFe8T89Rk8tQ7w==} dev: false /elkjs@0.8.2: @@ -1066,55 +1088,75 @@ packages: type-fest: 1.4.0 dev: false - /hast-util-from-dom@4.2.0: - resolution: {integrity: sha512-t1RJW/OpJbCAJQeKi3Qrj1cAOLA0+av/iPFori112+0X7R3wng+jxLA+kXec8K4szqPRGI8vPxbbpEYvvpwaeQ==} + /hast-util-from-dom@5.0.0: + resolution: {integrity: sha512-d6235voAp/XR3Hh5uy7aGLbM3S4KamdW0WEgOaU1YoewnuYw4HXb5eRtv9g65m/RFGEfUY1Mw4UqCc5Y8L4Stg==} dependencies: - hastscript: 7.2.0 + '@types/hast': 3.0.1 + hastscript: 8.0.0 web-namespaces: 2.0.1 dev: false - /hast-util-from-html-isomorphic@1.0.0: - resolution: {integrity: sha512-Yu480AKeOEN/+l5LA674a+7BmIvtDj24GvOt7MtQWuhzUwlaaRWdEPXAh3Qm5vhuthpAipFb2vTetKXWOjmTvw==} + /hast-util-from-html-isomorphic@2.0.0: + resolution: {integrity: sha512-zJfpXq44yff2hmE0XmwEOzdWin5xwH+QIhMLOScpX91e/NSGPsAzNCvLQDIEPyO2TXi+lBmU6hjLIhV8MwP2kw==} dependencies: - '@types/hast': 2.3.5 - hast-util-from-dom: 4.2.0 - hast-util-from-html: 1.0.2 - unist-util-remove-position: 4.0.2 + '@types/hast': 3.0.1 + hast-util-from-dom: 5.0.0 + hast-util-from-html: 2.0.1 + unist-util-remove-position: 5.0.0 dev: false - /hast-util-from-html@1.0.2: - resolution: {integrity: sha512-LhrTA2gfCbLOGJq2u/asp4kwuG0y6NhWTXiPKP+n0qNukKy7hc10whqqCFfyvIA1Q5U5d0sp9HhNim9gglEH4A==} + /hast-util-from-html@2.0.1: + resolution: {integrity: sha512-RXQBLMl9kjKVNkJTIO6bZyb2n+cUH8LFaSSzo82jiLT6Tfc+Pt7VQCS+/h3YwG4jaNE2TA2sdJisGWR+aJrp0g==} dependencies: - '@types/hast': 2.3.5 - hast-util-from-parse5: 7.1.2 + '@types/hast': 3.0.1 + devlop: 1.1.0 + hast-util-from-parse5: 8.0.1 parse5: 7.1.2 - vfile: 5.3.7 - vfile-message: 3.1.4 + vfile: 6.0.1 + vfile-message: 4.0.2 dev: false - /hast-util-from-parse5@7.1.2: - resolution: {integrity: sha512-Nz7FfPBuljzsN3tCQ4kCBKqdNhQE2l0Tn+X1ubgKBPRoiDIu1mL08Cfw4k7q71+Duyaw7DXDN+VTAp4Vh3oCOw==} + /hast-util-from-parse5@8.0.1: + resolution: {integrity: sha512-Er/Iixbc7IEa7r/XLtuG52zoqn/b3Xng/w6aZQ0xGVxzhw5xUFxcRqdPzP6yFi/4HBYRaifaI5fQ1RH8n0ZeOQ==} dependencies: - '@types/hast': 2.3.5 - '@types/unist': 2.0.7 - hastscript: 7.2.0 - property-information: 6.2.0 - vfile: 5.3.7 - vfile-location: 4.1.0 + '@types/hast': 3.0.1 + '@types/unist': 3.0.0 + devlop: 1.1.0 + hastscript: 8.0.0 + property-information: 6.3.0 + vfile: 6.0.1 + vfile-location: 5.0.2 web-namespaces: 2.0.1 dev: false - /hast-util-is-element@2.1.3: - resolution: {integrity: sha512-O1bKah6mhgEq2WtVMk+Ta5K7pPMqsBBlmzysLdcwKVrqzZQ0CHqUPiIVspNhAG1rvxpvJjtGee17XfauZYKqVA==} + /hast-util-is-element@3.0.0: + resolution: {integrity: sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==} dependencies: - '@types/hast': 2.3.5 - '@types/unist': 2.0.7 + '@types/hast': 3.0.1 dev: false - /hast-util-parse-selector@3.1.1: - resolution: {integrity: sha512-jdlwBjEexy1oGz0aJ2f4GKMaVKkA9jwjr4MjAAI22E5fM/TXVZHuS5OpONtdeIkRKqAaryQ2E9xNQxijoThSZA==} + /hast-util-parse-selector@4.0.0: + resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==} dependencies: - '@types/hast': 2.3.5 + '@types/hast': 3.0.1 + dev: false + + /hast-util-raw@9.0.1: + resolution: {integrity: sha512-5m1gmba658Q+lO5uqL5YNGQWeh1MYWZbZmWrM5lncdcuiXuo5E2HT/CIOp0rLF8ksfSwiCVJ3twlgVRyTGThGA==} + dependencies: + '@types/hast': 3.0.1 + '@types/unist': 3.0.0 + '@ungap/structured-clone': 1.2.0 + hast-util-from-parse5: 8.0.1 + hast-util-to-parse5: 8.0.0 + html-void-elements: 3.0.0 + mdast-util-to-hast: 13.0.2 + parse5: 7.1.2 + unist-util-position: 5.0.0 + unist-util-visit: 5.0.0 + vfile: 6.0.1 + web-namespaces: 2.0.1 + zwitch: 2.0.4 dev: false /hast-util-to-estree@2.3.3: @@ -1139,26 +1181,38 @@ packages: - supports-color dev: false - /hast-util-to-text@3.1.2: - resolution: {integrity: sha512-tcllLfp23dJJ+ju5wCCZHVpzsQQ43+moJbqVX3jNWPB7z/KFC4FyZD6R7y94cHL6MQ33YtMZL8Z0aIXXI4XFTw==} + /hast-util-to-parse5@8.0.0: + resolution: {integrity: sha512-3KKrV5ZVI8if87DVSi1vDeByYrkGzg4mEfeu4alwgmmIeARiBLKCZS2uw5Gb6nU9x9Yufyj3iudm6i7nl52PFw==} dependencies: - '@types/hast': 2.3.5 - '@types/unist': 2.0.7 - hast-util-is-element: 2.1.3 - unist-util-find-after: 4.0.1 + '@types/hast': 3.0.1 + comma-separated-tokens: 2.0.3 + devlop: 1.1.0 + property-information: 6.3.0 + space-separated-tokens: 2.0.2 + web-namespaces: 2.0.1 + zwitch: 2.0.4 + dev: false + + /hast-util-to-text@4.0.0: + resolution: {integrity: sha512-EWiE1FSArNBPUo1cKWtzqgnuRQwEeQbQtnFJRYV1hb1BWDgrAlBU0ExptvZMM/KSA82cDpm2sFGf3Dmc5Mza3w==} + dependencies: + '@types/hast': 3.0.1 + '@types/unist': 3.0.0 + hast-util-is-element: 3.0.0 + unist-util-find-after: 5.0.0 dev: false /hast-util-whitespace@2.0.1: resolution: {integrity: sha512-nAxA0v8+vXSBDt3AnRUNjyRIQ0rD+ntpbAp4LnPkumc5M9yUbSMa4XDU9Q6etY4f1Wp4bNgvc1yjiZtsTTrSng==} dev: false - /hastscript@7.2.0: - resolution: {integrity: sha512-TtYPq24IldU8iKoJQqvZOuhi5CyCQRAbvDOX0x1eW6rsHSxa/1i2CCiptNTotGHJ3VoHRGmqiv6/D3q113ikkw==} + /hastscript@8.0.0: + resolution: {integrity: sha512-dMOtzCEd3ABUeSIISmrETiKuyydk1w0pa+gE/uormcTpSYuaNJPbX1NU3JLyscSLjwAQM8bWMhhIlnCqnRvDTw==} dependencies: - '@types/hast': 2.3.5 + '@types/hast': 3.0.1 comma-separated-tokens: 2.0.3 - hast-util-parse-selector: 3.1.1 - property-information: 6.2.0 + hast-util-parse-selector: 4.0.0 + property-information: 6.3.0 space-separated-tokens: 2.0.2 dev: false @@ -1166,6 +1220,10 @@ packages: resolution: {integrity: sha512-2bsegYkkHO+h/9MGbn6KWcE45cHZgPANo5LXF7EvWdT0yT2EguSVO1nDgU5c8+ZOPwp2vMNa7YFsJhVcDR9Sdg==} dev: false + /html-void-elements@3.0.0: + resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} + dev: false + /iconv-lite@0.6.3: resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==} engines: {node: '>=0.10.0'} @@ -1278,8 +1336,8 @@ packages: resolution: {integrity: sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==} dev: false - /katex@0.16.8: - resolution: {integrity: sha512-ftuDnJbcbOckGY11OO+zg3OofESlbR5DRl2cmN8HeWeeFIV7wTXvAOx8kEjZjobhA+9wh2fbKeO6cdcA9Mnovg==} + /katex@0.16.9: + resolution: {integrity: sha512-fsSYjWS0EEOwvy81j3vRA8TEAhQhKiqO+FQaKWp0m39qwOzHVBgAUBIXWj1pB+O2W3fIpNa6Y9KSKCVbfPhyAQ==} hasBin: true dependencies: commander: 8.3.0 @@ -1528,6 +1586,19 @@ packages: unist-util-visit: 4.1.2 dev: false + /mdast-util-to-hast@13.0.2: + resolution: {integrity: sha512-U5I+500EOOw9e3ZrclN3Is3fRpw8c19SMyNZlZ2IS+7vLsNzb2Om11VpIVOR+/0137GhZsFEF6YiKD5+0Hr2Og==} + dependencies: + '@types/hast': 3.0.1 + '@types/mdast': 4.0.1 + '@ungap/structured-clone': 1.2.0 + devlop: 1.1.0 + micromark-util-sanitize-uri: 2.0.0 + trim-lines: 3.0.1 + unist-util-position: 5.0.0 + unist-util-visit: 5.0.0 + dev: false + /mdast-util-to-markdown@1.5.0: resolution: {integrity: sha512-bbv7TPv/WC49thZPg3jXuqzuvI45IL2EVAr/KxF0BSdHsU0ceFHOmwQn6evxAh1GaoK/6GQ1wp4R4oW2+LFL/A==} dependencies: @@ -1547,11 +1618,11 @@ packages: '@types/mdast': 3.0.12 dev: false - /mermaid@10.3.1: - resolution: {integrity: sha512-hkenh7WkuRWPcob3oJtrN3W+yzrrIYuWF1OIfk/d0xGE8UWlvDhfexaHmDwwe8DKQgqMLI8DWEPwGprxkumjuw==} + /mermaid@10.5.0: + resolution: {integrity: sha512-9l0o1uUod78D3/FVYPGSsgV+Z0tSnzLBDiC9rVzvelPxuO80HbN1oDr9ofpPETQy9XpypPQa26fr09VzEPfvWA==} dependencies: '@braintree/sanitize-url': 6.0.4 - '@types/d3-scale': 4.0.3 + '@types/d3-scale': 4.0.5 '@types/d3-scale-chromatic': 3.0.0 cytoscape: 3.26.0 cytoscape-cose-bilkent: 4.1.0(cytoscape@3.26.0) @@ -1559,8 +1630,8 @@ packages: d3: 7.8.5 d3-sankey: 0.12.3 dagre-d3-es: 7.0.10 - dayjs: 1.11.9 - dompurify: 3.0.5 + dayjs: 1.11.10 + dompurify: 3.0.6 elkjs: 0.8.2 khroma: 2.0.0 lodash-es: 4.17.21 @@ -1568,7 +1639,7 @@ packages: non-layered-tidy-tree-layout: 2.0.2 stylis: 4.3.0 ts-dedent: 2.2.0 - uuid: 9.0.0 + uuid: 9.0.1 web-worker: 1.2.0 transitivePeerDependencies: - supports-color @@ -1671,7 +1742,7 @@ packages: resolution: {integrity: sha512-es0CcOV89VNS9wFmyn+wyFTKweXGW4CEvdaAca6SWRWPyYCbBisnjaHLjWO4Nszuiud84jCpkHsqAJoa768Pvg==} dependencies: '@types/katex': 0.16.2 - katex: 0.16.8 + katex: 0.16.9 micromark-factory-space: 1.1.0 micromark-util-character: 1.2.0 micromark-util-symbol: 1.1.0 @@ -1802,6 +1873,13 @@ packages: micromark-util-types: 1.1.0 dev: false + /micromark-util-character@2.0.1: + resolution: {integrity: sha512-3wgnrmEAJ4T+mGXAUfMvMAbxU9RDG43XmGce4j6CwPtVxB3vfwXSZ6KhFwDzZ3mZHhmPimMAXg71veiBGzeAZw==} + dependencies: + micromark-util-symbol: 2.0.0 + micromark-util-types: 2.0.0 + dev: false + /micromark-util-chunked@1.1.0: resolution: {integrity: sha512-Ye01HXpkZPNcV6FiyoW2fGZDUw4Yc7vT0E9Sad83+bEDiCJ1uXu0S3mr8WLpsz3HaG3x2q0HM6CTuPdcZcluFQ==} dependencies: @@ -1842,6 +1920,10 @@ packages: resolution: {integrity: sha512-EuEzTWSTAj9PA5GOAs992GzNh2dGQO52UvAbtSOMvXTxv3Criqb6IOzJUBCmEqrrXSblJIJBbFFv6zPxpreiJw==} dev: false + /micromark-util-encode@2.0.0: + resolution: {integrity: sha512-pS+ROfCXAGLWCOc8egcBvT0kf27GoWMqtdarNfDcjb6YLuV5cM3ioG45Ys2qOVqeqSbjaKg72vU+Wby3eddPsA==} + dev: false + /micromark-util-events-to-acorn@1.2.3: resolution: {integrity: sha512-ij4X7Wuc4fED6UoLWkmo0xJQhsktfNh1J0m8g4PbIMPlx+ek/4YdW5mvbye8z/aZvAPUoxgXHrwVlXAPKMRp1w==} dependencies: @@ -1879,6 +1961,14 @@ packages: micromark-util-symbol: 1.1.0 dev: false + /micromark-util-sanitize-uri@2.0.0: + resolution: {integrity: sha512-WhYv5UEcZrbAtlsnPuChHUAsu/iBPOVaEVsntLBIdpibO0ddy8OzavZz3iL2xVvBZOpolujSliP65Kq0/7KIYw==} + dependencies: + micromark-util-character: 2.0.1 + micromark-util-encode: 2.0.0 + micromark-util-symbol: 2.0.0 + dev: false + /micromark-util-subtokenize@1.1.0: resolution: {integrity: sha512-kUQHyzRoxvZO2PuLzMt2P/dwVsTiivCK8icYTeR+3WgbuPqfHgPPy7nFKbeqRivBvn/3N3GBiNC+JRTMSxEC7A==} dependencies: @@ -1892,10 +1982,18 @@ packages: resolution: {integrity: sha512-uEjpEYY6KMs1g7QfJ2eX1SQEV+ZT4rUD3UcF6l57acZvLNK7PBZL+ty82Z1qhK1/yXIY4bdx04FKMgR0g4IAag==} dev: false + /micromark-util-symbol@2.0.0: + resolution: {integrity: sha512-8JZt9ElZ5kyTnO94muPxIGS8oyElRJaiJO8EzV6ZSyGQ1Is8xwl4Q45qU5UOg+bGH4AikWziz0iN4sFLWs8PGw==} + dev: false + /micromark-util-types@1.1.0: resolution: {integrity: sha512-ukRBgie8TIAcacscVHSiddHjO4k/q3pnedmzMQ4iwDcK0FtFCohKOlFbaOL/mPgfnPsL3C1ZyxJa4sbWrBl3jg==} dev: false + /micromark-util-types@2.0.0: + resolution: {integrity: sha512-oNh6S2WMHWRZrmutsRmDDfkzKtxF+bc2VxLC9dvtrDIRFln627VsFP6fLMgTryGDljgLPjkrzQSDcPrjPyDJ5w==} + dev: false + /micromark@3.2.0: resolution: {integrity: sha512-uD66tJj54JLYq0De10AhWycZWGQNUvDI55xPgk2sQM5kn1JYlhbCMTtEeT27+vAhW2FBQxLlOmS3pmA7/2z4aA==} dependencies: @@ -2016,7 +2114,7 @@ packages: - babel-plugin-macros dev: false - /nextra-theme-docs@2.11.0(next@13.4.16)(nextra@2.11.0)(react-dom@18.2.0)(react@18.2.0): + /nextra-theme-docs@2.11.0(next@13.4.16)(nextra@2.13.2)(react-dom@18.2.0)(react@18.2.0): resolution: {integrity: sha512-kNBVNB/NPW/3MI8Em7KFWjfX5Mtf5xY0UPhDveF5+aEvVUlrViS8Q0hfAdcbxq+0sUEc0hdr4KehU4H36cCkqg==} peerDependencies: next: '>=9.5.3' @@ -2036,15 +2134,15 @@ packages: next: 13.4.16(react-dom@18.2.0)(react@18.2.0) next-seo: 6.1.0(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) next-themes: 0.2.1(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) - nextra: 2.11.0(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) + nextra: 2.13.2(next@13.4.16)(react-dom@18.2.0)(react@18.2.0) react: 18.2.0 react-dom: 18.2.0(react@18.2.0) scroll-into-view-if-needed: 3.0.10 zod: 3.22.0 dev: false - /nextra@2.11.0(next@13.4.16)(react-dom@18.2.0)(react@18.2.0): - resolution: {integrity: sha512-I9F+NYl5fMBG6HUdPAvD6SbH3lpAvBeOmkS2Hkk+Cn3r8Ouc/QgLmJfpBXmG3gVFFxqYs2eQ2w/ppIivLLdylg==} + /nextra@2.13.2(next@13.4.16)(react-dom@18.2.0)(react@18.2.0): + resolution: {integrity: sha512-pIgOSXNUqTz1laxV4ChFZOU7lzJAoDHHaBPj8L09PuxrLKqU1BU/iZtXAG6bQeKCx8EPdBsoXxEuENnL9QGnGA==} engines: {node: '>=16'} peerDependencies: next: '>=9.5.3' @@ -2054,22 +2152,23 @@ packages: '@headlessui/react': 1.7.16(react-dom@18.2.0)(react@18.2.0) '@mdx-js/mdx': 2.3.0 '@mdx-js/react': 2.3.0(react@18.2.0) - '@napi-rs/simple-git': 0.1.8 - '@theguild/remark-mermaid': 0.0.4(react@18.2.0) - '@theguild/remark-npm2yarn': 0.1.1 + '@napi-rs/simple-git': 0.1.9 + '@theguild/remark-mermaid': 0.0.5(react@18.2.0) + '@theguild/remark-npm2yarn': 0.2.1 clsx: 2.0.0 github-slugger: 2.0.0 graceful-fs: 4.2.11 gray-matter: 4.0.3 - katex: 0.16.8 + katex: 0.16.9 lodash.get: 4.4.2 next: 13.4.16(react-dom@18.2.0)(react@18.2.0) next-mdx-remote: 4.4.1(react-dom@18.2.0)(react@18.2.0) p-limit: 3.1.0 react: 18.2.0 react-dom: 18.2.0(react@18.2.0) - rehype-katex: 6.0.3 + rehype-katex: 7.0.0 rehype-pretty-code: 0.9.11(shiki@0.14.3) + rehype-raw: 7.0.0 remark-gfm: 3.0.1 remark-math: 5.1.1 remark-reading-time: 2.0.1 @@ -2078,7 +2177,7 @@ packages: title: 3.5.3 unist-util-remove: 4.0.0 unist-util-visit: 5.0.0 - zod: 3.22.0 + zod: 3.22.4 transitivePeerDependencies: - supports-color dev: false @@ -2094,9 +2193,9 @@ packages: path-key: 2.0.1 dev: false - /npm-to-yarn@2.0.0: - resolution: {integrity: sha512-/IbjiJ7vqbxfxJxAZ+QI9CCRjnIbvGxn5KQcSY9xHh0lMKc/Sgqmm7yp7KPmd6TiTZX5/KiSBKlkGHo59ucZbg==} - engines: {node: '>=6.0.0'} + /npm-to-yarn@2.1.0: + resolution: {integrity: sha512-2C1IgJLdJngq1bSER7K7CGFszRr9s2rijEwvENPEgI0eK9xlD3tNwDc0UJnRj7FIT2aydWm72jB88uVswAhXHA==} + engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0} dev: false /p-finally@1.0.0: @@ -2176,6 +2275,10 @@ packages: resolution: {integrity: sha512-kma4U7AFCTwpqq5twzC1YVIDXSqg6qQK6JN0smOw8fgRy1OkMi0CYSzFmsy6dnqSenamAtj0CyXMUJ1Mf6oROg==} dev: false + /property-information@6.3.0: + resolution: {integrity: sha512-gVNZ74nqhRMiIUYWGQdosYetaKc83x8oT41a0LlV3AAFCAZwCpg4vmGkq8t34+cUhp3cnM4XDiU/7xlgK7HGrg==} + dev: false + /protocols@2.0.1: resolution: {integrity: sha512-/XJ368cyBJ7fzLMwLKv1e4vLxOju2MNAIokcr7meSaNcVbWz/CPcW22cP04mwxOErdA5mwjA8Q6w/cdAQxVn7Q==} dev: false @@ -2209,15 +2312,16 @@ packages: resolution: {integrity: sha512-srw17NI0TUWHuGa5CFGGmhfNIeja30WMBfbslPNhf6JrqQlLN5gcrvig1oqPxiVaXb0oW0XRKtH6Nngs5lKCIA==} dev: false - /rehype-katex@6.0.3: - resolution: {integrity: sha512-ByZlRwRUcWegNbF70CVRm2h/7xy7jQ3R9LaY4VVSvjnoVWwWVhNL60DiZsBpC5tSzYQOCvDbzncIpIjPZWodZA==} + /rehype-katex@7.0.0: + resolution: {integrity: sha512-h8FPkGE00r2XKU+/acgqwWUlyzve1IiOKwsEkg4pDL3k48PiE0Pt+/uLtVHDVkN1yA4iurZN6UES8ivHVEQV6Q==} dependencies: - '@types/hast': 2.3.5 - '@types/katex': 0.14.0 - hast-util-from-html-isomorphic: 1.0.0 - hast-util-to-text: 3.1.2 - katex: 0.16.8 - unist-util-visit: 4.1.2 + '@types/hast': 3.0.1 + '@types/katex': 0.16.3 + hast-util-from-html-isomorphic: 2.0.0 + hast-util-to-text: 4.0.0 + katex: 0.16.9 + unist-util-visit-parents: 6.0.1 + vfile: 6.0.1 dev: false /rehype-pretty-code@0.9.11(shiki@0.14.3): @@ -2232,6 +2336,14 @@ packages: shiki: 0.14.3 dev: false + /rehype-raw@7.0.0: + resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==} + dependencies: + '@types/hast': 3.0.1 + hast-util-raw: 9.0.1 + vfile: 6.0.1 + dev: false + /remark-gfm@3.0.1: resolution: {integrity: sha512-lEFDoi2PICJyNrACFOfDD3JlLkuSbOa5Wd8EPt06HUdptv8Gn0bxYTdbU/XXQ3swAPkEaGxxPN9cbnMHvVu1Ig==} dependencies: @@ -2492,11 +2604,11 @@ packages: vfile: 5.3.7 dev: false - /unist-util-find-after@4.0.1: - resolution: {integrity: sha512-QO/PuPMm2ERxC6vFXEPtmAutOopy5PknD+Oq64gGwxKtk4xwo9Z97t9Av1obPmGU0IyTa6EKYUfTrK2QJS3Ozw==} + /unist-util-find-after@5.0.0: + resolution: {integrity: sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==} dependencies: - '@types/unist': 2.0.7 - unist-util-is: 5.2.1 + '@types/unist': 3.0.0 + unist-util-is: 6.0.0 dev: false /unist-util-generated@2.0.1: @@ -2527,6 +2639,12 @@ packages: '@types/unist': 2.0.7 dev: false + /unist-util-position@5.0.0: + resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==} + dependencies: + '@types/unist': 3.0.0 + dev: false + /unist-util-remove-position@4.0.2: resolution: {integrity: sha512-TkBb0HABNmxzAcfLf4qsIbFbaPDvMO6wa3b3j4VcEzFVaw1LBKwnW4/sRJ/atSLSzoIg41JWEdnE7N6DIhGDGQ==} dependencies: @@ -2534,6 +2652,13 @@ packages: unist-util-visit: 4.1.2 dev: false + /unist-util-remove-position@5.0.0: + resolution: {integrity: sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==} + dependencies: + '@types/unist': 3.0.0 + unist-util-visit: 5.0.0 + dev: false + /unist-util-remove@4.0.0: resolution: {integrity: sha512-b4gokeGId57UVRX/eVKej5gXqGlc9+trkORhFJpu9raqZkZhU0zm8Doi05+HaiBsMEIJowL+2WtQ5ItjsngPXg==} dependencies: @@ -2548,6 +2673,12 @@ packages: '@types/unist': 2.0.7 dev: false + /unist-util-stringify-position@4.0.0: + resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} + dependencies: + '@types/unist': 3.0.0 + dev: false + /unist-util-visit-parents@4.1.1: resolution: {integrity: sha512-1xAFJXAKpnnJl8G7K5KgU7FY55y3GcLIXqkzUj5QF/QVP7biUm0K0O2oqVkYsdjzJKifYeWn9+o6piAK2hGSHw==} dependencies: @@ -2593,8 +2724,8 @@ packages: unist-util-visit-parents: 6.0.1 dev: false - /uuid@9.0.0: - resolution: {integrity: sha512-MXcSTerfPa4uqyzStbRoTgt5XIe3x5+42+q1sDuy3R5MDk66URdLMOZe5aPX/SQd+kuYAh0FdP/pO28IkQyTeg==} + /uuid@9.0.1: + resolution: {integrity: sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==} hasBin: true dev: false @@ -2609,11 +2740,11 @@ packages: sade: 1.8.1 dev: false - /vfile-location@4.1.0: - resolution: {integrity: sha512-YF23YMyASIIJXpktBa4vIGLJ5Gs88UB/XePgqPmTa7cDA+JeO3yclbpheQYCHjVHBn/yePzrXuygIL+xbvRYHw==} + /vfile-location@5.0.2: + resolution: {integrity: sha512-NXPYyxyBSH7zB5U6+3uDdd6Nybz6o6/od9rk8bp9H8GR3L+cm/fC0uUTbqBmUTnMCUDslAGBOIKNfvvb+gGlDg==} dependencies: - '@types/unist': 2.0.7 - vfile: 5.3.7 + '@types/unist': 3.0.0 + vfile: 6.0.1 dev: false /vfile-matter@3.0.1: @@ -2631,6 +2762,13 @@ packages: unist-util-stringify-position: 3.0.3 dev: false + /vfile-message@4.0.2: + resolution: {integrity: sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==} + dependencies: + '@types/unist': 3.0.0 + unist-util-stringify-position: 4.0.0 + dev: false + /vfile@5.3.7: resolution: {integrity: sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==} dependencies: @@ -2640,6 +2778,14 @@ packages: vfile-message: 3.1.4 dev: false + /vfile@6.0.1: + resolution: {integrity: sha512-1bYqc7pt6NIADBJ98UiG0Bn/CHIVOoZ/IyEkqIruLg0mE1BKzkOXY2D6CSqQIcKqgadppE5lrxgWXJmXd7zZJw==} + dependencies: + '@types/unist': 3.0.0 + unist-util-stringify-position: 4.0.0 + vfile-message: 4.0.2 + dev: false + /vscode-oniguruma@1.7.0: resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} dev: false @@ -2688,6 +2834,10 @@ packages: resolution: {integrity: sha512-y5KZY/ssf5n7hCGDGGtcJO/EBJEm5Pa+QQvFBeyMOtnFYOSflalxIFFvdaYevPhePcmcKC4aTbFkCcXN7D0O8Q==} dev: false + /zod@3.22.4: + resolution: {integrity: sha512-iC+8Io04lddc+mVqQ9AZ7OQ2MrUKGN+oIQyq1vemgt46jwCwLfhq7/pwnBnNXXXZb8VTVLKwp9EDkx+ryxIWmg==} + dev: false + /zwitch@2.0.4: resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==} dev: false From 8afae7d54d501c1a0989b9f6f82f1d5be9af3708 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Wed, 11 Oct 2023 16:29:58 +0100 Subject: [PATCH 3/8] feat(docs/concepts): add details around controllers --- docs/site/pages/concepts/controllers.mdx | 243 ++++++++++++++++++++++- 1 file changed, 242 insertions(+), 1 deletion(-) diff --git a/docs/site/pages/concepts/controllers.mdx b/docs/site/pages/concepts/controllers.mdx index 66753b0..2ae3e0f 100644 --- a/docs/site/pages/concepts/controllers.mdx +++ b/docs/site/pages/concepts/controllers.mdx @@ -8,4 +8,245 @@ Head to the configuration reference section for [Controllers](/configuration/con to learn how they can be configured. -Controllers declare _how_ to handle storing, removing and retrieving resource kinds from a repository. +Controllers declare _how_ to handle storing, retrieving and removing resource kinds from a repository. + +Requests to Cup for a particular resource (get, list, put or delete) ultimately end up being handled by a **controller**. +By default, Flipt ships with a basic controller known as the `template` controller and an extensible controller called the `wasm` controller. + + +You will learn in the next section on [bindings](/concepts/bindings) how to configure which controllers handle which resource definitions. + + +Controllers are the most important extension point in Flipt. +They allow operators to create custom transformation logic between API resources and their resulting representation in the repository. +Meaning there is no strict requirement that these two concepts need to have a 1:1 mapping (though the `template` controller does support this kind of logic out of the box). + +## Lifecycle of a Cup Resource Request + +Cup automatically exposes four verbs for each configured resource: + +- Get +- List +- Put +- Delete + +The first two are read-only operations and the second two produce written changes to state. +Reads simply source the current state from Git for a particular revision through the means of a controller to handle parsing source and serializing responses. +Writes also go through to Git via the means of a controller, however, they also result in changes being presented as a pull request. + +The following two sections attempts to explain these processes in a little more depth. + +### Read Requests + +```mermaid +sequenceDiagram + participant A as User + participant S as API Server + participant C as Controller + participant G as Git + A ->>+ S: GET /apis/g/v/k/... + S ->>+ G: checkout + S ->>+ C: Get(g, v, k) + C -->> G: read() + G -->>- C: []byte + C -->>- S: return Resource{} + S -->>- A: 200 {"apiVersion": ...} +``` + +The API server is the first stop for all operations on resources in Cup. +It takes care of collecting up the relevant state from Git and delegating onto the relevant **controller**. +Controllers have no concept of Git, they work purely over a filesystem abstraction. +It is up to the API layer to build the expected implementation of the filesystem for a particular revision. +This filesystems root will be the root directory of the target Git repository being sourced from. + +### Write Requests + +```mermaid +sequenceDiagram + participant A as User + participant S as API Server + participant C as Controller + participant G as Git + participant SCM as SCM + A ->>+ S: PUT /apis/g/v/k/... + S ->>+ G: checkout new branch + S ->>+ C: PUT(Resource{}) + C ->> G: write([]byte) + C ->> G: add, commit and push + G -->>- C: + C -->>- S: return + S ->> SCM: OpenPR(branch, title) + SCM -->> S: PR{} + S -->>- A: 202 Accepted +``` + +Write requests on the other hand are a little more complicated. +In this scenario, the filesystem abstraction passed to a Controller can handle writes. +The API server which builds the implementation of the filesystem, will do so over a worktree on a new branch. +Ultimately, the server will add, commit and push changes made by the controller to the configured upstream. +Once the branch is pushed, it will also open a pull request and return to the caller a URL for where to find it. + +For `PUT` operations the controller has to reconcile the current filesystem state with a new desired state for the requested resource. +This involves locating the relevant file(s) for the requested resource and updating them to match the current desired state. + +For `DELETE` operations the controller needs to locate and remove any state from the filesystem relevant to the requested resource. + +Controllers need to be developed to ensure these operations are idempotent. +For a filesystem in one particular state and a request for a resource to be either set (put) to some or removed (delete) the result should be some new filesystem state. This result should always be the same, for the same combination of initial filesystem state and requested operation. + +## Built-in Controllers + +Cup comes with a couple baked in controllers. One controller (`template`) is configuration driven and the other (`wasm`) is broadly extensible through your own code. + +### Template Controller + +This controller is simple, but effective. It only requires a little configuration to set it up and get going. + +All this controller does is handle API resource payloads as-is. +Meaning, for a PUT operation it simply writes the entire API payload to a particular file in the target filesystem. +For GET operations it expects the API resource to be written and encoded accordingly to a particular file path location. +And finally, for DELETE, it simply removes the file at an expected file path location. + +In order to decide which file path is relevant for a particular resource, the `template` controller uses Go's template language to build a relevant path. +This is where the controller gets it's name. + +```go +const ( + defaultListTmpl = `{{ .Namespace }}/{{ .Group }}-{{ .Version }}-{{ .Kind }}-*.json` + defaultResourceTmpl = `{{ .Namespace }}/{{ .Group }}-{{ .Version }}-{{ .Kind }}-{{ .Name }}.json` +) +``` + +Above are the default definitions for the two configurable templates used by the controller to both locate a single instance, or list many. +The listing template produces a glob syntax path. This glob path will be used on `list` operations to locate all the files containing definitions for resources of a particular kind in a particular namespace. +The resource template identifies a single path for a single named resource. + +Both of these templates can be overriden via Cups controller configuration. +Head to [Configuration: Controller: Template](/configuration/controllers#template) to learn how. + +### WASM Controller + +The WASM controller leverages the [Wazero](https://wazero.io/) runtime for Go to support implementing Controllers in the language of your choice. +WASM binary implementations should expose a command-line interfaces with a number of subcommands. + +The controller will take care of adapting each request into an appropriate set of command line arguments and/or STDIN written payloads. +It then interprets any exit codes and output written to the standard output streams (STDOUT / STDERR). + +It is also the controllers job to prepare the WASM runtime environment for a given request. +A request can identify a desired target revision. +Otherwise, a default reference is chosen from configuration. +The controller will receive a filesystem implementation of the entire Git tree for the resolved revision. +This will be mounted as the root filesystem for the WASM runtime. + +Given a mutating operation is requested (`put` or `delete`), the controller will support writes on the filesystem. + +A single binary is responsible for handling the core controller operations across a group of one or more kinds. + +#### get + +Retrieving an instance of a resource by `namespace` and `name`. + +``` +exec wasm ["get", "", "", ""] + ┌──────────────────────┐ + │ │ { + │ WASM Binary │ "apiVersion": "..." + │ │ "kind": "...", + │ │ ... + │ ├──────▶ } + └──────────────────────┘ +``` + +The purpose of this subcommand is to address an instance by namespace and name. +It should handle the sub-command `get`. +Then the following two arguments will the `namespace`, followed by the `name` of the instance. + +The resource should be extracted from the local-filesystem. +The filesystem will contain the configured target Git repositories HEAD tree for the resolved reference mounted at `/`. + +##### Output + +| Meaning | Exit code | STDOUT | +| --------- | --------- | --------------------- | +| success | 0 | JSON encoded resource | +| error | 1 | JSON encoded message | +| not found | 2 | JSON encoded message | + +#### list + +Listing and filtering a set of resource instances by `namespace` and optional `labels` + +``` +exec wasm ["list", "", "", ...(k/v pairs)] + ┌──────────────────────┐ + │ │ [{ + │ WASM Binary │ "apiVersion": "..." + │ │ "kind": "...", + │ │ ... + │ ├──────▶ }, ...] + └──────────────────────┘ +``` + +The purpose of this subcommand is to return a list of instances found by the target controller. +The controller should handle filtering by namespace and optionall by a list of `key=value` pairs of labels. + +##### Output + +| Meaning | Exit code | STDOUT | +| --------- | --------- | ---------------------------- | +| success | 0 | JSON encoded resource stream | +| error | 1 | JSON encoded message | +| not found | 2 | JSON encoded message | + +#### put + +Creating or updating an existing resource. + +``` +exec wasm ["put", ""] + ┌──────────────────────┐ +{ │ │ + "apiVersion": "..." │ WASM Binary │ + "kind": "...", │ │ + ... │ │ +} ──────▶ ├──────▶ { TBD } + └──────────────────────┘ +``` + +The purpose of this subcommand is to create a new or update (upsert) an existing resource. +Implementations should adjust the filesystem appropriately for the resource type and controllers needs. +The new resource payload is serialized on STDIN. + +TBD: + +- What makes sense to return from the binary? + +##### Output + +| Meaning | Exit code | STDOUT | +| --------- | --------- | -------------------- | +| success | 0 | TBD | +| error | 1 | JSON encoded message | + +#### delete + +Removing an existing resource. + +``` +exec wasm ["delete", "", "", ""] + ┌──────────────────────┐ + │ │ + │ WASM Binary │ + │ │ + │ │ + │ ├──────▶ { TBD } + └──────────────────────┘ +``` + +The purpose of this subcommand is to remove an existing resource. +Implementations should adjust the filesystem appropriately for the resource type and controllers needs. +The namespace and name of the resource is passed as arguments to the subcommand. + +TBD: + +- What makes sense to return from the binary? From 9f68ec87201ca1d999ef2b77377119dfa2d906b8 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Wed, 11 Oct 2023 16:44:31 +0100 Subject: [PATCH 4/8] feat(docs/concepts): add details around bindings --- docs/site/pages/concepts/bindings.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/site/pages/concepts/bindings.mdx b/docs/site/pages/concepts/bindings.mdx index f48f2c0..9c19951 100644 --- a/docs/site/pages/concepts/bindings.mdx +++ b/docs/site/pages/concepts/bindings.mdx @@ -8,4 +8,15 @@ Head to the configuration reference section for [Bindings](/configuration/bindin to learn how they can be configured. -Bindings are the glue that combines definitions and controllers together and expose them through the Cup API. +Bindings are the glue that combines definitions and controllers together and exposes them through the Cup API. +This is the last and simplest piece of the equation when configuring a Cup instance. +A binding declares which resource definitions should be exposed and the controller that will handle their operations. + +It is as simple as that. +Without them Cup wont expose anything, so do remember to set up your bindings! + +```mermaid +erDiagram + BINDING ||--|| CONTROLLER : configures + BINDING ||--o{ RESOURCE-DEFINITION : "across all" +``` From cc272dd1e22c2f8cd96a8af6cc63498d528d771a Mon Sep 17 00:00:00 2001 From: George Date: Thu, 12 Oct 2023 11:49:05 +0100 Subject: [PATCH 5/8] chore: update docs/site/pages/concepts/controllers.mdx Co-authored-by: Yoofi Quansah --- docs/site/pages/concepts/controllers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/pages/concepts/controllers.mdx b/docs/site/pages/concepts/controllers.mdx index 2ae3e0f..c2e1be4 100644 --- a/docs/site/pages/concepts/controllers.mdx +++ b/docs/site/pages/concepts/controllers.mdx @@ -17,7 +17,7 @@ By default, Flipt ships with a basic controller known as the `template` controll You will learn in the next section on [bindings](/concepts/bindings) how to configure which controllers handle which resource definitions. -Controllers are the most important extension point in Flipt. +Controllers are the most important extension point in Cup. They allow operators to create custom transformation logic between API resources and their resulting representation in the repository. Meaning there is no strict requirement that these two concepts need to have a 1:1 mapping (though the `template` controller does support this kind of logic out of the box). From 9f936b7ce3eb6325a09ee0e2f4e79186d4f3999a Mon Sep 17 00:00:00 2001 From: George Date: Thu, 12 Oct 2023 11:49:43 +0100 Subject: [PATCH 6/8] chore: update docs/site/pages/concepts/controllers.mdx Co-authored-by: Yoofi Quansah --- docs/site/pages/concepts/controllers.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/site/pages/concepts/controllers.mdx b/docs/site/pages/concepts/controllers.mdx index c2e1be4..767248e 100644 --- a/docs/site/pages/concepts/controllers.mdx +++ b/docs/site/pages/concepts/controllers.mdx @@ -82,7 +82,7 @@ sequenceDiagram Write requests on the other hand are a little more complicated. In this scenario, the filesystem abstraction passed to a Controller can handle writes. -The API server which builds the implementation of the filesystem, will do so over a worktree on a new branch. +In Git's case, the API server which builds the implementation of the filesystem, will do so over a worktree on a new branch. Ultimately, the server will add, commit and push changes made by the controller to the configured upstream. Once the branch is pushed, it will also open a pull request and return to the caller a URL for where to find it. From 4bb09637b748c3974fb7823d1bd7d897e5dcbc60 Mon Sep 17 00:00:00 2001 From: George MacRorie Date: Thu, 12 Oct 2023 13:06:11 +0100 Subject: [PATCH 7/8] feat(concepts/controllers): add callout linking to flipt controller --- docs/site/pages/concepts/controllers.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/site/pages/concepts/controllers.mdx b/docs/site/pages/concepts/controllers.mdx index 2ae3e0f..3fde184 100644 --- a/docs/site/pages/concepts/controllers.mdx +++ b/docs/site/pages/concepts/controllers.mdx @@ -129,6 +129,10 @@ Head to [Configuration: Controller: Template](/configuration/controllers#templat The WASM controller leverages the [Wazero](https://wazero.io/) runtime for Go to support implementing Controllers in the language of your choice. WASM binary implementations should expose a command-line interfaces with a number of subcommands. + +Checkout the [Flipt Controller](https://github.com/flipt-io/cup/blob/53f1aa7cfb90c3a11aecf62eb8d1b726623a37cd/ext/controllers/flipt.io/v1alpha1/cmd/flipt/main.go#L27-L32) we have implemented in Go. This is compiled to WASM so that we can managed features flags as configuration via Cup. + + The controller will take care of adapting each request into an appropriate set of command line arguments and/or STDIN written payloads. It then interprets any exit codes and output written to the standard output streams (STDOUT / STDERR). From 67bd2b9270034a969c34b91e12f309b4fd8d7954 Mon Sep 17 00:00:00 2001 From: George Date: Fri, 13 Oct 2023 09:20:05 +0100 Subject: [PATCH 8/8] chore(concepts): address spelling feedback Co-authored-by: Mark Phelps <209477+markphelps@users.noreply.github.com> --- docs/site/pages/concepts/controllers.mdx | 2 +- docs/site/pages/concepts/definitions.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/site/pages/concepts/controllers.mdx b/docs/site/pages/concepts/controllers.mdx index 2679828..e9dd95d 100644 --- a/docs/site/pages/concepts/controllers.mdx +++ b/docs/site/pages/concepts/controllers.mdx @@ -127,7 +127,7 @@ Head to [Configuration: Controller: Template](/configuration/controllers#templat ### WASM Controller The WASM controller leverages the [Wazero](https://wazero.io/) runtime for Go to support implementing Controllers in the language of your choice. -WASM binary implementations should expose a command-line interfaces with a number of subcommands. +WASM binary implementations should expose a command-line interface with a number of subcommands. Checkout the [Flipt Controller](https://github.com/flipt-io/cup/blob/53f1aa7cfb90c3a11aecf62eb8d1b726623a37cd/ext/controllers/flipt.io/v1alpha1/cmd/flipt/main.go#L27-L32) we have implemented in Go. This is compiled to WASM so that we can managed features flags as configuration via Cup. diff --git a/docs/site/pages/concepts/definitions.mdx b/docs/site/pages/concepts/definitions.mdx index e636c56..c2b1104 100644 --- a/docs/site/pages/concepts/definitions.mdx +++ b/docs/site/pages/concepts/definitions.mdx @@ -9,7 +9,7 @@ to learn how they can be configured. Resource definitions describe the schema for the different resource kinds available in a Cup instance. -When you interact with the Cup API, you do so through the various resource definition configured. +When you interact with the Cup API, you do so through the various configured resource definitions. A Cup resource is comprised of a few components to build the entire definition. These components and concepts are taken directly from Kubernetes and its custom resource definitions (CRD).