Megular Expressions (#263)

* Add multiaddr expression group matching

Support captures

export some things

wip thinking about public API

Think about exposing meg as a public API

doc comments

Finish rename

Add helper for meg and add test

add comment for devs

* Move meg package to /x/ for experimental

* Add fuzz cases

* faster Code() method

twice as fast without the copy

* avoid copying an empty map if no captures

* Faster megular expressions (#265)

* much cheaper copies of captures

* Add a benchmark

* allocate to a slice. Use indexes as handles

* cleanup

* Add nocapture loop benchmark

It's really fast. No surprise

* cleanup

* nits

* feat(x/meg): Support capturing components (#269)

* Use Matchable interface

* Add Bytes to Matchable interface

* feat(x/meg): Support capturing bytes

* Export CaptureWithF

Can be used by more specific capturers (e.g capture net.AddrIP)

* Support Any match, RawValue, and multiple Concatenations

* Add CaptureAddrPort

* Fix typo in rebase

* workaround for go generics

* less hacky workaround for go generics

* Avoid unnecessary copy

* Make `matchAny` less greedy when there are alternatives

The state machine handling was modified to deprioritize the `matchAny`
path
when alternatives exist, resulting in less greedy matching behavior when
using Any patterns.

* PR comments

* Update Pattern type to return next state

Author: MarcoPolo

component.go

@@ -162,6 +162,13 @@ func (c *Component) Protocol() Protocol {
 	return *c.protocol
 }
 
+func (c *Component) Code() int {
+	if c == nil {
+		return 0
+	}
+	return c.Protocol().Code
+}
+
 func (c *Component) RawValue() []byte {
 	if c == nil {
 		return nil

meg_capturers.go

@@ -0,0 +1,54 @@
+package multiaddr
+
+import (
+	"encoding/binary"
+	"fmt"
+	"net/netip"
+
+	"github.com/multiformats/go-multiaddr/x/meg"
+)
+
+func CaptureAddrPort(network *string, ipPort *netip.AddrPort) (capturePattern meg.Pattern) {
+	var ipOnly netip.Addr
+	capturePort := func(s meg.Matchable) error {
+		switch s.Code() {
+		case P_UDP:
+			*network = "udp"
+		case P_TCP:
+			*network = "tcp"
+		default:
+			return fmt.Errorf("invalid network: %s", s.Value())
+		}
+
+		port := binary.BigEndian.Uint16(s.RawValue())
+		*ipPort = netip.AddrPortFrom(ipOnly, port)
+		return nil
+	}
+
+	pattern := meg.Cat(
+		meg.Or(
+			meg.CaptureWithF(P_IP4, func(s meg.Matchable) error {
+				var ok bool
+				ipOnly, ok = netip.AddrFromSlice(s.RawValue())
+				if !ok {
+					return fmt.Errorf("invalid ip4 address: %s", s.Value())
+				}
+				return nil
+			}),
+			meg.CaptureWithF(P_IP6, func(s meg.Matchable) error {
+				var ok bool
+				ipOnly, ok = netip.AddrFromSlice(s.RawValue())
+				if !ok {
+					return fmt.Errorf("invalid ip6 address: %s", s.Value())
+				}
+				return nil
+			}),
+		),
+		meg.Or(
+			meg.CaptureWithF(P_UDP, capturePort),
+			meg.CaptureWithF(P_TCP, capturePort),
+		),
+	)
+
+	return pattern
+}

meg_test.go

@@ -0,0 +1,72 @@
+package multiaddr
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/multiformats/go-multiaddr/x/meg"
+)
+
+func TestMatchAndCaptureMultiaddr(t *testing.T) {
+	m := StringCast("/ip4/1.2.3.4/udp/8231/quic-v1/webtransport/certhash/b2uaraocy6yrdblb4sfptaddgimjmmpy/certhash/zQmbWTwYGcmdyK9CYfNBcfs9nhZs17a6FQ4Y8oea278xx41")
+
+	var udpPort string
+	var certhashes []string
+	found, _ := m.Match(
+		meg.Or(
+			meg.Val(P_IP4),
+			meg.Val(P_IP6),
+		),
+		meg.CaptureStringVal(P_UDP, &udpPort),
+		meg.Val(P_QUIC_V1),
+		meg.Val(P_WEBTRANSPORT),
+		meg.CaptureZeroOrMoreStrings(P_CERTHASH, &certhashes),
+	)
+	if !found {
+		t.Fatal("failed to match")
+	}
+	if udpPort != "8231" {
+		t.Fatal("unexpected value")
+	}
+
+	if len(certhashes) != 2 {
+		t.Fatal("Didn't capture all certhashes")
+	}
+
+	{
+		m, c := SplitLast(m)
+		if c.Value() != certhashes[1] {
+			t.Fatal("unexpected value. Expected", c.RawValue(), "but got", []byte(certhashes[1]))
+		}
+		_, c = SplitLast(m)
+		if c.Value() != certhashes[0] {
+			t.Fatal("unexpected value. Expected", c.RawValue(), "but got", []byte(certhashes[0]))
+		}
+	}
+}
+
+func TestCaptureAddrPort(t *testing.T) {
+	m := StringCast("/ip4/1.2.3.4/udp/8231/quic-v1/webtransport")
+	var addrPort netip.AddrPort
+	var network string
+
+	found, err := m.Match(
+		CaptureAddrPort(&network, &addrPort),
+		meg.ZeroOrMore(meg.Any),
+	)
+	if err != nil {
+		t.Fatal("error", err)
+	}
+	if !found {
+		t.Fatal("failed to match")
+	}
+	if !addrPort.IsValid() {
+		t.Fatal("failed to capture addrPort")
+	}
+	if network != "udp" {
+		t.Fatal("unexpected network", network)
+	}
+	if addrPort.String() != "1.2.3.4:8231" {
+		t.Fatal("unexpected ipPort", addrPort)
+	}
+}

util.go

@@ -2,6 +2,8 @@ package multiaddr
 
 import (
 	"fmt"
+
+	"github.com/multiformats/go-multiaddr/x/meg"
 )
 
 // Split returns the sub-address portions of a multiaddr.
@@ -120,3 +122,17 @@ func ForEach(m Multiaddr, cb func(c Component) bool) {
 		}
 	}
 }
+
+type componentList []Component
+
+func (m componentList) Get(i int) meg.Matchable {
+	return &m[i]
+}
+
+func (m componentList) Len() int {
+	return len(m)
+}
+func (m Multiaddr) Match(p ...meg.Pattern) (bool, error) {
+	matcher := meg.PatternToMatcher(p...)
+	return meg.Match(matcher, componentList(m))
+}