Enterprise

Connect to a Core

Connect and authenticate a Python or TypeScript client with a Synnax Core: log in with arguments or sy login, use TLS, and close the client.

Create a client to connect your code to a Synnax Core. The client logs in with the username and password of a user on the Core.

Connect with arguments

import synnax as sy

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
)

The client logs in when you create it. It raises sy.AuthError when the credentials are wrong. It raises Unreachable, from the freighter package, when it cannot reach the Core.

import { Synnax } from "@synnaxlabs/client";

const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
});
await client.connect();

The client starts to connect when you create it, but it does not wait. connect waits for the connection. It throws AuthError when the credentials are wrong, and DisconnectedError when it cannot reach the Core. Without connect, the first request throws the same errors.

To keep credentials out of a script, read them from environment variables that you set. The clients read no environment variables by themselves.

The sy login command saves your credentials, so Python scripts can connect with no arguments. It is part of the Python client. Run it in a terminal:

sy login

Answer the prompts. Press Enter to keep the default in parentheses:

Enter your Synnax connection parameters:
Host (localhost): core.example.com
Port (9090):
Username (synnax): operator
Password:
Secure Connection? [y/n] (n):

When you answer y to the secure prompt, the command also asks for the “CA certificate path”. Enter the path to the ca.crt file of the Core. Leave it empty when the Core has a certificate from a public authority.

The command connects to the Core, then prints “Connection successful!”. In your scripts, create the client with no arguments:

import synnax as sy

client = sy.Synnax()

The command stores the host, port, username, TLS setting, and CA certificate path in ~/.synnax/config.json. It stores the password in the keychain of your operating system, under the name synnax. When the login fails, the command saves nothing. Run sy login again to change the values.

With no saved login, sy.Synnax() raises sy.ValidationError. When you give no host, the client ignores the other arguments and uses the saved login.

Connect with TLS

When the Core serves TLS, set secure to true. For how to give the Core a certificate, see Set up TLS.

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
)

The Python client checks the certificate of the Core, and checks that the certificate is for the host that you connect to. A certificate from a public authority, such as Let’s Encrypt, needs no setup. When the Core uses a self-signed certificate, give the path to its CA certificate in ca_cert:

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
    ca_cert="/path/to/ca.crt",
)

A Core that you start with --auto-cert makes its own CA certificate. Give its path in ca_cert, or save it with sy login. To find the file, see Copy the CA certificate.

const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
  secure: true,
});

The TypeScript client checks the certificate of the Core. When the Core uses a self-signed certificate, the computer must trust its CA certificate. The TypeScript client has no CA certificate option. In a browser, install the CA certificate on the computer. For Node.js, see Node.js.

Close the client

Close the client when your code is done with it:

client.close()

When the script exits, the client closes by itself.

await client.close();

A Node.js script does not exit until you close the client.

Client options

hoststr: The hostname or IP address of the Core. With no host, the client uses the values that sy login saved.
portint: The port of the Core.
usernamestr: The username to log in with.
passwordstr: The password to log in with.
securebool = False: Connect with TLS.
ca_certstr: The path to the CA certificate that signs the certificate of the Core. With ca_cert and no secure, the client raises ValueError. With no path, the client trusts the CA certificates of the computer.
open_timeoutTimeSpan = 5 s: How long to wait to open a connection.
read_timeoutTimeSpan = 5 s: How long to wait for a response.
keep_aliveTimeSpan = 30 s: How often an async streamer checks its connection to the Core.
max_retriesint = 3: How many times to retry a request that fails to reach the Core.
clock_skew_thresholdTimeSpan = 1 s: The largest difference between the clocks of the computer and the Core before the client prints a warning.

hoststring: The hostname or IP address of the Core.
portnumber | string: The port of the Core.
usernamestring: The username to log in with.
passwordstring: The password to log in with.
secureboolean = false: Connect with TLS.
connectivityPollFrequencyTimeSpan = 30 s: How often the client checks that it can reach the Core.
clockSkewThresholdTimeSpan = 1 s: The largest difference between the clocks of the computer and the Core before the client prints a warning.
namestring: A name for the Core, which the client shows in its connection status messages.
retryobject: How the client retries a request that fails to reach the Core: baseInterval (1 s), maxInterval, maxRetries (5), scale (1), and jitter (0).
cacheboolean = true: Keep retrieved resources in memory and update them as they change on the Core.
onRetryfunction: Called each time the client retries a failed request. By default, the client logs a warning.
onInternalErrorfunction: Called with cache errors that have no caller to throw to. By default, the client logs the error.

When the client cannot connect, see Troubleshooting.

Quick start

Series and frames

Connect to a Core

Connect with arguments

Log in once with sy login

Connect with TLS

Close the client

Client options