@constructive-io/graphql-server 2.10.16 → 2.10.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +114 -2
  2. package/package.json +15 -15
package/README.md CHANGED
@@ -9,9 +9,122 @@
9
9
  <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
10
10
  </a>
11
11
  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
12
- <a href="https://www.npmjs.com/package/@constructive-io/graphql-server"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2Fserver%2Fpackage.json"/></a>
12
+ <a href="https://www.npmjs.com/package/@constructive-io/graphql-server"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphql%2Fserver%2Fpackage.json"/></a>
13
13
  </p>
14
14
 
15
+ **Constructive GraphQL Server** is an Express-based server built on PostGraphile. It reads Constructive metadata to select API schemas, applies RLS-aware auth, and exposes a production-ready GraphQL API.
16
+
17
+ ## 🚀 Quick Start
18
+
19
+ ### Use as SDK
20
+
21
+ Install the package:
22
+
23
+ ```bash
24
+ pnpm add @constructive-io/graphql-server @constructive-io/graphql-env
25
+ ```
26
+
27
+ Start a server:
28
+
29
+ ```ts
30
+ import { getEnvOptions } from '@constructive-io/graphql-env';
31
+ import { GraphQLServer } from '@constructive-io/graphql-server';
32
+
33
+ GraphQLServer(
34
+ getEnvOptions({
35
+ pg: { database: 'constructive_db' },
36
+ server: { host: '0.0.0.0', port: 3000 }
37
+ })
38
+ );
39
+ ```
40
+
41
+ > **Tip:** Set `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` to control DB connectivity.
42
+ See [Configuration](#configuration) for the full list of supported env vars and defaults.
43
+
44
+ ### Local Development (this repo)
45
+
46
+ ```bash
47
+ pnpm install
48
+ cd graphql/server
49
+ pnpm dev
50
+ ```
51
+
52
+ This starts the server with env defaults from `@constructive-io/graphql-env`.
53
+ > **Tip:** Set `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` to control DB connectivity.
54
+ See [Configuration](#configuration) for the full list of supported env vars and defaults.
55
+
56
+
57
+ ## What it does
58
+
59
+ Runs an Express server that wires CORS, uploads, domain parsing, auth, and PostGraphile into a single GraphQL endpoint. It serves `/graphql` and `/graphiql`, injects per-request `pgSettings`, and flushes cached schemas on demand or via database notifications. When meta API is enabled, it resolves API config (schemas, roles, modules) from the meta schema using the request host and enforces `api.isPublic`, with optional header overrides in private mode; when meta API is disabled, it serves the fixed schemas and roles from `api.exposedSchemas`, `api.anonRole`, `api.roleName`, and `api.defaultDatabaseId`.
60
+
61
+ ## Key Features
62
+
63
+ - Automatic GraphQL API generation from PostgreSQL schemas
64
+ - RLS-aware authentication and per-request `pgSettings`
65
+ - Meta-schema routing by domain + subdomain
66
+ - File uploads via `graphql-upload`
67
+ - GraphiQL and health check endpoints
68
+ - Schema cache flush via `/flush` or database notifications
69
+
70
+ ## Routes
71
+
72
+ - `GET /healthz` -> health check
73
+ - `GET /graphiql` -> GraphiQL UI
74
+ - `GET /graphql` / `POST /graphql` -> GraphQL endpoint
75
+ - `POST /graphql` (multipart) -> file uploads
76
+ - `POST /flush` -> clears cached Graphile schema for the current API
77
+
78
+ ## Meta API routing
79
+
80
+ When `API_ENABLE_META=true` (default):
81
+
82
+ - The server resolves APIs from `meta_public.domains` using the request host.
83
+ - Only APIs where `api.is_public` matches `API_IS_PUBLIC` are served.
84
+ - In private mode (`API_IS_PUBLIC=false`), you can override with headers:
85
+ - `X-Api-Name` + `X-Database-Id`
86
+ - `X-Schemata` + `X-Database-Id`
87
+ - `X-Meta-Schema` + `X-Database-Id`
88
+
89
+ When `API_ENABLE_META=false`:
90
+
91
+ - The server skips meta lookups and serves the fixed schemas in `API_EXPOSED_SCHEMAS`.
92
+ - Roles and database IDs come from `API_ANON_ROLE`, `API_ROLE_NAME`, and `API_DEFAULT_DATABASE_ID`.
93
+
94
+ ## Configuration
95
+
96
+ Configuration is merged from defaults, config files, and env vars via `@constructive-io/graphql-env`. See `graphql/env/README.md` for the full list and examples.
97
+
98
+ | Env var | Purpose | Default |
99
+ | --- | --- | --- |
100
+ | `PGHOST` | Postgres host | `localhost` |
101
+ | `PGPORT` | Postgres port | `5432` |
102
+ | `PGUSER` | Postgres user | `postgres` |
103
+ | `PGPASSWORD` | Postgres password | `password` |
104
+ | `PGDATABASE` | Postgres database | `postgres` |
105
+ | `GRAPHILE_SCHEMA` | Comma-separated schemas to expose | empty |
106
+ | `FEATURES_SIMPLE_INFLECTION` | Enable simple inflection | `true` |
107
+ | `FEATURES_OPPOSITE_BASE_NAMES` | Enable opposite base names | `true` |
108
+ | `FEATURES_POSTGIS` | Enable PostGIS support | `true` |
109
+ | `API_ENABLE_META` | Enable meta API routing | `true` |
110
+ | `API_IS_PUBLIC` | Serve public APIs only | `true` |
111
+ | `API_EXPOSED_SCHEMAS` | Schemas when meta routing is disabled | empty |
112
+ | `API_META_SCHEMAS` | Meta schemas to query | `collections_public,meta_public` |
113
+ | `API_ANON_ROLE` | Anonymous role name | `administrator` |
114
+ | `API_ROLE_NAME` | Authenticated role name | `administrator` |
115
+ | `API_DEFAULT_DATABASE_ID` | Default database ID | `hard-coded` |
116
+
117
+ ## Testing
118
+
119
+ Use `supertest` or your HTTP client of choice against `/graphql`. For RLS-aware tests, provide a `Bearer` token and ensure the API's auth function is available.
120
+
121
+ ## Related Packages
122
+
123
+ - `@constructive-io/graphql-env` - env parsing + defaults for GraphQL
124
+ - `@constructive-io/graphql-types` - shared types and defaults
125
+ - `graphile-settings` - PostGraphile configuration
126
+ - `graphile-meta-schema` - meta schema support
127
+
15
128
  ---
16
129
 
17
130
  ## Education and Tutorials
@@ -54,7 +167,6 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
54
167
  * [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
55
168
  * [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
56
169
  * [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
57
- * [pg-ast](https://www.npmjs.com/package/pg-ast): **🔍 Low-level AST tools** and transformations for Postgres query structures.
58
170
 
59
171
  ### 🚀 API & Dev Tools
60
172
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@constructive-io/graphql-server",
3
- "version": "2.10.16",
3
+ "version": "2.10.17",
4
4
  "author": "Constructive <developers@constructive.io>",
5
5
  "description": "Constructive GraphQL Server",
6
6
  "main": "index.js",
@@ -41,26 +41,26 @@
41
41
  "dependencies": {
42
42
  "@constructive-io/graphql-env": "^2.8.8",
43
43
  "@constructive-io/graphql-types": "^2.12.6",
44
- "@constructive-io/s3-utils": "^2.3.6",
44
+ "@constructive-io/s3-utils": "^2.3.7",
45
45
  "@constructive-io/upload-names": "^2.3.4",
46
- "@constructive-io/url-domains": "^2.3.5",
46
+ "@constructive-io/url-domains": "^2.3.6",
47
47
  "@graphile-contrib/pg-many-to-many": "^1.0.2",
48
48
  "@pgpmjs/logger": "^1.3.5",
49
- "@pgpmjs/server-utils": "^2.8.8",
49
+ "@pgpmjs/server-utils": "^2.8.9",
50
50
  "@pgpmjs/types": "^2.12.6",
51
51
  "cors": "^2.8.5",
52
- "express": "^5.1.0",
52
+ "express": "^5.2.1",
53
53
  "graphile-build": "^4.14.1",
54
54
  "graphile-cache": "^1.6.9",
55
- "graphile-i18n": "^0.2.20",
56
- "graphile-meta-schema": "^0.3.20",
57
- "graphile-plugin-connection-filter": "^2.4.20",
58
- "graphile-plugin-connection-filter-postgis": "^1.1.21",
59
- "graphile-plugin-fulltext-filter": "^2.1.20",
55
+ "graphile-i18n": "^0.2.21",
56
+ "graphile-meta-schema": "^0.3.21",
57
+ "graphile-plugin-connection-filter": "^2.4.21",
58
+ "graphile-plugin-connection-filter-postgis": "^1.1.22",
59
+ "graphile-plugin-fulltext-filter": "^2.1.21",
60
60
  "graphile-query": "^2.4.6",
61
- "graphile-search-plugin": "^0.2.20",
62
- "graphile-settings": "^2.9.16",
63
- "graphile-simple-inflector": "^0.2.20",
61
+ "graphile-search-plugin": "^0.2.21",
62
+ "graphile-settings": "^2.9.17",
63
+ "graphile-simple-inflector": "^0.2.21",
64
64
  "graphile-utils": "^4.14.1",
65
65
  "graphql": "15.10.1",
66
66
  "graphql-tag": "2.12.6",
@@ -73,7 +73,7 @@
73
73
  "request-ip": "^3.3.0"
74
74
  },
75
75
  "devDependencies": {
76
- "@aws-sdk/client-s3": "^3.956.0",
76
+ "@aws-sdk/client-s3": "^3.958.0",
77
77
  "@types/cors": "^2.8.17",
78
78
  "@types/express": "^5.0.6",
79
79
  "@types/graphql-upload": "^8.0.12",
@@ -83,5 +83,5 @@
83
83
  "nodemon": "^3.1.10",
84
84
  "ts-node": "^10.9.2"
85
85
  },
86
- "gitHead": "8eaef530cad9cfa4f905ad085d5f0475563cf856"
86
+ "gitHead": "976cc9e0e09201c7df40518a1797f4178fc21c2c"
87
87
  }