11 make docs warnings left, but I'm out of time for tonight.

This commit is contained in:
Cory McWilliams 2024-03-06 20:57:38 -05:00
parent 7ce89123f7
commit 540059368c
2 changed files with 464 additions and 0 deletions

View File

@ -114,47 +114,213 @@ bool tf_ssb_db_blob_store(tf_ssb_t* ssb, const uint8_t* blob, size_t size, char*
** @return The message.
*/
JSValue tf_ssb_db_get_message_by_id(tf_ssb_t* ssb, const char* id, bool is_keys);
/**
** Get a message by its author and sequence number.
** @param ssb The SSB instance.
** @param author The author's identity.
** @param sequence The message sequence number.
** @param[out] out_message_id Populated with the message identifier.
** @param out_message_id_size The size of the out_message_id buffer.
** @param[out] out_timestamp Populated with the timestamp.
** @param[out] out_content Populated with the message content. Free with tf_free().
** @return True if the message was found and retrieved.
*/
bool tf_ssb_db_get_message_by_author_and_sequence(
tf_ssb_t* ssb, const char* author, int64_t sequence, char* out_message_id, size_t out_message_id_size, double* out_timestamp, char** out_content);
/**
** Get information about the last message from an author.
** @param ssb The SSB instance.
** @param author The author's identity.
** @param[out] out_sequence Populated with the message sequence number.
** @param[out] out_message_id Populated with the message identifier.
** @param out_message_id_size The size of the out_message_id buffer.
** @return True if the message was found and information was retrieved.
*/
bool tf_ssb_db_get_latest_message_by_author(tf_ssb_t* ssb, const char* author, int64_t* out_sequence, char* out_message_id, size_t out_message_id_size);
/**
** Call a function for each result row of an SQL query.
** @param ssb The SSB instance.
** @param query The SQL query.
** @param binds An array of values to bind to SQL parameters.
** @param callback A callback to call for each result row.
** @param user_data User data to pass to the callback.
** @return A promise resolved when the query completes or rejected if it fails.
*/
JSValue tf_ssb_db_visit_query(tf_ssb_t* ssb, const char* query, const JSValue binds, void (*callback)(JSValue row, void* user_data), void* user_data);
/**
** Sanity check the feed for the given author.
** @param db The SQLite database instance to use.
** @param author The identity of the author to check.
** @return True if the author's feed is fully valid.
*/
bool tf_ssb_db_check(sqlite3* db, const char* author);
/**
** Get the number of SSB identities a Tilde Friends user has.
** @param ssb The SSB instance.
** @param user The user's username.
** @return The number of identities found.
*/
int tf_ssb_db_identity_get_count_for_user(tf_ssb_t* ssb, const char* user);
/**
** Create a new identity for a user.
** @param ssb The SSB instance.
** @param user The user's username.
** @param[out] out_public_key A buffer populated with the new public key.
** @param[out] out_private_key A buffer populated with the new privatee key.
** @return True if the identity was created.
*/
bool tf_ssb_db_identity_create(tf_ssb_t* ssb, const char* user, uint8_t* out_public_key, uint8_t* out_private_key);
/**
** Delete an identity for a user from the database. This is an unrecoverable operation.
** @param ssb The SSB instance.
** @param user The user's username.
** @param public_key The identity to delete.
** @return True if the identity was deleted.
*/
bool tf_ssb_db_identity_delete(tf_ssb_t* ssb, const char* user, const char* public_key);
/**
** Add an identity for a user to the database.
** @param ssb The SSB instance.
** @param user The user's username.
** @param public_key The public key of the identity.
** @param private_key The private key of the identity.
*/
bool tf_ssb_db_identity_add(tf_ssb_t* ssb, const char* user, const char* public_key, const char* private_key);
/**
** Call a function for each identity owned by a user.
** @param ssb The SSB instance.
** @param user The user's username.
** @param callback The function to call for each identity.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_db_identity_visit(tf_ssb_t* ssb, const char* user, void (*callback)(const char* identity, void* user_data), void* user_data);
/**
** Call a function for all identities in the database.
** @param ssb The SSB instance.
** @param callback The callback to call for each identity.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_db_identity_visit_all(tf_ssb_t* ssb, void (*callback)(const char* identity, void* user_data), void* user_data);
/**
** Get the private key for an identity in the database.
** @param ssb The SSB instance.
** @param user The owning user's username.
** @param public_key The public key of the identity.
** @param[out] out_private_key A buffer to receive the private key of the identity.
** @param private_key_size The size of the out_private_key buffer.
** @return True if the private key was found and retrieved.
*/
bool tf_ssb_db_identity_get_private_key(tf_ssb_t* ssb, const char* user, const char* public_key, uint8_t* out_private_key, size_t private_key_size);
/**
** Format a message in the standard format for SSB signing.
** @param context A JS context.
** @param previous The previous message identifier.
** @param author The author's public key.
** @param sequence The message sequence number.
** @param timestamp The message timestamp.
** @param hash The hash type (probably "sha256").
** @param content The message content.
** @param signature The signature of the message.
** @param sequence_before_author The order of the message fields (prefer false).
*/
JSValue tf_ssb_format_message(JSContext* context, const char* previous, const char* author, int64_t sequence, double timestamp, const char* hash, const char* content,
const char* signature, bool sequence_before_author);
/** Information about a single followed account. */
typedef struct _tf_ssb_following_t
{
/** The number of known users the account is following. */
int following_count;
/** The number of known users the account is blocking. */
int blocking_count;
/** The number of known users following the account. */
int followed_by_count;
/** The number of known users blocking the account. */
int blocked_by_count;
/** The account's identity. */
char id[k_id_base64_len];
} tf_ssb_following_t;
/**
** Get all the identities visible from a set of identities given known follows and blocks.
** @param ssb The SSB instance.
** @param ids An array of identities.
** @param count The number of identities.
** @param depth The following depth to use (prefer 2).
** @return An array of identities. Free with tf_free().
*/
const char** tf_ssb_db_following_deep_ids(tf_ssb_t* ssb, const char** ids, int count, int depth);
/**
** Return information about identities visible from a set of identities given known follows and blocks.
** @param ssb The SSB instance.
** @param ids An array of identities.
** @param count The number of identities.
** @param depth The following depth to use (prefer 2).
** @return An array of information about visible accounts. Fere with tf_free().
*/
tf_ssb_following_t* tf_ssb_db_following_deep(tf_ssb_t* ssb, const char** ids, int count, int depth);
/**
** Get all visible identities from all local accounts.
** @param ssb The SSB instance.
** @param depth The following depth to consider (prefer 2).
** @return The visible identities. Free with tf_free().
*/
const char** tf_ssb_db_get_all_visible_identities(tf_ssb_t* ssb, int depth);
/**
** Information about a stored SHS connection.
*/
typedef struct _tf_ssb_db_stored_connection_t
{
/** The connection's address. */
char address[256];
/** The network port number of the connection. */
int port;
/** The identity. */
char pubkey[k_id_base64_len];
} tf_ssb_db_stored_connection_t;
/**
** Get the list of stored connections from the SSB connection tracker.
** @param ssb The SSB instance.
** @param[out] out_count Populated with the number of returned connections.
** @return Information about all the stored connections.
*/
tf_ssb_db_stored_connection_t* tf_ssb_db_get_stored_connections(tf_ssb_t* ssb, int* out_count);
/**
** Remove a stored connection.
** @param ssb The SSB instance.
** @param address The connection address.
** @param port The connection network port number.
** @param pubkey The identity of the connection.
*/
void tf_ssb_db_forget_stored_connection(tf_ssb_t* ssb, const char* address, int port, const char* pubkey);
/**
** An SQLite authorizer callback. See https://www.sqlite.org/c3ref/set_authorizer.html for use.
** @param user_data User data registered with the authorizer.
** @param action_code The type of action.
** @param arg0 Depends on the action.
** @param arg1 Depends on the action.
** @param arg2 Depends on the action.
** @param arg3 Depends on the action.
** @return A value indicating whether the operation is allowed.
*/
int tf_ssb_sqlite_authorizer(void* user_data, int action_code, const char* arg0, const char* arg1, const char* arg2, const char* arg3);
/** @} */

298
src/ssb.h
View File

@ -514,37 +514,221 @@ void tf_ssb_add_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_c
*/
void tf_ssb_remove_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_changed_callback_t* callback, void* user_data);
/**
** A callback called when a new broadcast is received or one expires.
** @param ssb The SSB instance.
** @param user_data The user data.
*/
typedef void(tf_ssb_broadcasts_changed_callback_t)(tf_ssb_t* ssb, void* user_data);
/**
** Register a callback when broadcasts change.
** @param ssb The SSB instance.
** @param callback The callback function.
** @param cleanup A function to call when the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_add_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Remove a callback registered for when broadcasts changed.
** @param ssb The SSB instance.
** @param callback The callback function.
** @param user_data The user data registered with the callback.
*/
void tf_ssb_remove_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, void* user_data);
/**
** A callback called when a message is added to the database.
** @param ssb The SSB instance.
** @param id The message identifier.
** @param user_data The user data.
*/
typedef void(tf_ssb_message_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data);
/**
** Register a callback called when a message is added to the database.
** @param ssb The SSB instance.
** @param callback The callback function.
** @param cleanup A function to call when the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_add_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Remove a callback registered for when a message is added to the database.
** @param ssb The SSB instance.
** @param callback The callback function.
** @param user_data User data registered with the callback.
*/
void tf_ssb_remove_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, void* user_data);
/**
** Call all callbacks registered for when a message is added to the database.
** @param ssb The SSB instance.
** @param id The message identity added.
** @param message_with_keys The message added in the format required if keys are requested.
*/
void tf_ssb_notify_message_added(tf_ssb_t* ssb, const char* id, JSValue message_with_keys);
/**
** Record that a new blob was stored.
** @param ssb The SSB instance.
** @param id The identity of the newly stored blob.
*/
void tf_ssb_notify_blob_stored(tf_ssb_t* ssb, const char* id);
/**
** A callback called when a blob is newly requested.
** @param ssb The SSB instance.
** @param id The blob identity.
** @param user_data The user data.
*/
typedef void(tf_ssb_blob_want_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data);
/**
** Register a function to be called when a blob is newly requested.
** @param ssb The SSB instance.
** @param callback The callback.
** @param cleanup A function to call when the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_add_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Remove a callback registered for when a blob is newly requested.
** @param ssb The SSB instance.
** @param callback The callback to remove.
** @param user_data The user data registered with the callback.
*/
void tf_ssb_remove_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, void* user_data);
/**
** Call all callbacks registered for when a blob is newly requested.
** @param ssb The SSB instance.
** @param id The requested blob identity.
*/
void tf_ssb_notify_blob_want_added(tf_ssb_t* ssb, const char* id);
/**
** A function called when a MUXRPC request is made.
** @param connection The SSB connection.
** @param flags The RPC flags.
** @param request_number The request number.
** @param args Request arguments.
** @param message The raw message data.
** @param size The size of the raw message data.
** @param user_data User data registered with the callback.
*/
typedef void(tf_ssb_rpc_callback_t)(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue args, const uint8_t* message, size_t size, void* user_data);
/**
** Register a MUXRPC callback by name.
** @param ssb The SSB instance.
** @param name The NULL-terminated name.
** @param callback The callback.
** @param cleanup A function to be called when the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_add_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Remove a MUXRPC callback.
** @param ssb The SSB instance.
** @param name The NULL-terminated name.
** @param callback The callback to remove.
** @param user_data The user data registered with the callback.
*/
void tf_ssb_remove_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, void* user_data);
/**
** Send a MUXRPC message.
** @param connection The connection on which to send the message.
** @param flags The message flags.
** @param request_number The request number.
** @param message The message payload.
** @param size The size of the message.
** @param callback A callback to call if a response is received.
** @param cleanup A callback to call if the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_connection_rpc_send(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const uint8_t* message, size_t size, tf_ssb_rpc_callback_t* callback,
tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Send a JSON MUXRPC message.
** @param connection The connection on which to send the message.
** @param flags The message flags.
** @param request_number The request number.
** @param message The JS message payload.
** @param callback A callback to call if a response is received.
** @param cleanup A callback to call if the callback is removed.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_connection_rpc_send_json(
tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue message, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
/**
** Send a MUXRPC error message.
** @param connection The connection on which to send the message.
** @param flags The message flags.
** @param request_number The request number.
** @param error The error string.
*/
void tf_ssb_connection_rpc_send_error(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* error);
/**
** Send a MUXRPC "method not allowed" error message.
** @param connection The connection on which to send the message.
** @param flags The message flags.
** @param request_number The request number.
** @param name The name of the not-allowed method.
*/
void tf_ssb_connection_rpc_send_error_method_not_allowed(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* name);
/**
** Register a callback to be called when a message is received for the given
** request number.
** @param connection The connection on which to register the callback.
** @param request_number The request number.
** @param callback The callback.
** @param cleanup The function to call when the callback is removed.
** @param user_data User data to pass to the callback.
** @param dependent_connection A connection, which, if removed, invalidates this request.
*/
void tf_ssb_connection_add_request(tf_ssb_connection_t* connection, int32_t request_number, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data,
tf_ssb_connection_t* dependent_connection);
/**
** Remove a callback registered to be called when a message is received for the
** given request number.
** @param connection The connection.
** @param request_number The request number.
*/
void tf_ssb_connection_remove_request(tf_ssb_connection_t* connection, int32_t request_number);
/**
** A function scheduled to be run later.
** @param connection The owning connection.
** @param user_data User data registered with the callback.
*/
typedef void(tf_ssb_scheduled_callback_t)(tf_ssb_connection_t* connection, void* user_data);
/**
** Schedule work to be run when the server is next idle.
** @param connection The owning connection.
** @param callback The callback to call.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_connection_schedule_idle(tf_ssb_connection_t* connection, tf_ssb_scheduled_callback_t* callback, void* user_data);
/**
** Schedule work to run on a worker thread.
** @param connection The owning connection.
** @param work_callback The callback to run on a thread.
** @param after_work_callback The callback to run on the main thread when the work is complete.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_connection_run_work(tf_ssb_connection_t* connection, void (*work_callback)(tf_ssb_connection_t* connection, void* user_data),
void (*after_work_callback)(tf_ssb_connection_t* connection, int result, void* user_data), void* user_data);
@ -562,36 +746,150 @@ tf_ssb_connection_t* tf_ssb_connection_tunnel_create(tf_ssb_t* ssb, const char*
int32_t tf_ssb_connection_get_ebt_request_number(tf_ssb_connection_t* connection);
void tf_ssb_connection_set_ebt_request_number(tf_ssb_connection_t* connection, int32_t request_number);
/**
** Get the EBT clock for a connection.
** @param connection An SHS connection.
** @return The EBT clock.
*/
JSValue tf_ssb_connection_get_ebt_send_clock(tf_ssb_connection_t* connection);
/**
** Set the EBT clock for a connection.
** @param connection An SHS connection.
** @param send_clock The clock state.
*/
void tf_ssb_connection_set_ebt_send_clock(tf_ssb_connection_t* connection, JSValue send_clock);
/**
** Get whether the EBT clock has been sent for a connection.
** @param connection An SHS connection.
** @return True if the clock has been sent.
*/
bool tf_ssb_connection_get_sent_clock(tf_ssb_connection_t* connection);
/**
** Set the EBT clock sent state for a connection.
** @param connection An SHS connection.
** @param sent_clock Whether the clock has been sent.
*/
void tf_ssb_connection_set_sent_clock(tf_ssb_connection_t* connection, bool sent_clock);
/**
** Get the JS class ID of the SSB connection class.
** @return The class ID
*/
JSClassID tf_ssb_get_connection_class_id();
/**
** Get general statistics about an SSB instance.
** @param ssb The SSB instance.
** @param[out] out_stats Populated with performance statistics.
*/
void tf_ssb_get_stats(tf_ssb_t* ssb, tf_ssb_stats_t* out_stats);
/**
** Get information about requested blobs.
** @param connection An SHS connection.
** @return Blob wants information.
*/
tf_ssb_blob_wants_t* tf_ssb_connection_get_blob_wants_state(tf_ssb_connection_t* connection);
/**
** Get a report of information about recent disconnections.
** @param ssb The SSB instance.
** @param context A JS context.
** @return Information about disconnections.
*/
JSValue tf_ssb_get_disconnection_debug(tf_ssb_t* ssb, JSContext* context);
/**
** Record whether the calling thread is busy.
** @param ssb The SSB instance.
** @param busy True if the calling thread is now busy.
*/
void tf_ssb_record_thread_busy(tf_ssb_t* ssb, bool busy);
/**
** Get an estimate of utilization of all running threads.
** @param ssb The SSB instance.
** @return The utilization percent.
*/
float tf_ssb_get_average_thread_percent(tf_ssb_t* ssb);
/**
** Register a callback to be called when the main thread blocks for an
** unreasonable amount of time.
** @param ssb The SSB instance.
** @param callback The callback to call.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_set_hitch_callback(tf_ssb_t* ssb, void (*callback)(const char* name, uint64_t duration_ns, void* user_data), void* user_data);
/**
** Get the queue of messages in the progress of being stored.
** @param ssb The SSB instance.
** @return The queue.
*/
tf_ssb_store_queue_t* tf_ssb_get_store_queue(tf_ssb_t* ssb);
/**
** Increment the SSB instance's ref count. Prevents it from being destroyed
** until it reaches zero.
** @param ssb The SSB instance.
*/
void tf_ssb_ref(tf_ssb_t* ssb);
/**
** Decrement the SSB instance's ref count. May destroy the instance when the
** count returns to zero.
** @param ssb The SSB instance.
*/
void tf_ssb_unref(tf_ssb_t* ssb);
/**
** Record whether the calling thread is the main thread or not. Some
** operations are disallowed on the main thread for performance.
** @param ssb The SSB instance.
** @param main_thread Whether the calling thread is the main thread.
*/
void tf_ssb_set_main_thread(tf_ssb_t* ssb, bool main_thread);
/**
** Get whether the running server is operating a room.
** @param ssb The SSB instance.
** @return True if the server is a room.
*/
bool tf_ssb_is_room(tf_ssb_t* ssb);
/**
** Set whether the running server is operating a room.
** @param ssb The SSB instance.
** @param is_room Whether to run a room.
*/
void tf_ssb_set_is_room(tf_ssb_t* ssb, bool is_room);
/**
** Get the name of the room hosted by the running server.
** @param ssb The SSB instance.
** @return The room name or NULL.
*/
const char* tf_ssb_get_room_name(tf_ssb_t* ssb);
/**
** Set the name of the room hosted by the running server.
** @param ssb The SSB instance.
** @param room_name The name of the room.
*/
void tf_ssb_set_room_name(tf_ssb_t* ssb, const char* room_name);
/**
** Schedule work to be run after a time delay.
** @param ssb The SSB instance.
** @param delay_ms The duration to wait in milliseconds.
** @param callback The callback to call to run the work.
** @param user_data User data to pass to the callback.
*/
void tf_ssb_schedule_work(tf_ssb_t* ssb, int delay_ms, void (*callback)(tf_ssb_t* ssb, void* user_data), void* user_data);
/** @} */