feat: Embedded SDK

.github/workflows/release-embedded-sdk.yml

@@ -0,0 +1,61 @@
+name: release-embedded-sdk-workflow
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  build:
+    name: Build and publish the embedded sdk if version changed
+
+    runs-on: ubuntu-20.04
+
+    strategy:
+      matrix:
+        node-version: [16]
+
+    steps:
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/
+
+      - name: Cache npm
+        uses: actions/cache@v1
+        with:
+          path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS
+          key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.OS }}-node-
+            ${{ runner.OS }}-
+
+      - name: Get npm cache directory path
+        id: npm-cache-dir-path
+        run: echo "::set-output name=dir::$(npm config get cache)"
+      - name: Cache npm
+        uses: actions/cache@v1
+        id: npm-cache # use this to check for `cache-hit` (`steps.npm-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: ${{ steps.npm-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      - name: Configure npm
+        run: |
+          echo "@superset-ui:registry=https://registry.npmjs.org/" > .npmrc
+          echo "registry=https://registry.npmjs.org/" >> .npmrc
+          echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" >> $HOME/.npmrc 2> /dev/null
+          npm whoami
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Install dependencies
+        working-directory: ./superset-embedded-sdk
+        run: npm ci
+
+      - name: Build packages
+        working-directory: ./superset-embedded-sdk
+        run: npm run ci:release

superset-embedded-sdk/.gitignore

@@ -0,0 +1,3 @@
+bundle
+dist
+lib

superset-embedded-sdk/CONTRIBUTING.md

@@ -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.
+-->
+
+# Contributing to the Superset Embedded SDK
+
+The superset-embedded-sdk directory is a self contained sub-project in the Superset codebase.
+
+This is because the SDK has different requirements from other parts of the Superset codebase:
+Namely, we need to export a lightweight frontend library that can be used in as many environments as possible.
+Having separate configs allows for better separation of concerns and allows the SDK code to remain simple.
+
+## Building
+
+The library is built in two modes: one for consumption by package managers
+and subsequent build systems, and one for consumption directly by a web browser.
+
+Babel is used to build the sdk into a relatively modern js package in the `lib` directory.
+This is used by consumers who install the embedded sdk via npm, yarn, or other package manager.
+
+Webpack is used to bundle the `bundle` directory,
+for use directly in the browser with no build step e.g. when importing via unpkg.
+
+Typescript outputs type definition files to the `dist` directory.
+
+Which of these outputs is used by the library consumer is determined by our package.json's `main`, `module`, and `types` fields.
+
+## Testing
+
+You may notice a lack of tests in this directory. The functions used in the sdk so far are very closely tied to browser behavior,
+and are not easily testable. We have instead opted to test the sdk behavior using end-to-end tests.
+This way, the tests can assert that the sdk actually mounts the iframe and communicates with it correctly.
+
+At time of writing, these tests are not written yet, because we haven't yet put together the demo app that they will leverage.
+
+## Publishing
+
+To publish a new version, first determine whether it will be a major/minor/patch version according to [semver rules](https://semver.org/).
+Run `npm version [major|minor|patch]`, and commit the resulting version change.
+
+Building the package and publishing to npm will be handled by github actions automatically on merge to master,
+provided that the currently specified package version isn't already published.

superset-embedded-sdk/README.md

@@ -0,0 +1,90 @@
+<!--
+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.
+-->
+
+# Superset Embedded SDK
+
+The Embedded SDK allows you to embed dashboards from Superset into your own app,
+using your app's authentication.
+
+Embedding is done by inserting an iframe, containing a Superset page, into the host application.
+
+## Embedding a Dashboard
+
+Using npm:
+
+```sh
+npm install --save @superset-ui/embedded-sdk
+```
+
+```js
+import { embedDashboard } from "@superset-ui/embedded-sdk";
+
+embedDashboard({
+  id: "abc123", // given by the Superset embedding UI
+  supersetDomain: "https://superset.example.com",
+  mountPoint: document.getElementById("my-superset-container"), // any html element that can contain an iframe
+  fetchGuestToken: () => fetchGuestTokenFromBackend(),
+});
+```
+
+You can also load the Embedded SDK from a CDN. The SDK will be available as `supersetEmbeddedSdk` globally:
+
+```html
+<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
+
+<script>
+  supersetEmbeddedSdk.embedDashboard({
+    // ... here you supply the same parameters as in the example above
+  });
+</script>
+```
+
+## Authentication/Authorization with Guest Tokens
+
+Embedded resources use a special auth token called a Guest Token to grant Superset access to your users,
+without requiring your users to log in to Superset directly. Your backend must create a Guest Token
+by requesting Superset's `POST /security/guest_token` endpoint, and pass that guest token to your frontend.
+
+The Embedding SDK takes the guest token and use it to embed a dashboard.
+
+### Creating a Guest Token
+
+From the backend, http `POST` to `/security/guest_token` with some parameters to define what the guest token will grant access to.
+Guest tokens can have Row Level Security rules which filter data for the user carrying the token.
+
+The agent making the `POST` request must be authenticated with the `can_grant_guest_token` permission.
+
+Example `POST /security/guest_token` payload:
+
+```json
+{
+  "user": {
+    "username": "stan_lee",
+    "first_name": "Stan",
+    "last_name": "Lee"
+  },
+  "resources": [{
+    "type": "dashboard",
+    "id": "abc123"
+  }],
+  "rls": [
+    { "clause": "publisher = 'Nintendo'" }
+  ]
+}
+```

superset-embedded-sdk/babel.config.js

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+module.exports = {
+  presets: [
+    "@babel/preset-typescript",
+    "@babel/preset-env"
+  ],
+  sourceMaps: true,
+};