ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MCP/lib/AnyEvent/MCP/Extension.pm
Revision: 1.3
Committed: Thu Oct 22 09:01:49 2026 UTC (4 weeks, 3 days ago) by root
Branch: MAIN
CVS Tags: rel-0_71, rel-0_65, rel-0_7, rel-0_62
Changes since 1.2: +8 -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     =item ($host, $port, $token, $alias) = AnyEvent::MCP::Extension::parse_url $url
40    
41 root 1.3 Parse C<http://host[:port]/token/alias>, including bracketed IPv6 hosts.
42     An omitted port defaults to 80. The URL names a raw TCP extension endpoint
43     sharing an HTTP listener; no HTTP request is sent. Tokens use the ordinary
44     listener token syntax and aliases use ASCII letters, digits, underscores and hyphens.
45 root 1.1
46     =back
47    
48     =cut
49    
50     package AnyEvent::MCP::Extension;
51    
52     use common::sense;
53     use JSON::XS ();
54    
55     sub parse_url {
56     my ($url) = @_;
57    
58     my ($host, $port, $token, $alias) =
59 root 1.3 $url =~ m{\Ahttp://(\[[^\]]+\]|[^/:?#]+)(?::([0-9]+))?/([A-Za-z0-9_.~-]+)/([A-Za-z0-9_-]+)\z};
60     defined $host && (!defined $port || $port > 0 && $port <= 65535)
61     or die "Expected extension URL http://host[:port]/token/alias\n";
62 root 1.1 $host =~ s/\A\[(.*)\]\z/$1/;
63    
64 root 1.3 ($host, defined $port ? 0 + $port : 80, $token, $alias)
65 root 1.1 }
66    
67     sub accept {
68     my ($handle, $tokens, $done, $reject) = @_;
69    
70     my $rbuf_max = $handle->{rbuf_max};
71     $handle->rtimeout (15);
72     $handle->{rbuf_max} = 4096;
73     $handle->push_read (line => sub {
74     my (undef, $line) = @_;
75    
76     my $ok = eval {
77     my $hello = JSON::XS->new->utf8->max_depth (8)->decode ($line);
78     ref $hello eq "ARRAY" && @$hello >= 2
79     && defined $hello->[0] && !ref $hello->[0]
80     && defined $hello->[1] && !ref $hello->[1]
81     && (grep $_ eq $hello->[1], @$tokens)
82     or die "Invalid extension hello\n";
83    
84     $handle->rtimeout (0);
85     $handle->{rbuf_max} = $rbuf_max;
86     $done->($handle, $hello);
87     1
88     };
89     ($reject ? $reject->($handle) : $handle->destroy) unless $ok;
90     });
91     }
92    
93     1;