magic.lambda.sockets 14.1.3

.NET Standard 2.0
Install-Package magic.lambda.sockets -Version 14.1.3
dotnet add package magic.lambda.sockets --version 14.1.3
<PackageReference Include="magic.lambda.sockets" Version="14.1.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add magic.lambda.sockets --version 14.1.3
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: magic.lambda.sockets, 14.1.3"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install magic.lambda.sockets as a Cake Addin
#addin nuget:?package=magic.lambda.sockets&version=14.1.3

// Install magic.lambda.sockets as a Cake Tool
#tool nuget:?package=magic.lambda.sockets&version=14.1.3
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Using Web Sockets and SignalR from Hyperlambda

This project provides web sockets hooks for for Magic. The main idea of the project, is that it allows you to resolve Hyperlambda files, execute these, passing in a URL and JSON arguments over a web socket connection - In addition to subscribing to messages published by the server over a web socket connection from some client of your choosing. The project builds upon SignalR, but the internals are completely abstracted away, and you could probably easily exchange SignalR with any other web socket library with similar capabilities. The project contains one socket SignalR hub method with the following signature.

execute(string file, string json);

To connect to the hub use the relative URL /sockets, optionally passing in a JWT token, and then transmit messages to the hub using something such as for instance the following TypeScript.

let builder = new HubConnectionBuilder();

this.connection = builder.withUrl('http://localhost:5000/sockets', {
    accessTokenFactory: () => 'return-your-JWT-token-here'
  }).build();

this.connection.invoke(
  'execute',
  '/foo/some-hyperlambda-file',
  JSON.stringify({
    foo:'bar'
  }));

The above will resolve to a Hyperlambda file expected to exist at /modules/foo/some-hyperlambda-file.socket.hl, passing in the foo argument as lambda nodes.

[sockets.signal]

In addition to the above, you can explicitly publish SignalR events by signaling the [sockets.signal] slot, which will automatically transform the specified children [args] nodes to JSON, and invoke the specified method for all connections somehow subscribing to the specified method - Allowing you to filter according to groups, users and roles if you wish. Below is an example.

sockets.signal:foo.bar
   roles:root, admin
   args
      howdy:world

The above will invoke the foo.bar method, passing in {"howdy":"world"} as a JSON string, but only users belonging to the roles of either admin or root will be notified. Both the [roles] and the [args] arguments are optional. To subscribe to the above invocation, you could use something such as the following in TypeScript.

this.connection.on('foo.bar', (args: string) => {
  console.log(JSON.parse(args));
});

You can also signal a list of specified users, such as the following illustrates.

sockets.signal:foo.bar
   users:user1, user2, user3
   args
      howdy:world

In addition to that you can signal a list of specified groups, such as the following illustrates.

sockets.signal:foo.bar
   groups:group1, group2, group3
   args
      howdy:world

Finally, you can signal a list of specified client connections, such as the following illustrates.

sockets.signal:foo.bar
   clients:e6U2Zz6kqHDCEVyEX6v35w, 5uWWytAM8kJ2gfIL0fEw2A
   args
      howdy:world

The above will only signal the two specified client connections.

Notice - If you signal a group or a list of groups, you'll have to add your users to the group before you do.

Arguments to [sockets.signal]

  • [roles] - Comma separated list of roles to send message to
  • [users] - Comma separated list of users to send message to
  • [clients] - Comma separated list of client connections to send message to
  • [groups] - Comma separated list of groups to send message to
  • [args] - Arguments to transmit to subscribers as JSON (string)

Only one of [users], [roles], [clients], or [groups] can be supplied, and all the above arguments are optional.

Groups and users

You can associate a user with one or more groups. This is done with the following slots.

  • [sockets.user.add-to-group] - Adds the specified user to the specified group
  • [sockets.user.remove-from-group] - Removes the specified user from the specified group

Below you can find an example of how to add a user to a group, for then to later de-associate the user with the group.

// Associating a user with a group.
sockets.user.add-to-group:some-username-here
   group:some-group-name-here

// Publishing message, now to group, such that 'some-username-here' gets it
sockets.signal:foo.bar
   group:some-group-name-here
   args
      howdy:world

// De-associating the user with the group again.
sockets.user.remove-from-group:some-username-here
   group:some-group-name-here

Notice - SignalR users might have multiple connections. This implies that once you add a user to a group, all connections are associated with that group. The message will only be published to connections explicitly having registered an interest in the foo.bar message for our above example, irrelevant of whether the user belongs to the group or not.

Meta data

This project also allows you to retrieve meta data about currently connected users, through for instance the [sockets.users] slot and the [sockets.users.count] slot, that will return the username of all currently connected users, and the count matching your specified filter condition. An example of using it can be found below.

sockets.users
   filter:some-filter-condition
   offset:3
   limit:20

sockets.users.count
   filter:some-filter-condition

Notice - If a client connected anonymously somehow over a socket, the client will (obviously) not have a username, and the default userId will be returned instead. Also please notice, that each user might have multiple connections, and this will return each connection for each username matching the specified filter condition. The filter conditions and paging arguments are optional, and will be null and 0-10 if not specified.

Connection context

From within your Hyperlambda files executed by invoking the execute method, you have access to your SignalR connectionId as a context object named "sockets.connection". Below is an example of how to retrieve the current SignalR connectionId. Notice, this only works from within a socket executed Hyperlambda file, implying only if you're executing the file using the execute method, through your SignalR socket connection.

get-context:sockets.connection

This might sometimes be useful, especially if you want to dynamically add only one connection to a group for instance. To add the currently active connection explicitly to a group for instance, you can use the following slots.

  • [sockets.connection.enter-group] - Associates the current connection only with the specified group
  • [sockets.connection.leave-group] - De-associates the current connection with the specified group

If the user has additional connections, none of the other connections will be modified in any ways. Also realise that both of these slots can only be used from within a Hyperlambda file executed through a SignalR socket connection somehow. Below is an example.

// Retrieving connectionId
get-context:sockets.connection

// Entering group
sockets.connection.enter-group:x:@get-context
   group:foo-bar-group

// Do stuff here that requires the user to belong to group ...

// Leaving group
sockets.connection.leave-group:x:@get-context
   group:foo-bar-group

Project website

The source code for this repository can be found at github.com/polterguy/magic.lambda.sockets, and you can provide feedback, provide bug reports, etc at the same place.

Quality gates

  • Build status
  • Quality Gate Status
  • Bugs
  • Code Smells
  • Coverage
  • Duplicated Lines (%)
  • Lines of Code
  • Maintainability Rating
  • Reliability Rating
  • Security Rating
  • Technical Debt
  • Vulnerabilities
Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on magic.lambda.sockets:

Package Downloads
magic.library

Helper project for Magic to wire up everything easily by simply adding one package, and invoking two simple methods. When using Magic, this is (probably) the only package you should actually add, since this package pulls in everything else you'll need automatically, and wires up everything sanely by default. To use package go to https://polterguy.github.io

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
14.1.3 63 8/7/2022
14.1.2 48 8/7/2022
14.1.1 42 8/7/2022
14.0.14 98 7/26/2022
14.0.12 78 7/24/2022
14.0.11 78 7/23/2022
14.0.10 56 7/23/2022
14.0.9 55 7/23/2022
14.0.8 133 7/17/2022
14.0.5 205 7/11/2022
14.0.4 183 7/6/2022
14.0.3 120 7/2/2022
14.0.2 88 7/2/2022
14.0.0 106 6/25/2022
13.4.0 535 5/31/2022
13.3.4 392 5/9/2022
13.3.1 176 5/1/2022
13.3.0 115 5/1/2022
13.2.0 263 4/21/2022
13.1.0 284 4/7/2022
13.0.0 138 4/5/2022
11.0.5 442 3/2/2022
11.0.4 186 2/22/2022
11.0.3 187 2/9/2022
11.0.2 199 2/6/2022
11.0.1 171 2/5/2022
10.0.21 174 1/28/2022
10.0.20 171 1/27/2022
10.0.19 160 1/23/2022
10.0.18 141 1/17/2022
10.0.15 341 12/31/2021
10.0.14 227 12/28/2021
10.0.7 668 12/22/2021
10.0.5 331 12/18/2021
9.9.9 1,021 11/29/2021
9.9.3 360 11/9/2021
9.9.2 270 11/4/2021
9.9.0 385 10/30/2021
9.8.9 322 10/29/2021
9.8.7 286 10/27/2021
9.8.6 277 10/27/2021
9.8.5 345 10/26/2021
9.8.0 681 10/20/2021
9.7.9 291 10/19/2021
9.7.5 788 10/14/2021
9.7.2 146 10/14/2021
9.7.0 411 10/9/2021
9.6.6 637 8/14/2021
9.2.5 2,971 6/7/2021
9.2.3 428 6/6/2021
9.2.2 277 6/4/2021
9.2.1 403 6/1/2021