1 | import { MessageConnection } from 'vscode-ws-jsonrpc';
|
2 | import { Event, Emitter } from '../event';
|
3 | import { Disposable } from '../disposable';
|
4 | import { ConnectionHandler } from './handler';
|
5 | export declare type JsonRpcServer<Client> = Disposable & {
|
6 | |
7 |
|
8 |
|
9 |
|
10 |
|
11 | setClient(client: Client | undefined): void;
|
12 | getClient?(): Client | undefined;
|
13 | };
|
14 | export interface JsonRpcConnectionEventEmitter {
|
15 | readonly onDidOpenConnection: Event<void>;
|
16 | readonly onDidCloseConnection: Event<void>;
|
17 | }
|
18 | export declare type JsonRpcProxy<T> = T & JsonRpcConnectionEventEmitter;
|
19 | export declare class JsonRpcConnectionHandler<T extends object> implements ConnectionHandler {
|
20 | readonly path: string;
|
21 | readonly targetFactory: (proxy: JsonRpcProxy<T>) => any;
|
22 | readonly factoryConstructor: new () => JsonRpcProxyFactory<T>;
|
23 | constructor(path: string, targetFactory: (proxy: JsonRpcProxy<T>) => any, factoryConstructor?: new () => JsonRpcProxyFactory<T>);
|
24 | onConnection(connection: MessageConnection): void;
|
25 | }
|
26 | /**
|
27 | * Factory for JSON-RPC proxy objects.
|
28 | *
|
29 | * A JSON-RPC proxy exposes the programmatic interface of an object through
|
30 | * JSON-RPC. This allows remote programs to call methods of this objects by
|
31 | * sending JSON-RPC requests. This takes place over a bi-directional stream,
|
32 | * where both ends can expose an object and both can call methods each other's
|
33 | * exposed object.
|
34 | *
|
35 | * For example, assuming we have an object of the following type on one end:
|
36 | *
|
37 | * class Foo {
|
38 | * bar(baz: number): number { return baz + 1 }
|
39 | * }
|
40 | *
|
41 | * which we want to expose through a JSON-RPC interface. We would do:
|
42 | *
|
43 | * let target = new Foo()
|
44 | * let factory = new JsonRpcProxyFactory<Foo>('/foo', target)
|
45 | * factory.onConnection(connection)
|
46 | *
|
47 | * The party at the other end of the `connection`, in order to remotely call
|
48 | * methods on this object would do:
|
49 | *
|
50 | * let factory = new JsonRpcProxyFactory<Foo>('/foo')
|
51 | * factory.onConnection(connection)
|
52 | * let proxy = factory.createProxy();
|
53 | * let result = proxy.bar(42)
|
54 | * // result is equal to 43
|
55 | *
|
56 | * One the wire, it would look like this:
|
57 | *
|
58 | * --> {"jsonrpc": "2.0", "id": 0, "method": "bar", "params": {"baz": 42}}
|
59 | * <-- {"jsonrpc": "2.0", "id": 0, "result": 43}
|
60 | *
|
61 | * Note that in the code of the caller, we didn't pass a target object to
|
62 | * JsonRpcProxyFactory, because we don't want/need to expose an object.
|
63 | * If we had passed a target object, the other side could've called methods on
|
64 | * it.
|
65 | *
|
66 | * @param <T> - The type of the object to expose to JSON-RPC.
|
67 | */
|
68 | export declare class JsonRpcProxyFactory<T extends object> implements ProxyHandler<T> {
|
69 | target?: any;
|
70 | protected readonly onDidOpenConnectionEmitter: Emitter<void>;
|
71 | protected readonly onDidCloseConnectionEmitter: Emitter<void>;
|
72 | protected connectionPromiseResolve: (connection: MessageConnection) => void;
|
73 | protected connectionPromise: Promise<MessageConnection>;
|
74 | |
75 |
|
76 |
|
77 |
|
78 |
|
79 |
|
80 | constructor(target?: any);
|
81 | protected waitForConnection(): void;
|
82 | /**
|
83 | * Connect a MessageConnection to the factory.
|
84 | *
|
85 | * This connection will be used to send/receive JSON-RPC requests and
|
86 | * response.
|
87 | */
|
88 | listen(connection: MessageConnection): void;
|
89 | /**
|
90 | * Process an incoming JSON-RPC method call.
|
91 | *
|
92 | * onRequest is called when the JSON-RPC connection received a method call
|
93 | * request. It calls the corresponding method on [[target]].
|
94 | *
|
95 | * The return value is a Promise object that is resolved with the return
|
96 | * value of the method call, if it is successful. The promise is rejected
|
97 | * if the called method does not exist or if it throws.
|
98 | *
|
99 | * @returns A promise of the method call completion.
|
100 | */
|
101 | protected onRequest(method: string, ...args: any[]): Promise<any>;
|
102 | /**
|
103 | * Process an incoming JSON-RPC notification.
|
104 | *
|
105 | * Same as [[onRequest]], but called on incoming notifications rather than
|
106 | * methods calls.
|
107 | */
|
108 | protected onNotification(method: string, ...args: any[]): void;
|
109 | /**
|
110 | * Create a Proxy exposing the interface of an object of type T. This Proxy
|
111 | * can be used to do JSON-RPC method calls on the remote target object as
|
112 | * if it was local.
|
113 | *
|
114 | * If `T` implements `JsonRpcServer` then a client is used as a target object for a remote target object.
|
115 | */
|
116 | createProxy(): JsonRpcProxy<T>;
|
117 | /**
|
118 | * Get a callable object that executes a JSON-RPC method call.
|
119 | *
|
120 | * Getting a property on the Proxy object returns a callable that, when
|
121 | * called, executes a JSON-RPC call. The name of the property defines the
|
122 | * method to be called. The callable takes a variable number of arguments,
|
123 | * which are passed in the JSON-RPC method call.
|
124 | *
|
125 | * For example, if you have a Proxy object:
|
126 | *
|
127 | * let fooProxyFactory = JsonRpcProxyFactory<Foo>('/foo')
|
128 | * let fooProxy = fooProxyFactory.createProxy()
|
129 | *
|
130 | * accessing `fooProxy.bar` will return a callable that, when called,
|
131 | * executes a JSON-RPC method call to method `bar`. Therefore, doing
|
132 | * `fooProxy.bar()` will call the `bar` method on the remote Foo object.
|
133 | *
|
134 | * @param target - unused.
|
135 | * @param p - The property accessed on the Proxy object.
|
136 | * @param receiver - unused.
|
137 | * @returns A callable that executes the JSON-RPC call.
|
138 | */
|
139 | get(target: T, p: PropertyKey, receiver: any): any;
|
140 | /**
|
141 | * Return whether the given property represents a notification.
|
142 | *
|
143 | * A property leads to a notification rather than a method call if its name
|
144 | * begins with `notify` or `on`.
|
145 | *
|
146 | * @param p - The property being called on the proxy.
|
147 | * @return Whether `p` represents a notification.
|
148 | */
|
149 | protected isNotification(p: PropertyKey): boolean;
|
150 | protected serializeError(e: any): any;
|
151 | protected deserializeError(capturedError: Error, e: any): any;
|
152 | }
|
153 | //# sourceMappingURL=proxy-factory.d.ts.map |
\ | No newline at end of file |