nsinnovations/fusionpbx
2
0
Fork 0
mirror of https://github.com/fusionpbx/fusionpbx.git synced 2026-01-06 11:43:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation, format class, no modification. (#7628)

Browse Source
This commit is contained in:
frytimo
2025-11-18 21:49:39 -04:00
committed by GitHub
parent adfc4cc469
commit bbe7b9e9b7
37 changed files with 5051 additions and 4144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
core/websockets/resources/classes/base_message.php
View File

@@ -29,19 +29,22 @@
/**
* A base message for communication
*
* @param string $payload ;
*
* @author Tim Fry <tim@fusionpbx.com>
* @param string $payload;
*/
class base_message {
/**
* The id is contained to the base_message class. Subclasses or child classes should not adjust this value
*
* @var int
*/
private $id;
/**
* Payload can be any value
*
* @var mixed
*/
protected $payload;
@@ -51,6 +54,7 @@ class base_message {
* When the array is provided as an associative array, the object properties
* are filled using the array key as the property name and the value of the array
* for the value of the property in the object.
*
* @param array $associative_properties_array
*/
public function __construct($associative_properties_array = []) {
@@ -69,7 +73,9 @@ class base_message {
* If the method exists then the method will be called to get the value in the object property.
* If the method is not in the object then the property name is checked to see if it is valid. If the
* name is not available then an exception is thrown.
*
* @param string $name Name of the property
*
* @return mixed
* @throws InvalidProperty
*/
@@ -90,13 +96,15 @@ class base_message {
/**
* Sets the object property in the given name to be the given value
* @param string $name Name of the object property
* @param mixed $value Value of the object property
*
* @param string $name Name of the object property
* @param mixed $value Value of the object property
*
* @return void
* @throws \InvalidArgumentException
*/
public function __set(string $name, $value): void {
if (method_exists($this, "set_$name")){
if (method_exists($this, "set_$name")) {
//
// By calling the method with the setter name of the property first, we give
// the child object the opportunity to modify the value before it is
@@ -124,6 +132,7 @@ class base_message {
/**
* Provides a method that PHP will call if the object is echoed or printed.
*
* @return string JSON string representing the object
* @depends to_json
*/
@@ -133,6 +142,7 @@ class base_message {
/**
* Returns this object ID given by PHP
*
* @return int
*/
public function get_id(): int {
@@ -141,7 +151,9 @@ class base_message {
/**
* Sets the message payload to be delivered
*
* @param mixed $payload Payload for the message to carry
*
* @return $this Returns this object for chaining
*/
public function set_payload($payload) {
@@ -151,6 +163,7 @@ class base_message {
/**
* Returns the payload contained in this message
*
* @return mixed Payload in the message
*/
public function get_payload() {
@@ -164,8 +177,11 @@ class base_message {
* the method is called with no parameters given, the payload is
* returned to the caller.
* Payload the message object is delivering
*
* @param mixed $payload If set, payload is set to the value. Otherwise, the payload is returned.
* @return mixed If payload was given to call the method, this object is returned. If no value was provided the payload is returned.
*
* @return mixed If payload was given to call the method, this object is returned. If no value was provided the
* payload is returned.
* @see set_payload
* @see get_payload
*/
@@ -178,7 +194,9 @@ class base_message {
/**
* Recursively convert this object or child object to an array.
*
* @param mixed $iterate Private value to be set while iterating over the object properties
*
* @return array Array representing the properties of this object
*/
public function to_array($iterate = null): array {
@@ -191,7 +209,7 @@ class base_message {
$value = $this->to_array($value);
} elseif (is_object($value) && method_exists($value, 'to_array')) {
$value = $value->to_array();
} elseif (is_object($value) && method_exists($value, '__toArray')) { // PHP array casting
} elseif (is_object($value) && method_exists($value, '__toArray')) { // PHP array casting
$value = $value->__toArray();
}
$array[$property] = $value;
@@ -201,6 +219,7 @@ class base_message {
/**
* Returns a json string
*
* @return string
* @depends to_array
*/
@@ -210,6 +229,7 @@ class base_message {
/**
* Returns an array representing this object or child object.
*
* @return array Array of object properties
*/
public function __toArray(): array {

64
core/websockets/resources/classes/base_websocket_system_service.php
View File

@@ -1,7 +1,7 @@
<?php
/**
* Description of base_websocket_system_service
* Description of base_websocket_system_service
*
* @author Tim Fry <tim@fusionpbx.com>
*/
@@ -12,12 +12,14 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Sets a time to fire the on_timer function
*
* @var int|null
*/
protected $timer_expire_time = null;
/**
* Websocket client
*
* @var websocket_client $ws_client
*/
protected $ws_client;
@@ -26,6 +28,7 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Array of topics and their callbacks
*
* @var array
*/
protected $topics;
@@ -35,24 +38,37 @@ abstract class base_websocket_system_service extends service implements websocke
* Listener is an array of socket and callback used to listen for events on the socket. When a listener is added,
* the socket is added to the array of listeners. When the socket is closed, the listener is removed from the
* array of listeners. When an event is received on the respective socket, the provided callback is called.
*
* @var array
*/
protected $listeners;
/**
* Outputs the version of the Service.
*
* @return void
*/
protected static function display_version(): void {
echo "System Dashboard Service 1.0\n";
}
/**
* Set a timer to trigger the defined function every $seconds. To stop the timer, set the value to null
*
* @param int $seconds
*
* @return void
* @see on_timer
*/
protected function set_timer(int $seconds, callable $callable): void {
$this->timers[] = ['expire_time' => time() + $seconds, 'callable' => $callable];
}
}
/**
* Append command options to set the websockets port and host address
*
* @return void
*/
protected static function set_command_options() {
parent::append_command_option(
command_option::new()
@@ -74,10 +90,20 @@ abstract class base_websocket_system_service extends service implements websocke
);
}
/**
* Sets the port for the WebSocket connection.
*
* @param int $port The new port number to use for the WebSocket connection
*/
protected static function set_websockets_port($port): void {
self::$websocket_port = $port;
}
/**
* Set the host address for websockets connections.
*
* @param string $host The host address to use for websockets connections
*/
protected static function set_websockets_host_address($host): void {
self::$websocket_host = $host;
}
@@ -85,14 +111,20 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Add a socket listener
*
* @param $socket
* @param $socket
* @param callable $callback
*
* @return void
*/
protected function add_listener($socket, callable $callback): void {
$this->listeners[] = [$socket, $callback];
}
/**
* Main execution loop for handling WebSocket events and timers.
*
* @return int Exit code, indicating whether the process exited normally (0) or with an error (1).
*/
public function run(): int {
// set the timers property as an array
$this->timers = [];
@@ -175,7 +207,7 @@ abstract class base_websocket_system_service extends service implements websocke
// Timers can be set by child classes
if (!empty($this->timers)) {
// Check all timers
foreach($this->timers as $key => $array) {
foreach ($this->timers as $key => $array) {
// Check if the timer should be run
if (time() >= $array['expire_time']) {
// Get the callback function
@@ -197,6 +229,7 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Connects to the web socket server using a websocket_client object
*
* @return bool True if connected and False if not able to connect
*/
protected function connect_to_ws_server(): bool {
@@ -227,7 +260,7 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Handles the message from the web socket client and triggers the appropriate requested topic event
* @param resource $ws_client
*
* @return void
*/
private function handle_websocket_event() {
@@ -257,7 +290,8 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Call each of the registered events for the websocket topic that has arrived
* @param string $topic
*
* @param string $topic
* @param websocket_message $websocket_message
*/
private function trigger_topic(string $topic, websocket_message $websocket_message) {
@@ -272,6 +306,11 @@ abstract class base_websocket_system_service extends service implements websocke
}
}
/**
* Authenticate with the websocket server using a service token
*
* @param websocket_message $websocket_message The incoming websocket message that triggered this event
*/
protected function on_authenticate(websocket_message $websocket_message) {
$this->info("Authenticating with websocket server");
// Create a service token
@@ -283,7 +322,8 @@ abstract class base_websocket_system_service extends service implements websocke
/**
* Allows the service to register a callback so when the topic arrives the callable is called
* @param string $topic
*
* @param string $topic
* @param callable $callable
*/
protected function on_topic($topic, $callable) {
@@ -293,9 +333,19 @@ abstract class base_websocket_system_service extends service implements websocke
$this->topics[$topic][] = $callable;
}
/**
* Send a websocket message to the client
*
* @param websocket_message $websocket_message The message to be sent
*/
protected function respond(websocket_message $websocket_message): void {
websocket_client::send($this->ws_client->socket(), $websocket_message);
}
/**
* Register topics and associated callbacks.
*
* @return void
*/
abstract protected function register_topics(): void;
}

21
core/websockets/resources/classes/permission_filter.php
View File

@@ -36,11 +36,25 @@ class permission_filter implements filter {
private $field_map;
private $permissions;
/**
* Initializes a new instance of this class with a map of event field keys to permissions and an optional list of
* additional permissions.
*
* @param array $event_field_key_to_permission_map Map of event field keys to permissions
* @param array $permissions Optional list of additional permissions (default: [])
*/
public function __construct(array $event_field_key_to_permission_map, array $permissions = []) {
$this->field_map = $event_field_key_to_permission_map;
$this->add_permissions($permissions);
}
/**
* Invokes the object to check if a value can be set for a given field.
*
* @param string $key The key of the field to check
*
* @return bool|null True if the value can be set, null otherwise
*/
public function __invoke(string $key, $value): ?bool {
$permission = $this->field_map[$key] ?? null;
if ($permission === null || $this->has_permission($permission)) {
@@ -50,7 +64,9 @@ class permission_filter implements filter {
}
/**
* Adds an associative array of permissions where $key is the name of the permission and $value is ignored as it should always be set to true.
* Adds an associative array of permissions where $key is the name of the permission and $value is ignored as it
* should always be set to true.
*
* @param array $permissions
*/
public function add_permissions(array $permissions) {
@@ -62,6 +78,7 @@ class permission_filter implements filter {
/**
* Adds a single permission
*
* @param string $key
*/
public function add_permission(string $key) {
@@ -70,7 +87,9 @@ class permission_filter implements filter {
/**
* Checks if the filter has a permission
*
* @param string $key
*
* @return bool
*/
public function has_permission(string $key): bool {

11
core/websockets/resources/classes/socket_exception.php
View File

@@ -33,6 +33,17 @@
*/
class socket_exception extends \Exception {
public $id;
/**
* Initializes a new instance of the object.
*
* @param mixed $id Unique identifier for this exception (default: null)
* @param string $message Exception message (default: "")
* @param int $code Exception code (default: 0)
* @param \Throwable|null $previous The previous exception (default: null)
*
* @return void
*/
public function __construct($id = null, string $message = "", int $code = 0, ?\Throwable $previous = null) {
$this->id = $id;
return parent::__construct($message, $code, $previous);

193
core/websockets/resources/classes/subscriber.php
View File

@@ -30,12 +30,14 @@ declare(strict_types=1);
/**
* Description of subscriber
*
* @author Tim Fry <tim@fusionpbx.com>
*/
class subscriber {
/**
* The ID of the object given by PHP
*
* @var spl_object_id
*/
private $id;
@@ -51,128 +53,151 @@ class subscriber {
* The resource is cast to an integer and then saved in order to match the
* a resource to the original socket. This is primarily used in the equals
* method to test for equality.
*
* @var int
*/
private $socket_id;
/**
* Remote IP of the socket resource connection
*
* @var string
*/
private $remote_ip;
/**
* Remote port of the socket resource connection
*
* @var int
*/
private $remote_port;
/**
* Services the subscriber has subscribed to
*
* @var array
*/
private $services;
/**
* Permissions array of the subscriber
*
* @var array
*/
private $permissions;
/**
* Domain name the subscriber belongs to
*
* @var string|null
*/
private $domain_name;
/**
* Domain UUID the subscriber belongs to
*
* @var string|null
*/
private $domain_uuid;
/**
* Token hash used to validate this subscriber
*
* @var string|null
*/
private $token_hash;
/**
* Token name used to validate this subscriber
*
* @var string|null
*/
private $token_name;
/**
* Epoch time the token was issued
*
* @var int
*/
private $token_time;
/**
* Time limit in seconds
*
* @var int
*/
private $token_limit;
/**
* Whether the subscriber has a time limit set for their token or not
*
* @var bool True when there is a time limit. False if no time limit set.
*/
private $enable_token_time_limit;
/**
* Whether the subscriber is able to broadcast messages as a service
*
* @var bool
*/
private $service;
/**
* The name of the service class object to handle callbacks
*
* @var string|null
*/
private $service_class;
/**
* If the subscriber is a service the service name used
*
* @var string|null
*/
private $service_name;
/**
* The filter used to send web socket messages
*
* @var filter
*/
private $filter;
/**
* Function or method name to call when sending information through the socket
*
* @var callable
*/
private $callback;
/**
* Subscriptions to services
*
* @var array
*/
private $subscriptions;
/**
* Whether or not this subscriber has been authenticated
*
* @var bool
*/
private $authenticated;
/**
* User information
*
* @var array
*/
private $user;
/**
* Creates a subscriber object.
* @param resource|stream $socket Connected socket
* @param callable $frame_wrapper The callback used to wrap communication in a web socket frame. Sending NULL to the frame wrapper should send a disconnect.
*
* @param resource|stream $socket Connected socket
* @param callable $frame_wrapper The callback used to wrap communication in a web socket frame. Sending
* NULL to the frame wrapper should send a disconnect.
*
* @throws \socket_exception Thrown when the passed socket is already closed
* @throws \InvalidArgumentException Thrown when the $callback is not a valid callback
*/
@@ -186,9 +211,9 @@ class subscriber {
}
// set object identifiers
$this->id = md5(spl_object_hash($this)); // PHP unique object hash is similar to 000000000000000f0000000000000000 so we use md5
$this->socket = $socket;
$this->socket_id = (int) $socket;
$this->id = md5(spl_object_hash($this)); // PHP unique object hash is similar to 000000000000000f0000000000000000 so we use md5
$this->socket = $socket;
$this->socket_id = (int)$socket;
$this->domain_name = '';
$this->domain_uuid = '';
@@ -197,14 +222,14 @@ class subscriber {
[$this->remote_ip, $this->remote_port] = self::get_remote_information_from_socket($socket);
// set defaults
$this->authenticated = false;
$this->permissions = [];
$this->services = [];
$this->authenticated = false;
$this->permissions = [];
$this->services = [];
$this->enable_token_time_limit = false;
$this->subscriptions = [];
$this->service = false;
$this->service_name = '';
$this->user = [];
$this->subscriptions = [];
$this->service = false;
$this->service_name = '';
$this->user = [];
// Save the websocket frame wrapper used to communicate to this subscriber
$this->callback = $frame_wrapper;
@@ -215,6 +240,7 @@ class subscriber {
/**
* Returns the user array information in this subscriber
*
* @return array
*/
public function get_user_array(): array {
@@ -222,18 +248,23 @@ class subscriber {
}
/**
* Returns the user information from the provided key.
* @param string $key
* @return mixed
* Retrieves a user setting by its key.
*
* @param string $key The name of the user setting to retrieve
* @param mixed $default_value The default value to return if the setting is not found (optional)
*
* @return mixed The value of the user setting, or the default value if it does not exist
*/
public function get_user_setting($key, $default_value = null) {
return $this->user[$key] ?? $default_value;
}
/**
* Gets or sets the subscribed to services
* @param array $services
* @return $this|array
* Checks if this subscriber is subscribed to the given services
*
* @param array $services Optional list of service names, e.g. [active.calls, inactive.calls]
*
* @return mixed This object or an array of subscribed service names
*/
public function subscribed_to($services = []) {
if (func_num_args() > 0) {
@@ -245,7 +276,9 @@ class subscriber {
/**
* Gets or sets the service class name for this subscriber
* @param string $service_class
*
* @param ?string $service_class
*
* @return $this|string
*/
public function service_class($service_class = null) {
@@ -258,7 +291,9 @@ class subscriber {
/**
* Sets the filter used for this subscriber
*
* @param filter $filter
*
* @return $this
*/
public function set_filter(filter $filter) {
@@ -268,6 +303,7 @@ class subscriber {
/**
* Returns the filter used for this subscriber
*
* @return filter
*/
public function get_filter() {
@@ -284,6 +320,7 @@ class subscriber {
/**
* Disconnects the socket resource used for this subscriber
*
* @return bool true on success and false on failure
*/
public function disconnect(): bool {
@@ -298,9 +335,11 @@ class subscriber {
}
/**
* Compares the current object with another object to see if they are exactly the same object
* @param subscriber|resource $object_or_resource_or_id
* @return bool
* Checks if this subscriber is equal to the given object, resource or id.
*
* @param mixed $object_or_resource_or_id The object, resource or id to compare with
*
* @return bool True if the subscribers are equal, false otherwise
*/
public function equals($object_or_resource_or_id): bool {
// Compare by resource
@@ -322,7 +361,9 @@ class subscriber {
/**
* Compares this object to another object or resource id.
* @param type $object_or_resource
*
* @param $object_or_resource The object or resource to compare
*
* @return bool True if this object is not equal to the other object or resource. False otherwise.
* @see subscriber::equals()
*/
@@ -332,9 +373,10 @@ class subscriber {
/**
* Allow accessing <b>copies</b> of the private values to ensure the object values are immutable.
* @param string $name
* @return mixed
* @throws \InvalidArgumentException
*
* @param string $name The name of the attribute to be accessed
*
* @throws \InvalidArgumentException If the attribute does not exist or direct access is prohibited
*/
public function __get(string $name) {
switch ($name) {
@@ -357,6 +399,7 @@ class subscriber {
/**
* Returns the current ID of this subscriber.
* The ID is set in the constructor using the spl_object_id given by PHP
*
* @return string
*/
public function id(): string {
@@ -365,7 +408,9 @@ class subscriber {
/**
* Checks if this subscriber has the permission given in $permission
* @param string $permission
*
* @param string $permission The permission to check
*
* @return bool True when this subscriber has the permission and false otherwise
*/
public function has_permission(string $permission): bool {
@@ -378,6 +423,7 @@ class subscriber {
/**
* Returns the array of permissions this subscriber has been assigned.
*
* @return array
*/
public function get_permissions(): array {
@@ -388,6 +434,7 @@ class subscriber {
* Returns the domain name used.
* <p>Note:<br>
* This value is not validated in the object and must be validated.</p>
*
* @return string
*/
public function get_domain_name(): string {
@@ -395,8 +442,9 @@ class subscriber {
}
/**
* Returns the current socket resource used to communicate with this subscriber
* @return resource|stream Resource Id or stream used
* Returns the associated socket
*
* @return resource
*/
public function socket() {
return $this->socket;
@@ -404,6 +452,7 @@ class subscriber {
/**
* Returns the socket ID that was cast to an integer when the object was created.
*
* @return int The socket ID cast as an integer.
*/
public function socket_id(): int {
@@ -412,7 +461,9 @@ class subscriber {
/**
* Validates the given token against the loaded token in the this subscriber
*
* @param array $token Must be an associative array with name and hash as the keys.
*
* @return bool
*/
public function is_valid_token(array $token): bool {
@@ -456,7 +507,9 @@ class subscriber {
* Validates the given token array against the token previously saved in the file system. When the token is valid
* the token will be saved in this object and the file removed. This method should not be called a second time
* once a token has be authenticated.
*
* @param array $request_token
*
* @return bool
*/
public function authenticate_token(array $request_token): bool {
@@ -486,9 +539,9 @@ class subscriber {
$array = include($token_file);
// Assign to local variables to reflect local storage
$token_name = $array['token']['name'] ?? '';
$token_hash = $array['token']['hash'] ?? '';
$token_time = intval($array['token']['time'] ?? 0);
$token_name = $array['token']['name'] ?? '';
$token_hash = $array['token']['hash'] ?? '';
$token_time = intval($array['token']['time'] ?? 0);
$token_limit = intval($array['token']['limit'] ?? 0);
// Compare the token given in the request with the one that was in local storage
@@ -504,11 +557,11 @@ class subscriber {
if ($valid) {
// Store the valid token information in this object
$this->token_name = $token_name;
$this->token_hash = $token_hash;
$this->token_time = $token_time;
$this->token_name = $token_name;
$this->token_hash = $token_hash;
$this->token_time = $token_time;
$this->enable_token_time_limit = $token_limit > 0;
$this->token_limit = $token_limit * 60; // convert to seconds for time() comparison
$this->token_limit = $token_limit * 60; // convert to seconds for time() comparison
// Add the domain
$this->domain_name = $array['domain']['name'] ?? '';
@@ -534,7 +587,7 @@ class subscriber {
//
// Set the service information in the object
//
$this->service_name = "" . ($array['service_name'] ?? '');
$this->service_name = "" . ($array['service_name'] ?? '');
$this->service_class = "" . ($array['service_class'] ?? '');
//
@@ -565,6 +618,7 @@ class subscriber {
/**
* Returns whether or not this subscriber has been authenticated.
*
* @return bool
*/
public function is_authenticated(): bool {
@@ -573,7 +627,9 @@ class subscriber {
/**
* Allows overriding the token authentication
*
* @param bool $authenticated
*
* @return self
*/
public function set_authenticated(bool $authenticated): self {
@@ -583,12 +639,14 @@ class subscriber {
/**
* Sets the domain UUID and name
*
* @param string $uuid
* @param string $name
*
* @return self
* @throws invalid_uuid_exception
* @depends is_uuid()
* @see is_uuid()
* @see is_uuid()
*/
public function set_domain(string $uuid, string $name): self {
if (is_uuid($uuid)) {
@@ -602,6 +660,7 @@ class subscriber {
/**
* Returns whether or not this subscriber is a service.
*
* @return bool True if this subscriber is a service and false if this subscriber is not a service.
*/
public function is_service(): bool {
@@ -610,6 +669,7 @@ class subscriber {
/**
* Alias of service_name without the parameters
*
* @return string
*/
public function get_service_name(): string {
@@ -618,7 +678,9 @@ class subscriber {
/**
* Get or set the service_name
*
* @param string|null $service_name
*
* @return string|$this
*/
public function service_name($service_name = null) { /* : string|self */
@@ -631,7 +693,9 @@ class subscriber {
/**
* Returns whether or not the service name matches this subscriber
*
* @param string $service_name Name of the service
*
* @return bool True if this subscriber matches the provided service name. False if this subscriber does not
* match or this subscriber is not a service.
*/
@@ -641,6 +705,7 @@ class subscriber {
/**
* Returns true if the socket/stream is still open (not at EOF).
*
* @return bool Returns true if connected and false if the connection has closed
*/
public function is_connected(): bool {
@@ -649,6 +714,7 @@ class subscriber {
/**
* Returns true if the subscriber is no longer connected
*
* @return bool Returns true if the subscriber is no longer connected
*/
public function is_not_connected(): bool {
@@ -657,7 +723,9 @@ class subscriber {
/**
* Checks if this subscriber is subscribed to the given service name
*
* @param string $service_name The service name ie. active.calls
*
* @return bool
* @see subscriber::subscribe
*/
@@ -667,7 +735,9 @@ class subscriber {
/**
* Subscribe to a service by ensuring this subscriber has the appropriate permissions
*
* @param string $service_name
*
* @return self
*/
public function subscribe(string $service_name): self {
@@ -677,7 +747,9 @@ class subscriber {
/**
* Sends a response to the subscriber using the provided callback web socket wrapper in the constructor
*
* @param string $json Valid JSON response to send to the connected client
*
* @throws subscriber_token_expired_exception Thrown when the time limit set in the token has expired
*/
public function send(string $json) {
@@ -691,7 +763,9 @@ class subscriber {
/**
* Sends the given message through the websocket
*
* @param websocket_message $message
*
* @throws socket_disconnected_exception
*/
public function send_message(websocket_message $message) {
@@ -716,17 +790,21 @@ class subscriber {
throw new \socket_disconnected_exception($this->id);
}
$this->send((string) $message);
$this->send((string)$message);
return;
}
/**
* The remote information is retrieved using the stream_socket_get_name function.
*
* @param resource $socket
* @return array Returns a zero-based indexed array of first the IP address and then the port of the remote machine.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return information.
*
* @return array Returns a zero-based indexed array of first the IP address and then the port of the remote
* machine.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return
* information.
*/
public static function get_remote_information_from_socket($socket): array {
return explode(':', stream_socket_get_name($socket, true), 2);
@@ -734,10 +812,13 @@ class subscriber {
/**
* The remote information is retrieved using the stream_socket_get_name function.
*
* @param resource $socket
*
* @return string Returns the IP address of the remote machine or an empty string.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return information.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return
* information.
*/
public static function get_remote_ip_from_socket($socket): string {
$array = explode(':', stream_socket_get_name($socket, true), 2);
@@ -746,10 +827,13 @@ class subscriber {
/**
* The remote information is retrieved using the stream_socket_get_name function.
*
* @param resource $socket
*
* @return string Returns the port of the remote machine as a string or an empty string.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return information.
* @see stream_socket_get_name();
* @link https://php.net/stream_socket_get_name PHP documentation for underlying function used to return
* information.
*/
public static function get_remote_port_from_socket($socket): string {
$array = explode(':', stream_socket_get_name($socket, true), 2);
@@ -760,10 +844,13 @@ class subscriber {
* Returns the name and path for the token.
* Priority is given to the /dev/shm folder if it exists as this is much faster. If that is not available, then the
* sys_get_temp_dir() function is called to get a storage location.
*
* @param string $token_name
*
* @return string
* @see sys_get_temp_dir()
* @link https://php.net/sys_get_temp_dir PHP Documentation for the function used to get the temporary storage location.
* @see sys_get_temp_dir()
* @link https://php.net/sys_get_temp_dir PHP Documentation for the function used to get the temporary storage
* location.
*/
public static function get_token_file($token_name): string {
// Try to store in RAM first
@@ -787,9 +874,10 @@ class subscriber {
* the web socket service may not yet have access to the token before the
* web socket client requests authorization.
*
* @param array $token Standard token issued from the token object
* @param array $services A simple array list of service names to subscribe to
* @param int $time_limit_in_minutes Set a token time limit. Setting to zero will disable the time limit
* @param array $token Standard token issued from the token object
* @param array $services A simple array list of service names to subscribe to
* @param int $time_limit_in_minutes Set a token time limit. Setting to zero will disable the time limit
*
* @see token::create()
*/
public static function save_token(array $token, array $services, int $time_limit_in_minutes = 0) {
@@ -813,7 +901,7 @@ class subscriber {
//
// Store the epoch time and time limit
//
$array['token']['time'] = "" . time();
$array['token']['time'] = "" . time();
$array['token']['limit'] = $time_limit_in_minutes;
//
@@ -839,6 +927,7 @@ class subscriber {
/**
* Checks the token time stored in this subscriber
*
* @return bool True if the token has expired. False if the token is still valid
*/
public function token_time_exceeded(): bool {

11
core/websockets/resources/classes/subscriber_exception.php
View File

@@ -33,6 +33,17 @@
*/
class subscriber_exception extends \Exception {
public $subscriber_id;
/**
* Initializes a new instance of the class.
*
* @param mixed $subscriber_id The subscriber's ID.
* @param string $message [optional] The exception message. Defaults to an empty string.
* @param int $code [optional] The user-defined errorCode integer. Defaults to 0.
* @param Throwable|null $previous [optional] The previous throwable that caused this one, or null if none. Defaults to null.
*
* @return void
*/
public function __construct($subscriber_id, string $message = "", int $code = 0, ?\Throwable $previous = null) {
parent::__construct($message, $code, $previous);
$this->subscriber_id = $subscriber_id;

10
core/websockets/resources/classes/subscriber_missing_permission_exception.php
View File

@@ -32,6 +32,16 @@
* @author Tim Fry <tim@fusionpbx.com>
*/
class subscriber_missing_permission_exception extends \subscriber_exception {
/**
* Initializes the object with subscriber id and error message.
*
* @param string|int $subscriber_id Subscriber's unique identifier
* @param string $message [optional] Custom error message. Defaults to "Subscriber is missing required permission".
* @param int $code [optional] Error code. Defaults to 0.
* @param \Throwable|null $previous [optional] The previous exception. Defaults to null.
*
* @return void
*/
public function __construct($subscriber_id, string $message = "Subscriber is missing required permission", int $code = 0, ?\Throwable $previous = null) {
return parent::__construct($subscriber_id, $message, $code, $previous);
}

8
core/websockets/resources/classes/subscriber_not_subscribed_exception.php
View File

@@ -32,6 +32,14 @@
* @author Tim Fry <tim@fusionpbx.com>
*/
class subscriber_not_subscribed_exception extends subscriber_exception {
/**
* Initializes a new instance of the class with the specified subscriber ID and message.
*
* @param string|int $subscriber_id The identifier for the subscriber.
* @param string $message The error message. Defaults to "Subscriber is not subscribed".
* @param int $code The HTTP status code. Defaults to 0.
* @param \Throwable|null $previous The previous exception, if any.
*/
public function __construct($subscriber_id, string $message = "Subscriber is not subscribed", int $code = 0, ?\Throwable $previous = null) {
parent::__construct($subscriber_id, $message, $code, $previous);
}

13
core/websockets/resources/classes/subscriber_token_expired_exception.php
View File

@@ -32,6 +32,19 @@
* @author Tim Fry <tim@fusionpbx.com>
*/
class subscriber_token_expired_exception extends \subscriber_exception {
/**
* Constructor for the class.
*
* Initializes a new instance of the class with optional subscriber ID, message,
* code, and previous exception information.
*
* @param string|null $subscriber_id Optional subscriber ID.
* @param string $message The error message. Defaults to "Subscriber token expired".
* @param int $code The HTTP status code. Defaults to 0.
* @param \Throwable|null $previous The previous exception. Defaults to null.
*
* @return void
*/
public function __construct($subscriber_id = null, string $message = "Subscriber token expired", int $code = 0, ?\Throwable $previous = null) {
return parent::__construct($subscriber_id, $message, $code, $previous);
}

125
core/websockets/resources/classes/websocket_client.php
View File

@@ -58,10 +58,10 @@ class websocket_client {
* Connects to the WebSocket server and performs handshake.
*/
public function connect(): void {
$parts = parse_url($this->url);
$this->host = $parts['host'] ?? '';
$this->port = $parts['port'] ?? 80;
$this->path = $parts['path'] ?? '/';
$parts = parse_url($this->url);
$this->host = $parts['host'] ?? '';
$this->port = $parts['port'] ?? 80;
$this->path = $parts['path'] ?? '/';
$this->origin = ($parts['scheme'] ?? 'http') . '://' . $this->host;
$this->resource = stream_socket_client("tcp://{$this->host}:{$this->port}", $errno, $errstr, 5);
@@ -100,7 +100,7 @@ class websocket_client {
if (!preg_match('/Sec-WebSocket-Accept: (.*)\r\n/', $response, $m)) {
throw new \RuntimeException("Handshake failed: no Accept header");
}
$accept = trim($m[1]);
$accept = trim($m[1]);
$expected = base64_encode(sha1($this->key . '258EAFA5-E914-47DA-95CA-C5AB0DC85B11', true));
if ($accept !== $expected) {
throw new \RuntimeException("Handshake failed: invalid Accept key");
@@ -112,19 +112,47 @@ class websocket_client {
}
}
/**
* Sets the blocking mode of the underlying socket.
*
* @param bool $block If true, sets the socket to block on read/write operations; otherwise, sets it to non-blocking.
*
* @return void
*/
public function set_blocking(bool $block) {
if ($this->is_connected())
stream_set_blocking($this->resource, $block);
}
/**
* Sets the file descriptor to be in blocking mode.
*
* This ensures that any write operations on this socket will block until the entire data has been sent.
*
* @return void
*/
public function block() {
$this->set_blocking(true);
}
/**
* Disables blocking mode for this resource.
*
* This method sets the resource to non-blocking mode, allowing I/O operations to complete immediately
* without waiting for completion. If an operation is attempted while in non-blocking mode and no data
* is available, a BlockingQueueException will be raised.
*
* @return void
*/
public function unblock() {
$this->set_blocking(false);
}
/**
* Checks if the underlying socket is in a non-blocking state.
*
* @return bool True if the socket is blocking, false otherwise.
*/
public function is_blocking(): bool {
if ($this->is_connected()) {
//
@@ -141,7 +169,9 @@ class websocket_client {
}
/**
* Returns true if socket is connected.
* Checks if a connection to the web socket server is established and active.
*
* @return bool
*/
public function is_connected(): bool {
return isset($this->resource) && is_resource($this->resource) && !feof($this->resource);
@@ -150,7 +180,13 @@ class websocket_client {
/**
* Sends text to the web socket server.
* The web socket client wraps the payload in a web frame socket before sending on the socket.
*
* @param $resource
* @param string|null $payload
*
* @return bool
* @throws \Random\RandomException
* @throws \socket_disconnected_exception
*/
public static function send($resource, ?string $payload): bool {
if (!is_resource($resource)) {
@@ -164,7 +200,7 @@ class websocket_client {
}
$frame_header = "\x81"; // FIN=1, opcode=1 (text frame)
$length = strlen($payload);
$length = strlen($payload);
// Set mask bit and payload length
if ($length <= 125) {
@@ -176,7 +212,7 @@ class websocket_client {
}
// must be masked when sending to the server
$mask = random_bytes(4);
$mask = random_bytes(4);
$masked_payload = '';
for ($i = 0; $i < $length; ++$i) {
@@ -210,6 +246,17 @@ class websocket_client {
}
}
/**
* Returns a file path for a token.
*
* Tries to store in RAM first, otherwise uses the filesystem.
*
* @param string $token_name The name of the token.
*
* @return string The file path for the token.
* @see \sys_get_temp_dir()
* @link https://php.net/sys_get_temp_dir
*/
public static function get_token_file($token_name): string {
// Try to store in RAM first
if (is_dir('/dev/shm') && is_writable('/dev/shm')) {
@@ -221,8 +268,18 @@ class websocket_client {
return $token_file;
}
/**
* Sends a control frame over the WebSocket connection.
*
* This method sends a FIN=1 (final fragment) control frame with the given opcode and payload.
*
* @param int $opcode The opcode for the control frame.
* @param string $payload The payload to send, default is an empty string.
*
* @return void
*/
private function send_control_frame(int $opcode, string $payload = ''): void {
$header = chr(0x80 | $opcode); // FIN=1, control frame
$header = chr(0x80 | $opcode); // FIN=1, control frame
$payload_len = strlen($payload);
// Payload length
@@ -233,7 +290,7 @@ class websocket_client {
} else {
// Control frames should never be this large; truncate to 125
$payload = substr($payload, 0, 125);
$header .= chr(125);
$header .= chr(125);
}
@fwrite($this->resource, $header . $payload);
@@ -241,7 +298,9 @@ class websocket_client {
/**
* Reads a web socket data frame and converts it to a regular string
* @param resource $this->resource
*
* @param resource $this ->resource
*
* @return string
*/
public function read(): ?string {
@@ -249,7 +308,7 @@ class websocket_client {
throw new \RuntimeException("Not connected");
}
$final_frame = false;
$final_frame = false;
$payload_data = '';
while (!$final_frame) {
@@ -262,8 +321,8 @@ class websocket_client {
$byte2 = ord($header[1]);
$final_frame = ($byte1 >> 7) & 1;
$opcode = $byte1 & 0x0F;
$masked = ($byte2 >> 7) & 1;
$opcode = $byte1 & 0x0F;
$masked = ($byte2 >> 7) & 1;
$payload_len = $byte2 & 0x7F;
// Extended payload length
@@ -335,8 +394,16 @@ class websocket_client {
}
// Helper function to fully read N bytes
/**
* Reads up to the specified number of bytes from the underlying resource.
*
* @param int $length The maximum number of bytes to read.
*
* @return string|null The requested data, or null on error.
*/
private function read_bytes(int $length): ?string {
$data = '';
$data = '';
$max_chunk_size = stream_get_chunk_size($this->resource);
// 20 tries waits 200 ms total per chunk
@@ -376,16 +443,26 @@ class websocket_client {
return $data;
}
/**
* Sends an authentication request to the server.
*
* @param string $token_name The name of the token to authenticate with.
* @param string $token_hash The hash of the token to authenticate with.
*
* @return mixed|null The response from the server, or null on error.
*/
public function authenticate($token_name, $token_hash) {
return self::send($this->resource, json_encode(['service' => 'authentication', 'token' => ['name' => $token_name, 'hash' => $token_hash]]));
}
/**
* Create a token for a service that can broadcast a message
*
* @param string $service_name
* @param string $service_class
* @param array $permissions
* @param int $time_limit_in_minutes
* @param array $permissions
* @param int $time_limit_in_minutes
*
* @return array
*/
public static function create_service_token(string $service_name, string $service_class, array $permissions = [], int $time_limit_in_minutes = 0) {
@@ -410,15 +487,15 @@ class websocket_client {
//
// Store the epoch time and time limit
//
$array['token']['time'] = "" . time();
$array['token']['time'] = "" . time();
$array['token']['limit'] = $time_limit_in_minutes;
//
// Store the service name used by web browser to subscribe
// and store the class name of this service
//
$array['service'] = true;
$array['service_name'] = $service_name;
$array['service'] = true;
$array['service_name'] = $service_name;
$array['service_class'] = $service_class;
//
@@ -441,6 +518,14 @@ class websocket_client {
// PHP <=7.4 compatibility - Replaced in PHP 8.0+
if (!function_exists('stream_get_chunk_size')) {
/**
* Returns the recommended chunk size for reading data from a stream.
*
* @param resource $stream The stream to retrieve the chunk size for.
*
* @return int The recommended chunk size.
* @link https://php.net/stream_get_chunk_size
*/
function stream_get_chunk_size($stream): int {
// For PHP versions lower then 8 we send the maximum size defined from https://php.net/stream_get_chunk_size
return 8192;

146
core/websockets/resources/classes/websocket_message.php
View File

@@ -29,17 +29,18 @@
/**
* A structured web socket message easily converted to and from a json string
*
* @param string $service_name ;
* @param string $token_name ;
* @param string $token_hash ;
* @param string $status_string ;
* @param string $status_code ;
* @param string $request_id ;
* @param string $resource_id ;
* @param string $domain_uuid ;
* @param string $permissions ;
* @param string $topic ;
*
* @author Tim Fry <tim@fusionpbx.com>
* @param string $service_name;
* @param string $token_name;
* @param string $token_hash;
* @param string $status_string;
* @param string $status_code;
* @param string $request_id;
* @param string $resource_id;
* @param string $domain_uuid;
* @param string $permissions;
* @param string $topic;
*/
class websocket_message extends base_message {
@@ -58,30 +59,39 @@ class websocket_message extends base_message {
public function __construct($associative_properties_array = []) {
// Initialize empty default values
$this->service_name = '';
$this->token_name = '';
$this->token_hash = '';
$this->service_name = '';
$this->token_name = '';
$this->token_hash = '';
$this->status_string = '';
$this->status_code = '';
$this->request_id = '';
$this->resource_id = '';
$this->domain_uuid = '';
$this->domain_name = '';
$this->permissions = [];
$this->topic = '';
$this->status_code = '';
$this->request_id = '';
$this->resource_id = '';
$this->domain_uuid = '';
$this->domain_name = '';
$this->permissions = [];
$this->topic = '';
//
// Send to parent (base_message) constructor
//
parent::__construct($associative_properties_array);
}
/**
* Checks if a permission is granted to this service.
*
* @param string $permission_name The name of the permission to check for.
*
* @return bool True if the permission is granted, false otherwise.
*/
public function has_permission($permission_name) {
return isset($this->permissions[$permission_name]);
}
/**
* Alias of service_name.
*
* @param string $service_name
*
* @return $this
* @see service_name
*/
@@ -97,7 +107,9 @@ class websocket_message extends base_message {
* Gets or Sets the service name
* If no parameters are provided then the service_name is returned. If the service name is provided, then the
* service_name is set to the value provided.
*
* @param string $service_name
*
* @return $this
*/
public function service_name($service_name = null) {
@@ -110,7 +122,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the permissions array
*
* @param array $permissions
*
* @return $this
*/
public function permissions($permissions = []) {
@@ -124,6 +138,7 @@ class websocket_message extends base_message {
/**
* Applies a filter to the payload of this message.
* When a filter returns null then the payload is set to null
*
* @param filter $filter
*/
public function apply_filter(?filter $filter) {
@@ -134,9 +149,8 @@ class websocket_message extends base_message {
if ($result === null) {
$this->payload = null;
return;
}
// Remove a key if filter does not pass
elseif(!$result) {
} // Remove a key if filter does not pass
elseif (!$result) {
unset($this->payload[$key]);
}
}
@@ -145,7 +159,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the domain UUID
*
* @param string $domain_uuid
*
* @return $this or $domain_uuid
*/
public function domain_uuid($domain_uuid = '') {
@@ -158,7 +174,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the domain name
*
* @param string $domain_name
*
* @return $this or $domain_name
*/
public function domain_name($domain_name = '') {
@@ -173,7 +191,9 @@ class websocket_message extends base_message {
* Gets or Sets the service name
* If no parameters are provided then the service_name is returned. If the service name is provided, then the
* topic is set to the value provided.
*
* @param string $topic
*
* @return $this
*/
public function topic($topic = null) {
@@ -186,7 +206,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the token array using the key values of 'name' and 'hash'
*
* @param array $token_array
*
* @return array|$this
* @see token_name
* @see token_hash
@@ -201,11 +223,13 @@ class websocket_message extends base_message {
/**
* Sets the token name
*
* @param string $token_name
*
* @return $this
* @see token_hash
*/
public function token_name($token_name = '') {
public function token_name($token_name = '') {
if (func_num_args() > 0) {
$this->token_name = $token_name;
return $this;
@@ -215,7 +239,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the status code of this message
*
* @param int $status_code
*
* @return $this
*/
public function status_code($status_code = '') {
@@ -228,7 +254,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the resource id
* @param type $resource_id
*
* @param mixed $resource_id
*
* @return $this
*/
public function resource_id($resource_id = null) {
@@ -241,7 +269,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the request ID
* @param type $request_id
*
* @param string $request_id
*
* @return $this
*/
public function request_id($request_id = null) {
@@ -254,10 +284,12 @@ class websocket_message extends base_message {
/**
* Gets or sets the status string
* @param type $status_string
*
* @param string $status_string
*
* @return $this
*/
public function status_string( $status_string = null) {
public function status_string($status_string = null) {
if (func_num_args() > 0) {
$this->status_string = $status_string;
return $this;
@@ -267,7 +299,9 @@ class websocket_message extends base_message {
/**
* Gets or sets the token hash
* @param type $token_hash
*
* @param string $token_hash
*
* @return $this
* @see token_name
*/
@@ -281,8 +315,10 @@ class websocket_message extends base_message {
/**
* Convert the 'statusString' key that comes from javascript
* @param type $status_string
* @return type
*
* @param string $status_string
*
* @return string
*/
public function statusString($status_string = '') {
return $this->status_string($status_string);
@@ -290,7 +326,9 @@ class websocket_message extends base_message {
/**
* Convert the 'statusCode' key that comes from javascript
* @param type $status_code
*
* @param string $status_code
*
* @return $this
*/
public function statusCode($status_code = 200) {
@@ -299,7 +337,9 @@ class websocket_message extends base_message {
/**
* Unwrap a JSON message to an associative array
*
* @param string $json_string
*
* @return array
*/
public static function unwrap($json_string = '') {
@@ -308,7 +348,9 @@ class websocket_message extends base_message {
/**
* Helper function to respond with a connected message
*
* @param string|int $request_id
*
* @return string
*/
public static function connected($request_id = ''): string {
@@ -317,7 +359,9 @@ class websocket_message extends base_message {
/**
* Helper function to respond with a authentication message
*
* @param string|int $request_id
*
* @return string
*/
public static function request_authentication($request_id = ''): string {
@@ -334,9 +378,11 @@ class websocket_message extends base_message {
/**
* Helper function to respond with a bad request message
*
* @param string|int $request_id
* @param string $service
* @param string $topic
* @param string $service
* @param string $topic
*
* @return string
*/
public static function request_is_bad($request_id = '', string $service = '', string $topic = ''): string {
@@ -352,28 +398,32 @@ class websocket_message extends base_message {
/**
* Helper function to respond with an authenticated message
*
* @param string|int $request_id
* @param string $service
* @param string $topic
* @param string $service
* @param string $topic
*
* @return string
*/
public static function request_authenticated($request_id = '', string $service = '', string $topic = 'authenticated'): string {
$class = static::class;
return (new $class())
->request_id($request_id)
->service_name($service)
->topic($topic)
->status_code(200)
->status_string('OK')
->__toString()
->request_id($request_id)
->service_name($service)
->topic($topic)
->status_code(200)
->status_string('OK')
->__toString()
;
}
/**
* Helper function to respond with an unauthorized request message
*
* @param string|int $request_id
* @param string $service
* @param string $topic
* @param string $service
* @param string $topic
*
* @return string
*/
public static function request_unauthorized($request_id = '', string $service = '', string $topic = 'unauthorized'): string {
@@ -389,9 +439,11 @@ class websocket_message extends base_message {
/**
* Helper function to respond with a forbidden message
*
* @param string|int $request_id
* @param string $service
* @param string $topic
* @param string $service
* @param string $topic
*
* @return string
*/
public static function request_forbidden($request_id = '', string $service = '', string $topic = 'forbidden'): string {
@@ -407,7 +459,9 @@ class websocket_message extends base_message {
/**
* Returns a websocket_message object (or child object) using the provided JSON string or JSON array
*
* @param string|array $websocket_message_json JSON array or JSON string
*
* @return static|null Returns a new websocket_message object (or child object)
* @throws \InvalidArgumentException
*/

150
core/websockets/resources/classes/websocket_server.php
View File

@@ -40,94 +40,133 @@ class websocket_server {
/**
* Address to bind to. (Default 8080)
*
* @var string
*/
protected $address;
/**
* Port to bind to. (Default 0.0.0.0 - all PHP detected IP addresses of the system)
*
* @var int
*/
protected $port;
/**
* Tracks if the server is running
*
* @var bool
*/
protected $running;
/**
* Resource or stream of the server socket binding
*
* @var resource|stream
*/
protected $server_socket;
/**
* List of connected client sockets
*
* @var array
*/
protected $clients;
/**
* Used to track on_message events
*
* @var array
*/
private $message_callbacks;
/**
* Used to track on_connect events
*
* @var array
*/
private $connect_callbacks;
/**
* Used to track on_disconnect events
*
* @var array
*/
private $disconnect_callbacks;
/**
* Used to track switch listeners or other socket connection types
*
* @var array
*/
private $listeners;
/**
* Creates a websocket_server instance
*
* @param string $address IP to bind (default 0.0.0.0)
* @param int $port TCP port (default 8080)
*/
public function __construct(string $address = '127.0.0.1', int $port = 8080) {
$this->running = false;
$this->address = $address;
$this->port = $port;
$this->port = $port;
// Initialize arrays
$this->listeners = [];
$this->clients = [];
$this->message_callbacks = [];
$this->connect_callbacks = [];
$this->listeners = [];
$this->clients = [];
$this->message_callbacks = [];
$this->connect_callbacks = [];
$this->disconnect_callbacks = [];
}
/**
* Log a debugging message to the log handler.
*
* @param string $message The message to be logged.
*
* @return void
*/
private function debug(string $message) {
self::log($message, LOG_DEBUG);
}
/**
* Log a warning message to the log file.
*
* @param string $message The warning message to be logged.
*
* @return void
*/
private function warn(string $message) {
self::log($message, LOG_WARNING);
}
/**
* Log an error message to the log file. If the logging fails for any reason, it is silently ignored and no further action is taken.
*
* @param string $message The error message to be logged.
*
* @return void
*/
private function error(string $message) {
self::log($message, LOG_ERR);
}
/**
* Logs information level message to the log handler.
*
* @param string $message The message to be logged.
*
* @return void
*/
private function info(string $message) {
self::log($message, LOG_INFO);
}
/**
* Starts server: accepts new clients, reads frames, and broadcasts messages.
*
* @returns int A non-zero indicates an abnormal termination
*/
public function run(): int {
@@ -143,8 +182,8 @@ class websocket_server {
while ($this->running) {
$listeners = array_column($this->listeners, 0);
$read = array_merge([$this->server_socket], $listeners, $this->clients);
$write = $except = [];
$read = array_merge([$this->server_socket], $listeners, $this->clients);
$write = $except = [];
// Server connection issue
if (false === stream_select($read, $write, $except, null)) {
$this->running = false;
@@ -194,12 +233,15 @@ class websocket_server {
$this->trigger_message($client_socket, $message);
}
}
return 0;
}
/**
* Add a non-blocking socket to listen for traffic on
*
* @param resource $socket
* @param callable $on_data_ready_callback Callable function to call when data arrives on the socket
*
* @throws \InvalidArgumentException
*/
public function add_listener($socket, callable $on_data_ready_callback) {
@@ -211,6 +253,7 @@ class websocket_server {
/**
* Returns true if there are connected web socket clients.
*
* @return bool
*/
public function has_clients(): bool {
@@ -220,7 +263,9 @@ class websocket_server {
/**
* When a web socket message is received the $on_message_callback function is called.
* Multiple on_message functions can be specified.
*
* @param callable $on_message_callback Callable function to call when data arrives on the socket
*
* @throws InvalidArgumentException
*/
public function on_message(callable $on_message_callback) {
@@ -232,8 +277,10 @@ class websocket_server {
/**
* Calls all the on_message functions
*
* @param resource $socket
* @param string $message
* @param string $message
*
* @return void
*/
private function trigger_message($socket, string $message) {
@@ -249,7 +296,9 @@ class websocket_server {
/**
* When a web socket handshake has completed, the $on_connect_callback function is called.
* Multiple on_connect functions can be specified.
*
* @param callable $on_connect_callback Callable function to call when a new connection occurs.
*
* @throws InvalidArgumentException
*/
public function on_connect(callable $on_connect_callback) {
@@ -261,7 +310,10 @@ class websocket_server {
/**
* Calls all the on_connect functions
*
* @param resource $socket
*
* @throws \socket_disconnected_exception
*/
private function trigger_connect($socket) {
foreach ($this->connect_callbacks as $callback) {
@@ -275,7 +327,11 @@ class websocket_server {
/**
* When a web socket has disconnected, the $on_disconnect_callback function is called.
* Multiple functions can be specified with subsequent calls
* @param string|callable $on_disconnect_callback Callable function to call when a socket disconnects. The function must accept a single parameter for the socket that was disconnected.
*
* @param string|callable $on_disconnect_callback Callable function to call when a socket disconnects. The function
* must accept a single parameter for the socket that was
* disconnected.
*
* @throws InvalidArgumentException
*/
public function on_disconnect($on_disconnect_callback) {
@@ -287,7 +343,8 @@ class websocket_server {
/**
* Calls all the on_disconnect_callback functions
* @param type $socket
*
* @param resource $socket
*/
private function trigger_disconnect($socket) {
foreach ($this->disconnect_callbacks as $callback) {
@@ -297,6 +354,7 @@ class websocket_server {
/**
* Returns the socket used in the server connection
*
* @return resource
*/
public function get_socket() {
@@ -304,15 +362,19 @@ class websocket_server {
}
/**
* Remove a client socket on disconnect.
* @return bool Returns true on client disconnect and false when the client is not found in the tracking array
* Disconnect a client from the server.
*
* @param resource $resource The socket or resource id of the client to disconnect.
* @param string|null $error A custom error message to send to the client, if any.
*
* @return bool True if the client was successfully disconnected, false otherwise.
*/
protected function disconnect_client($socket, $error = null): bool {
protected function disconnect_client($resource, $error = null): bool {
$index = array_search($resource, $this->clients, true);
if ($index !== false) {
self::disconnect($resource);
unset($this->clients[$index]);
$this->trigger_disconnect($socket);
$this->trigger_disconnect($resource);
return true;
}
return false;
@@ -320,7 +382,8 @@ class websocket_server {
/**
* Sends a disconnect frame with no payload
* @param type $resource
*
* @param resource $resource
*/
public static function disconnect($resource) {
if (is_resource($resource)) {
@@ -332,7 +395,8 @@ class websocket_server {
/**
* Performs web socket handshake on new connection.
* @param type $socket Socket to perform the handshake on.
*
* @param resource $socket Socket to perform the handshake on.
*/
protected function handshake($socket) {
// ensure blocking to read full header
@@ -347,21 +411,23 @@ class websocket_server {
if (!preg_match("/Sec-WebSocket-Key: (.*)\r\n/", $request_header, $matches)) {
throw new \invalid_handshake_exception($socket, "Invalid WebSocket handshake");
}
$key = trim($matches[1]);
$accept_key = base64_encode(
sha1($key . "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", true)
$key = trim($matches[1]);
$accept_key = base64_encode(
sha1($key . "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", true)
);
$response_header = "HTTP/1.1 101 Switching Protocols\r\n"
. "Upgrade: websocket\r\n"
. "Connection: Upgrade\r\n"
. "Sec-WebSocket-Accept: {$accept_key}\r\n\r\n";
. "Upgrade: websocket\r\n"
. "Connection: Upgrade\r\n"
. "Sec-WebSocket-Accept: {$accept_key}\r\n\r\n";
fwrite($socket, $response_header);
}
/**
* Read specific number of bytes from a web socket
*
* @param resource $socket
* @param int $length
* @param int $length
*
* @return string
*/
private function read_bytes($socket, int $length): string {
@@ -379,15 +445,17 @@ class websocket_server {
/**
* Reads a web socket data frame and converts it to a regular string
*
* @param resource $socket
* @return string
*
* @return string|null
*/
private function receive_frame($socket): string {
private function receive_frame($socket): ?string {
if (!is_resource($socket)) {
throw new \RuntimeException("Not connected");
}
$final_frame = false;
$final_frame = false;
$payload_data = '';
while (!$final_frame) {
@@ -399,8 +467,8 @@ class websocket_server {
$byte2 = ord($header[1]);
$final_frame = ($byte1 >> 7) & 1;
$opcode = $byte1 & 0x0F;
$masked = ($byte2 >> 7) & 1;
$opcode = $byte1 & 0x0F;
$masked = ($byte2 >> 7) & 1;
$payload_len = $byte2 & 0x7F;
// Extended payload length
@@ -480,8 +548,11 @@ class websocket_server {
/**
* Send text frame to client. If the socket connection is not a valid resource, the send
* method will fail silently and return false.
* @param resource $resource The socket or resource id to communicate on.
* @param string|null $payload The message to send to the clients. Sending null as the message sends a close frame packet.
*
* @param resource $resource The socket or resource id to communicate on.
* @param string|null $payload The message to send to the clients. Sending null as the message sends a close frame
* packet.
*
* @return bool True if message was sent on the provided resource or false if there was an error.
*/
public static function send($resource, ?string $payload): bool {
@@ -496,20 +567,20 @@ class websocket_server {
return true;
}
$chunk_size = 4096; // 4 KB
$chunk_size = 4096; // 4 KB
$payload_len = strlen($payload);
$offset = 0;
$first = true;
$offset = 0;
$first = true;
while ($offset < $payload_len) {
$remaining = $payload_len - $offset;
$chunk = substr($payload, $offset, min($chunk_size, $remaining));
$chunk = substr($payload, $offset, min($chunk_size, $remaining));
$chunk_len = strlen($chunk);
// Determine FIN bit and opcode
$fin = ($offset + $chunk_size >= $payload_len) ? 0x80 : 0x00; // 0x80 if final
$fin = ($offset + $chunk_size >= $payload_len) ? 0x80 : 0x00; // 0x80 if final
$opcode = $first ? 0x1 : 0x0; // text for first frame, continuation for rest
$first = false;
$first = false;
// Build header
$header = chr($fin | $opcode);
@@ -542,7 +613,9 @@ class websocket_server {
/**
* Get the IP and port of the connected remote system.
*
* @param socket $socket The socket stream of the connection
*
* @return array An associative array of remote_ip and remote_port
*/
public static function get_remote_info($socket): array {
@@ -552,9 +625,10 @@ class websocket_server {
/**
* Print socket information
*
* @param resource $resource
* @param bool $return If you would like to capture the output of print_r(), use the return parameter. When this
* parameter is set to true, print_r() will return the information rather than print it.
* @param bool $return If you would like to capture the output of print_r(), use the return parameter. When this
* parameter is set to true, print_r() will return the information rather than print it.
*/
public static function print_stream_info($resource, $return = false) {
if (is_resource($resource)) {

153
core/websockets/resources/classes/websocket_service.php
View File

@@ -35,48 +35,56 @@ class websocket_service extends service {
/**
* Address to bind to. (Default 8080)
*
* @var string
*/
protected $ip;
/**
* Port to bind to. (Default 0.0.0.0 - all PHP detected IP addresses of the system)
*
* @var int
*/
protected $port;
/**
* Resource or stream of the server socket binding
*
* @var resource|stream
*/
protected $server_socket;
/**
* List of connected client sockets
*
* @var array
*/
protected $clients;
/**
* Used to track on_message events
*
* @var array
*/
protected $message_callbacks;
/**
* Used to track on_connect events
*
* @var array
*/
protected $connect_callbacks;
/**
* Used to track on_disconnect events
*
* @var array
*/
protected $disconnect_callbacks;
/**
* Used to track switch listeners or other socket connection types
*
* @var array
*/
protected $listeners;
@@ -84,12 +92,14 @@ class websocket_service extends service {
/**
* Subscriber Objects
*
* @var subscriber
*/
protected $subscribers;
/**
* Array of registered services
*
* @var array
*/
private $services;
@@ -100,18 +110,19 @@ class websocket_service extends service {
/**
* Reload settings
*
* @return void
* @throws \RuntimeException
* @access protected
*/
protected function reload_settings(): void {
// Initialize tracking arrays
$this->listeners = [];
$this->clients = [];
$this->message_callbacks = [];
$this->connect_callbacks = [];
$this->listeners = [];
$this->clients = [];
$this->message_callbacks = [];
$this->connect_callbacks = [];
$this->disconnect_callbacks = [];
$this->subscribers = [];
$this->subscribers = [];
$settings = new settings(['database' => database::new(['config' => config::load()])]);
@@ -134,6 +145,7 @@ class websocket_service extends service {
/**
* Display the version on the console
*
* @return void
* @access protected
*/
@@ -143,6 +155,7 @@ class websocket_service extends service {
/**
* Set extra command options from the command line
*
* @access protected
*/
protected static function set_command_options() {
@@ -170,6 +183,13 @@ class websocket_service extends service {
}
}
/**
* Retrieves a subscriber object from the given socket ID.
*
* @param mixed $socket The socket ID to search for
*
* @return subscriber|null The matching subscriber, or null if not found
*/
private function get_subscriber_from_socket_id($socket): ?subscriber {
$subscriber = null;
// Get the subscriber based on their socket ID
@@ -182,6 +202,16 @@ class websocket_service extends service {
return $subscriber;
}
/**
* Authenticate a subscriber based on the provided token and message.
*
* @param subscriber $subscriber The subscriber to authenticate.
* @param websocket_message $message The message containing the authentication token.
*
* @return bool Whether the authentication was successful or not.
* @throws \socket_disconnected_exception
* @throws \subscriber_token_expired_exception
*/
private function authenticate_subscriber(subscriber $subscriber, websocket_message $message) {
$this->info("Authenticating client: $subscriber->id");
@@ -204,7 +234,7 @@ class websocket_service extends service {
foreach ($subscriptions as $subscribed_to) {
if (isset($this->services[$subscribed_to])) {
$subscriber_service = $this->services[$subscribed_to];
$class_name = $subscriber_service->service_class();
$class_name = $subscriber_service->service_class();
// Make sure we can call the 'create_filter_chain_for' method
if (is_a($class_name, 'websocket_service_interface', true)) {
// Call the service class method to validate the subscriber
@@ -227,6 +257,14 @@ class websocket_service extends service {
return;
}
/**
* Broadcast a message to all subscribers except the specified broadcaster.
*
* @param subscriber $broadcaster The subscriber that is broadcasting the message.
* @param websocket_message|null $message The message being broadcasted. If null, do nothing.
*
* @return void
*/
private function broadcast_service_message(subscriber $broadcaster, ?websocket_message $message = null) {
$this->debug("Processing Broadcast");
@@ -268,8 +306,7 @@ class websocket_service extends service {
$this->handle_disconnect($subscriber->socket_id());
}
}
}
// Route a specific request from a service back to a subscriber
} // Route a specific request from a service back to a subscriber
else {
// Get the subscriber object hash
$object_id = $message->resource_id;
@@ -288,9 +325,11 @@ class websocket_service extends service {
/**
* Filters subscribers based on the service name given
* @param array $subscribers
*
* @param array $subscribers
* @param websocket_message $message
* @param string $service_name
* @param string $service_name
*
* @return array List of subscriber objects or an empty array if there are no subscribers to that service name
*/
private function filter_subscribers(array $subscribers, websocket_message $message, string $service_name): array {
@@ -299,7 +338,7 @@ class websocket_service extends service {
foreach ($subscribers as $subscriber) {
$caller_context = strtolower($message->caller_context ?? '');
if (!empty($caller_context) && $subscriber->has_subscribed_to($service_name) && ($subscriber->show_all || $caller_context === $subscriber->domain_name || $caller_context === 'public' || $caller_context === 'default'
)
)
) {
$filtered[] = $subscriber;
} else {
@@ -313,13 +352,15 @@ class websocket_service extends service {
/**
* Create a subscriber for each connection
*
* @param resource $socket
*
* @return void
*/
private function handle_connect($socket) {
// We catch only the socket disconnection exception as there is a general try/catch already
try {
$subscriber = new subscriber($socket, [websocket_service::class, 'send']);
$subscriber = new subscriber($socket, [websocket_service::class, 'send']);
$this->subscribers[$subscriber->id] = $subscriber;
$subscriber->send(websocket_message::connected());
} catch (\socket_disconnected_exception $sde) {
@@ -332,6 +373,7 @@ class websocket_service extends service {
/**
* Web socket client disconnected from the server or this service has requested a disconnect from the subscriber
*
* @param subscriber|resource|int|string $object_or_resource_or_id
*/
private function handle_disconnect($object_or_resource_or_id) {
@@ -377,8 +419,9 @@ class websocket_service extends service {
/**
* When a message event occurs, send to all the subscribers
*
* @param resource $socket
* @param mixed $data
* @param mixed $data
*/
private function handle_message($socket, $data) {
$subscriber = $this->get_subscriber_from_socket_id($socket);
@@ -436,6 +479,14 @@ class websocket_service extends service {
}
}
/**
* Handle a client message by routing it to its intended service.
*
* @param subscriber $subscriber The client subscriber instance associated with the incoming message.
* @param websocket_message $message The incoming WebSocket message containing details about the request.
*
* @return void
*/
private function handle_client_message(subscriber $subscriber, websocket_message $message) {
//find the service with that name
foreach ($this->subscribers as $service) {
@@ -454,7 +505,7 @@ class websocket_service extends service {
$message->resource_id = $subscriber->id;
//send the modified web socket message to the service
$service->send((string) $message);
$service->send((string)$message);
//continue searching for service providers
continue;
@@ -465,6 +516,7 @@ class websocket_service extends service {
/**
* Runs the web socket server binding to the ip and port set in default settings
* The run method will stop if the SIG_TERM or SIG_HUP signal is processed in the parent
*
* @return int
* @throws \RuntimeException
* @throws socket_exception
@@ -494,7 +546,7 @@ class websocket_service extends service {
//
// Merge all sockets to a single array
//
$read = array_merge([$this->server_socket], $this->clients);
$read = array_merge([$this->server_socket], $this->clients);
$write = $except = [];
//$this->debug("Waiting on event. Connected Clients: (".count($this->clients).")", LOG_DEBUG);
@@ -577,10 +629,10 @@ class websocket_service extends service {
// Get the error details
//
$subscriber_id = $se->getSubscriberId();
$message = $se->getMessage();
$code = $se->getCode();
$file = $se->getFile();
$line = $se->getLine();
$message = $se->getMessage();
$code = $se->getCode();
$file = $se->getFile();
$line = $se->getLine();
//
// Dump the details in the log
@@ -595,10 +647,12 @@ class websocket_service extends service {
}
}
}
return 0;
}
/**
* Overrides the parent class to shutdown all sockets
*
* @override service
*/
public function __destruct() {
@@ -610,12 +664,18 @@ class websocket_service extends service {
parent::__destruct();
}
/**
* Retrieves an array of open sockets.
*
* @return array An array containing open socket connections.
*/
public function get_open_sockets(): array {
return $this->clients;
}
/**
* Returns true if there are connected web socket clients.
*
* @return bool
*/
public function has_clients(): bool {
@@ -625,7 +685,9 @@ class websocket_service extends service {
/**
* When a web socket message is received the $on_message_callback function is called.
* Multiple on_message functions can be specified.
*
* @param callable $on_message_callback
*
* @throws InvalidArgumentException
*/
public function on_message(callable $on_message_callback) {
@@ -637,8 +699,10 @@ class websocket_service extends service {
/**
* Calls all the on_message functions
*
* @param resource $resource
* @param string $message
* @param string $message
*
* @return void
* @access protected
*/
@@ -652,7 +716,9 @@ class websocket_service extends service {
/**
* When a web socket handshake has completed, the $on_connect_callback function is called.
* Multiple on_connect functions can be specified.
*
* @param callable $on_connect_callback
*
* @throws InvalidArgumentException
*/
public function on_connect(callable $on_connect_callback) {
@@ -664,7 +730,9 @@ class websocket_service extends service {
/**
* Calls all the on_connect functions
*
* @param resource $resource
*
* @access protected
*/
protected function trigger_connect($resource) {
@@ -676,7 +744,9 @@ class websocket_service extends service {
/**
* When a web socket has disconnected, the $on_disconnect_callback function is called.
* Multiple functions can be specified with subsequent calls
*
* @param string|callable $on_disconnect_callback
*
* @throws InvalidArgumentException
*/
public function on_disconnect($on_disconnect_callback) {
@@ -688,7 +758,9 @@ class websocket_service extends service {
/**
* Calls all the on_disconnect_callback functions
*
* @param resource $socket
*
* @access protected
*/
protected function trigger_disconnect($socket) {
@@ -699,6 +771,7 @@ class websocket_service extends service {
/**
* Returns the socket used in the server connection
*
* @return resource
*/
public function get_socket() {
@@ -707,7 +780,9 @@ class websocket_service extends service {
/**
* Remove a client socket on disconnect.
*
* @param resource $resource Resource for the socket connection
*
* @return bool Returns true on client disconnect and false when the client is not found in the tracking array
* @access protected
*/
@@ -750,6 +825,8 @@ class websocket_service extends service {
/**
* Performs web socket handshake on new connection.
*
* @param resource $resource
* @access protected
*/
protected function handshake($resource): void {
@@ -765,21 +842,23 @@ class websocket_service extends service {
if (!preg_match("/Sec-WebSocket-Key: (.*)\r\n/i", $request_header, $matches)) {
throw new invalid_handshake_exception($resource, "Invalid WebSocket handshake");
}
$key = trim($matches[1]);
$accept_key = base64_encode(
sha1($key . "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", true)
$key = trim($matches[1]);
$accept_key = base64_encode(
sha1($key . "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", true)
);
$response_header = "HTTP/1.1 101 Switching Protocols\r\n"
. "Upgrade: websocket\r\n"
. "Connection: Upgrade\r\n"
. "Sec-WebSocket-Accept: {$accept_key}\r\n\r\n";
. "Upgrade: websocket\r\n"
. "Connection: Upgrade\r\n"
. "Sec-WebSocket-Accept: {$accept_key}\r\n\r\n";
fwrite($resource, $response_header);
}
/**
* Read specific number of bytes from a websocket
*
* @param resource $socket
* @param int $length
* @param int $length
*
* @return string
*/
private function read_bytes($socket, int $length): string {
@@ -797,7 +876,9 @@ class websocket_service extends service {
/**
* Reads a websocket data frame and converts it to a regular string
*
* @param resource $socket
*
* @return string
*/
private function receive_frame($socket): string {
@@ -810,8 +891,8 @@ class websocket_service extends service {
$this->update_connected_clients();
return '';
}
$bytes = unpack('Cfirst/Csecond', $hdr);
$fin = ($bytes['first'] >> 7) & 0x1;
$bytes = unpack('Cfirst/Csecond', $hdr);
$fin = ($bytes['first'] >> 7) & 0x1;
$opcode = $bytes['first'] & 0x0F;
$masked = ($bytes['second'] >> 7) & 0x1;
$length = $bytes['second'] & 0x7F;
@@ -829,7 +910,7 @@ class websocket_service extends service {
if (strlen($ext) < 8)
return '';
// unpack 64-bit BE; PHP 7.0+: use J, else fallback
$arr = unpack('J', $ext);
$arr = unpack('J', $ext);
$length = $arr[1];
}
@@ -863,8 +944,10 @@ class websocket_service extends service {
/**
* Send text frame to client. If the socket connection is not a valid resource, the send
* method will fail silently and return false.
* @param resource $resource The socket or resource id to communicate on.
* @param string|null $payload The string to wrap in a web socket frame to send to the clients
*
* @param resource $resource The socket or resource id to communicate on.
* @param string|null $payload The string to wrap in a web socket frame to send to the clients
*
* @return bool
*/
public static function send($resource, ?string $payload): bool {
@@ -878,7 +961,7 @@ class websocket_service extends service {
}
$payload_length = strlen($payload);
$frame_header = "\x81"; // FIN = 1, text frame
$frame_header = "\x81"; // FIN = 1, text frame
// Create frame header
if ($payload_length <= 125) {
$frame_header .= chr($payload_length);
@@ -893,7 +976,7 @@ class websocket_service extends service {
// Attempt to write full frame
$written = @fwrite($resource, $frame);
if ($written === false) {
self::log("fwrite() failed for socket " . (int) $resource, LOG_ERR);
self::log("fwrite() failed for socket " . (int)$resource, LOG_ERR);
throw new socket_disconnected_exception($resource);
}
@@ -907,7 +990,9 @@ class websocket_service extends service {
/**
* Get the IP and port of the connected remote system.
*
* @param resource $resource The resource or stream of the connection
*
* @return array An associative array of remote_ip and remote_port
*/
public static function get_remote_info($resource): array {