initial version

grafana · Jun 25, 2024 · 5e8b5f3 · 5e8b5f3
commit 5e8b5f3
Show file tree

Hide file tree

Showing 9 changed files with 1,028 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -0,0 +1 @@
+* @grafana/k6-extensions
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -0,0 +1,77 @@
+# k6registry
+
+**Data model for the k6 extension registry**
+
+This repository contains the [JSON schema](registry.schema.json) of the k6 extension registry and the golang data model generated from it.
+
+## Concept
+
+The k6 extension registry is a JSON file that contains the most important properties of extensions.
+
+### Registered Properties
+
+Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.
+
+Properties that are available using the repository manager API are intentionally not registered.
+
+The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)
+
+### Extension Identification
+
+The primary identifier of an extension is the extension's [go module path](https://go.dev/ref/mod#module-path).
+
+The extension has no `name` property, the module path or part of it can be used as the extension name. For example, using the first two elements of the module path after the host name, the name `grafana/xk6-dashboard` can be formed from the module path `github.com/grafana/xk6-dashboard`. This is typically the repository owner name (`grafana`) and the repository name in the repository manager (`xk6-dashboard`).
+
+The extension has no URL property, a URL can be created from the module path that refers to the extension within the repository manager.
+
+### JavaScript Modules
+
+The JavaScript module names implemented by the extension can be specified in the `imports` property. An extension can register multiple JavaScript module names, so this is an array property.
+
+### Output Names
+
+The output names implemented by the extension can be specified in the `outputs` property. An extension can register multiple output names, so this is an array property.
+
+### Cloud Enabled
+
+The `true` value of the `cloud` flag indicates that the extension is also available in the Grafana k6 cloud.
+
+### Officially Supported
+
+The `true` value of the `official` flag indicates that the extension is officially supported by Grafana.
+
+## Example
+
+```json file=example.json
+{
+  "extensions": [
+    {
+      "module": "github.com/grafana/xk6-dashboard",
+      "description": "Web-based metrics dashboard for k6",
+      "outputs": ["dashboard"],
+      "official": true
+    },
+    {
+      "module": "github.com/grafana/xk6-sql",
+      "description": "Load test SQL Servers",
+      "imports": ["k6/x/sql"],
+      "official": true
+    },
+    {
+      "module": "github.com/grafana/xk6-distruptor",
+      "description": "Inject faults to test",
+      "imports": ["k6/x/distruptor"],
+      "official": true
+    },
+    {
+      "module": "github.com/szkiba/xk6-faker",
+      "description": "Generate random fake data",
+      "imports": ["k6/x/faker"]
+    }
+  ]
+}
+```
+
+## Development
+
+The source of the schema is contained in the [registry.schema.yaml](registry.schema.yaml) file. This file must be edited if required. The `go generate` command generates the [registry_gen.go](registry_gen.go) and [registry.schema.json](registry.schema.json) files and updates the example code block in the README.md from the [example.json](example.json) file.
diff --git a/example.json b/example.json
@@ -0,0 +1,27 @@
+{
+  "extensions": [
+    {
+      "module": "github.com/grafana/xk6-dashboard",
+      "description": "Web-based metrics dashboard for k6",
+      "outputs": ["dashboard"],
+      "official": true
+    },
+    {
+      "module": "github.com/grafana/xk6-sql",
+      "description": "Load test SQL Servers",
+      "imports": ["k6/x/sql"],
+      "official": true
+    },
+    {
+      "module": "github.com/grafana/xk6-distruptor",
+      "description": "Inject faults to test",
+      "imports": ["k6/x/distruptor"],
+      "official": true
+    },
+    {
+      "module": "github.com/szkiba/xk6-faker",
+      "description": "Generate random fake data",
+      "imports": ["k6/x/faker"]
+    }
+  ]
+}
diff --git a/go.mod b/go.mod
@@ -0,0 +1,3 @@
+module github.com/grafana/k6registry
+
+go 1.22
diff --git a/registry.go b/registry.go
@@ -0,0 +1,6 @@
+// Package k6registry contains the data model of the k6 extensions registry.
+package k6registry
+
+//go:generate go run github.com/atombender/[email protected] -p k6registry --only-models -o registry_gen.go registry.schema.yaml
+//go:generate sh -c "go run github.com/mikefarah/yq/[email protected] -o=json -P registry.schema.yaml > registry.schema.json"
+//go:generate go run github.com/szkiba/[email protected] update
diff --git a/registry.schema.json b/registry.schema.json
@@ -0,0 +1,85 @@
+{
+  "$id": "https://grafana.github.io/k6registry/registry.schema.json",
+  "$ref": "#/$defs/registry",
+  "$defs": {
+    "registry": {
+      "description": "k6 Extension Registry.\n\nThe k6 extension registry contains the most important properties of registered extensions.\n",
+      "type": "object",
+      "properties": {
+        "extensions": {
+          "description": "An array containing the registration data of the k6 golang extensions.\n",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/extension"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "extension": {
+      "type": "object",
+      "description": "Properties of the registered k6 extension.\n\nOnly those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.\n\nProperties that are available using the repository manager API are intentionally not registered.\n\nThe string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)\n",
+      "properties": {
+        "module": {
+          "type": "string",
+          "description": "The extension's go module path.\n\nThis is the unique identifier of the extension.\nMore info about module paths: https://go.dev/ref/mod#module-path\n\nThe extension has no name property, the module path or part of it can be used as the extension name. For example, using the first two elements of the module path after the host name, the name `grafana/xk6-dashboard` can be formed from the module path `github.com/grafana/xk6-dashboard`. This is typically the repository owner name and the repository name in the repository manager.\n\nThe extension has no URL property, a URL can be created from the module path that refers to the extension within the repository manager.\n",
+          "examples": [
+            "github.com/grafana/xk6-dashboard",
+            "github.com/szkiba/xk6-top"
+          ]
+        },
+        "imports": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of JavaScript import paths registered by the extension.\n\nCurrently, paths must start with the prefix `k6/x/`.\nThe extensions used by k6 scripts are automatically detected based on the values specified here, therefore it is important that the values used here are consistent with the values registered by the extension at runtime.\n",
+          "examples": [
+            [
+              "k6/x/csv",
+              "k6/x/csv/stream"
+            ],
+            [
+              "k6/x/toml"
+            ]
+          ]
+        },
+        "outputs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "example": null,
+          "description": "List of output names registered by the extension.\n\nThe extensions used by k6 scripts are automatically detected based on the values specified here, therefore it is important that the values used here are consistent with the values registered by the extension at runtime.\n",
+          "examples": [
+            [
+              "dashboard"
+            ],
+            [
+              "plugin"
+            ]
+          ]
+        },
+        "official": {
+          "type": "boolean",
+          "default": "false",
+          "description": "Officially supported extension flag.\n\nA value of true indicates that the extension is officially supported by Grafana. Extensions owned by the `grafana` GitHub organization are not officially supported by Grafana by default.\n"
+        },
+        "cloud": {
+          "type": "boolean",
+          "default": "false",
+          "description": "Cloud-enabled extension flag.\n\nA value of true indicates that the extension is also available in the Grafana k6 cloud.\n"
+        },
+        "description": {
+          "type": "string",
+          "description": "Brief description of the extension.\n"
+        }
+      },
+      "required": [
+        "module",
+        "description"
+      ],
+      "additionalProperties": false
+    }
+  }
+}
diff --git a/registry.schema.yaml b/registry.schema.yaml
@@ -0,0 +1,88 @@
+$id: https://grafana.github.io/k6registry/registry.schema.json
+$ref: "#/$defs/registry"
+$defs:
+  registry:
+    description: |
+      k6 Extension Registry.
+
+      The k6 extension registry contains the most important properties of registered extensions.
+    type: object
+    properties:
+      extensions:
+        description: |
+          An array containing the registration data of the k6 golang extensions.
+        type: array
+        items:
+          $ref: "#/$defs/extension"
+    additionalProperties: false
+  extension:
+    type: object
+    description: |
+      Properties of the registered k6 extension.
+
+      Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.
+
+      Properties that are available using the repository manager API are intentionally not registered.
+
+      The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)
+    properties:
+      module:
+        type: string
+        description: |
+          The extension's go module path.
+
+          This is the unique identifier of the extension.
+          More info about module paths: https://go.dev/ref/mod#module-path
+
+          The extension has no name property, the module path or part of it can be used as the extension name. For example, using the first two elements of the module path after the host name, the name `grafana/xk6-dashboard` can be formed from the module path `github.com/grafana/xk6-dashboard`. This is typically the repository owner name and the repository name in the repository manager.
+
+          The extension has no URL property, a URL can be created from the module path that refers to the extension within the repository manager.
+        examples:
+          - github.com/grafana/xk6-dashboard
+          - github.com/szkiba/xk6-top
+      imports:
+        type: array
+        items:
+          type: string
+        description: |
+          List of JavaScript import paths registered by the extension.
+
+          Currently, paths must start with the prefix `k6/x/`.
+          The extensions used by k6 scripts are automatically detected based on the values specified here, therefore it is important that the values used here are consistent with the values registered by the extension at runtime.
+        examples:
+          - ["k6/x/csv", "k6/x/csv/stream"]
+          - ["k6/x/toml"]
+      outputs:
+        type: array
+        items:
+          type: string
+        example:
+        description: |
+          List of output names registered by the extension.
+
+          The extensions used by k6 scripts are automatically detected based on the values specified here, therefore it is important that the values used here are consistent with the values registered by the extension at runtime.
+        examples:
+          - ["dashboard"]
+          - ["plugin"]
+      official:
+        type: boolean
+        default: "false"
+        description: |
+          Officially supported extension flag.
+
+          A value of true indicates that the extension is officially supported by Grafana. Extensions owned by the `grafana` GitHub organization are not officially supported by Grafana by default.
+      cloud:
+        type: boolean
+        default: "false"
+        description: |
+          Cloud-enabled extension flag.
+
+          A value of true indicates that the extension is also available in the Grafana k6 cloud.
+      description:
+        type: string
+        description: |
+          Brief description of the extension.
+    required:
+      - module
+      - description
+    additionalProperties: false
diff --git a/registry_gen.go b/registry_gen.go