You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
salt-net-api/README.md

118 lines
3.8 KiB

# Salt Net API
Salt Net API is a TypeScript client for SaltStack to add essential type checking and validation, as well as make working the somewhat convoluted
data structures of SaltStack much easier.
This library heavily utilizes types to provide a clean interface for interacting with minimal logical code to manage.
## Missing Types
SaltStack has an extremely expansive amount of functions and modules available. Initially, I'm mostly adding them as I need manually and
thus providing a way for you to easily extend types that are missing.
I welcome PRs to add more typings around more functions.
Eventually when things look more solid I might generate these automatically from the Salt API documentation.
## Using This Client
This client provides a few abstractions around the matching Salt clients.
```typescript
import { LocalClient, WheelClient, Core, Modules, Runner } from "salt-net-api";
// Create a connection to the Local salt client
export const local = new LocalClient({
endpoint: process.env.SALT_ENDPOINT!,
username: process.env.SALT_USERNAME!,
password: process.env.SALT_PASSWORD!,
eauth: "file",
});
// Define the request type and the expected response type.
const a2 = await local.exec<Modules.Test.IPingRequest, Modules.Test.IPingResult>({
fun: "test.ping",
tgt: "test-site",
});
// You can also execute against the async client where available
const asyncResponse: Core.ILocalAsyncResponse = await local.execAsync<Modules.Service.IRestartRequest>({
fun: "service.restart",
kwarg: {
// The type inference will validate that you are passing this required argument
name: "service-name",
},
});
// Other clients are also available
export const wheel = new WheelClient({
endpoint: process.env.SALT_ENDPOINT!,
username: process.env.SALT_USERNAME!,
password: process.env.SALT_PASSWORD!,
eauth: "file",
});
// This also works for other clients
const a1 = await wheel.exec<Runner.Key.IListRequest, Runner.Key.IListResponse>({
fun: "key.list",
match: "pre",
});
// If a type is missing you can easily specify it yourself
interface INginxStatusRequest extends Core.ILocalRequest {
kwarg: {
url: string;
}
}
interface INginxStatusResponse {
[key: string]: {
connections: number;
status: boolean;
}
}
const customTypeResponse = await local.exec<INginxStatusRequest, INginxStatusResponse>({
fun: "nginx.status",
kwarg: {
url: "http://localhost",
}
});
```
## Events Client
The SaltStack Event Bus is an incredibly useful tool for building event driven automation and functionality from. The events client allows you to easily
leverage this functionality.
```typescript
import { EventsClient } from 'salt-net-api';
const client = new EventsClient({
endpoint: process.env.SALT_ENDPOINT!,
username: process.env.SALT_USERNAME!,
password: process.env.SALT_PASSWORD!,
eauth: "file",
});
client.subscribe({
tag: "salt/auth",
handler: (event: any) => {
console.log(event);
}
});
await client.start();
```
## Why
I wanted to create a way to easily interact with the SaltStack Net API while also taking advantage of TypeScript's ability to type things to make
it have access to required argument validation and auto completion. The SaltStack API has a massive amount of formatting and data differences between
modules and even within a single module.
Originally I started by implementing functions within each client type for every module but it very quickly became far too much essentially boiler plate
code that was just really wrapping types and executing a simple request.
Eventually I deprecated that version and decided to almost entirely rely on TypeScript's ability to type check and generics. This minimizes the amount
of code that actually needs to be unit tested, thus making everything much simpler. It also makes it easy for people to easy create their own types
for modules that may be missing, or custom modules.