@ocel/pulumi 0.0.0

package/README.md

@@ -0,0 +1,131 @@
+# @ocel/pulumi
+
+Publish resources your Pulumi program provisions as ocel bindings, so an ocel app can
+reach them by name.
+
+## Install
+
+```bash
+pnpm add @ocel/pulumi
+```
+
+`@pulumi/pulumi` and `ocel` are peer dependencies. `ocel` is resolved from the ocel
+project — the directory holding `ocel.json` — not from the Pulumi program.
+
+## Use
+
+`ocel.json` beside `Pulumi.yaml` in the same package is the supported layout.
+Declare the binding in the Pulumi program:
+
+```ts
+import * as aws from "@pulumi/aws";
+import { Config } from "@pulumi/pulumi";
+import { bind } from "@ocel/pulumi";
+
+const password = new Config().requireSecret("dbPassword");
+
+const orders = new aws.rds.Instance("orders", {
+  engine: "postgres",
+  password,
+  /* … */
+});
+
+bind.postgres("orders", {
+  host: orders.address,
+  port: orders.port,
+  database: orders.dbName,
+  username: orders.username,
+  password,
+});
+```
+
+Name it in `ocel.json`:
+
+```json
+{
+  "$schema": "https://ocel.dev/schema/0.0.0/ocel.schema.json",
+  "slug": "shop",
+  "provider": { "name": "aws" },
+  "bindings": ["orders"],
+  "apps": [{ "name": "api", "path": "." }]
+}
+```
+
+Then read it in the app:
+
+```ts
+import { postgres } from "ocel/postgres";
+
+export const orders = postgres("orders");
+```
+
+`pulumi up` publishes the binding; `ocel deploy` hands it to the app.
+
+## `bind.postgres(name, resource, opts?)`
+
+`name` is the name the app binds to. `resource` is the postgres fields, each of them
+an input this update resolves before the record is published, so a resource's outputs
+are handed over as they are:
+
+```ts
+bind.postgres("orders", {
+  host,
+  port,
+  database,
+  username,
+  password,
+  grants: [{ actions: ["rds-db:connect"], resources: [dbUserArn] }],
+});
+```
+
+`opts` says where the binding lands:
+
+| Option        | Default                     | Meaning                                                                                    |
+| ------------- | --------------------------- | ------------------------------------------------------------------------------------------ |
+| `class`       | `"production"`              | The ocel class the binding is published to.                                                     |
+| `environment` | none                        | One preview environment; `class: "preview"` only. Left off, the binding serves every preview.   |
+| `project`     | the program's directory     | The directory holding `ocel.json`.                                                      |
+| `parent`      | none                        | The Pulumi resource this binding hangs under.                                                   |
+
+One call is one resource. Remove the call and the published binding goes with it. A name
+belongs to whoever published it — the URN of the resource the call creates — so two
+stacks publishing `orders` into one project is refused rather than silently handing
+every app bound to that name another database.
+
+## `bind.custom(name, { properties }, opts?)`
+
+Publishes values ocel neither types nor delivers, for a transform to read:
+
+```ts
+bind.custom("network", {
+  properties: {
+    subnetIds: vpc.privateSubnetIds,
+    securityGroupIds: [securityGroup.id],
+  },
+});
+```
+
+A transform module in the ocel project reads them by name:
+
+```ts
+export default defineTransform(({ bindings }) => ({
+  function: {
+    vpc: {
+      subnetIds: bindings.network.subnetIds,
+      securityGroupIds: bindings.network.securityGroupIds,
+    },
+  },
+}));
+```
+
+The properties are inserted verbatim — string, number, boolean, list or object — and
+the surface being filled is what rejects a value of the wrong shape. `opts` is the same
+as for `bind.postgres`.
+
+No app reads a custom binding, so it takes no `grants`: nothing would attach them. Naming
+one in `bindings` is refused for the same reason.
+
+## Types
+
+There is one function per ocel binding type an app resolves. A resource ocel cannot type is
+not bindable by name — publish what a transform needs from it with `bind.custom` instead.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+export declare const source = "pulumi";
+export interface Target {
+    project: string;
+    class: "production" | "preview";
+    environment?: string;
+}
+export declare function runBindings(args: string[], target: Target, input?: string): void;
+export declare function checkTarget(target: Target): void;

package/dist/cli.js

@@ -0,0 +1,59 @@
+import childProcess from "node:child_process";
+import nodeModule from "node:module";
+import path from "node:path";
+export const source = "pulumi";
+export function runBindings(args, target, input) {
+    checkTarget(target);
+    const [runtime, entry] = ocelCommand(target.project);
+    const result = childProcess.spawnSync(runtime, [entry, "bindings", ...args, ...flagsFor(target)], {
+        cwd: target.project,
+        input,
+        encoding: "utf8",
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(refusal(result.stderr ?? "", result.status));
+    }
+}
+export function checkTarget(target) {
+    if (!target.project) {
+        throw new Error("an ocel project is required: it is the directory holding ocel.json, whose apps consume this binding, and it is never read from a Pulumi stack or project name");
+    }
+    if (target.class !== "production" && target.class !== "preview") {
+        throw new Error(`class ${JSON.stringify(target.class ?? null)} is neither "production" nor "preview": a binding is published to an ocel class, never to a Pulumi stack name`);
+    }
+    if (target.environment === classWideMarker) {
+        throw new Error(`${classWideMarker} is reserved: leave the environment off to publish to the whole class, which serves every preview including the ephemeral ones`);
+    }
+    if (target.environment && target.class !== "preview") {
+        throw new Error(`environment ${target.environment} is named alongside class ${target.class}: a binding is published to a class and, in preview, to one preview environment`);
+    }
+}
+function flagsFor(target) {
+    const flags = target.class === "preview" ? ["--preview"] : [];
+    if (target.environment) {
+        flags.push("--environment", target.environment);
+    }
+    return flags;
+}
+const classWideMarker = "*";
+function refusal(stderr, status) {
+    const said = stderr.trim();
+    if (!said) {
+        return `ocel bindings exited ${status ?? "on a signal"} without saying why`;
+    }
+    return said;
+}
+function ocelCommand(project) {
+    const require = nodeModule.createRequire(path.join(project, "ocel.json"));
+    let manifest;
+    try {
+        manifest = require.resolve("ocel/package.json");
+    }
+    catch (cause) {
+        throw new Error(`@ocel/pulumi runs the ocel CLI in ${project}, and ocel is not installed there. Add ocel to that project's dependencies.`, { cause });
+    }
+    return [process.execPath, path.join(path.dirname(manifest), "bin", "run.js")];
+}

package/dist/custom.d.ts

@@ -0,0 +1,7 @@
+/** One `common.bindings.v1.Binding` holding a custom record's open properties, ready for protobuf JSON. */
+export interface CustomBinding {
+    name: string;
+    custom: Record<string, unknown>;
+    source: string;
+}
+export declare function customBinding(name: string, properties: Record<string, unknown>): CustomBinding;

package/dist/custom.js

@@ -0,0 +1,15 @@
+import { source } from "./cli.js";
+export function customBinding(name, properties) {
+    if (!name) {
+        throw new Error("a binding is published under no name; the name is what a transform reads it by");
+    }
+    if (Object.keys(properties).length === 0) {
+        throw new Error(`custom binding ${name} carries no properties; a custom binding is the values a transform reads out of it, so an empty one has nothing to read`);
+    }
+    for (const [key, value] of Object.entries(properties)) {
+        if (value === undefined) {
+            throw new Error(`custom binding ${name} carries ${key} as undefined; a property a transform names must have a value the deploy can insert`);
+        }
+    }
+    return { name, custom: properties, source };
+}

package/dist/grants.d.ts

@@ -0,0 +1,18 @@
+import type { Input } from "@pulumi/pulumi";
+/** A provider-native permission an app receives along with the binding's properties. */
+export interface Grant {
+    actions: string[];
+    resources: string[];
+    label?: string;
+}
+/**
+ * A grant as it is written in a Pulumi program, where the resource a permission
+ * names is an output of the resource being bound and is resolved before the
+ * record is published.
+ */
+export interface GrantInput {
+    actions: string[];
+    resources: Input<string>[];
+    label?: string;
+}
+export declare function scoped(name: string, grants: Grant[] | undefined): Grant[] | undefined;

package/dist/grants.js

@@ -0,0 +1,22 @@
+export function scoped(name, grants) {
+    if (!grants || grants.length === 0) {
+        return undefined;
+    }
+    for (const grant of grants) {
+        if (grant.actions.length === 0 || grant.actions.some(unscopedAction)) {
+            throw new Error(`binding ${name} carries a grant over ${grant.actions.join(", ") || "no action"}: an action naming a whole service reaches past the resource the binding names`);
+        }
+        if (grant.resources.length === 0 || grant.resources.includes(wildcard)) {
+            throw new Error(`binding ${name} carries a grant over ${grant.resources.join(", ") || "no resource"}: an app receives permissions for the resource it binds and nothing else`);
+        }
+    }
+    return grants;
+}
+const wildcard = "*";
+function unscopedAction(action) {
+    const separator = action.indexOf(":");
+    if (separator < 0) {
+        return action === wildcard;
+    }
+    return action.slice(0, separator) === wildcard || action.slice(separator + 1) === wildcard;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { custom, postgres } from "./resource.js";
+export type { CustomBinding } from "./custom.js";
+export type { Grant, GrantInput } from "./grants.js";
+export type { PostgresBinding, PostgresProperties } from "./postgres.js";
+export type { BindOptions, CustomProperties, DescribedPostgresResource, } from "./resource.js";
+/**
+ * The ocel bindings this Pulumi program publishes, one call per binding.
+ *
+ * A binding is one resource an app reaches, published under a name of this
+ * program's choosing — `bind.postgres("pulumi-pg-orders", …)` here, and the app's
+ * config binds a declared resource to it with
+ * `"bindings": { "postgres": { "orders": "pulumi-pg-orders" } }`. Each
+ * call is one Pulumi resource, so removing the call removes the published
+ * record, and there is one function per ocel binding type an app resolves: a
+ * resource ocel cannot type is not bindable by name, and nothing here refuses
+ * at update what it could refuse by having no function to call.
+ *
+ * `custom` is the exception an app never sees: it publishes values ocel neither
+ * types nor delivers, read only by a transform module through
+ * `bindings.<name>.<property>`.
+ */
+export declare const bind: {
+    postgres: typeof postgres;
+    custom: typeof custom;
+};

package/dist/index.js

@@ -0,0 +1,18 @@
+import { custom, postgres } from "./resource.js";
+/**
+ * The ocel bindings this Pulumi program publishes, one call per binding.
+ *
+ * A binding is one resource an app reaches, published under a name of this
+ * program's choosing — `bind.postgres("pulumi-pg-orders", …)` here, and the app's
+ * config binds a declared resource to it with
+ * `"bindings": { "postgres": { "orders": "pulumi-pg-orders" } }`. Each
+ * call is one Pulumi resource, so removing the call removes the published
+ * record, and there is one function per ocel binding type an app resolves: a
+ * resource ocel cannot type is not bindable by name, and nothing here refuses
+ * at update what it could refuse by having no function to call.
+ *
+ * `custom` is the exception an app never sees: it publishes values ocel neither
+ * types nor delivers, read only by a transform module through
+ * `bindings.<name>.<property>`.
+ */
+export const bind = { postgres, custom };

package/dist/postgres.d.ts

@@ -0,0 +1,21 @@
+import { type Grant } from "./grants.js";
+/** The typed properties a postgres binding carries, as `common.bindings.v1.PostgresProperties`. */
+export interface PostgresProperties {
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+}
+/** One `common.bindings.v1.Binding` holding postgres properties, ready for protobuf JSON. */
+export interface PostgresBinding {
+    name: string;
+    postgres: PostgresProperties;
+    grants?: Grant[];
+    source: string;
+}
+export interface DescribedPostgres {
+    properties: Record<string, unknown>;
+    grants?: Grant[];
+}
+export declare function postgresBinding(name: string, described: DescribedPostgres): PostgresBinding;

package/dist/postgres.js

@@ -0,0 +1,37 @@
+import { source } from "./cli.js";
+import { scoped } from "./grants.js";
+export function postgresBinding(name, described) {
+    if (!name) {
+        throw new Error("a binding is published under no name; the name is what a consuming app binds to");
+    }
+    const binding = {
+        name,
+        postgres: propertiesFor(name, described.properties),
+        source,
+    };
+    const grants = scoped(name, described.grants);
+    if (grants) {
+        binding.grants = grants;
+    }
+    return binding;
+}
+const textFields = ["host", "database", "username", "password"];
+function propertiesFor(name, properties) {
+    const out = {};
+    for (const field of textFields) {
+        const value = properties[field];
+        if (typeof value !== "string" || value === "") {
+            throw new Error(`postgres binding ${name} carries no ${field}; a postgres binding is its host, port, database, username and password, and an app resolving it reads every one`);
+        }
+        out[field] = value;
+    }
+    out.port = portFor(name, properties.port);
+    return out;
+}
+function portFor(name, value) {
+    const port = typeof value === "string" ? Number(value) : value;
+    if (typeof port !== "number" || !Number.isInteger(port) || port <= 0) {
+        throw new Error(`postgres binding ${name} carries port ${JSON.stringify(value ?? null)}, and a port is a whole number an app can connect to`);
+    }
+    return port;
+}

package/dist/resource.d.ts

@@ -0,0 +1,109 @@
+import { type Input, type Resource } from "@pulumi/pulumi";
+import { type Target } from "./cli.js";
+import type { GrantInput } from "./grants.js";
+import { type DescribedPostgres } from "./postgres.js";
+/**
+ * A postgres resource described from what a Pulumi resource exposes.
+ *
+ * The fields are the ones `common.bindings.v1.PostgresProperties` declares, each of them
+ * an `Input`, so a resource's outputs are handed over as they are and resolved
+ * before the record is published. The grants are explicit: nothing is inferred
+ * about what an app may do with the resource.
+ */
+export interface DescribedPostgresResource {
+    host: Input<string>;
+    port: Input<number>;
+    database: Input<string>;
+    username: Input<string>;
+    password: Input<string>;
+    grants?: GrantInput[];
+}
+/**
+ * A record only transforms read: the properties written out by hand, under a
+ * name a transform names.
+ *
+ * Ocel neither types nor interprets what a custom binding carries — it hands the
+ * values to a transform that fills a surface field with them, so nothing is
+ * delivered to an app and no grants are accepted.
+ */
+export type CustomProperties = Record<string, Input<unknown>>;
+/**
+ * Where a binding lands: an ocel class, one preview environment, the project
+ * holding both, and the Pulumi resource this one hangs under.
+ */
+export interface BindOptions {
+    class?: "production" | "preview";
+    environment?: string;
+    project?: string;
+    parent?: Resource;
+}
+interface BindingInputs extends Target {
+    name: string;
+    owner: string;
+}
+interface PostgresInputs extends BindingInputs, DescribedPostgres {
+}
+interface CustomInputs extends BindingInputs {
+    properties: Record<string, unknown>;
+}
+interface BindingState extends Target {
+    name: string;
+    owner: string;
+    digest: string;
+}
+export declare const postgresProvider: {
+    create(inputs: PostgresInputs): Promise<{
+        id: string;
+        outs: BindingState;
+    }>;
+    diff(_id: string, olds: BindingState, news: PostgresInputs): Promise<{
+        changes: boolean;
+        replaces: string[];
+        deleteBeforeReplace: boolean;
+    }>;
+    update(_id: string, _olds: BindingState, news: PostgresInputs): Promise<{
+        outs: BindingState;
+    }>;
+    delete(_id: string, props: BindingState): Promise<void>;
+};
+export declare const customProvider: {
+    create(inputs: CustomInputs): Promise<{
+        id: string;
+        outs: BindingState;
+    }>;
+    diff(_id: string, olds: BindingState, news: CustomInputs): Promise<{
+        changes: boolean;
+        replaces: string[];
+        deleteBeforeReplace: boolean;
+    }>;
+    update(_id: string, _olds: BindingState, news: CustomInputs): Promise<{
+        outs: BindingState;
+    }>;
+    delete(_id: string, props: BindingState): Promise<void>;
+};
+/**
+ * Publishes one Pulumi-defined resource as one ocel binding, as a side effect of
+ * this update.
+ *
+ * The name is this program's own, published for an app's config to bind a
+ * declared resource to — `postgres("pulumi-pg-orders", …)` here, and
+ * `"bindings": { "postgres": { "orders": "pulumi-pg-orders" } }` in `ocel.json`
+ * — and the resource is the postgres fields read off whatever provisioned it,
+ * each of them an output this update resolves.
+ * `class` defaults to production, `environment` names one preview environment,
+ * and `project` is the directory holding `ocel.json`, which is the
+ * directory Pulumi runs the program from unless it is given.
+ */
+export declare function postgres(name: string, resource: DescribedPostgresResource, opts?: BindOptions): void;
+/**
+ * Publishes one set of values your own infrastructure holds as one ocel custom
+ * binding, as a side effect of this update.
+ *
+ * The name is the one a transform reads — `bind.custom("network", …)` here,
+ * `bindings.custom.network.subnetIds` in a transform module. `class` defaults to
+ * production, `environment` names one preview environment, and `project` is the
+ * directory holding `ocel.json`, which is the directory Pulumi runs the
+ * program from unless it is given.
+ */
+export declare function custom(name: string, properties: CustomProperties, opts?: BindOptions): void;
+export {};

package/dist/resource.js

@@ -0,0 +1,114 @@
+import crypto from "node:crypto";
+import { createUrn, dynamic } from "@pulumi/pulumi";
+import { checkTarget, runBindings } from "./cli.js";
+import { customBinding } from "./custom.js";
+import { postgresBinding } from "./postgres.js";
+function bindingProvider(recordFor, resolved) {
+    const digestOf = (inputs) => crypto
+        .createHash("sha256")
+        .update(JSON.stringify(recordFor(inputs)))
+        .digest("hex");
+    const stateOf = (inputs) => ({
+        name: inputs.name,
+        owner: inputs.owner,
+        project: inputs.project,
+        class: inputs.class,
+        environment: inputs.environment,
+        digest: digestOf(inputs),
+    });
+    const set = (inputs) => runBindings(["set", "--owner", inputs.owner], inputs, `${JSON.stringify(recordFor(inputs))}\n`);
+    return {
+        async create(inputs) {
+            set(inputs);
+            return { id: idFor(inputs), outs: stateOf(inputs) };
+        },
+        async diff(_id, olds, news) {
+            const replaces = replacesFor(olds, news);
+            return {
+                changes: replaces.length > 0 || !resolved(news) || olds.digest !== digestOf(news),
+                replaces,
+                deleteBeforeReplace: replaces.length > 0,
+            };
+        },
+        async update(_id, _olds, news) {
+            set(news);
+            return { outs: stateOf(news) };
+        },
+        async delete(_id, props) {
+            runBindings(["rm", props.name], props);
+        },
+    };
+}
+export const postgresProvider = bindingProvider((inputs) => postgresBinding(inputs.name, {
+    properties: inputs.properties,
+    grants: inputs.grants,
+}), (inputs) => bindingFields.every((field) => inputs.properties[field] !== undefined));
+export const customProvider = bindingProvider((inputs) => customBinding(inputs.name, inputs.properties), (inputs) => Object.values(inputs.properties).every((value) => value !== undefined));
+/**
+ * Publishes one Pulumi-defined resource as one ocel binding, as a side effect of
+ * this update.
+ *
+ * The name is this program's own, published for an app's config to bind a
+ * declared resource to — `postgres("pulumi-pg-orders", …)` here, and
+ * `"bindings": { "postgres": { "orders": "pulumi-pg-orders" } }` in `ocel.json`
+ * — and the resource is the postgres fields read off whatever provisioned it,
+ * each of them an output this update resolves.
+ * `class` defaults to production, `environment` names one preview environment,
+ * and `project` is the directory holding `ocel.json`, which is the
+ * directory Pulumi runs the program from unless it is given.
+ */
+export function postgres(name, resource, opts) {
+    declare(postgresProvider, name, opts, describe(resource));
+}
+/**
+ * Publishes one set of values your own infrastructure holds as one ocel custom
+ * binding, as a side effect of this update.
+ *
+ * The name is the one a transform reads — `bind.custom("network", …)` here,
+ * `bindings.custom.network.subnetIds` in a transform module. `class` defaults to
+ * production, `environment` names one preview environment, and `project` is the
+ * directory holding `ocel.json`, which is the directory Pulumi runs the
+ * program from unless it is given.
+ */
+export function custom(name, properties, opts) {
+    declare(customProvider, name, opts, { properties });
+}
+const dynamicType = "pulumi-nodejs:dynamic:Resource";
+function declare(provider, name, opts, described) {
+    const target = {
+        project: opts?.project ?? process.cwd(),
+        class: opts?.class ?? "production",
+        environment: opts?.environment,
+    };
+    checkTarget(target);
+    const logical = `ocel-binding-${name}`;
+    new BindingResource(provider, logical, {
+        ...target,
+        name,
+        owner: createUrn(logical, dynamicType, opts?.parent),
+        ...described,
+    }, { parent: opts?.parent });
+}
+class BindingResource extends dynamic.Resource {
+}
+function idFor(inputs) {
+    return [inputs.class, inputs.environment, inputs.name].filter(Boolean).join("/");
+}
+const identity = ["name", "owner", "project", "class", "environment"];
+function replacesFor(olds, news) {
+    return identity.filter((field) => olds[field] !== news[field]);
+}
+const bindingFields = ["host", "port", "database", "username", "password"];
+function describe(resource) {
+    return {
+        properties: pick(resource),
+        grants: resource.grants,
+    };
+}
+function pick(properties) {
+    const out = {};
+    for (const field of bindingFields) {
+        out[field] = properties[field];
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ocel/pulumi",
+  "version": "0.0.0",
+  "private": false,
+  "type": "module",
+  "description": "Publishes Pulumi-defined resources as ocel bindings, one binding per call",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@pulumi/pulumi": "^3",
+    "ocel": "^0.0.0"
+  },
+  "devDependencies": {
+    "@pulumi/pulumi": "~3.252.0",
+    "@types/node": "^20",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9",
+    "ocel": "^0.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ocelhq/ocel.git",
+    "directory": "packages/ocel-pulumi"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}