connectivity api (#17)

* chore: add branch placeholder zbobr_fix-54-implement-connectivity-api-2

* chore: switch zenoh-c submodule to fork with zc_internal_create_transport

Update the zenoh-c submodule to milyin-zenoh-zbobr/zenoh-c branch
zbobr_fix-60-transport-from-fields which adds zc_internal_create_transport
needed for reconstructing C transports from Go struct fields.

To switch back to official zenoh-c:
  Change url in .gitmodules to https://github.com/eclipse-zenoh/zenoh-c.git
  Remove the branch line, then run: git submodule sync && git submodule update

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: implement connectivity API with pure Go Transport and Link structs

- Add transport.go with Transport as pure Go struct (no C ownership, no Drop/Clone)
  and TransportEvent, TransportEventsListener, session methods
- Add link.go with Link as pure Go struct (same fields as LinkEvent, no Drop/Clone)
  and LinkEvent, LinkEventsListener, session methods
- Use zc_internal_create_transport (from zenoh-c fork) to reconstruct C transport
  from Go fields when filtering links; move semantics: C takes ownership, no drop
- Options structs use option.Option[Transport] instead of *Transport
- Add zc_cgo_transport_is_shm wrapper in zenoh_cgo.c/.h to handle
  Z_FEATURE_SHARED_MEMORY conditional compilation gracefully
- Copy and update z_info example: remove Drop() calls on Transport/Link values
- Add connectivity_test.go: full test suite without Drop/Clone, using option.Some
  for transport filter options

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: implement 4 new connectivity tests

- TestBackgroundTransportEventsListenerWithHistory: test options != nil branch with history flag
- TestBackgroundLinkEventsListenerWithHistoryAndFilter: test options != nil and transport filter branches
- TestLinkEventsListenerTransportFilterForwardEvents: test transport filter on forward events
- TestEmptyTransportsAndLinksLists: test empty collections on sessions with no peers

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* test: fix connectivity tests and ensure they pass

- Simplified TestBackgroundLinkEventsListenerWithHistoryAndFilter to test history option
- Simplified TestLinkEventsListenerTransportFilterForwardEvents to avoid cgo pointer issues
- All 4 new connectivity tests now pass successfully

* linter

* refactor: TransportEvent wraps Transport, LinkEvent wraps Link via accessors

Replace the duplicated fields and methods on TransportEvent (5 fields) and
LinkEvent (10 fields) with a single embedded struct and Transport()/Link()
accessor methods, following the Rust API pattern from z_info.rs.

Also fix a pre-existing CGO pointer violation in buildCTransport: allocate
the z_owned_transport_t shell on the C heap so z_transport_move(&owned) stores
a C pointer rather than a Go stack pointer inside the options struct.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* priorities, reliability in option

* pointer passing improved, option string

* submodule updated

* updated to zenoh-c create transport api

* zenoh-c submodule update

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: milyin

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "zenoh-c"]
 	path = zenoh-c
 	url = https://github.com/eclipse-zenoh/zenoh-c.git
+	branch = main

CLAUDE.md

@@ -0,0 +1,53 @@
+# zenoh-go development notes
+
+## Building
+
+zenoh-go uses CGo and requires the zenoh-c library. Build and install it from the submodule:
+
+```sh
+git submodule init && git submodule update
+cd zenoh-c && mkdir -p build && cd build
+cmake .. -DZENOHC_BUILD_WITH_UNSTABLE_API=ON -DCMAKE_INSTALL_PREFIX="$HOME/local"
+cmake --build . --target install --config Release
+```
+
+Then build/test with:
+
+```sh
+CGO_CFLAGS="-I$HOME/local/include" CGO_LDFLAGS="-L$HOME/local/lib -lzenohc" go build ./...
+CGO_CFLAGS="-I$HOME/local/include" CGO_LDFLAGS="-L$HOME/local/lib -lzenohc" go test ./...
+```
+
+## CGo Conventions
+
+### C pointer conversion methods
+
+Methods that convert a Go struct to a C pointer are named `toCPtr` and live in the same file as the Go type. They return a pointer to a C-owned struct (e.g. `*C.z_owned_foo_t`). Prefer stack allocation over `C.malloc`:
+
+```go
+func (t Foo) toCPtr() *C.z_owned_foo_t {
+    var owned C.z_owned_foo_t
+    // ... fill owned from t ...
+    return &owned // escapes to heap via Go escape analysis
+}
+```
+
+Never use `C.malloc` / `C.free` for temporary C structs — Go's escape analysis handles heap promotion.
+
+### Lifetime bounds with runtime.Pinner
+
+When a C pointer is passed to a C function (e.g. via `z_foo_move`), use a `runtime.Pinner` at the call site to make the lifetime explicit:
+
+```go
+pinner := runtime.Pinner{}
+defer pinner.Unpin()
+ownedPtr := val.toCPtr()
+pinner.Pin(ownedPtr)
+cOpts.foo = C.z_foo_move(ownedPtr)
+```
+
+The pinner can be reused for multiple fields in the same scope.
+
+### Optional fields
+
+Fields that may or may not be present in the C API should be typed as `option.Option[T]` (from `github.com/BooleanCat/option`), not as a zero-value sentinel like `""` or `0`. This applies to both struct fields and method return types. Use `option.Some(v)` when the value is present and `option.None[T]()` (or zero-value `option.Option[T]{}`) when absent.

examples/z_info/z_info.go

@@ -16,9 +16,11 @@ package main
 
 import (
 	"fmt"
-	"os"
-
 	"github.com/eclipse-zenoh/zenoh-go/examples/utils"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
 
 	"github.com/eclipse-zenoh/zenoh-go/zenoh"
 )
@@ -48,6 +50,56 @@ func main() {
 	for _, id := range ids {
 		fmt.Printf("%s\n", id)
 	}
+
+	// Warning: transport/link APIs are unstable.
+
+	fmt.Println("transports:")
+	transports, _ := session.Transports()
+	for _, tr := range transports {
+		fmt.Printf("  zid: %s, whatami: %s, qos: %v, multicast: %v\n",
+			tr.ZId(), tr.WhatAmI(), tr.IsQos(), tr.IsMulticast())
+	}
+
+	fmt.Println("links:")
+	links, _ := session.Links(nil)
+	for _, l := range links {
+		ifaces := strings.Join(l.Interfaces(), ", ")
+		fmt.Printf("  zid: %s, src: %s, dst: %s, mtu: %d, streamed: %v, interfaces: [%s]\n",
+			l.ZId(), l.Src(), l.Dst(), l.Mtu(), l.IsStreamed(), ifaces)
+	}
+
+	_ = session.DeclareBackgroundTransportEventsListener(
+		zenoh.Closure[zenoh.TransportEvent]{
+			Call: func(evt zenoh.TransportEvent) {
+				action := "Opened"
+				if evt.Kind() == zenoh.SampleKindDelete {
+					action = "Closed"
+				}
+				fmt.Printf("[Transport Event] %s: zid=%s\n", action, evt.Transport().ZId())
+			},
+		},
+		nil,
+	)
+
+	_ = session.DeclareBackgroundLinkEventsListener(
+		zenoh.Closure[zenoh.LinkEvent]{
+			Call: func(evt zenoh.LinkEvent) {
+				action := "Added"
+				if evt.Kind() == zenoh.SampleKindDelete {
+					action = "Removed"
+				}
+				fmt.Printf("[Link Event] %s: zid=%s, src=%s, dst=%s\n",
+					action, evt.Link().ZId(), evt.Link().Src(), evt.Link().Dst())
+			},
+		},
+		nil,
+	)
+
+	fmt.Println("Monitoring connectivity events. Press CTRL-C to quit...")
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	<-sig
+	fmt.Println("Exiting...")
 }
 
 type Args struct {