{"id":16440193,"url":"https://github.com/soypat/seqs","last_synced_at":"2025-03-16T17:36:24.413Z","repository":{"id":206812045,"uuid":"717756043","full_name":"soypat/seqs","owner":"soypat","description":"seqs: the hottest, most idiomatic userspace TCP/IP implementation on the internet. lwip in go basically","archived":false,"fork":false,"pushed_at":"2024-07-21T15:33:53.000Z","size":395,"stargazers_count":33,"open_issues_count":11,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-07-22T13:27:53.547Z","etag":null,"topics":["embedded","embedded-systems","ethernet","go","golang","heapless","ip","operating-systems","tcp","tcp-ip","tinygo","udp","userspace-networking"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soypat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-12T13:50:16.000Z","updated_at":"2024-07-16T01:00:12.000Z","dependencies_parsed_at":"2023-11-12T14:46:22.857Z","dependency_job_id":"cb05148c-851a-4c57-aea3-4219002d03c7","html_url":"https://github.com/soypat/seqs","commit_stats":null,"previous_names":["soypat/seqs"],"tags_count":0,"template":false,"template_full_name":"soypat/go-module-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soypat%2Fseqs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soypat%2Fseqs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soypat%2Fseqs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soypat%2Fseqs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soypat","download_url":"https://codeload.github.com/soypat/seqs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219861933,"owners_count":16555980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","embedded-systems","ethernet","go","golang","heapless","ip","operating-systems","tcp","tcp-ip","tinygo","udp","userspace-networking"],"created_at":"2024-10-11T09:11:26.085Z","updated_at":"2025-03-16T17:36:24.393Z","avatar_url":"https://github.com/soypat.png","language":"Go","readme":"# seqs\n[![go.dev reference](https://pkg.go.dev/badge/github.com/soypat/seqs)](https://pkg.go.dev/github.com/soypat/seqs)\n[![Go Report Card](https://goreportcard.com/badge/github.com/soypat/seqs)](https://goreportcard.com/report/github.com/soypat/seqs)\n[![codecov](https://codecov.io/gh/soypat/seqs/branch/main/graph/badge.svg)](https://codecov.io/gh/soypat/seqs)\n[![Go](https://github.com/soypat/seqs/actions/workflows/go.yml/badge.svg)](https://github.com/soypat/seqs/actions/workflows/go.yml)\n[![sourcegraph](https://sourcegraph.com/github.com/soypat/seqs/-/badge.svg)](https://sourcegraph.com/github.com/soypat/seqs?badge)\n\n`seqs` is what is commonly referred to as a userspace IP implementation. It handles:\n* Ethernet protocol\n* IP packet marshalling to sub-protocols:\n    * ARP requests and responses\n    * UDP packet handling\n    * DHCP client requests and DHCP server\n    * TCP connections over IP with support for multiple listeners on same port. These implement [net.Conn](https://pkg.go.dev/net#Conn) and [net.Listener](https://pkg.go.dev/net#Listener) interfaces. See [`stacks/tcpconn.go`](./stacks/tcpconn.go)\n    * HTTP: Algorithm to reuse heap memory between requests and avoid allocations. See `httpx` package\n    * NTP client for resolving time offset to a NTP server\n\n## ⚠️ Developer note ⚠️\nThis package may be superceded by https://github.com/soypat/lneto. \n\n### What does this mean?\nRest easy, the high-level API of `seqs` will be able to make use of `lneto`, so this package will be supported in the future.\n\nLow level bits of `seqs` may break or be completely removed such as anything inside [`eth`](./eth) package.\n\nBelow is a list of future proof APIs in seqs (their internal functioning is subject to change):\n- [`stacks.TCPConn`](./stacks/tcpconn.go)\n- [`stacks.TCPListener`](./stacks/tcplistener.go)\n- [`stacks.DNSClient`](./stacks/dns_client.go)\n- [`stacks.DHCPClient`](./stacks/dhcp_client.go)\n- [`stacks.NTPClient`](./stacks/ntp_client.go)\n- [`stacks.PortStack`](./stacks/portstack.go) - HandleEth, RecvEth methods will remain. Open* and Close* methods will remain. May require different initialization. \n\nUse above APIs if you plan on using most up to date version of `seqs` in the future.\n\n### Why?\nseqs has accumulated technical debt due to its design.`lneto` is being designed with ease of testing as a priority. \n`lneto` features:\n- Zero copy package processing for performance gains\n- Packet framing design\n  - Variable length headers included in frame type logic, no longer part of client/server implementation\n  - Huge reduction in stack memory usage. Much easier to avoid heap usage\n  - Early stack implementations are shown to be much simpler to write and read by humans\n- Client and Server logic is moved closer to frame logic, better separation of responsibility\n\n## Example of use\n\n```go\n// stack works by having access to Ethernet packet sending\n// and processing. NIC is our physical link to the internet.\nvar NIC NetworkInterfaceCard = getNIC()\n\nstack := stacks.NewPortStack(stacks.PortStackConfig{\n    MAC:             MAC,\n    MaxOpenPortsTCP: 1,\n    MaxOpenPortsUDP: 1,\n    MTU:             2048,\n})\n// stack.RecvEth should be called on receiving an ethernet packet. It should NOT block.\nNIC.SetRecvEthHandle(stack.RecvEth)\n\n// Static IP setting.\nip := netip.AddrFrom4([4]byte{192, 168, 1, 45}) \nstack.SetAddr(ip)\n\n// Or can request an address via DHCP.\ndhcpClient := stacks.NewDHCPClient(stack, dhcp.DefaultClientPort)\nerr = dhcpClient.BeginRequest(stacks.DHCPRequestConfig{\n    RequestedAddr: netip.AddrFrom4([4]byte{192, 168, 1, 69}),\n    Xid:           0x12345678,\n    Hostname:      \"tinygo-pico\",\n})\nif err != nil {\n    panic(err)\n}\n\nfmt.Println(\"Start DHCP...\")\nfor !dhcpClient.Done() {\n    doNICPoll(NIC)\n    time.Sleep(time.Second / 10)\n}\n\nofferedIP := dhcpClient.Offer()\nfmt.Println(\"got offer:\", offeredIP)\nstack.SetAddr(offeredIP)\n```\n\nHow to use `seqs`\n```sh\ngo mod download github.com/soypat/seqs@latest\n```\n\n\n## History - Precursors to seqs\nBefore `seqs` there was:\n\n* [`ether-swtch`](https://github.com/soypat/ether-swtch) - First known instance of a (barely) working TCP/IP stack in Go working on embedded systems, circa June 2021. Could blink an Arduino UNO's LED via HTTP (!). Famously bad design, code, performance, readability.\n* [`dgrams`](https://github.com/soypat/dgrams) - Library prepared for Pico W's wifi chip. Already shows similarities with `seqs`. Circa May 2023.\n","funding_links":[],"categories":["Embedded Systems"],"sub_categories":["Protocol implementations"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoypat%2Fseqs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoypat%2Fseqs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoypat%2Fseqs/lists"}