Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
subscriptions-transport-ws
Advanced tools
The subscriptions-transport-ws package is a transport layer for handling GraphQL subscriptions. It uses WebSocket as the communication channel to provide a real-time data exchange between the server and the client. This package is commonly used in the context of GraphQL servers to enable live updates to queries.
Setting up a subscription server
This code sample demonstrates how to set up a GraphQL subscription server using the subscriptions-transport-ws package. It creates a new instance of SubscriptionServer and attaches it to an HTTP server.
const { SubscriptionServer } = require('subscriptions-transport-ws');
const { execute, subscribe } = require('graphql');
const { createServer } = require('http');
const server = createServer((req, res) => {
res.writeHead(404);
res.end();
});
server.listen(3000, () => {
new SubscriptionServer({
execute,
subscribe,
schema: myGraphQLSchema
}, {
server: server,
path: '/subscriptions',
});
});
Connecting a client to the subscription server
This code sample shows how a client can connect to the subscription server and listen for real-time updates using the SubscriptionClient provided by the subscriptions-transport-ws package.
const { SubscriptionClient } = require('subscriptions-transport-ws');
const client = new SubscriptionClient('ws://localhost:3000/subscriptions', {
reconnect: true
});
client.request({
query: `subscription { newMessage { body sender } }`,
variables: {}
}).subscribe({
next(data) {
console.log(data);
},
error(err) {
console.error(err);
}
});
graphql-ws is a modern alternative to subscriptions-transport-ws, offering a similar set of functionalities for GraphQL subscriptions over WebSocket. It is designed to be more lightweight and focuses on the latest GraphQL over WebSocket protocol.
While not exclusively focused on subscriptions, apollo-server-express is a comprehensive GraphQL server that integrates with Express.js and supports subscriptions. It provides a more extensive set of features for building GraphQL APIs, including subscriptions, and is often used in conjunction with the subscriptions-transport-ws package.
The subscriptions-transport-ws
library is not being actively maintained. It is recommended that you use the graphql-ws library instead. For details read the GraphQL over WebSockets announcement.
(Work in progress!)
A GraphQL WebSocket server and client to facilitate GraphQL queries, mutations and subscriptions over WebSocket.
subscriptions-transport-ws
is an extension for GraphQL, and you can use it with any GraphQL client and server (not only Apollo).
See GitHunt-API and GitHunt-React for an example server and client integration.
Start by installing the package, using Yarn or NPM.
Using Yarn:
$ yarn add subscriptions-transport-ws
Or, using NPM:
$ npm install --save subscriptions-transport-ws
Note that you need to use this package on both GraphQL client and server.
This command also installs this package's dependencies, including
graphql-subscriptions
.
Starting with the server, create a new simple PubSub
instance. We will later use this PubSub
to publish and subscribe to data changes.
import { PubSub } from 'graphql-subscriptions';
export const pubsub = new PubSub();
Now, create SubscriptionServer
instance, with your GraphQL schema
, execute
and subscribe
(from graphql-js
package):
import { createServer } from 'http';
import { SubscriptionServer } from 'subscriptions-transport-ws';
import { execute, subscribe } from 'graphql';
import { schema } from './my-schema';
const WS_PORT = 5000;
// Create WebSocket listener server
const websocketServer = createServer((request, response) => {
response.writeHead(404);
response.end();
});
// Bind it to port and start listening
websocketServer.listen(WS_PORT, () => console.log(
`Websocket Server is now running on http://localhost:${WS_PORT}`
));
const subscriptionServer = SubscriptionServer.create(
{
schema,
execute,
subscribe,
},
{
server: websocketServer,
path: '/graphql',
},
);
Please refer to graphql-subscriptions
documentation for how to create your GraphQL subscriptions, and how to publish data.
When using this package for client side, you can choose either use HTTP request for Queries and Mutation and use the WebSocket for subscriptions only, or create a full transport that handles all type of GraphQL operations over the socket.
To start with a full WebSocket transport, that handles all types of GraphQL operations, import and create an instance of SubscriptionClient
.
Then, create your ApolloClient
instance and use the SubscriptionsClient
instance as network interface:
import { SubscriptionClient } from 'subscriptions-transport-ws';
import ApolloClient from 'apollo-client';
const GRAPHQL_ENDPOINT = 'ws://localhost:3000/graphql';
const client = new SubscriptionClient(GRAPHQL_ENDPOINT, {
reconnect: true,
});
const apolloClient = new ApolloClient({
networkInterface: client,
});
To start with a hybrid WebSocket transport, that handles only subscription
s over WebSocket, create your SubscriptionClient
and a regular HTTP network interface, then extend your network interface to use the WebSocket client for GraphQL subscriptions:
import {SubscriptionClient, addGraphQLSubscriptions} from 'subscriptions-transport-ws';
import ApolloClient, {createNetworkInterface} from 'apollo-client';
// Create regular NetworkInterface by using apollo-client's API:
const networkInterface = createNetworkInterface({
uri: 'http://localhost:3000' // Your GraphQL endpoint
});
// Create WebSocket client
const wsClient = new SubscriptionClient(`ws://localhost:5000/`, {
reconnect: true,
connectionParams: {
// Pass any arguments you want for initialization
}
});
// Extend the network interface with the WebSocket
const networkInterfaceWithSubscriptions = addGraphQLSubscriptions(
networkInterface,
wsClient
);
// Finally, create your ApolloClient instance with the modified network interface
const apolloClient = new ApolloClient({
networkInterface: networkInterfaceWithSubscriptions
});
Now, when you want to use subscriptions in client side, use your ApolloClient
instance, with subscribe
or query
subscribeToMore
:
apolloClient.subscribe({
query: gql`
subscription onNewItem {
newItemCreated {
id
}
}`,
variables: {}
}).subscribe({
next (data) {
// Notify your application with the new arrived data
}
});
apolloClient.query({
query: ITEM_LIST_QUERY,
variables: {}
}).subscribeToMore({
document: gql`
subscription onNewItem {
newItemCreated {
id
}
}`,
variables: {},
updateQuery: (prev, { subscriptionData, variables }) => {
// Perform updates on previousResult with subscriptionData
return updatedResult;
}
});
If you don't use any package/modules loader, you can still use this package, by using unpkg
service, and get the client side package from:
https://unpkg.com/subscriptions-transport-ws@VERSION/browser/client.js
Replace VERSION with the latest version of the package.
You can use this package's power with GraphiQL, and subscribe to live-data stream inside GraphiQL.
If you are using the latest version of graphql-server
flavors (graphql-server-express
, graphql-server-koa
, etc...), you already can use it! Make sure to specify subscriptionsEndpoint
in GraphiQL configuration, and that's it!
For example, graphql-server-express
users need to add the following:
app.use('/graphiql', graphiqlExpress({
endpointURL: '/graphql',
subscriptionsEndpoint: `YOUR_SUBSCRIPTION_ENDPOINT_HERE`,
}));
If you are using older version, or another GraphQL server, start by modifying GraphiQL static HTML, and add this package and it's fetcher from CDN:
<script src="//unpkg.com/subscriptions-transport-ws@0.5.4/browser/client.js"></script>
<script src="//unpkg.com/graphiql-subscriptions-fetcher@0.0.2/browser/client.js"></script>
Then, create SubscriptionClient
and define the fetcher:
let subscriptionsClient = new window.SubscriptionsTransportWs.SubscriptionClient('SUBSCRIPTION_WS_URL_HERE', {
reconnect: true
});
let myCustomFetcher = window.GraphiQLSubscriptionsFetcher.graphQLFetcher(subscriptionsClient, graphQLFetcher);
graphQLFetcher
is the default fetcher, and we use it as fallback for non-subscription GraphQL operations.
And replace your GraphiQL creation logic to use the new fetcher:
ReactDOM.render(
React.createElement(GraphiQL, {
fetcher: myCustomFetcher, // <-- here
onEditQuery: onEditQuery,
onEditVariables: onEditVariables,
onEditOperationName: onEditOperationName,
query: ${safeSerialize(queryString)},
response: ${safeSerialize(resultString)},
variables: ${safeSerialize(variablesString)},
operationName: ${safeSerialize(operationName)},
}),
document.body
);
Constructor(url, options, webSocketImpl)
url: string
: url that the client will connect to, starts with ws://
or wss://
options?: Object
: optional, object to modify default client behavior
timeout?: number
: how long the client should wait in ms for a keep-alive message from the server (default 30000 ms), this parameter is ignored if the server does not send keep-alive messages. This will also be used to calculate the max connection time per connect/reconnectminTimeout?: number
: the minimum amount of time the client should wait for a connection to be made (default 1000 ms)lazy?: boolean
: use to set lazy mode - connects only when first subscription created, and delay the socket initializationconnectionParams?: Object | Function | Promise<Object>
: object that will be available as first argument of onConnect
(in server side), if passed a function - it will call it and send the return value, if function returns as promise - it will wait until it resolves and send the resolved value.reconnect?: boolean
: automatic reconnect in case of connection errorreconnectionAttempts?: number
: how much reconnect attemptsconnectionCallback?: (error) => {}
: optional, callback that called after the first init message, with the error (if there is one)inactivityTimeout?: number
: how long the client should wait in ms, when there are no active subscriptions, before disconnecting from the server. Set to 0 to disable this behavior. (default 0)webSocketImpl?: Object
- optional, constructor for W3C compliant WebSocket implementation. Use this when your environment does not have a built-in native WebSocket (for example, with NodeJS client)request(options) => Observable<ExecutionResult>
: returns observable to execute the operation.options: {OperationOptions}
query: string
: GraphQL subscriptionvariables: Object
: GraphQL subscription variablesoperationName: string
: operation name of the subscriptioncontext: Object
: use to override context for a specific callunsubscribeAll() => void
- unsubscribes from all active subscriptions.on(eventName, callback, thisContext) => Function
eventName: string
: the name of the event, available events are: connecting
, connected
, reconnecting
, reconnected
, disconnected
and error
callback: Function
: function to be called when websocket connects and initialized.thisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onConnected(callback, thisContext) => Function
- shorthand for .on('connected', ...)
callback: Function(payload)
: function to be called when websocket connects and initialized, after ACK message returned from the server. Includes payload from server, if any.thisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onReconnected(callback, thisContext) => Function
- shorthand for .on('reconnected', ...)
callback: Function(payload)
: function to be called when websocket reconnects and initialized, after ACK message returned from the server. Includes payload from server, if any.thisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onConnecting(callback, thisContext) => Function
- shorthand for .on('connecting', ...)
callback: Function
: function to be called when websocket starts it's connectionthisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onReconnecting(callback, thisContext) => Function
- shorthand for .on('reconnecting', ...)
callback: Function
: function to be called when websocket starts it's reconnectionthisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onDisconnected(callback, thisContext) => Function
- shorthand for .on('disconnected', ...)
callback: Function
: function to be called when websocket disconnected.thisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.onError(callback, thisContext) => Function
- shorthand for .on('error', ...)
callback: Function
: function to be called when an error occurs.thisContext: any
: this
context to use when calling the callback function.off
method to cancel the event subscription.close() => void
- closes the WebSocket connection manually, and ignores reconnect
logic if it was set to true
.use(middlewares: MiddlewareInterface[]) => SubscriptionClient
- adds middleware to modify OperationOptions
per each requestmiddlewares: MiddlewareInterface[]
- Array contains list of middlewares (implemented applyMiddleware
method) implementation, the SubscriptionClient
will use the middlewares to modify OperationOptions
for every operationstatus: number
: returns the current socket's readyState
Constructor(options, socketOptions | socketServer)
options: {ServerOptions}
rootValue?: any
: Root value to use when executing GraphQL root operationsschema?: GraphQLSchema
: GraphQL schema object. If not provided, you have to return the schema as a property on the object returned from onOperation
.execute?: (schema, document, rootValue, contextValue, variableValues, operationName) => Promise<ExecutionResult> | AsyncIterator<ExecutionResult>
: GraphQL execute
function, provide the default one from graphql
package. Return value of AsyncItrator
is also valid since this package also support reactive execute
methods.subscribe?: (schema, document, rootValue, contextValue, variableValues, operationName) => Promise<ExecutionResult | AsyncIterator<ExecutionResult>>
: GraphQL subscribe
function, provide the default one from graphql
package.onOperation?: (message: SubscribeMessage, params: ExecutionParams, webSocket: WebSocket)
: optional method to create custom params that will be used when resolving this operation. It can also be used to dynamically resolve the schema that will be used for the particular operation.onOperationComplete?: (webSocket: WebSocket, opId: string)
: optional method that called when a GraphQL operation is done (for query and mutation it's immediately, and for subscriptions when unsubscribing)onConnect?: (connectionParams: Object, webSocket: WebSocket, context: ConnectionContext)
: optional method that called when a client connects to the socket, called with the connectionParams
from the client, if the return value is an object, its elements will be added to the context. return false
or throw an exception to reject the connection. May return a Promise.onDisconnect?: (webSocket: WebSocket, context: ConnectionContext)
: optional method that called when a client disconnectskeepAlive?: number
: optional interval in ms to send KEEPALIVE
messages to all clientssocketOptions: {WebSocket.IServerOptions}
: options to pass to the WebSocket object (full docs here)
server?: HttpServer
- existing HTTP server to use (use without host
/port
)host?: string
- server hostport?: number
- server portpath?: string
- endpoint pathsocketServer: {WebSocket.Server}
: a configured server if you need more control. Can be used for integration testing with in-memory WebSocket implementation.
AsyncIterator
internally using iterall, for more information click here, or the proposalThe current version of this transport, also support a previous version of the protocol.
v0.11.0 (2021-11-02)
graphql@16
and bump minimal supported version to be graphql@15.7.2
. As part of this change signatures for ExecuteFunction
and SubscribeFunction
were changed. <br/>
@IvanGoncharov in #902FAQs
A websocket transport for GraphQL subscriptions
The npm package subscriptions-transport-ws receives a total of 1,318,139 weekly downloads. As such, subscriptions-transport-ws popularity was classified as popular.
We found that subscriptions-transport-ws demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.