ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MCP/lib/AnyEvent/MCP/Extension.pm
Revision: 1.4
Committed: Sun Nov 1 23:30:55 2026 UTC (2 weeks, 6 days ago) by root
Branch: MAIN
CVS Tags: rel-0_91, rel-0_81, rel-0_82, rel-0_8, rel-0_9, HEAD
Changes since 1.3: +9 -8 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.1 =head1 NAME
2    
3     AnyEvent::MCP::Extension - authenticated non-HTTP connections on an MCP listener
4    
5 root 1.2 =head1 DESCRIPTION
6    
7     The HTTP listeners used by the bundled servers can also accept private
8     raw-TCP protocols on the same port. This helper authenticates the initial
9     JSON handshake and passes the already-buffered connection to its protocol
10     handler; it does B<not> implement HTTP or MCP dispatch.
11    
12     C<mcp-multibroker> uses this mechanism for reverse-connecting MCP servers.
13     Vim editor and browser connections can also share an MCP HTTP listener,
14     but they use WebSocket upgrades rather than this raw JSON hello protocol.
15     Ordinary MCP clients should use
16     L<AnyEvent::MCP::Client::HTTP> or
17     L<AnyEvent::MCP::Client::JSONL>, not this extension protocol.
18    
19     my ($host, $port, $token, $alias) =
20     AnyEvent::MCP::Extension::parse_url
21     "http://127.0.0.1:31740/TOKEN/files";
22    
23     The returned address is for a raw TCP extension connection, not an HTTP
24     request. See L<AnyEvent::MCP::Server::Connect> for the MCP user of it.
25    
26 root 1.1 =head1 FUNCTIONS
27    
28     =over
29    
30     =item AnyEvent::MCP::Extension::accept $handle, [$token...], $callback->($handle, $hello), $reject->($handle)
31    
32     Read one bounded newline-terminated JSON array beginning with a protocol name
33     and accepted token. Authenticate before calling the protocol-specific handler.
34     Invalid hellos close the connection. The callback takes ownership of the same
35     handle, including buffered bytes after the hello. Remaining array fields belong
36     to the selected protocol. An optional C<$reject> callback releases any
37     listener ownership on rejection; otherwise the handle is destroyed.
38    
39 root 1.4 =item ($host, $port, $token, $alias, $scheme) = AnyEvent::MCP::Extension::parse_url $url
40 root 1.1
41 root 1.4 Parse C<http[s]://host[:port]/token/alias>, including bracketed IPv6 hosts.
42     An omitted port defaults to 80 for HTTP and 443 for HTTPS. The URL names a
43     raw extension endpoint sharing an HTTP listener; no HTTP request is sent.
44     Tokens use the ordinary
45 root 1.3 listener token syntax and aliases use ASCII letters, digits, underscores and hyphens.
46 root 1.1
47     =back
48    
49     =cut
50    
51     package AnyEvent::MCP::Extension;
52    
53     use common::sense;
54     use JSON::XS ();
55    
56     sub parse_url {
57     my ($url) = @_;
58    
59 root 1.4 my ($scheme, $host, $port, $token, $alias) =
60     $url =~ m{\A(https?)://(\[[^\]]+\]|[^/:?#]+)(?::([0-9]+))?/([A-Za-z0-9_.~-]+)/([A-Za-z0-9_-]+)\z};
61 root 1.3 defined $host && (!defined $port || $port > 0 && $port <= 65535)
62 root 1.4 or die "Expected extension URL http[s]://host[:port]/token/alias\n";
63 root 1.1 $host =~ s/\A\[(.*)\]\z/$1/;
64    
65 root 1.4 ($host, defined $port ? 0 + $port : $scheme eq "https" ? 443 : 80, $token, $alias, $scheme)
66 root 1.1 }
67    
68     sub accept {
69     my ($handle, $tokens, $done, $reject) = @_;
70    
71     my $rbuf_max = $handle->{rbuf_max};
72     $handle->rtimeout (15);
73     $handle->{rbuf_max} = 4096;
74     $handle->push_read (line => sub {
75     my (undef, $line) = @_;
76    
77     my $ok = eval {
78     my $hello = JSON::XS->new->utf8->max_depth (8)->decode ($line);
79     ref $hello eq "ARRAY" && @$hello >= 2
80     && defined $hello->[0] && !ref $hello->[0]
81     && defined $hello->[1] && !ref $hello->[1]
82     && (grep $_ eq $hello->[1], @$tokens)
83     or die "Invalid extension hello\n";
84    
85     $handle->rtimeout (0);
86     $handle->{rbuf_max} = $rbuf_max;
87     $done->($handle, $hello);
88     1
89     };
90     ($reject ? $reject->($handle) : $handle->destroy) unless $ok;
91     });
92     }
93    
94     1;