# Oso Dev Server

This package provides convenient access to the Oso Cloud Dev Server via a NodeJS package.

The package contains the following features:
- Downloads and installs the relevant Dev Server as a `postinstall` script. (See [versioning](#versioning)).
- Exposes the dev server as a Node binary (e.g. run with `npx @osohq/dev-server`).
- Provides functions for managing an in-process version of the Dev Server, with convenience
  functions for getting ephemeral test keys.

## Usage

This is primarily designed for usage in tests, for example, Jest tests using this might look like:

```ts
import { glob } from "glob";
import { Oso } from "oso-cloud";
import {
  configureDevServer,
  getEphemeralOsoKey,
  stopRunningInstance,
} from "@osohq/dev-server";

async function testOso() {
  const { url, apiKey } = await getEphemeralOsoKey();
  const oso = new Oso(url, apiKey);
}

describe("Oso tests", () => {
  beforeAll(async () => {
    // load all policy files on starting the server
    // these will be copied into each ephmeral test
    // instance
    const policyFiles = await glob("**/*.polar");
    await configureDevServer({ policyFiles });
    
    // Or specify a port if you need a fixed port:
    // await configureDevServer({ policyFiles, port: 8080 });
  })

  afterEach(async () => {
    try {
      // clean up any instances if they're still running
      await stopRunningInstance();
    } catch (e) {
      // ignore
    }
  });

  it("can get list results back", async () => {
    const oso = await testOso();
    const results = await oso.list(
      { type: "User", id: "alice" },
      "read",
      "Foo"
    );

    expect(results).toEqual(["123"]);
  });
});
```


## Versioning

Versions of this package have two components:
1. The package version, e.g. `0.0.1`
2. The version of the Dev Server it links by default, e.g. `1.10.6` -- captured as a build version.

e.g. version 0.0.1 built to link against 1.10.6 is versioned as `0.0.1+1.10.6`.

If you wish to override the Dev Server build, you can do so by specifying the environment variable
`OSO_DEV_SERVER_VERSION`

## Configuration Options

The `configureDevServer` function accepts the following options:

| Option | Type | Description |
|--------|------|-------------|
| `policyFiles` | `string[]` | Array of policy file paths to load on server start |
| `enabledFeatures` | `string[]` | Array of feature flags to enable |
| `port` | `number` | Specific port to use for the dev server. If not specified, an available port is automatically selected |