Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ jobs:
# the e2e suite and the client and server tests exercise each other's
# packages. make coverpkg-check keeps it equal to COVER_PKGS.
coverpkg: >-
github.com/otfabric/go-ethernetip,github.com/otfabric/go-ethernetip/cip,github.com/otfabric/go-ethernetip/client,github.com/otfabric/go-ethernetip/eds,github.com/otfabric/go-ethernetip/encap,github.com/otfabric/go-ethernetip/implicit,github.com/otfabric/go-ethernetip/internal/logx,github.com/otfabric/go-ethernetip/logix,github.com/otfabric/go-ethernetip/scanner,github.com/otfabric/go-ethernetip/server
github.com/otfabric/go-ethernetip,github.com/otfabric/go-ethernetip/cip,github.com/otfabric/go-ethernetip/client,github.com/otfabric/go-ethernetip/eds,github.com/otfabric/go-ethernetip/encap,github.com/otfabric/go-ethernetip/implicit,github.com/otfabric/go-ethernetip/internal/callback,github.com/otfabric/go-ethernetip/internal/goid,github.com/otfabric/go-ethernetip/internal/logx,github.com/otfabric/go-ethernetip/logix,github.com/otfabric/go-ethernetip/scanner,github.com/otfabric/go-ethernetip/server
go-versions: '["1.26", "1.27"]'
# The race and e2e suites need more than the default 15 minutes on
# loaded runners.
Expand Down
22 changes: 17 additions & 5 deletions API.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,20 @@ timeout rules.
`implicit.Endpoint`, `implicit.Connection`, `logix.Client` and
`logix.TagServer` are safe for concurrent use. Codec values (`cip.Request`,
`cip.Path`, ...) are plain values.
- **Callbacks** (`OnWrite`, `OnInput`, `OnData`, `OnState`, metrics, state
handlers) run on library goroutines: they must not block, and slices
passed to them are valid only during the call.
- **Callbacks** (`OnWrite`, `OnInput`, `OnData`, `OnState`, `Produce`,
request handlers, metrics, state handlers) run on library goroutines:
they must not block, and slices passed to them are valid only during the
call. `Produce`, `OnData`, `OnTimeout`, `OnInput`, `OnState` and a
server's request handlers may call the methods of the object that calls
them, `Close` included; the client's state handler must not call the
client. A `Close` called from such a callback returns without waiting
for the goroutine it runs on, which ends when the callback returns; it
waits for the others. A `Close` on another goroutine waits for a
callback in progress, except `OnState` (see `IOConfig.OnState`). A
callback that does not return normally is logged at Error
level with its stack ([OBSERVABILITY.md](OBSERVABILITY.md)), and the
library goes on as the callback's documentation states; a request
handler's request is answered with general status 0x10.
- **Ownership**: byte slices returned by decoders alias their input unless
documented otherwise; values returned by clients (`Response.Data`,
attribute values) are owned by the caller.
Expand Down Expand Up @@ -56,7 +67,7 @@ timeout rules.
|---|---|
| `New(client, opts...)` with `WithLocalAddr`, `WithEndpoint`, `WithLogger` | a scanner of the client's target |
| `Scanner.Open(ctx, IOConfig)` → `*IO`; `Scanner.Close(ctx)`, `Endpoint` | I/O connections |
| `IOConfig` | instances, sizes, RPIs, formats, class 0, multicast, timeout multiplier, large, key, `Reconnect`, `OnInput`, `OnState` |
| `IOConfig` | instances, sizes, RPIs, floors on the O->T API (`OTAPIDivisor`, `MinOTAPI`), formats, class 0, multicast, timeout multiplier, large, key, `Reconnect`, `OnInput`, `OnState` |
| `IO.SetOutput`, `SetRun`, `Input`, `State`, `Err`, `Done`, `Info`, `Stats`, `Close` | one connection |

## `server`
Expand All @@ -72,7 +83,8 @@ timeout rules.

## `logix` (vendor specific)

`NewClient(doer, WithMaxData)` with `Read`, `Write`, `WriteBit`,
`NewClient(doer, WithMaxData, WithMaxTagListReplies, WithMaxTagListData,
WithMaxTemplateReplies)` with `Read`, `Write`, `WriteBit`,
`ReadMany`, `ListTags`, `Template`, `DecodeStruct`, `ProgramName`;
`ParseTag`; `Value` (`Int`, `Uint`, `Float`, `Bool`, `Text`) with `Ints`,
`Uints`, `Floats`, `Strings`; `Template`, `Member`, `Field`, `SymbolType`;
Expand Down
13 changes: 12 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,18 @@ goroutine only while reopening after a timeout.

Every goroutine is tied to a `Close`: `Client.Close`, `Server.Close`,
`Scanner.Close`, `IO.Close`, `Endpoint.Close`. The e2e suite checks after
all its tests that no goroutine or file descriptor is left.
all its tests that no goroutine or file descriptor is left. A goroutine
that runs application callbacks which may call `Close` (an I/O
connection's for `Produce`, an endpoint's receiving one for `OnData` and
`OnInput`, a server session's for its request handlers) records its
identifier when it starts (`internal/goid`). `Close` compares the
identifier of the goroutine it is called on with them: it does not wait
for its own goroutine, which ends when the callback returns, and waits
for every other one, the callbacks in progress included. The reopening
goroutine of a scanner's connection instead leaves the count `Close`
waits for while it reports a state to `OnState`. Application code is
called through `internal/callback`, which stops a call that does not
return normally at the library's boundary and logs it.

## Protocol machines

Expand Down
2 changes: 2 additions & 0 deletions ERRORS.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,8 @@ length 0x65, unsupported protocol 0x69).
| set of a read-only attribute | 0x0E |
| set data too short / too long | 0x13 / 0x15 |
| output assembly owned by an I/O connection | 0x0C object state conflict |
| a request handler that does not return normally (`ServeCIP`, a `SymbolHandler`, a `ServiceFunc`, an `Attribute` function, the reset handler, `Assembly.OnWrite` for Set_Attribute_Single, `logix.TagServer.OnWrite`); within a Multiple Service Packet, that service only | 0x10 device state conflict, logged at Error level with its stack |
| a Forward_Open whose configuration data's `Assembly.OnWrite` does not return normally | 0x10 device state conflict; no connection is opened |
| malformed path | 0x04 path segment error; a path that runs past the message 0x26 |
| Forward_Open refusals | 0x01 with the extended status of [CATALOG.md](CATALOG.md) (0x0100 duplicate triad, 0x0106 ownership conflict, 0x0109/0x0127/0x0128 sizes, 0x0112 RPI, 0x0113 out of connections (`WithMaxConnections`, `WithMaxConnectionsPerOriginator`), Class 3 O->T below 4 or T->O below 6 octets 0x0127/0x0128 with the smallest size, 0x0114-0x0116 electronic key, 0x0117/0x012A/0x012B paths, 0x0119 listen-only without producer, 0x0311 port, 0x0315 segment, ...) |
| Forward_Close of an unknown connection | 0x01 / 0x0107 |
Expand Down
12 changes: 11 additions & 1 deletion OBSERVABILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,15 @@ Messages are constant strings ("session registered", "connection opened",
"Forward_Open refused", "I/O connection timed out", ...): filter on them.
Debug entries are only built when the handler is enabled for debug.

Application code that does not return normally (a handler, a callback, a
metrics hook, the state handler) is logged at Error level with the message
"application code did not return normally" and the fields `callback` (the
call site: `OnData`, `Produce`, `OnTimeout`, `OnInput`, `OnState`,
`Object.ServeCIP`, `SymbolHandler.ServeSymbol`, `Assembly.OnWrite`,
`state handler`, `Metrics.OnConnect`, `ServerMetrics.OnHandled`,
`IOMetrics.OnIOSent`, ...), `value` (what it ended with) and `stack`. The
library then goes on as the callback's documentation states.

## Metrics

`WithMetrics(m)` takes an `ethernetip.Metrics`: `OnConnect`, `OnDisconnect`,
Expand All @@ -37,7 +46,8 @@ need. A value that also implements:
"wrong source", "wrong size", "old encapsulation sequence", "malformed").

Callbacks run on the protocol goroutines: they must be safe for concurrent
use and must not block.
use and must not block. A metrics hook that does not return normally is
logged as above; what the library sends and answers does not change.

## State

Expand Down
113 changes: 113 additions & 0 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,118 @@
# go-ethernetip Releases

## v0.8.0

**Date:** 2026-11-14
**Previous release:** v0.7.1

## Summary

A minor release on v0.7.1. Application code the library calls (a handler,
a callback, a metrics hook, a state handler) that does not return normally
is stopped at the library's boundary and logged at Error level with its
stack, and the process keeps running; a request whose handler it was is
answered with general status 0x10. `implicit.Config.Produce`, `OnData`,
`OnInput` and the server's request handlers may call `Close` of the
object that calls them; a `Close` on another goroutine still waits for
them. New `IOConfig` fields and Logix client options
lower, raise or disable the scanner's floors on the O->T actual packet
interval and the bounds of `ListTags` and `Template`; their defaults are
the values of v0.7.1. No exported identifier is removed or changed.

## Changes

### Breaking

- **all packages**: application code that does not return normally is
logged at Error level ("application code did not return normally", with
the fields `callback`, `value` and `stack`), and the library goes on:
- **server**: the request of a handler (`Object.ServeCIP`,
`SymbolHandler.ServeSymbol`, a `ServiceFunc`, an `Attribute` function,
the reset handler, `Assembly.OnWrite` for Set_Attribute_Single,
`logix.TagServer.OnWrite`) is answered with 0x10 (device state
conflict), within a Multiple Service Packet that service only, and the
session goes on. A Forward_Open whose configuration data's
`Assembly.OnWrite` does not return normally is refused with 0x10 and
opens no connection; the data stays written. For I/O data, the
connection goes on.
- **implicit**: a `Produce` call sends nothing at that interval; after
`OnData` the endpoint goes on with the next datagram; after `OnTimeout`
the connection is closed, as after any timeout.
- **scanner**: after `OnInput` the connection goes on; after `OnState`
the state change stands.
- **client**: after the state handler the state change stands.
- **metrics**: after a hook of the client, the server or an I/O
endpoint, what the library sends and answers does not change.

### Fixes

- **implicit, scanner, server**: `Close` called from a callback that runs
on a goroutine it waits for returns: `Connection.Close` and
`Endpoint.Close` from `Produce`, `Endpoint.Close` from `OnData`,
`Scanner.Close` with the scanner's own endpoint from `OnInput`,
`Server.Close` from a request's handler. In v0.7.1 these calls did not
return. Such a `Close` does not wait for the goroutine it is called on,
which ends when the callback returns, and waits for every other one, as
a `Close` on another goroutine does. What a `Produce` call that called
`Close` returns is not sent. The goroutines that run these callbacks
record their identifier when they start (`internal/goid`), and `Close`
compares it with the goroutine it runs on.

### Additions

- **scanner**: `IOConfig.OTAPIDivisor` and `IOConfig.MinOTAPI` set the two
floors on the O->T actual packet interval of a Forward_Open reply: the
O->T RPI divided by `OTAPIDivisor` (default 4), and `MinOTAPI` (default
100 µs, or the RPI when that is shorter). Zero keeps the default, a
positive value replaces it and a negative value disables that floor; an
O->T interval of 0 is refused in any case.
- **logix**: `WithMaxTagListReplies`, `WithMaxTagListData` and
`WithMaxTemplateReplies` set the bounds of `ListTags` (65536 replies,
16 MiB of them) and `Template` (65536 Read Template replies for one
definition); a value below 1 keeps the default.

### Tests

- One test per call site of application code that does not return
normally, in the `callbacks_test.go` of `server`, `implicit`, `scanner`
and `client`, in `logix/tagserver_test.go` and in `internal/callback`
(TESTING.md lists them).
- Row L10 of the lifecycle matrix: `TestCloseFromProduceAndOnData`,
`TestOnInputCallsScannerClose` and `TestHandlerCallsClose`; and that
a `Close` on another goroutine, or from a callback for the other
goroutines, waits for a callback in progress: `TestCloseWaitsForCallback`
(implicit), `TestScannerCloseWaitsForOnInput`, `TestCloseWaitsForHandler`
(server), with `testenv.Blocking`, which observes the `Close` waiting.
`internal/goid` has its own tests.
- Boundary tables for the new fields and options: `TestOTAPIFloor`,
`TestReplyAPIFloors`, `TestListAndTemplateBoundDefaults`,
`TestListTagsRepliesOption`, `TestListTagsDataOption`,
`TestTemplateRepliesOption`. The defaults stay those of v0.7.1
(`TestMinOTAPI`, `TestReplyAPIs`, `TestListTagsReplyLimit`,
`TestTemplateReplyLimit`).
- **client**: `TestConnWriteFailureBoundedByContext` ends the request by
its context in every run, and `TestConnWriteFailureAfterRequestTaken`
covers a failed write whose request is no longer the connection's
pending one: both sides of that branch of `Conn.do` are covered.
- **server**: `TestDelayedDiscoveryBound` failed in one run in about
1000: the delay of a ListIdentity reply is drawn at random up to the
maximum the request asks for, and a draw of zero is answered at once,
outside the bound the test checks. The test now sets the server's
generator so that its requests draw a delay.
- TESTING.md gives the figure of `BenchmarkConsume` for v0.8.0.

### Documentation

- The doc comments of the callbacks, of the `Close` methods and of the new
fields and options.
- API.md, ARCHITECTURE.md (the goroutines `Close` waits for,
`internal/callback` and `internal/goid`), ERRORS.md (the 0x10 answers),
OBSERVABILITY.md (the Error entry), SECURITY.md, TESTING.md,
docs/LIMITATIONS.md, docs/IMPLICIT.md, docs/LOGIX.md, docs/OBJECTS.md,
docs/api.

---

## v0.7.1

**Date:** 2026-11-14
Expand Down
6 changes: 4 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,10 @@ The server bounds what a peer can make it hold:
interval is 0, whose O->T actual packet interval is below a quarter of
the O->T RPI or below 100 µs (the RPI itself when that is shorter), or
whose O->T connection ID is 0, and closes that connection at the
target; O->T data goes to the target's address, whatever address the
reply's Sockaddr Info O->T item names;
target; the two floors are `IOConfig.OTAPIDivisor` and
`IOConfig.MinOTAPI`, which lower, raise or disable them, and an O->T
interval of 0 is refused in any case; O->T data goes to the target's
address, whatever address the reply's Sockaddr Info O->T item names;
- `eds.Parse` reads at most 16 MiB, 16384 sections, 262144 entries, 4096
fields per entry and 1048576 fields in all;
- replies are written with a deadline, so a peer that stops reading loses
Expand Down
Loading
Loading