]> git.bitcoin.ninja Git - ldk-java/blob - src/main/java/org/ldk/structs/PeerManager.java
4a73a3a6918824d21370bbc89fd1e031220f124f
[ldk-java] / src / main / java / org / ldk / structs / PeerManager.java
1 package org.ldk.structs;
2
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
5 import org.ldk.util.*;
6 import java.util.Arrays;
7
8
9 /**
10  * A PeerManager manages a set of peers, described by their SocketDescriptor and marshalls socket
11  * events into messages which it passes on to its MessageHandlers.
12  * 
13  * Rather than using a plain PeerManager, it is preferable to use either a SimpleArcPeerManager
14  * a SimpleRefPeerManager, for conciseness. See their documentation for more details, but
15  * essentially you should default to using a SimpleRefPeerManager, and use a
16  * SimpleArcPeerManager when you require a PeerManager with a static lifetime, such as when
17  * you're using lightning-net-tokio.
18  */
19 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
20 public class PeerManager extends CommonBase {
21         PeerManager(Object _dummy, long ptr) { super(ptr); }
22         @Override @SuppressWarnings("deprecation")
23         protected void finalize() throws Throwable {
24                 super.finalize();
25                 if (ptr != 0) { bindings.PeerManager_free(ptr); }
26         }
27
28         /**
29          * Constructs a new PeerManager with the given message handlers and node_id secret key
30          * ephemeral_random_data is used to derive per-connection ephemeral keys and must be
31          * cryptographically secure random bytes.
32          */
33         public static PeerManager constructor_new(ChannelMessageHandler message_handler_chan_handler_arg, RoutingMessageHandler message_handler_route_handler_arg, byte[] our_node_secret, byte[] ephemeral_random_data, Logger logger) {
34                 long ret = bindings.PeerManager_new(bindings.MessageHandler_new(message_handler_chan_handler_arg == null ? 0 : message_handler_chan_handler_arg.ptr, message_handler_route_handler_arg == null ? 0 : message_handler_route_handler_arg.ptr), our_node_secret, ephemeral_random_data, logger == null ? 0 : logger.ptr);
35                 PeerManager ret_hu_conv = new PeerManager(null, ret);
36                 ret_hu_conv.ptrs_to.add(ret_hu_conv);
37                 ret_hu_conv.ptrs_to.add(message_handler_chan_handler_arg);
38                 ret_hu_conv.ptrs_to.add(message_handler_route_handler_arg);
39                 ret_hu_conv.ptrs_to.add(logger);
40                 return ret_hu_conv;
41         }
42
43         /**
44          * Get the list of node ids for peers which have completed the initial handshake.
45          * 
46          * For outbound connections, this will be the same as the their_node_id parameter passed in to
47          * new_outbound_connection, however entries will only appear once the initial handshake has
48          * completed and we are sure the remote peer has the private key for the given node_id.
49          */
50         public byte[][] get_peer_node_ids() {
51                 byte[][] ret = bindings.PeerManager_get_peer_node_ids(this.ptr);
52                 return ret;
53         }
54
55         /**
56          * Indicates a new outbound connection has been established to a node with the given node_id.
57          * Note that if an Err is returned here you MUST NOT call socket_disconnected for the new
58          * descriptor but must disconnect the connection immediately.
59          * 
60          * Returns a small number of bytes to send to the remote node (currently always 50).
61          * 
62          * Panics if descriptor is duplicative with some other descriptor which has not yet had a
63          * socket_disconnected().
64          */
65         public Result_CVec_u8ZPeerHandleErrorZ new_outbound_connection(byte[] their_node_id, SocketDescriptor descriptor) {
66                 long ret = bindings.PeerManager_new_outbound_connection(this.ptr, their_node_id, descriptor == null ? 0 : descriptor.ptr);
67                 Result_CVec_u8ZPeerHandleErrorZ ret_hu_conv = Result_CVec_u8ZPeerHandleErrorZ.constr_from_ptr(ret);
68                 this.ptrs_to.add(descriptor);
69                 return ret_hu_conv;
70         }
71
72         /**
73          * Indicates a new inbound connection has been established.
74          * 
75          * May refuse the connection by returning an Err, but will never write bytes to the remote end
76          * (outbound connector always speaks first). Note that if an Err is returned here you MUST NOT
77          * call socket_disconnected for the new descriptor but must disconnect the connection
78          * immediately.
79          * 
80          * Panics if descriptor is duplicative with some other descriptor which has not yet had
81          * socket_disconnected called.
82          */
83         public Result_NonePeerHandleErrorZ new_inbound_connection(SocketDescriptor descriptor) {
84                 long ret = bindings.PeerManager_new_inbound_connection(this.ptr, descriptor == null ? 0 : descriptor.ptr);
85                 Result_NonePeerHandleErrorZ ret_hu_conv = Result_NonePeerHandleErrorZ.constr_from_ptr(ret);
86                 this.ptrs_to.add(descriptor);
87                 return ret_hu_conv;
88         }
89
90         /**
91          * Indicates that there is room to write data to the given socket descriptor.
92          * 
93          * May return an Err to indicate that the connection should be closed.
94          * 
95          * Will most likely call send_data on the descriptor passed in (or the descriptor handed into
96          * new_*\\_connection) before returning. Thus, be very careful with reentrancy issues! The
97          * invariants around calling write_buffer_space_avail in case a write did not fully complete
98          * must still hold - be ready to call write_buffer_space_avail again if a write call generated
99          * here isn't sufficient! Panics if the descriptor was not previously registered in a
100          * new_\\*_connection event.
101          */
102         public Result_NonePeerHandleErrorZ write_buffer_space_avail(SocketDescriptor descriptor) {
103                 long ret = bindings.PeerManager_write_buffer_space_avail(this.ptr, descriptor == null ? 0 : descriptor.ptr);
104                 Result_NonePeerHandleErrorZ ret_hu_conv = Result_NonePeerHandleErrorZ.constr_from_ptr(ret);
105                 this.ptrs_to.add(descriptor);
106                 return ret_hu_conv;
107         }
108
109         /**
110          * Indicates that data was read from the given socket descriptor.
111          * 
112          * May return an Err to indicate that the connection should be closed.
113          * 
114          * Will *not* call back into send_data on any descriptors to avoid reentrancy complexity.
115          * Thus, however, you almost certainly want to call process_events() after any read_event to
116          * generate send_data calls to handle responses.
117          * 
118          * If Ok(true) is returned, further read_events should not be triggered until a send_data call
119          * on this file descriptor has resume_read set (preventing DoS issues in the send buffer).
120          * 
121          * Panics if the descriptor was not previously registered in a new_*_connection event.
122          */
123         public Result_boolPeerHandleErrorZ read_event(SocketDescriptor peer_descriptor, byte[] data) {
124                 long ret = bindings.PeerManager_read_event(this.ptr, peer_descriptor == null ? 0 : peer_descriptor.ptr, data);
125                 Result_boolPeerHandleErrorZ ret_hu_conv = Result_boolPeerHandleErrorZ.constr_from_ptr(ret);
126                 this.ptrs_to.add(peer_descriptor);
127                 return ret_hu_conv;
128         }
129
130         /**
131          * Checks for any events generated by our handlers and processes them. Includes sending most
132          * response messages as well as messages generated by calls to handler functions directly (eg
133          * functions like ChannelManager::process_pending_htlc_forward or send_payment).
134          */
135         public void process_events() {
136                 bindings.PeerManager_process_events(this.ptr);
137         }
138
139         /**
140          * Indicates that the given socket descriptor's connection is now closed.
141          * 
142          * This must only be called if the socket has been disconnected by the peer or your own
143          * decision to disconnect it and must NOT be called in any case where other parts of this
144          * library (eg PeerHandleError, explicit disconnect_socket calls) instruct you to disconnect
145          * the peer.
146          * 
147          * Panics if the descriptor was not previously registered in a successful new_*_connection event.
148          */
149         public void socket_disconnected(SocketDescriptor descriptor) {
150                 bindings.PeerManager_socket_disconnected(this.ptr, descriptor == null ? 0 : descriptor.ptr);
151                 this.ptrs_to.add(descriptor);
152         }
153
154         /**
155          * Disconnect a peer given its node id.
156          * 
157          * Set no_connection_possible to true to prevent any further connection with this peer,
158          * force-closing any channels we have with it.
159          * 
160          * If a peer is connected, this will call `disconnect_socket` on the descriptor for the peer,
161          * so be careful about reentrancy issues.
162          */
163         public void disconnect_by_node_id(byte[] node_id, boolean no_connection_possible) {
164                 bindings.PeerManager_disconnect_by_node_id(this.ptr, node_id, no_connection_possible);
165         }
166
167         /**
168          * This function should be called roughly once every 30 seconds.
169          * It will send pings to each peer and disconnect those which did not respond to the last round of pings.
170          * Will most likely call send_data on all of the registered descriptors, thus, be very careful with reentrancy issues!
171          */
172         public void timer_tick_occured() {
173                 bindings.PeerManager_timer_tick_occured(this.ptr);
174         }
175
176 }