docs(pylon.mdx): update to pylon v2 (#8643)

Hi!

I just release Pylon v2. Due to some breaking changes I need to adapt
the docs.

- Docs: https://pylon.cronit.io/docs/getting-started
- Release notes: https://pylon.cronit.io/docs/release-notes/v2.0
- Migration guide:
https://pylon.cronit.io/docs/release-notes/migrating-from-v1-to-v2
This commit is contained in:
Nico Schett 2024-09-24 08:43:39 +02:00 committed by GitHub
parent e5e233b439
commit eb97be6fdf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 46 additions and 44 deletions

View File

@ -1 +0,0 @@
You have to install Pylon as described in [their documentation](https://pylon.cronit.io/docs/installation/).

View File

@ -6,7 +6,6 @@ sidebar_label: Pylon
import AppJWT from "../imports/_app_jwt.mdx"; import AppJWT from "../imports/_app_jwt.mdx";
import ServiceuserJWT from "../imports/_serviceuser_jwt.mdx"; import ServiceuserJWT from "../imports/_serviceuser_jwt.mdx";
import ServiceuserRole from "../imports/_serviceuser_role.mdx"; import ServiceuserRole from "../imports/_serviceuser_role.mdx";
import SetupPylon from "../imports/_setup_pylon.mdx";
This integration guide demonstrates the recommended way to incorporate ZITADEL into your [Pylon](https://pylon.cronit.io) service. This integration guide demonstrates the recommended way to incorporate ZITADEL into your [Pylon](https://pylon.cronit.io) service.
It explains how to check the token validity in the API and how to check for permissions. It explains how to check the token validity in the API and how to check for permissions.
@ -43,26 +42,27 @@ And the following from the Serviceuser:
## Setup new Pylon service ## Setup new Pylon service
### Setup Pylon Pylon allows you to create a new service using the `npm create pylon` command. This command creates a new Pylon project with a basic project structure and configuration.
During the setup process, you can choose your preferred runtime, such as Bun, Node.js, or Cloudflare Workers.
<SetupPylon /> **This guide uses the Bun runtime.**
### Creating a new project ### Creating a new project
To create a new Pylon project, run the following command: To create a new Pylon project, run the following command:
```bash ```bash
pylon new my-pylon-project npm create pylon my-pylon@latest
``` ```
This will create a new directory called `my-pylon-project` with a basic Pylon project structure. This will create a new directory called `my-pylon` with a basic Pylon project structure.
### Project structure ### Project structure
Pylon projects are structured as follows: Pylon projects are structured as follows:
``` ```
my-pylon-project/ my-pylon/
├── .pylon/ ├── .pylon/
├── src/ ├── src/
│ ├── index.ts │ ├── index.ts
@ -81,16 +81,18 @@ my-pylon-project/
Here's an example of a basic Pylon service: Here's an example of a basic Pylon service:
```ts ```ts
import { defineService } from "@getcronit/pylon"; import { app } from "@getcronit/pylon";
export default defineService({ export const graphql = {
Query: { Query: {
sum: (a: number, b: number) => a + b, sum: (a: number, b: number) => a + b,
}, },
Mutation: { Mutation: {
divide: (a: number, b: number) => a / b, divide: (a: number, b: number) => a / b,
}, },
}); };
export default app;
``` ```
## Secure the API ## Secure the API
@ -113,6 +115,8 @@ AUTH_PROJECT_ID='250719519163548112'
2. Copy the `.json`-key-file that you downloaded from the ZITADEL Console into the root folder of your project and rename it to `key.json`. 2. Copy the `.json`-key-file that you downloaded from the ZITADEL Console into the root folder of your project and rename it to `key.json`.
3. (Optional) For added convenience in production environments, you can include the content of the .json key file as `AUTH_KEY` in the .env file or as an environment variable.
### Auth ### Auth
Pylon provides a auth module and a decorator to check the validity of the token and the permissions. Pylon provides a auth module and a decorator to check the validity of the token and the permissions.
@ -140,8 +144,7 @@ The following code demonstrates how to create a Pylon service with the required
```ts ```ts
import { import {
defineService, app,
PylonAPI,
auth, auth,
requireAuth, requireAuth,
getContext, getContext,
@ -208,7 +211,7 @@ class User {
} }
} }
export default defineService({ export const graphql = {
Query: { Query: {
me: User.me, me: User.me,
info: () => "Public Data", info: () => "Public Data",
@ -216,43 +219,43 @@ export default defineService({
Mutation: { Mutation: {
createUser: User.create, createUser: User.create,
}, },
};
// Initialize the authentication middleware
app.use("*", auth.initialize());
// Automatically try to create a user for each request for demonstration purposes
app.use(async (_, next) => {
try {
await User.create();
} catch {
// Ignore errors
// Fail silently if the user already exists
}
await next();
}); });
export const configureApp: PylonAPI["configureApp"] = (app) => { app.get("/api/info", (c) => {
// Initialize the authentication middleware return new Response("Public Data");
app.use("*", auth.initialize()); });
// Automatically try to create a user for each request for demonstration purposes // The `auth.require()` middleware is optional here, as the `User.me` method already checks for it.
app.use(async (_, next) => { app.get("/api/me", auth.require(), async (c) => {
try { const user = await User.me();
await User.create();
} catch {
// Ignore errors
// Fail silently if the user already exists
}
await next(); return c.json(user);
}); });
app.get("/api/info", (c) => { // A role check for `read:messages` is not required here, as the `user.messages` method already checks for it.
return new Response("Public Data"); app.get("/api/me/messages", auth.require(), async (c) => {
}); const user = await User.me();
// The `auth.require()` middleware is optional here, as the `User.me` method already checks for it. // This will throw an error if the user does not have the `read:messages` role
app.get("/api/me", auth.require(), async (c) => { return c.json(await user.messages());
const user = await User.me(); });
return c.json(user); export default app;
});
// A role check for `read:messages` is not required here, as the `user.messages` method already checks for it.
app.get("/api/me/messages", auth.require(), async (c) => {
const user = await User.me();
// This will throw an error if the user does not have the `read:messages` role
return c.json(await user.messages());
});
};
``` ```
### Call the API ### Call the API
@ -273,7 +276,7 @@ export TOKEN='MtjHodGy4zxKylDOhg6kW90WeEQs2q...'
Now you have to start the Pylon service: Now you have to start the Pylon service:
```bash ```bash
bun run develop bun run dev
``` ```
With the access token, you can then do the following calls: With the access token, you can then do the following calls: