Developer SDK

C examples

Install the SDK · View source on GitHub ↗

embed/embed.h

c
/* Declarations shared by the files of the C embed example
 * (EMBED_CONTRACT.md): main.c runs the commands, session.c runs the embedded
 * device, status.c holds the status rules and reads the cap object, state.c
 * keeps the installation state, fetch.c obtains the client JWT and reads the
 * caps over a replaceable HTTP function, http_curl.c is that function on
 * libcurl, json.c reads json, and selftest.c checks the rules. Only main.c and
 * session.c call the sdk and only http_curl.c calls libcurl, so
 * `make self-test` builds the other files into a self-test that loads neither
 * library; urnetwork_sdk.h is included here for its constants. */
#ifndef UR_EMBED_H
#define UR_EMBED_H

/* POSIX 2008 with its XSI part (mkstemp), and on macOS the full system
 * headers (O_NOFOLLOW, mkdtemp). Every file includes this header first, before
 * any system header. */
#ifndef _WIN32
#define _XOPEN_SOURCE 700
#define _DARWIN_C_SOURCE
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

#ifdef _WIN32
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#else
#include <pthread.h>
#endif

#include <urnetwork_sdk.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ----- commands and exit codes (main.c) ----- */

enum {
  /* a requested stop: Ctrl-C, SIGTERM */
  UR_EMBED_EXIT_STOPPED = 0,
  /* any other failure */
  UR_EMBED_EXIT_FAILURE = 1,
  /* a configuration or credential problem that a restart does not fix
   * (sysexits EX_CONFIG) */
  UR_EMBED_EXIT_CONFIG = 78,
  /* an unknown command line is a configuration problem */
  UR_EMBED_EXIT_USAGE = UR_EMBED_EXIT_CONFIG,
};

#define UR_EMBED_USAGE "usage: embed [run] | --self-test | --licenses | --version"

/* The forms of the command line. */
typedef enum {
  UR_EMBED_COMMAND_RUN,
  UR_EMBED_COMMAND_SELF_TEST,
  UR_EMBED_COMMAND_LICENSES,
  UR_EMBED_COMMAND_VERSION,
  /* anything else: print the usage and exit with UR_EMBED_EXIT_USAGE */
  UR_EMBED_COMMAND_USAGE,
} ur_embed_command;

/* The command that the arguments name: no argument or `run` runs the app. */
static inline ur_embed_command ur_embed_parse_command(int argc, char **argv) {
  if (argc <= 1 || (argc == 2 && !strcmp(argv[1], "run")))
    return UR_EMBED_COMMAND_RUN;
  if (argc == 2 && !strcmp(argv[1], "--self-test"))
    return UR_EMBED_COMMAND_SELF_TEST;
  if (argc == 2 && !strcmp(argv[1], "--licenses"))
    return UR_EMBED_COMMAND_LICENSES;
  if (argc == 2 && !strcmp(argv[1], "--version"))
    return UR_EMBED_COMMAND_VERSION;
  return UR_EMBED_COMMAND_USAGE;
}

/* ----- small shared helpers ----- */

/* A mutex that guards state shared with sdk callbacks and the cap reader. */
#ifdef _WIN32
typedef SRWLOCK ur_mutex;
#define UR_MUTEX_INITIALIZER SRWLOCK_INIT
/* Takes the mutex. */
static inline void ur_mutex_lock(ur_mutex *mutex) {
  AcquireSRWLockExclusive(mutex);
}
/* Releases the mutex. */
static inline void ur_mutex_unlock(ur_mutex *mutex) {
  ReleaseSRWLockExclusive(mutex);
}
#else
typedef pthread_mutex_t ur_mutex;
#define UR_MUTEX_INITIALIZER PTHREAD_MUTEX_INITIALIZER
/* Takes the mutex. */
static inline void ur_mutex_lock(ur_mutex *mutex) {
  pthread_mutex_lock(mutex);
}
/* Releases the mutex. */
static inline void ur_mutex_unlock(ur_mutex *mutex) {
  pthread_mutex_unlock(mutex);
}
#endif

/* Owned bytes; data is NULL when length is 0. */
typedef struct {
  uint8_t *data;
  size_t length;
} ur_bytes;

/* Frees the bytes and empties them. */
static inline void ur_bytes_free(ur_bytes *bytes) {
  free(bytes->data);
  bytes->data = NULL;
  bytes->length = 0;
}

/* An owned copy of a string, NULL for NULL or when out of memory. */
static inline char *ur_embed_copy_string(const char *text) {
  if (!text)
    return NULL;
  size_t size = strlen(text) + 1;
  char *copy = (char *)malloc(size);
  if (copy)
    memcpy(copy, text, size);
  return copy;
}

/* Room for an error message, a path, a url and a status line. */
#define UR_EMBED_ERROR_CAPACITY 512
#define UR_EMBED_PATH_CAPACITY 4096
#define UR_EMBED_URL_CAPACITY 1024
#define UR_EMBED_LINE_CAPACITY 512
/* a canonical uuid and its terminator */
#define UR_EMBED_ID_CAPACITY 37

/* ----- json values (json.c) ----- */

/* The kind of a json value; none is a missing member or a malformed
 * document. */
typedef enum {
  UR_JSON_NONE = 0,
  UR_JSON_NULL,
  UR_JSON_FALSE,
  UR_JSON_TRUE,
  UR_JSON_NUMBER,
  UR_JSON_STRING,
  UR_JSON_ARRAY,
  UR_JSON_OBJECT,
} ur_json_type;

/* One json value: a span of the document it was read from. */
typedef struct {
  ur_json_type type;
  const char *text;
  size_t length;
} ur_json_value;

ur_json_value ur_json_parse(const char *text, size_t length);
ur_json_value ur_json_member(ur_json_value object, const char *key);
bool ur_json_int64(ur_json_value value, int64_t *number);
char *ur_json_string(ur_json_value value);

/* ----- status (status.c) ----- */

/* The status field's texts (EMBED_CONTRACT.md, "Status"). GUI apps show the
 * first two; a console app never prints them. */
#define UR_EMBED_STATUS_SIGNED_OUT "signed out"
#define UR_EMBED_STATUS_STOPPED "stopped"
#define UR_EMBED_STATUS_CLIENT_LIMIT "client limit"
#define UR_EMBED_STATUS_PAUSED "paused"
#define UR_EMBED_STATUS_DATA_CAP_REACHED "data cap reached"
#define UR_EMBED_STATUS_CONNECTED "connected"
#define UR_EMBED_STATUS_CONNECTING "connecting"

/* The data fields' texts before and without a reading. */
#define UR_EMBED_DATA_CHECKING "checking"
#define UR_EMBED_DATA_UNAVAILABLE "unavailable"
#define UR_EMBED_DATA_NO_CAP "no cap"

/* The server refuses the cap read with this message while the team has not
 * enabled Embed for the network (EMBED_CONTRACT.md, "Embed enablement"). The
 * refusal clears the last reading, so both data fields read unavailable. */
#define UR_EMBED_NOT_ENABLED_MESSAGE "Embed isn't enabled for this network."

/* The capped_reason values of the cap object. */
#define UR_EMBED_CAPPED_REASON_MONTHLY "monthly"
#define UR_EMBED_CAPPED_REASON_TOTAL "total"

/* One cap object (EMBED_CONTRACT.md, "The cap object"), read. A null or absent
 * limit is no cap; an absent used count is 0. */
typedef struct {
  bool has_monthly_byte_limit;
  int64_t monthly_byte_limit;
  int64_t monthly_used_byte_count;
  /* RFC 3339, as the server wrote it; empty when absent */
  char monthly_period_end[64];
  bool has_total_byte_limit;
  int64_t total_byte_limit;
  int64_t total_used_byte_count;
  bool capped;
  /* monthly, total, empty, or another value cut to fit */
  char capped_reason[24];
} ur_embed_cap;

/* What the data fields show: no reading yet, the first reading failed (or the
 * Embed-not-enabled refusal cleared the reading), or the latest reading. A
 * failure after a reading keeps that reading. */
typedef enum {
  UR_EMBED_CAPS_CHECKING,
  UR_EMBED_CAPS_UNAVAILABLE,
  UR_EMBED_CAPS_READ,
} ur_embed_caps_state;

typedef struct {
  ur_embed_caps_state state;
  /* the latest reading, when state is UR_EMBED_CAPS_READ */
  ur_embed_cap cap;
} ur_embed_caps;

/* The inputs of the status rules. */
typedef struct {
  /* GUI apps: before start or after stop; a console app is always started */
  bool started;
  /* GUI apps: after an auth logout or a token server refusal */
  bool signed_out;
  /* URNET_CLIENT_LIMIT_STATUS_NONE or URNET_CLIENT_LIMIT_STATUS_EXCEEDED */
  const char *client_limit_status;
  /* the end of the client limit hold in unix milliseconds, 0 without one */
  int64_t client_limit_retry_time;
  const ur_embed_caps *caps;
  /* ProviderStateAdded of the window status, 0 before the window exists */
  int64_t providers_added;
} ur_embed_status_input;

void ur_embed_print_line(const char *line);
/* "embed client <client_id>, installation <instance_id>", printed at start. */
void ur_embed_start_line(const char *client_id, const char *instance_id,
                         char *line, size_t capacity);
/* The GetLicenses app kind that --licenses prints: "apple" on Apple platforms,
 * "windows" on Windows, "linux" elsewhere. */
const char *ur_embed_license_app(void);
void ur_embed_format_byte_count(int64_t byte_count, char *text,
                                size_t capacity);
bool ur_embed_reset_text(const char *period_end, char *text, size_t capacity);
void ur_embed_client_limit_text(int64_t retry_time, char *text,
                                size_t capacity);
bool ur_embed_parse_cap(const char *json, size_t length, ur_embed_cap *cap);
bool ur_embed_parse_cap_value(ur_json_value value, ur_embed_cap *cap);
bool ur_embed_cap_not_enabled(const char *json, size_t length);
void ur_embed_caps_init(ur_embed_caps *caps);
void ur_embed_caps_apply(ur_embed_caps *caps, const ur_embed_cap *reading);
void ur_embed_caps_clear(ur_embed_caps *caps);
void ur_embed_data_field(const ur_embed_caps *caps, bool monthly, char *text,
                         size_t capacity);
void ur_embed_status_text(const ur_embed_status_input *input, char *text,
                          size_t capacity);
void ur_embed_status_line(const ur_embed_status_input *input, char *line,
                          size_t capacity);
int64_t ur_embed_providers_added(const char *window_status_json);
void ur_embed_read_client_limit_status(const char *client_limit_status_json,
                                       char *status, size_t capacity,
                                       int64_t *retry_time);

/* ----- installation state (state.c) ----- */

#define UR_EMBED_CLIENT_JWT_FILE_NAME "client.jwt"
#define UR_EMBED_INSTANCE_ID_FILE_NAME "instance-id"
/* the largest state file the app reads */
#define UR_EMBED_STATE_FILE_BYTE_LIMIT (64 * 1024)

/* The outcome of reading a state file. */
typedef enum {
  UR_EMBED_READ_OK,
  UR_EMBED_READ_MISSING,
  UR_EMBED_READ_FAILED,
} ur_embed_read_result;

char *ur_embed_environment(const char *name);
bool ur_embed_path_join(char *path, size_t capacity, const char *dir,
                        const char *name);
bool ur_embed_check_state_dir(const char *state_dir, char *error,
                              size_t capacity);
ur_embed_read_result ur_embed_read_private_file(const char *path,
                                                ur_bytes *data, char *error,
                                                size_t capacity);
bool ur_embed_write_private_file(const char *path, const void *data,
                                 size_t length, char *error, size_t capacity);
bool ur_embed_make_private_dir(const char *path, char *error,
                               size_t capacity);
bool ur_embed_make_temp_dir(char *path, size_t capacity);
bool ur_embed_remove_path(const char *path, bool dir);
bool ur_embed_random_bytes(uint8_t *data, size_t length);
bool ur_embed_base64_decode(const char *text, size_t length, bool url,
                            ur_bytes *data);
bool ur_embed_parse_uuid(const char *text, size_t length,
                         char uuid[UR_EMBED_ID_CAPACITY]);
bool ur_embed_new_uuid(char uuid[UR_EMBED_ID_CAPACITY]);
bool ur_embed_parse_client_jwt_client_id(const char *client_jwt,
                                         char client_id[UR_EMBED_ID_CAPACITY],
                                         char *error, size_t capacity);
bool ur_embed_load_or_create_instance_id(const char *state_dir,
                                         char instance_id[UR_EMBED_ID_CAPACITY],
                                         char *error, size_t capacity);
ur_embed_read_result ur_embed_load_client_jwt(
    const char *state_dir, char **client_jwt,
    char client_id[UR_EMBED_ID_CAPACITY], char *error, size_t capacity);
bool ur_embed_save_client_jwt(const char *state_dir, const char *client_jwt,
                              char *error, size_t capacity);

/* ----- http, the token fetch and the cap read (fetch.c, http_curl.c) ----- */

/* One HTTP request. authorization is the bearer token, sent as
 * "Authorization: Bearer <token>"; body, when set, is sent as
 * application/json. */
typedef struct {
  const char *method;
  const char *url;
  const char *authorization;
  const char *body;
} ur_embed_http_request;

/* One HTTP answer: its status and owned body. */
typedef struct {
  long status;
  char *body;
  size_t body_length;
} ur_embed_http_response;

/* Sends one request. False with the reason in error when no answer arrived:
 * the server is unreachable, the answer is too large, or a timeout. */
typedef bool (*ur_embed_http_fn)(void *context,
                                 const ur_embed_http_request *request,
                                 ur_embed_http_response *response, char *error,
                                 size_t capacity);

void ur_embed_http_response_free(ur_embed_http_response *response);
bool ur_embed_curl_http(void *context, const ur_embed_http_request *request,
                        ur_embed_http_response *response, char *error,
                        size_t capacity);

#define UR_EMBED_DEFAULT_API_URL "https://api.bringyour.com"
#define UR_EMBED_CLIENT_TOKEN_PATH "/urnetwork/client-token"
#define UR_EMBED_CLIENT_DATA_CAP_PATH "/network/client-data-cap"

bool ur_embed_origin_url(const char *origin, const char *path, char *url,
                         size_t capacity);

/* The outcome of a token fetch, with its exit code and GUI state
 * (EMBED_CONTRACT.md, "Obtaining the client JWT"). */
typedef enum {
  UR_EMBED_FETCH_OK,
  /* 401 unauthorized, 409 installation_limit or client_limit: exit 78, GUI
   * signed out */
  UR_EMBED_FETCH_REFUSED,
  /* unreachable, 5xx, or an invalid answer: exit 1, GUI stopped */
  UR_EMBED_FETCH_FAILED,
} ur_embed_fetch_result;

/* The token server's answer, checked. */
typedef struct {
  char client_id[UR_EMBED_ID_CAPACITY];
  /* owned; never print it */
  char *client_jwt;
  bool has_data_cap;
  ur_embed_cap data_cap;
} ur_embed_token;

ur_embed_fetch_result ur_embed_fetch_client_jwt(
    ur_embed_http_fn http, void *http_context, const char *token_server_url,
    const char *demo_session, const char *state_dir, const char *instance_id,
    ur_embed_token *token, char *error, size_t capacity);
void ur_embed_token_free(ur_embed_token *token);
/* The outcome of a cap read. */
typedef enum {
  UR_EMBED_CAP_READ_OK,
  UR_EMBED_CAP_READ_FAILED,
  /* the Embed-not-enabled refusal, which clears the last reading */
  UR_EMBED_CAP_READ_NOT_ENABLED,
} ur_embed_cap_read_result;

ur_embed_cap_read_result ur_embed_read_caps(ur_embed_http_fn http,
                                            void *http_context,
                                            const char *api_url,
                                            const char *client_jwt,
                                            ur_embed_cap *cap, char *error,
                                            size_t capacity);
void ur_embed_caps_record(ur_embed_caps *caps, ur_embed_cap_read_result result,
                          const ur_embed_cap *reading);

/* ----- configuration (fetch.c) ----- */

/* The settings of a run, as the environment gives them; NULL when unset. */
typedef struct {
  const char *state_dir;
  const char *token_server_url;
  const char *demo_session;
  const char *api_url;
} ur_embed_settings;

/* The configuration of a run, loaded at start. */
typedef struct {
  char state_dir[UR_EMBED_PATH_CAPACITY];
  /* owned; the run loop replaces it when the sdk refreshes the token */
  char *client_jwt;
  char client_id[UR_EMBED_ID_CAPACITY];
  char instance_id[UR_EMBED_ID_CAPACITY];
  /* the cap read's origin, checked */
  char api_url[UR_EMBED_URL_CAPACITY];
  /* the token server's data_cap, the first cap reading */
  bool has_first_cap;
  ur_embed_cap first_cap;
} ur_embed_config;

int ur_embed_load_config(const ur_embed_settings *settings,
                         ur_embed_http_fn http, void *http_context,
                         ur_embed_config *config, char *error,
                         size_t capacity);
void ur_embed_config_free(ur_embed_config *config);

/* ----- the running app (session.c) ----- */

/* One run: the network space manager, the local device and its
 * subscriptions. */
typedef struct {
  ur_embed_config *config;
  uint64_t manager;
  uint64_t space;
  uint64_t api;
  uint64_t device;
  uint64_t subs[3];
  ur_embed_caps caps;
} ur_embed_session;

void ur_embed_request_stop(void);
bool ur_embed_session_open(ur_embed_session *session, ur_embed_config *config,
                           char *error, size_t capacity);
int ur_embed_session_run(ur_embed_session *session);
void ur_embed_session_close(ur_embed_session *session);

/* ----- self-test (selftest.c) ----- */

bool ur_embed_self_test(char *failure, size_t capacity);
int ur_embed_self_test_main(void);

#ifdef __cplusplus
}
#endif

#endif