Typegate
Using Embedded Typegate (Recommended)
meta dev
You can launch the embedded typegate via two subcommands, meta dev and meta typegate. Check the Embedded Typegate for more info.
The typegate instance runs on port 7890 by default. You can check if the typegate node is running by accessing http://localhost:7890 in your browser.
Using docker (Not Recommended)
Install Docker and use the following compose.yml to launch a typegate node. For multi-instance production workloads, Redis and an S3 object store provider are required but the typegate will run using in-memory stores if no SYNC_* environment variable is detected. More details can be found here. In practice you might also want to add a database or other systems that the typegate can connect to.
services:
typegate:
image: ghcr.io/metatypedev/typegate:latest
ports:
- "7890:7890"
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
# only for dev, generate secure values for production
TG_SECRET: "a4lNi0PbEItlFZbus1oeH/+wyIxi9uH6TpL8AIqIaMBNvp7SESmuUBbfUwC0prxhGhZqHw8vMDYZAGMhSZ4fLw=="
TG_ADMIN_PASSWORD: password
DEBUG: "true"
# launch the containers
docker compose up --detach
# watch the typegate logs
docker compose logs typegate --follow
Internal APIs
Most of the internal APIs are still unstable, and may change without notice. If you still want to experiment with them, you can use the GraphQL introspection to discover them.
- /typegate
- /prisma-migration
The typegate nodes - or typegates - are the central components of the ecosystems. They build and type check typegraphs, and expose them through a HTTP/GraphQL interface. They enforce the type safety of the data flows, connect to all the runtimes and orchestrate the execution of incoming requests.
Request lifecycle
When a new request fires a trigger, the typegate orchestrates the following stages:
- extract the secure request context from custom authentication or JSON Web Token (JWT)
- retrieve cached execution plan or compute a new one
- traverse the typegraph to create a DAG of the required types
- optimize the DAG to reduce the number of calls to the runtimes
- pre-compute all structural elements and data resolutions
- execute the plan
- type check the arguments
- verify lazily policies on the need
- run the DAG execution
- enforce the rate-limiting
- type check the response
- manage metadata of the request
HTTP/GraphQL interface
For now, the typegate nodes are only accessible through HTTP/1.1 and HTTP/2. More protocols could be supported in the future. Typegates expose a GraphQL interface which is the result of a typegraph projected onto corresponding GraphQL types. While this reduces the type safety of the data flowing, it makes more interoperable thanks to the many high-quality and well-known GraphQL tooling already available. The underlying types are also exposed in order for API clients to verify the underlying types.
GraphQL, being a query language, offers a great asset for Metatype's philosophy:
- Efficient querying: the client can specify exactly what data it needs, reducing the amount of over- or under-fetching
- Flexibility: allows for retrieving multiple resources in a single request, unlike REST, which often requires multiple ones
- Typing: GraphQL has a built-in type system that allows for better documentation and stronger validation of the requests
- Improved tooling: tools and libraries around GraphQL are rapidly growing and great a development experience
Configuration
Environment variables.
The following environment variables can be used to configure the typegate. SYNC_* variables have special semantics which you can read about here.
| Environment variables | Desc | Default | Examples |
|---|---|---|---|
| HOSTNAME | Hostname that typegate is deployed on. | getHostname() result. | typegate-123 |
| TG_PORT | Tcp port to serve typegate APIs at. | 7890 | 7891 |
| TG_ADMIN_PASSWORD | Password use by the CLI/SDK to configure the typegate. | Required | My5up3r53cr37 |
| TG_SECRET | Symmetric key used to encrypt cookies and other things (64-byte binary string encoded in base64). | Required. | 0p64wJCpQCTiPqPOEze92HLBieszD3sGLtnx6tWm67kqo1tCYcNZ17rjFjEzMl7HJ/SOFZsTVWU0fUjndMrhsQ== |
| TMP_DIR | Top-level temporary directory. | $PWD/tmp | /tmp/typegate-tmp-dir |
| DEBUG | Enable debug output and other development paths. | false | true |
| TIMER_MAX_TIMEOUT_MS | Timeout for custom runtime functions and other proccesses. | 3000 | 5000 |
| TIMER_POLICY_EVAL_RETRIES | Number of retries when evaluating policies that have timed out | 1 | 3 |
| TIMER_DESTROY_RESOURCES | Force abort and attempt to restart operations that did not respond after multiple retries | true | false |
| JWT_MAX_DURATION_SEC | The lifetime of generated JWT access tokens. | 30 * 24 * 3600 | 604800 |
| JWT_REFRESH_DURATION_SEC | The lifetime of generated JWT refresh tokens. | 5 * 60 | 600 |
| SENTRY_DSN | Data source name for sentry | null | https://[email protected]/1 |
| SENTRY_SAMPLE_RATE | The rate of error events to be sent to Sentry (between 0.0 and 1.0) | 1.0 | 0.5 |
| SENTRY_TRACES_SAMPLE_RATE | The rate of transactions be sent to Sentry (between 0.0 and 1.0) | 1.0 | 0.2 |
| TRUST_PROXY | Whether to accept proxy headers when resolving request contexts. | false | true |
| TRUST_HEADER_IP | The header key on which to resolve request origin addresses. | X-Forwarded-For | X-Forwarded-For |
| DENO_V8_FLAGS | Flags for tuning the v8 javascript engine. Use the --help flag here to see what options are available. | --stack-size=1968 | |
| SYNC_REDIS_URL | URL to the Redis database. Must include the database number. | **Required (sync mode) | http://:password@localhost:6379/0 |
| SYNC_S3_HOST | Hostname of the S3 store. | **Required (sync mode) | play.min.io:9000 |
| SYNC_S3_REGION | S3 region. | Required (sync mode) | us-west-2 |
| SYNC_S3_ACCESS_KEY | Access key for the S3 store credentials. | Required (sync mode) | user |
| SYNC_S3_SECRET_KEY | Access key secret for the S3 store credentials. | Required (sync mode) | password |
| SYNC_S3_PATH_STYLE | true or false, force path style if true. | false | true |
| SYNC_S3_BUCKET | The bucket to be used for the system (dedicated). | Required (sync mode) | mybucket |
| SUBSTANTIAL_POLL_INTERVAL_SEC | Rate at which new schedules are read. | 1.0 | 0.6 |
| SUBSTANTIAL_LEASE_LIFESPAN_SEC | Lease duration associated to a workflow run | 2.0 | 6 |
| SUBSTANTIAL_MAX_ACQUIRE_PER_TICK | Max amount of new acquired replay requests per tick | 3 | 5 |