[ENHANCEMENT] add client package

client/.eslintrc.js

@@ -0,0 +1,14 @@
+// Copyright The Perses Authors
+// Licensed 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.
+
+module.exports = require('../.eslintrc.base.js');

client/README.md

@@ -0,0 +1,3 @@
+# Perses Client Package
+
+This [package](https://www.npmjs.com/package/@perses-dev/client) Functions as an API Client or Data Fetching Layer for interacting with a backend service. For more info about corresponding packages see the [general UI README here](https://github.com/perses/perses/blob/main/ui/README.md) and markdown files in each component folder.

client/jest.config.ts

@@ -0,0 +1,23 @@
+// Copyright The Perses Authors
+// Licensed 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 '@jest/types';
+import shared from '../jest.shared';
+
+const jestConfig: Config.InitialOptions = {
+  ...shared,
+
+  setupFilesAfterEnv: [...(shared.setupFilesAfterEnv ?? []), '<rootDir>/src/test/setup-tests.ts'],
+};
+
+export default jestConfig;

client/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@perses-dev/client",
+  "version": "0.1.0",
+  "description": "Functions as an API client or Data fetching Layer for interacting with a backend service",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/perses/perses/blob/main/README.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/perses/perses.git"
+  },
+  "bugs": {
+    "url": "https://github.com/perses/perses/issues"
+  },
+  "module": "dist/index.js",
+  "main": "dist/cjs/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@perses-dev/spec": "0.2.0-beta.0",
+    "zod": "^3.21.4"
+  },
+  "scripts": {
+    "clean": "rimraf dist/",
+    "build": "concurrently \"npm:build:*\"",
+    "build:cjs": "swc ./src -d dist/cjs --strip-leading-paths --config-file ../.cjs.swcrc",
+    "build:esm": "swc ./src -d dist --strip-leading-paths --config-file ../.swcrc",
+    "build:types": "tsc --project tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "start": "concurrently -P \"npm:build:* -- {*}\" -- --watch",
+    "test": "cross-env TZ=UTC jest --passWithNoTests",
+    "test:watch": "cross-env TZ=UTC jest --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint --fix src --ext .ts,.tsx"
+  },
+  "files": [
+    "dist"
+  ]
+}

client/src/index.ts

@@ -0,0 +1,16 @@
+// Copyright The Perses Authors
+// Licensed 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 * from './util';
+export * from './model';
+export * from './schema';

client/src/model/datasource-api.ts

@@ -0,0 +1,56 @@
+// Copyright The Perses Authors
+// Licensed 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 { DatasourceResource, DatasourceSelector, GlobalDatasourceResource } from './datasource';
+
+/**
+ * Parameters for building a datasource proxy URL
+ */
+export interface BuildDatasourceProxyUrlParams {
+  project?: string;
+  dashboard?: string;
+  name: string;
+}
+
+/**
+ * Function type for building datasource proxy URLs
+ */
+export type BuildDatasourceProxyUrlFunc = (params: BuildDatasourceProxyUrlParams) => string;
+
+/**
+ * The external API contract for fetching datasource resources.
+ * This defines the interface that must be implemented to provide
+ * datasource functionality to the dashboard.
+ */
+export interface DatasourceApi {
+  /**
+   * Optional function to build proxy URLs for datasources
+   */
+  buildProxyUrl?: BuildDatasourceProxyUrlFunc;
+  /**
+   * Get a datasource resource for a specific project
+   */
+  getDatasource: (project: string, selector: DatasourceSelector) => Promise<DatasourceResource | undefined>;
+  /**
+   * Get a global datasource resource
+   */
+  getGlobalDatasource: (selector: DatasourceSelector) => Promise<GlobalDatasourceResource | undefined>;
+  /**
+   * List all datasources for a project, optionally filtered by plugin kind
+   */
+  listDatasources: (project: string, pluginKind?: string) => Promise<DatasourceResource[]>;
+  /**
+   * List all global datasources, optionally filtered by plugin kind
+   */
+  listGlobalDatasources: (pluginKind?: string) => Promise<GlobalDatasourceResource[]>;
+}

client/src/model/datasource.ts

@@ -0,0 +1,44 @@
+// Copyright The Perses Authors
+// Licensed 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 { DatasourceSpec, DatasourceSelector } from '@perses-dev/spec';
+import { Metadata, ProjectMetadata } from './resource';
+export type { DatasourceSelector, DatasourceSpec };
+
+/**
+ * A Datasource that's available across all projects.
+ */
+export interface GlobalDatasourceResource {
+  kind: 'GlobalDatasource';
+  metadata: Metadata;
+  spec: DatasourceSpec;
+}
+
+/**
+ * A Datasource resource, that belongs to a project.
+ */
+export interface DatasourceResource {
+  kind: 'Datasource';
+  metadata: ProjectMetadata;
+  spec: DatasourceSpec;
+}
+
+/**
+ * An intermediary type to regroup the name and the spec of a datasource.
+ */
+export interface DatasourceDefinition {
+  name: string;
+  spec: DatasourceSpec;
+}
+
+export type Datasource = DatasourceResource | GlobalDatasourceResource;

client/src/model/http-proxy.ts

@@ -0,0 +1,37 @@
+// Copyright The Perses Authors
+// Licensed 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 { RequestHeaders } from './http';
+
+export interface HTTPProxy {
+  kind: 'HTTPProxy';
+  spec: HTTPProxySpec;
+}
+export interface HTTPProxySpec {
+  // url is the url of the datasource. It is not the url of the proxy.
+  // The Perses server is the proxy, so it needs to know where to redirect the request.
+  url: string;
+  // allowedEndpoints is a list of tuples of http methods and http endpoints that will be accessible.
+  // Leave it empty if you don't want to restrict the access to the datasource.
+  allowedEndpoints?: HTTPAllowedEndpoint[];
+  // headers can be used to provide additional headers that need to be forwarded when requesting the datasource
+  headers?: RequestHeaders;
+  // secret is the name of the secret that should be used for the proxy or discovery configuration
+  // It will contain any sensitive information such as password, token, certificate.
+  secret?: string;
+}
+
+export interface HTTPAllowedEndpoint {
+  endpointPattern: string;
+  method: string;
+}

client/src/model/http.ts

@@ -0,0 +1,21 @@
+// Copyright The Perses Authors
+// Licensed 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 { HTTPProxy } from './http-proxy';
+
+export type RequestHeaders = Record<string, string>;
+
+export interface HTTPDatasourceSpec {
+  directUrl?: string;
+  proxy?: HTTPProxy;
+}

client/src/model/index.ts

@@ -0,0 +1,19 @@
+// Copyright The Perses Authors
+// Licensed 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 * from './datasource';
+export * from './http';
+export * from './http-proxy';
+export * from './kind';
+export * from './resource';
+export * from './datasource-api';

client/src/model/kind.ts

@@ -0,0 +1,47 @@
+// Copyright The Perses Authors
+// Licensed 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 type Kind =
+  | 'Dashboard'
+  | 'Datasource'
+  | 'EphemeralDashboard'
+  | 'Folder'
+  | 'GlobalDatasource'
+  | 'GlobalRole'
+  | 'GlobalRoleBinding'
+  | 'GlobalSecret'
+  | 'GlobalVariable'
+  | 'Project'
+  | 'Role'
+  | 'RoleBinding'
+  | 'Secret'
+  | 'User'
+  | 'Variable';
+
+export const KINDS: Kind[] = [
+  'Dashboard',
+  'Datasource',
+  'EphemeralDashboard',
+  'Folder',
+  'GlobalDatasource',
+  'GlobalRole',
+  'GlobalRoleBinding',
+  'GlobalSecret',
+  'GlobalVariable',
+  'Project',
+  'Role',
+  'RoleBinding',
+  'Secret',
+  'User',
+  'Variable',
+];

client/src/model/resource.ts

@@ -0,0 +1,41 @@
+// Copyright The Perses Authors
+// Licensed 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 { Kind } from './kind';
+
+export function isProjectMetadata(metadata: Metadata | ProjectMetadata): metadata is ProjectMetadata {
+  return 'project' in metadata;
+}
+
+export interface Metadata {
+  name: string;
+  createdAt?: string;
+  updatedAt?: string;
+  version?: number;
+  tags?: string[];
+}
+
+export interface ProjectMetadata extends Metadata {
+  project: string;
+}
+
+export interface Resource {
+  kind: Kind;
+  metadata: Metadata | ProjectMetadata;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  spec?: any;
+}
+
+export function getMetadataProject(metadata: ProjectMetadata | Metadata): string | undefined {
+  return 'project' in metadata ? metadata.project : undefined;
+}