Skip to content

Releases

go-iec60870-5 v0.9.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 12:29
73afd27

Date: 2026-11-16
Previous release: v0.8.0

Opt-in pacing of the iec102 server's answers and of the iec103 server's
disturbance channels by the controlling station's polls, an
iec103.MEAOf that sets ER for NaN, tls.Config callbacks and
sec.Config.OnEvent of the IEC 104 client and server that end only what
they belong to, an IEC 104 Connect that fails with ErrClosed when
its Dialer stops during Close, and an IEC 104 test station that
listens on loopback. Three changes of behaviour are breaking; each says
who notices and how to get the previous behaviour back. Two fields are
added; no identifier is removed or changed, and no default changes.

Breaking

  • iec103: MEAOf(NaN) returns MEA{Error: true}: ER set ("MVAL is
    not a valid value", clause 7.2.6.8) and MVAL 0. Before, it converted
    NaN to int16, a result that Go leaves to the platform, without ER.
    Who notices: an application that passes NaN for a measurand it has no
    value for, and a controlling system that then sees ER set where it saw
    a plain value. Previous behaviour: pass iec103.MEA{} instead of
    MEAOf(v) when math.IsNaN(v).
  • iec104/client: a callback of the tls.Config given to WithTLS
    (GetClientCertificate, VerifyPeerCertificate, VerifyConnection
    and the others the handshake calls) or the sec.Config.OnEvent of the
    WithSecurity endpoint that does not return normally is logged at
    Error as callback did not return normally with its stack and closes
    the client: Connect, the reconnect loop or the request in progress
    fails with iec104.ErrClosed, and the state handler is told
    "disconnected" with an error that names tls.Config callback or
    sec.Config.OnEvent. Who notices: an application whose callback ended
    the process. Previous behaviour: the process ended; an application
    that wants that ends it itself in the callback.
  • iec104/server: a callback of the tls.Config of WithTLS, or of a
    TLS listener given to Serve (GetCertificate, GetConfigForClient,
    VerifyPeerCertificate, VerifyConnection and the others), that does
    not return normally is logged with its stack and rejects only that
    connection, as for WithAccept: Warn connection rejected with the
    reason tls.Config callback did not return normally. A session's
    sec.Config.OnEvent that does not return normally is logged with its
    stack and ends that session. The server serves the others. Who
    notices: an application whose callback ended the process. Previous
    behaviour: the process ended; an application that wants that ends it
    itself in the callback.

Added

  • iec102/server: Config.PaceAnswers. The answers the server builds
    itself (C_RD_NA_2, C_TI_NA_2, the reads of integrated totals and single
    points, refusals included) are queued as the controlling station's
    class 2 polls take the queue, so an answer longer than QueueSize
    goes out whole, its termination included. Meanwhile the server serves
    no other request: up to 16 wait, and more are refused with NACK and
    DFC. A reset of remote link drops the rest of the answer; Close ends
    the wait. Send, Mirror and the Handler are not paced. Off by
    default: an answer is cut where the queue is full, as before.
  • iec103/server: Config.PaceChannels. The ASDUs 30 and the ASDU 31
    of a disturbance channel are queued as the controlling system's class
    1 polls take the queue, so a channel longer than QueueSize goes out
    whole, and a record whose longest channel does not fit the queue is
    announced at its selection. Meanwhile other requests wait in the
    server's input, with DFC set while it is more than half full. A reset
    of the communication unit or of the FCB drops the rest of the channel,
    logged at Info as disturbance channel ended by a reset; Close ends
    the wait. Tags are not paced. Off by default: a channel is queued all
    or none (TOO 37 when it does not fit now, TOO 34 at the selection when
    it can never fit), as before.

Fixed

  • iec104/client: Connect returns iec104.ErrClosed when a Dialer
    that does not return normally races with Close; it no longer
    continues without a connection.

Documentation

  • The OnState docs of the iec101 server (unbalanced mode), the iec102
    server and the iec103 server say that OnState for StateUp runs on
    the link's reader under the lock of the secondary station, before the
    reset is acknowledged, so a slow OnState delays the link's answers.
  • iec103.Uints and iec103.Ints say that each value keeps its low
    size octets and that nothing reports a value that needs more.
  • WithTLS and WithSecurity of iec104/client and iec104/server,
    and sec.Config.OnEvent, say on which goroutine the callbacks run and
    what happens to one that does not return normally; the client's
    WithTLS says that a renegotiation, which tls.Config.Renegotiation
    allows, runs them later on the connection's reader.
    docs/iec102/README.md, docs/iec103/README.md,
    docs/iec103/INTEROPERABILITY.md (interpretation 15), docs/iec104/API.md,
    ERRORS.md, OBSERVABILITY.md, SECURITY.md and TESTING.md follow the
    changes above; docs/api is regenerated.

Tests

  • Pacing, on the fake clock of testing/synctest where unit:
    iec102/server TestAnswerLongerThanTheQueue (the default),
    TestPacedAnswer, TestPacedAnswerEnds (reset and Close);
    iec102/e2e.TestPacedAnswers; iec103/server TestPacedChannel,
    TestPacedChannelEnds (reset of the communication unit, of the FCB,
    Close); iec103/e2e.TestPacedChannels (on and off).
  • iec103.TestMEA covers 0, the largest value below full scale, full
    scale, beyond it in both directions, the infinities and NaN;
    TestGenericValues pins the octets Uints and Ints keep.
  • iec104/client.TestConnectWhenTheDialerStopsDuringClose: the Dialer
    stops once Close has closed the client, every time.
  • iec104/client.TestTLSCallbackThatDoesNotReturnNormally,
    iec104/server.TestTLSCallbackRejectsOnlyThatConnection,
    iec104/e2e.TestSecurityEventHandlerOfTheClient and
    TestSecurityEventHandlerOfTheStation.
  • The IEC 104 test station (iec104/internal/station) listens on
    127.0.0.1:0, the address the e2e suites dial, and on the wildcard
    only for the interop suites, which a container dials
    (iec104/e2e.TestStationListensOnLoopback). Another process that
    listens on the loopback address with the same port no longer takes the
    suites' connections.

go-iec60870-5 v0.8.0

Choose a tag to compare

@github-actions github-actions released this 16 Nov 08:31
ddb0a06

Date: 2026-11-16
Previous release: v0.7.0

State notifications of the serial stations that come one at a time and
in order, an iec102 client whose OnState may make requests, IEC 104
client callbacks and loggers that no longer end the process when they do
not return normally, a takeover in a redundancy group that ends the
previous session's started state at once, and the remaining tests that
waited a fixed time rewritten to wait for what they check. Four changes
of behaviour are breaking; each says who notices and how to get the
previous behaviour back where there is a way. No identifier is added,
removed or changed.

Breaking

  • iec102/client: Config.OnState runs on a goroutine of the client's
    own, outside the request slot, one call at a time and in the order of
    the changes, StateClosed last. A request made from OnState is
    answered after the request in progress, instead of waiting for the
    slot until its deadline. The request that changed the state goes on
    while OnState runs and returns once OnState has returned for that
    change, as before. Close called from OnState returns at once; the
    close completes, StateClosed reported included, when OnState has
    returned, so Done may close before OnState is told StateClosed.
    Who notices: an OnState that relies on running on the goroutine of the
    request that changed the state. Previous behaviour: none; the request
    still returns only after OnState for its change.
  • iec101/server, iec102/server, iec103/server: OnState is called
    one change at a time and in order, StateClosed last: Close waits for
    an OnState call in progress before it reports StateClosed. Before,
    on a transport that is not an io.Closer, StateClosed could be
    reported while OnState for the link coming up still ran on the link's
    reader. Who notices: an OnState that waits for something the closing
    goroutine does after Close returns. Previous behaviour: none; such an
    OnState returns and waits on another goroutine.
  • iec104/client: a Dialer (WithDialer) or a metrics callback
    (WithMetrics, iec104.RequestMetrics included) that does not return
    normally is logged at Error as callback did not return normally with
    its stack and closes the client, from whichever goroutine called it:
    the state handler is told "disconnected" with an error that wraps
    iec104.ErrClosed and names the callback, and Connect, the
    reconnect loop or the request that called it fails with
    iec104.ErrClosed. Previous behaviour: the process ended. An
    application that wants that ends it itself in the callback.
  • Every package: a call of the application's logger (Logger,
    FieldLogger, ContextLogger, DebugEnabled) that does not return
    normally loses its entry; the failure is written once more through
    Errorf as logger did not return normally with the method, the
    value and the stack, and dropped when Errorf does not return
    normally either. The client, server or session that logged goes on. A
    FieldLogger whose With does not return normally is used through
    its formatted methods; a DebugEnabled that does not return normally
    counts as false. Previous behaviour: the process ended. An application
    that wants that ends it itself in its logger.

Fixed

  • iec104/server: Session.Started reports false for a session that a
    takeover in a declared redundancy group ends, from before the STARTDT
    con of the new connection; it reported true until the session's
    protocol goroutine had seen its connection closed, so Sessions could
    show two started sessions of one group.
  • iec104/client: the "disconnected" notice names a callback that
    closed the client during a reconnect attempt, or while the loss of the
    connection was being reported (the metrics' OnDisconnect), as it
    does after a local close.
  • iec104/client: Connect on a client that is closed while it
    connects, by Close or by a callback that does not return normally,
    fails with iec104.ErrClosed, wrapped in the failure that names the
    callback where there is one; it returned nil when the link confirmed
    STARTDT, or the secure session came up, before the close reached it.
    The state handler is then told "disconnected" once, and no "started"
    or "stopped" that the link confirms after the close.

Documentation

  • The OnState docs of the iec101, iec102 and iec103 clients and servers
    say that the calls come one at a time and in order; the iec102 client
    no longer says that OnState must not make a request. WithDialer,
    WithMetrics and WithLogger of iec104/client and iec104/server,
    and iec60870.Logger, say what happens to a callback or a logger call
    that does not return normally. ARCHITECTURE.md, ERRORS.md,
    OBSERVABILITY.md, TESTING.md, docs/iec102/README.md and
    docs/iec104/API.md follow the changes above; docs/api is regenerated.

Tests

  • State order: TestStateNotificationsInOrder in iec102/client,
    iec102/server, iec103/client and iec103/server;
    iec101/e2e.TestServerStateNotificationsInOrder and
    TestClientStateNotificationsInOrder (both modes), on the fake clock
    of testing/synctest; iec102/client.TestRequestFromOnState.
  • Callbacks and loggers: iec104/client
    TestHookThatDoesNotReturnNormally, TestMetricsThatDoNotReturnNormally,
    TestLoggerThatDoesNotReturnNormally;
    internal/logx.TestLoggerThatDoesNotReturnNormally;
    iec101/e2e.TestLoggerThatDoesNotReturnNormally.
  • iec104/server.TestTakeoverStopsThePreviousSessionAtOnce.
  • iec104/client.TestConnectClosedWhileSTARTDTIsConfirmed: the client
    is closed while the link confirms STARTDT, held there by a failpoint.
  • iec104/server.TestTakeoverEndsThePreviousConnection,
    iec104/e2e.TestStopDuringEventStream and
    iec104/e2e.TestSecurityStations wait for the events they check:
    the event stream test counts the events on the wire before each STOPDT
    con and waits until the Handler has been given exactly those, and the
    station test waits for the standby connection before the switchover
    and checks the associations of the started sessions only.
    iec104/client.TestGroupFailsOverBehindABusyHandler waits for both
    connections to be established, not connecting, before it switches
    over. Fixed waits
    in the iec101, iec102, iec103 and iec104 tests that synchronised on
    time now wait for what they check; the waits left are pacing, a
    duration under test, or need a hook the library does not have.

go-iec60870-5 v0.7.0

Choose a tag to compare

@github-actions github-actions released this 14 Nov 19:56
09f173a

Date: 2026-11-14
Previous release: v0.6.0

Bounds on what a peer can make the IEC 104 client, the IEC 104 security
and the serial stations hold, IEC 104 server callbacks that close only
their own session when they do not return normally, session keys that
the controlled station stops accepting at their limits, and disturbance
transfers that keep to one fault. Five changes of behaviour are
breaking; each says how to get the previous behaviour back where there
is a way. The only new identifiers are client.WithMaxResult and
client.DefaultMaxResult of iec104/client; none is removed or
changed.

Breaking

  • iec104/client: WithMaxResult bounds what one collecting request
    returns: the ASDUs of Interrogate and of CounterInterrogate with
    asdu.FreezeRead, the directory entries of ListFiles. The answer
    that would exceed it ends the request with the results so far and an
    error wrapping telecontrol.ErrResultLimit, instead of growing it
    until its deadline; such a request is not retried. The default is
    DefaultMaxResult, 65536, as for the IEC 101 client. Why: a station
    that keeps answering held the request's memory until its deadline.
    Previous behaviour: WithMaxResult(-1).
  • iec104/server: a state handler (WithStateHandler), a Metrics or
    HandlerMetrics hook, an accept filter (WithAccept) or a security
    endpoint factory (WithSecurity) that does not return normally is
    logged at Error as callback did not return normally with its stack
    and closes only its session (the accept filter: rejects only that
    connection, logged as connection rejected with the reason accept filter did not return normally); the server goes on serving the
    others. After a Handler panic the session ends at once: ASDUs
    already received on it are no longer delivered to the Handler.
    Previous behaviour: the process ended (the Handler: the session closed
    in the background and later ASDUs were still delivered). An
    application that wants the process to end ends it itself in the
    callback.
  • sec: Trust checks the key usage of the remote certificate and the
    validity period of the authority certificates. A remote certificate
    with a key usage extension that allows neither keyAgreement nor
    digitalSignature is refused, and an authority certificate outside its
    validity period authorizes nothing. Why: the key of the certificate
    serves the key agreement of the Station Association, and an expired
    authority issues nothing valid. Previous behaviour: for the authority
    validity, Config.IgnoreValidity (which also skips the validity
    check of the station certificate); for the key usage there is none:
    issue the certificate with keyAgreement or digitalSignature, or
    without the extension.
  • sec: a Station Association completed at the controlled station ends
    its session: the session keys of the earlier association are no longer
    accepted, Ready reports false, and the Session Key Change that
    follows sets up new ones (IEC TS 60870-5-7:2025 Table 15). Why: new
    update keys replace the association the session keys were sent under.
    There is no way back; a controlling station that follows the TS, this
    module's included, changes the session keys right after the
    association.
  • iec103/server: the ASDUs 30 of a disturbance channel and the ASDU 31
    that ends it are queued all or none. When the class 1 queue has no
    room for all of them the channel ends with TOO 37 (aborted by the
    protection equipment), which the controlling station acknowledges
    negatively and may request again. The selection of a record whose
    longest channel cannot fit the class 1 queue at all is answered with
    TOO 34 and no transfer starts. Why: a channel cut at the queue bound
    went out with values missing.
    Previous behaviour, for long records: raise Config.QueueSize.

Added

  • iec104/client: WithMaxResult and DefaultMaxResult (above).

Changed

  • iec104/client: a request that waits for one answer (Command,
    Read, ClockSync, ...) queues at most 16 mirrors of earlier requests
    ahead of its answer, and otherwise ends with an error wrapping
    telecontrol.ErrResultLimit.
  • iec104/client: GetFile ends with iec104.ErrProtocol when the
    station announces more than 255 sections, the most a file can have (one
    per name of section, IEC 60870-5-101 7.2.6.33).
  • telecontrol: Requester.Collect queues at most MaxResult plus a
    small margin while its request is still being sent.
  • iec104: with IEC 62351-5, security output waiting for the peer's
    acknowledgements is bounded: above 128 KiB received I frames are no
    longer acknowledged, so a conformant peer stops after k more; a peer
    that keeps sending past its window is closed with ErrProtocol above
    1 MiB.
  • iec104: ignored or unsolicited STARTDT/STOPDT frames are logged at
    Debug instead of Warn.
  • sec: a controlled station stops accepting session keys as soon as
    they reach Settings.KeyUses or their lifetime, not only at its next
    Tick: it discards the message that finds them so, counts the
    invalidation and asks for new keys at once. Ready and
    Status().Ready report false from then.
  • sec: the remote certificate of an association (Status().Remote) is
    taken only once the Station Association has authenticated it.
  • sec: a connection not yet bound to an association answers one
    Station Association request per request timeout; a repeated request
    gets the same answer, with the same random data.
  • iec103/server: NOE announces the longest channel of a record, so
    that no channel carries values beyond it.
  • link: a broadcast reaches SecondaryHandler.UserData only as
    send/no reply in a variable-length frame, and only when the handler's
    FunctionFilter serves function 4, as an addressed message.
  • ci: the Extended workflow validates its fuzztime and chaos_seeds
    inputs and passes them to the shell through the environment.

Fixed

  • iec104/client: a callback that stops the client while it is still
    connecting is named in the "disconnected" notice, as after the connect.
  • link: an exchange (Primary, Balanced) ends with its context also
    while its frame waits for room in a full send queue, which a peer that
    stops reading leaves full.
  • link: Close on a transport that is not an io.Closer no longer waits
    for a writer blocked in Write; the writer ends when that Write
    returns and writes nothing more.
  • iec103/client: Disturbance keeps to the selected fault (FAN,
    IEC 60870-5-103 7.4.7): it skips an end of transmission of another
    FAN, ends with iec103.ErrInvalid (and the record so far) on a channel
    offered for another FAN, and acknowledges negatively a channel whose
    disturbance values carry another FAN. Disturbance values that add
    nothing to the record (no values, or another FAN) count against
    Config.MaxResult per channel.
  • iec102/client: ReadTotals and ReadSinglePoints keep only the data
    of the requested record address.
  • iec104/server: FileServer upload sections no longer hold more
    capacity than their announced length.
  • internal/pcapio: capture lengths are checked before they are
    converted to int, which is 32 bits wide on some platforms.

Documentation

  • iec102/ree: Session documents that its state follows the last
    access key received, so a C_AC_NA_2 with a wrong key closes an open
    session.
  • SECURITY.md, LIMITATIONS.md, ERRORS.md (new section Result bounds),
    ARCHITECTURE.md, OBSERVABILITY.md, TESTING.md, docs/REQUIREMENTS.md
    (LK-9, LK-16), docs/iec102, docs/iec103 (interpretations 14 and 15),
    docs/iec104/API.md, docs/iec104/ARCHITECTURE.md,
    docs/iec104/INTEROPERABILITY.md and docs/iec104/LIMITATIONS.md follow
    the changes above; docs/api is regenerated.

Tests

  • Result and queue bounds: iec104/client TestInterrogateResultLimit,
    TestListFilesResultLimit, TestGetFileSectionLimit,
    TestExchangeQueueBound; telecontrol.TestCollectQueueBound.
  • Security output: iec104/internal/link
    TestSecurityOutputSlowAcknowledgementStaysBounded,
    TestSecurityOutputPeerPastWindowIsClosed.
  • iec104/server callbacks: TestStateHandlerPanicClosesOnlyItsSession,
    TestMetricsPanicClosesOnlyItsSession,
    TestAcceptFilterPanicRejectsOnlyThatConnection,
    TestEndpointFactoryPanicEndsTheSession,
    TestHandlerPanicStopsDelivery.
  • sec: TestControlledKeyUsesEnforced,
    TestControlledKeyLifetimeAtUse, TestAssociationEndsSession,
    TestRemoteAfterAuthentication, TestCandidateAssociationRequests,
    TestCandidateKeyUses, TestCandidateAssociationEndsSession,
    TestTrustKeyUsage, TestTrustAuthorityValidity.
  • link: TestExchangeEndsWithContextOnFullQueue,
    TestCloseWithoutCloserBlockedWrite, TestCloseWithoutCloserIdleWriter,
    TestSecondaryBroadcastKindAndFilter.
  • IEC 103 disturbance data: iec103/e2e TestDisturbanceOtherFAN,
    TestDisturbanceEmptyValues; iec103/server
    TestDisturbanceChannelQueuedWhole, TestDisturbanceSelectNOE.
  • iec102/client.TestReadOtherRecord,
    internal/pcapio.TestPacketsLengthsBeyondInt32; the iec104/e2e
    station that announces sections without end now expects
    iec104.ErrProtocol after 255 sections.

go-iec60870-5 v0.6.0

Choose a tag to compare

@github-actions github-actions released this 14 Nov 16:02
81f0c15

Date: 2026-11-14
Previous release: v0.5.3

Bounds on what a peer can make a station hold, callbacks that stop only
their own station when they do not return normally, Close from inside a
callback in every serial station, and Done/Err where they were
missing. Three changes of behaviour are breaking; each says how to get
the previous behaviour back. No exported identifier is removed or
changed.

Breaking

  • iec104/server: a FileServer session has at most
    FileServer.MaxTransfers transfers open at once, files fetched and
    files delivered together; the default is DefaultMaxTransfers (16). A
    selection (F_SC_NA_1) or a file ready (F_FR_NA_1) beyond it is refused
    like a file the station does not have, with "unknown information object
    address", and logged at Warn, until a transfer of that session ends.
    Why: an open delivery keeps what arrived of up to asdu.MaxFileLength
    octets, and IEC 60870-5-101 7.4.11 has the files of a station
    transferred one after the other, so a controlling station has one or
    two open. Previous behaviour: set MaxTransfers to a negative value.

  • iec101/client, iec102/client, iec103/client: Config.MaxResult
    bounds the ASDUs one request collects; the request that would collect
    more ends with the ASDUs so far and an error wrapping
    telecontrol.ErrResultLimit (IEC 101: Interrogate,
    CounterInterrogate), iec102.ErrResultLimit (every request) or
    iec103.ErrResultLimit (Interrogate, the generic services, the tags
    of a disturbance transfer), instead of growing until its deadline. The
    defaults are DefaultMaxResult: 65536 (IEC 101, IEC 103) and 131072
    (IEC 102, more than three years of quarter-hour periods). The bound
    comes from telecontrol.Requester.MaxResult in IEC 101, whose zero
    value still means no bound. Previous behaviour: set MaxResult to a
    negative value.

  • A callback that does not return normally is recovered where the
    library calls it, logged at Error as callback did not return normally
    with its stack (fields callback, value, stack), and stops only the
    station that called it; the process goes on. The call sites:

    • link: the SecondaryHandler and BalancedHandler methods,
      Config.OnFrame (frames sent and received) and Config.OnDiscard.
      The station stops; Done closes and Err wraps link.ErrClosed
      and names the callback. The new link.Config.Logger receives the
      entry; the clients and servers pass theirs when it is nil.
    • iec101/client and iec101/server: Config.Handler,
      Config.OnState.
    • iec102/client: Config.Handler, Config.OnState;
      iec102/server: Config.Handler, Config.Clock, Config.OnState.
    • iec103/client: Config.Handler, Config.OnState;
      iec103/server: Config.Handler, Config.OnTimeSync, the methods of
      Config.Disturbances (DisturbanceSource), Config.OnState.
    • In those serial stations Done closes, Err wraps the standard's
      ErrClosed and names the callback, and requests in progress fail
      with ErrClosed.
    • iec104/client: the Handler (WithHandler), the state handler
      (WithStateHandler) and the start handler (WithStartHandler) close
      their client, which does not reconnect: the state handler is told
      "disconnected" with an error that wraps iec104.ErrClosed and names
      the callback. The switch handler (WithSwitchHandler) closes its
      group.

    Previous behaviour: the process ended. An application that wants that
    ends it itself when Err names a callback (serial), or when the state
    handler reports such an error (IEC 104).

Added

  • iec101.ErrInHandler, iec103.ErrInHandler: a request called where its
    answer cannot arrive (below).
  • telecontrol.ErrResultLimit, telecontrol.Requester.MaxResult,
    iec102.ErrResultLimit, iec103.ErrResultLimit, Config.MaxResult
    and DefaultMaxResult of the three serial clients,
    server.FileServer.MaxTransfers and server.DefaultMaxTransfers of
    iec104/server, link.Config.Logger.
  • iec103.ErrOverflow: a request that missed answers, which arrived
    faster than it took them beyond the 1024 ASDUs it buffers. It is the
    error such a request returned before, now exported, with the same text.
  • Done and Err on iec102/client.Client and iec103/server.Server,
    Err on iec102/server.Server: when and why the station stopped (the
    transport, or a callback that did not return normally); Err is nil
    while it runs and after Close.

Changed

  • iec101/client: a request that waits for an answer (Interrogate,
    CounterInterrogate, Read, Command, Deactivate, ClockSync,
    TestCommand, ResetProcess, MeasureDelay), called from
    Config.Handler or Config.OnState on one of the client's goroutines,
    returns iec101.ErrInHandler at once and is not sent; from OnState
    on a client goroutine so do Send and SetDelay. Before, such a
    request waited behind the Handler's queue and failed at its deadline
    once the station sent more than 256 ASDUs (LIMITATIONS.md; the
    Handler documentation of v0.5.3 says it must not wait for the
    station). Issue it from another goroutine.
  • iec103/client: the requests, Send, Broadcast and
    BroadcastClockSync, called from Config.Handler or Config.OnState
    on one of the client's goroutines, return iec103.ErrInHandler at once
    and are not sent, where they waited for the link loop that waits for
    the Handler. Issue them from another goroutine.
  • iec104/server: Server.Close waits for the goroutine of each event
    queue to end, and an event queued after Close starts none.

Fixed

  • Serial stations (link.Primary, link.Secondary, link.Balanced, the
    clients and servers of iec101, iec102 and iec103): Close called
    from one of the station's own callbacks (a handler, OnState, the iec102
    server's Clock, the iec103 server's OnTimeSync and
    DisturbanceSource, link.Config.OnFrame and OnDiscard) stops the
    station and returns at once, instead of waiting for the goroutine it
    runs on. The callback is not called again, the close completes when it
    has returned, and Err stays nil. The iec102/client reports
    StateClosed after its Close has completed, so OnState may call Close
    then too.
  • link: on a transport that is not an io.Closer, Close no longer
    waits for the reader's pending Read; the reader ends when that Read
    returns. A frame read after Close or after a callback stopped the
    station reaches no handler.
  • iec101/client: a request in flight at Close and every request after
    it return iec101.ErrClosed, in both modes, as Close documents; a
    request after Close returned iec101.ErrLinkDown before.
  • iec102: SinglePoints with a Qualifier above 127, which SPQ cannot
    hold, does not encode (ErrInvalid) where bit 7 was dropped.
  • iec103: Measurands with an MEA.Raw outside -4096..4095 does not
    encode (ErrInvalid) where the 13-bit MVAL kept the low bits.
  • iec103/server: a disturbance record is ended with TOO 34 when any of
    its channels has more values than NOE holds, not only the first, so the
    NFE of every ASDU 31 fits its two octets.

Deferred

  • Pacing a server answer longer than the send queue, or ending it with a
    negative termination (iec103/server disturbance data,
    iec102/server): it changes what a valid controlling station receives.
  • iec103.MEAOf(NaN) and the truncation of Uints/Ints in generic
    data: their documentation does not call those values invalid, so a
    change is a change of behaviour for valid input.
  • iec102/client: a request from OnState still waits for the request
    slot that the request calling OnState holds; OnState documents that it
    must not issue one.
  • Callbacks of iec104/server other than the handlers it already
    recovers (the state handler, WithAccept, the logger, metrics) and the
    Dialer, logger and metrics of iec104/client.

Documentation

  • Every handler, OnState and hook of the serial stations says it may call
    Close, what happens when it does not return normally, and which
    requests return ErrInHandler. LIMITATIONS.md, ERRORS.md, SECURITY.md,
    ARCHITECTURE.md, OBSERVABILITY.md, API.md, docs/iec102,
    docs/iec103, docs/iec104/API.md and docs/iec104/ARCHITECTURE.md follow
    the changes above; TESTING.md lists the new tests against the contract
    rows L3, L9, L10 and L12.

Tests

  • Callbacks that do not return normally, per call site:
    TestCallbackThatDoesNotReturnNormally in link, iec101/e2e (both
    modes), iec102/client, iec102/server, iec103/client,
    iec103/server and iec104/client;
    iec104/client.TestSwitchHandlerThatDoesNotReturnNormally;
    internal/callback.
  • Close from a callback: TestL10CallbackClosesSynchronously in link
    and iec101/e2e, TestCloseFromCallbacksSynchronously in
    iec102/server, iec103/client and iec103/server,
    iec102/client.TestCloseFromHandlerSynchronously,
    iec102/client.TestCloseFromOnState; link.TestCloseWithoutCloser.
  • Requests from a callback and after Close:
    TestRequestFromHandlerFailsAtOnce and TestRequestsFailWithErrClosed
    in iec101/e2e and iec103/client; TestServerWithoutHandlerRejects
    now expects iec101.ErrClosed after Close.
  • Bounds, on the fake clock of testing/synctest with an allocation
    budget: telecontrol.TestCollectResultLimit,
    iec101/e2e.TestInterrogationResultLimit,
    iec102/client.TestRequestResultLimit,
    iec103/client.TestInterrogationResultLimit;
    iec103/client.TestWaitOverflow;
    iec104/server.TestFileServerMaxTransfers. iec104/e2e
    TestHostileSectionAnnouncementBudget announces
    DefaultMaxTransfers / 2 files per round, so both rounds fit the
    bound.
  • Done/Err: TestDoneAndErr in iec102/client and iec103/server,
    iec102/server.TestErr.
  • iec104/server: TestCloseWaitsForEventQueues,
    TestNoEventQueueAfterClose.
  • Value bounds:...
Read more

go-iec60870-5 v0.5.3

Choose a tag to compare

@github-actions github-actions released this 14 Nov 13:23
d46221d

Date: 2026-11-14
Previous release: v0.5.2

Bounds and lifecycle fixes in every companion standard, from the policy 1.6
review: limits on what a peer can make a station hold or wait for, Close
that is safe to call more than once in the serial stations, balanced IEC 101
sends on the client's own goroutine, and the callback, ownership and Close
contracts documented on every station. No exported identifier is added,
removed or changed.

Fixed

  • sec: the segments of one security message are reassembled up to the
    longest message the A-Profile defines, the Association Response with a
    certificate of 65535 octets (IEC TS 60870-5-7:2025, Figure 8; 65797
    octets after the data unit identifier). A series that would grow beyond
    it is abandoned and counted in StatDiscardedMessages.
  • iec104/server with WithSecurity: a connection is bound to the
    association of its controlling station only once a message on it is
    authenticated for it (a Station Association or Session Key Change that
    completes, or Secure Data under the current session keys). Until then
    its key management runs on a copy of the association and changes
    nothing of it: the connection that carries the association keeps it,
    and Session.Security of the other is nil. An association that no
    message has authenticated is kept only while a connection waits for it;
    newEndpoint is called again for that AIM when its station is heard
    next.
  • iec104/server: Serve keeps serving through accept errors other than
    a closed listener (out of file descriptors, a connection aborted before
    accept, a timeout); each is logged and retried after a pause that
    doubles from 5 ms up to 1 s and ends when the server is closed. With
    WithMaxSessions, a TLS handshake in progress counts as a session, and
    a connection beyond the limit is closed before its handshake starts.
    Without a limit nothing changes.
  • iec104/server: FileServer reserves no memory for a file section a
    controlling station announces; an upload grows only with the segments
    that arrive.
  • iec104/client: a Dialer that returns neither a connection nor an
    error fails the connect with iec104.ErrConnectFailed. Close waits
    for the start handlers (WithStartHandler) to return, after cancelling
    their contexts; called from a start handler, it waits for everything
    else and returns.
  • ft12: after a pause longer than Decoder.Gap the rest of a rejected
    frame is no longer awaited, as an unfinished frame already was not:
    the octets after the pause start a new frame (IEC 60870-5-1 6.2.4.2, as
    Gap documents). Decoder.Reset also forgets the rest of a rejected
    frame still to come and the single-character hold-off.
  • iec101/client, balanced transmission: the supervisor goroutine sends
    the user data of requests, under the client's own context, as the
    poller does in unbalanced transmission. A request returns at its
    deadline even while the link repeats another frame, and an exchange
    whose request ended is still finished on the link, so the station
    receives the message once and the FCB stays in step. OnState for a
    failed send is called from the supervisor. The first test function for
    link follows one TestInterval after the link came up.
  • iec103/client: Disturbance keeps at most the NOC channels of NOE
    values its ASDU 26 announced (clauses 7.2.6.10, 7.2.6.11). A value or a
    channel beyond them ends the transfer at once with an error wrapping
    iec103.ErrInvalid, returns the record so far and sends no further
    order.
  • iec103/server: AnswerGI and AckCommand return an error wrapping
    iec103.ErrInvalid, and send nothing, for a request whose body is not
    a general interrogation or general command (an ASDU 7 or 20 with a
    private cause decodes as iec103.Raw). The quickstart example checks
    the body the same way.
  • iec103/server: a time synchronization whose time is flagged invalid,
    or lies outside the years 1970 to 2069 of CP56Time2a, is not applied:
    the clock and OnTimeSync stay as they were, and an addressed one is
    answered with ASDU 6 carrying the station's time with IV set (clause
    7.4.2 defines no negative answer; interpretation 13 of
    docs/iec103/INTEROPERABILITY.md). The clock offset is held within
    ±36525 days. iec101/server and iec102/server apply no clock
    synchronization themselves (the handler, or ree.Session.OnSetTime,
    does).
  • iec102/client: an answer belongs to a request only when it also
    repeats the request's information object, its addresses and time range
    (iec102.ASDU.Mirrors is unchanged). A request after one that ended
    before its answer was complete first polls the station until it has no
    more data and drops the rest of that answer; ASDUs of other common
    addresses still go to the Handler.
  • Serial stations (link.Primary, link.Secondary, link.Balanced, the
    clients and servers of iec101, iec102 and iec103): Close is safe
    to call more than once and from several goroutines. The first call
    closes the transport, once, also when the writer closed it after a
    write error, and returns its error; later calls return nil.

Changed

  • iec104/client: each reconnect, request retry and Group redial wait
    is chosen at random between half the delay and the delay (equal
    jitter); the logged retry_in is that wait.

Documentation

  • Every handler and OnState of the serial stations says which goroutine
    calls it, what it may call, and that it must not call Close (Close
    waits for that goroutine; call it in a new goroutine, which returns
    once the handler has returned). The iec101 and iec103 client Handlers
    no longer say they may issue requests: a request from them stalls
    behind their queue (LIMITATIONS.md).
  • Ownership: the slices that cross the link API (SendNoReply,
    SendConfirm, Balanced.Send, what Class1, Class2 and UserData
    hand over, the OnDiscard buffer), the ASDUs the iec102 and iec103
    handlers receive, and the *asdu.ASDU that the iec104 client shares
    between its Handler and the request that collects it (read-only).
  • Close needs a transport whose Close unblocks Read (link, iec101).
    iec104/server.Server.Close does not wait for the goroutines of the
    event queues.
  • No transaction identifier: a late confirmation of a request that ended
    completes the next identical request (LIMITATIONS.md,
    docs/iec104/LIMITATIONS.md, the telecontrol package doc).
  • TESTING.md lists the long-lived types against the contract test matrix
    (L1 to L16). SECURITY.md, ERRORS.md, ARCHITECTURE.md, OBSERVABILITY.md,
    docs/iec104/API.md, docs/iec102 and docs/iec103 follow the changes
    above.

Tests

  • sec: TestReassemblyLengthLimit (the bound, one octet below, at and
    above it), TestReassemblyAllocationBudget (20,000 segments without
    FIN within 8 times the bound); FuzzDecode checks the bound on every
    input.
  • iec104/server: TestUnauthenticatedMessageLeavesTheAssociation,
    TestAuthenticatedSessionTakesTheAssociationOver,
    TestPendingAssociationIsShared,
    TestUnauthenticatedAssociationsAreNotKept,
    TestServeRetriesAcceptErrors, TestServeEndsWhenTheListenerIsClosed,
    TestTLSHandshakesCountAgainstTheSessionLimit; iec104/e2e:
    TestHostileSectionAnnouncementBudget.
  • iec104/client: TestReconnectPausesAreJittered,
    TestRetryPausesAreJittered, TestGroupRedialPausesAreJittered,
    TestDialerWithoutConnection, TestCloseWaitsForTheStartHandler,
    TestCloseFromTheStartHandler.
  • ft12: the rejected-header case of TestDecoderGap,
    TestDecoderResetForgetsARejectedFrame,
    TestDecoderGapKeepsAFrameWithoutPause; iec101/e2e: the
    rejected-header case of the half-open line in TestHostileServer.
  • iec101/e2e: TestBalancedRequestDeadlineWhileTheLinkRepeats,
    TestBalancedSendAfterItsDeadline.
  • iec103: TestDisturbanceWithinAnnounced (e2e),
    TestAnswersNeedTheirRequestBody, TestTimeSyncValidity,
    TestTimeSyncRefusedKeepsTheClock, TestTimeSyncOffsetClamped
    (server).
  • iec102: TestUnfinishedAnswerNotTaken (e2e),
    TestMirrorOfAnotherRange (client).
  • Contract rows L1, L2 and L10 for the serial stations:
    link.TestL01CloseTwice, link.TestL01CloseAfterAWriteError,
    link.TestL02ConcurrentClose, link.TestL10CallbackClosesAsynchronously,
    the same three in iec101/e2e, and TestCloseTwice,
    TestConcurrentClose, TestCloseFromHandler in the iec102 and iec103
    clients and servers.
  • internal/testutil/leakcheck compares goroutine stacks instead of counting
    goroutines; leakcheck.Main runs after the tests of link, telecontrol,
    the iec101, iec102, iec103 and iec104 clients and servers and
    iec104/internal/link, and the e2e suites use leakcheck.Check. The
    iec104/internal/capture replay peer queues frames without a bound,
    so its reader ends with the connection.
  • Waits that slept are now events, hooks or testing/synctest in
    link/close_test.go, iec101/client/waitup_test.go,
    iec101/e2e/hostile_test.go, iec101/e2e/deadline_test.go,
    ft12/gap_test.go, iec102/client/client_test.go,
    iec103/e2e/silent_test.go, iec104/server/ordering_test.go,
    iec104/server/reconnect_test.go, iec104/internal/link/link_test.go
    and iec104/internal/link/invariants_test.go.

go-iec60870-5 v0.5.2

Choose a tag to compare

@github-actions github-actions released this 12 Nov 22:56
edf1b1b

Date: 2026-11-12
Previous release: v0.5.1

The interop suites of all four standards move to the reference images of
otfabric/iec60870-5-interop v0.5.0 (was v0.4.0). No change to the library's
code or API.

Changed

  • Interop pin: iec60870-5-interop v0.5.0 (contract 2.3, unchanged; the same
    upstream revisions as v0.4.0, rebuilt), its 13 reference images pinned by
    multi-arch index digest in iec101/interop/harness.go,
    iec102/interop/harness.go, iec103/interop/harness.go,
    iec104/interop/harness.go, the Makefile and the Interop workflow. The
    copied harness tables (testdata/cases.tsv, known-bugs.tsv,
    known-bugs-consumer.tsv) are refreshed from v0.5.0.
  • iec103/interop: known-bugs-consumer.tsv entries may name a role
    (vitusdong@client, vitusdong@server, open103@client), as the harness
    writes them since v0.5.0. The suite strips the role after checking that it
    agrees with its own table of client bugs; a disagreement fails the run.
  • Docs (README, TESTING, LIMITATIONS, INTEROPERABILITY, docs/FEATURE-STATUS,
    docs/iec102, docs/iec103, docs/iec104) name the v0.5.0 images.

Verified

Locally on linux/arm64 (Docker on macOS), 2026-11-12, on the pinned v0.5.0
images: IEC 101 3 top-level tests, 490 subtests passed, 5 skipped (the
digitalpetri balanced known bug), 0 failed; IEC 102 2 top-level tests, 19
subtests passed, 0 failed; IEC 103 4 top-level tests, 75 subtests passed, 38
skipped (known bugs and undeclared features), 0 failed; IEC 104 31 top-level
tests, 519 subtests passed, 35 skipped (undeclared features and the j60870
known bug), 0 failed.
The same counts as on the v0.4.0 images.

go-iec60870-5 v0.5.1

Choose a tag to compare

@github-actions github-actions released this 12 Nov 15:10
40002fc

Date: 2026-11-12
Previous release: v0.5.0

Fixes a silent loss of data on a noisy line in every serial standard (IEC
101, 102, 103): the FT 1.2 decoder could take an E5 octet inside the user
data of a corrupted frame for a single-character answer.

Fixed

  • ft12: after rejecting a frame, Decoder resynchronized on the next
    start character inside the rejected octets. A single character (E5) has
    no checksum, so an E5 in the user data of a corrupted variable frame was
    returned as a frame: the controlling station took it for "no data"
    (or a positive acknowledgement), toggled FCB on its next request, and the
    message the corrupted frame carried was lost while the procedure ended
    successfully (otfabric/iec60870ctl's chaos test: 7 of 8 general
    interrogation messages). Since v0.1.0. Now a rejected variable frame
    whose two length octets agree is dropped whole (4 + L + 2 octets, also
    when the rest arrives in later reads), and after any other error a
    single character is accepted only from octets that arrive after a pause
    of ErrorIdle (10 ms), the line idle IEC 60870-5-1 asks for after an
    error. A real answer follows a request sent after the error, so it is
    not affected; a frame dropped in error is repeated by the link layer.

Added

  • ft12.ErrorIdle.

Tests

  • ft12: TestDecoderNoSingleFromRejectedFrame (five corruptions, one read
    and one octet per read), TestDecoderDropsTheRestOfARejectedFrame,
    TestDecoderSingleAfterIdle; TestDecoderResync now expects the E5 read
    with a rejected header to be dropped.

go-iec60870-5 v0.5.0

Choose a tag to compare

@github-actions github-actions released this 12 Nov 14:11
209bce1

Date: 2026-11-12
Previous release: v0.4.1

Two lifecycle fixes, found by otfabric/iec60870ctl's tests: a link station
no longer outlives its Close, and the IEC 101 and IEC 103 clients no longer
wait in vain for a link whose transport has failed.

Added

  • iec103/client: Client.Done and Client.Err, as iec101/client has
    them: Done is closed when the transport failed or the client was closed,
    Err returns the transport error.

Fixed

  • link: Close of a Primary, Secondary or Balanced waits for the
    writer goroutine as well as the reader. Config.OnFrame is no longer
    called, and no frame is written, after Close returned; a frame queued
    before the station stopped is not sent after it.
  • iec101/client, iec103/client: WaitUp returns the transport error
    when the transport fails before the link came up (a peer that closed the
    connection, say), instead of waiting until its context ended; it returns
    ErrClosed after Close. The client stops initializing the link on a
    failed transport instead of retrying every RetryInterval.
    (iec102/client.Init already returned the error.)

Tests

  • link: TestCloseWaitsForTheWriter; iec101/client, iec103/client:
    TestWaitUpTransportClosedBeforeLinkUp, TestWaitUpCloseWhileWaiting.
    Each fails on v0.4.1.

go-iec60870-5 v0.4.1

Choose a tag to compare

@github-actions github-actions released this 12 Nov 08:20

Date: 2026-11-12
Previous release: v0.4.0

iec103/client keeps every identification a station sends after a reset,
so the one with cause 4 is not lost behind a start/restart (cause 5).

Added

  • iec103/client: Client.IdentificationFor(cause) returns the last
    identification (ASDU 5) with that cause (IEC 60870-5-103:1997 7.4.1,
    table 8). Identification still returns the last one of any cause.

Fixed

  • iec103/interop: the identification case reads the cause 4
    identification with IdentificationFor. A station that follows clause
    7.4.1 and sends start/restart (cause 5) after it, as the fixed
    vitusdong/iec103-dotnet (vitusdong/iec103-dotnet#10) does, failed the
    case.

go-iec60870-5 v0.4.0

Choose a tag to compare

@github-actions github-actions released this 12 Nov 01:21
76271b2

Date: 2026-11-12
Previous release: v0.3.0

More independent evidence for the serial standards: IEC 101 against a third
reference, digitalpetri/iec60870, and with four non-default sets of field
sizes; IEC 103 generic services and disturbance data against the harness's
contract 2.3, with the server's disturbance data transfer evidenced by
Open103. iec104/client returns from a counter freeze or reset at the
confirmation and shares the matching rules of telecontrol. SAST stays at
zero. All interop suites pin the images of iec60870-5-interop v0.4.0
(contract 2.3) by digest.

Fixed

  • iec104/client: CounterInterrogate with a freeze or reset qualifier
    returns at the activation confirmation with no ASDUs, instead of waiting
    for a termination the station does not send (IEC 60870-5-104 7.8;
    IEC 60870-5-101:2003 7.4.8 mode C, figures 95 and 96). It is still never
    retried. A termination or totals a station sends anyway reach the
    Handler.
  • telecontrol: the test sequence counter of C_TS_TA_1 starts at 0
    (IEC 60870-5-104 8.8), as in iec104/client.

Changed

  • iec104/client uses the matching rules of telecontrol (Mirrored,
    FromStation) instead of its own copy; behaviour is unchanged. It keeps
    its own request handling; see docs/IEC104_PARITY.md for why it does not
    use telecontrol.Requester.

Security hardening

  • internal/testutil/serialline: the noise octet of the faulty test line is
    bounded to a byte before conversion (gosec G115). Its use of math/rand
    (G404, a seeded, reproducible test line, not security relevant) is
    recorded as a false positive in the organisation's triage records. SAST
    (gosec, opengrep) at the lowest thresholds: 0 findings, also in the nested
    module iec104/interop/cbsigma.

Tests

  • All interop suites pin the images of otfabric/iec60870-5-interop v0.4.0
    (contract 2.3) by multi-arch index digest (iec101, iec102, iec103
    and iec104/interop/harness.go, the Makefile, the Interop workflow); the
    testdata copies of its case and known-bug tables are those of v0.4.0. On
    those images (2026-11-12, linux/arm64): IEC 101 490 subtests passed and 5
    skipped (known bug), IEC 102 18 passed, IEC 103 75 passed and 38 skipped
    (known bugs, undeclared features), IEC 104 519 passed and 35 skipped, the
    cB-Sigma IEC 62351-5 tests pass; 0 failures.
  • iec101/interop: digitalpetri/iec60870 as third reference, and the field
    sizes 2/2/2/3, 1/2/1/3, 2/1/2/2 and (balanced) 0/1/1/2 (link address,
    cause, common address, object address). This module's client: 5 + 5
    scenarios and 12 + 16 field-size runs pass against lib60870-C and against
    cB-Sigma (unbalanced + balanced), against digitalpetri 5 scenarios and 12
    field-size runs unbalanced; balanced against a digitalpetri station is
    skipped as the harness's known bug
    digitalpetri-balanced-server-no-link-reset (testdata/known-bugs.tsv),
    checked to reproduce on every run. The reference clients replay the
    harness's 64 cases (33 with field sizes) against this module's server:
    61 + 64 pass for lib60870-C and for cB-Sigma, 55 + 64 for digitalpetri (6
    cases with a common address other than its link address not run). 0
    failures (INTEROPERABILITY.md).
  • iec103/interop: the 7 cases of generic services and disturbance data and
    5 value checks. Open103's client against iec103/server: the disturbance
    transfer case passes and the description, tags and channel ratings match
    the fixture; its values hit the known Open103 bug open103-asdu30-nfe.
    vitusdong's client: the disturbance list case passes; the generic cases,
    the transfer and the value checks are known vitusdong bugs. This module's
    client against vitusdong's server: generic read, generic write and the
    list are known server bugs, asserted on the octets; the transfer is
    skipped (vitusdong declares no disturbanceDataServer). The bugs no
    harness pairing shows are in testdata/known-bugs-consumer.tsv (six
    entries); none is counted as a pass
    (docs/iec103/INTEROPERABILITY.md).
  • Unit and e2e: the counter freeze returning at the confirmation
    (iec104/client), the C_TS_TA_1 counter starting at 0 (telecontrol),
    a full IEC 103 class 1 queue (iec103/server), a broadcast on a closed
    IEC 103 client.

Documentation

  • docs/IEC104_PARITY.md: the decision that iec104/client shares the
    matching rules of telecontrol but not telecontrol.Requester, and why.
  • docs/iec103/INTEROPERABILITY.md: interpretation 12, the numbering of the
    disturbance values (NFE counts from 0, as TAP counts tag positions), and
    the contract 2.3 results.
  • README, LIMITATIONS, ROADMAP, FEATURE-STATUS, STANDARDS: the IEC 101 and
    IEC 103 evidence of this release.

Behaviour changes

CounterInterrogate with a freeze or reset qualifier returns at the
confirmation.