V310 (#207)

Author: halturin

.github/ISSUE_TEMPLATE/bug-report.md

@@ -25,7 +25,7 @@ If applicable, add screenshots to help explain your problem.
 **Environment (please complete the following information):**
  - Arch: [e.g. aarch64 or x86_64]
  - OS: [e.g. Linux]
- - Framework Version [e.g. 2.1.0]
+ - Framework Version [e.g. 3.1.0]
  - Number of CPU or (GOMAXPROCS value)
 
 **Additional context**

.github/images/kaspersky.png

@@ -47,7 +47,7 @@ To inspect the node, network stack, running applications, and processes, you can
 To install the Observer tool, you need to have the Go compiler version 1.20 or higher. Run the following command:
 
 ```
-$ go install ergo.services/tools/observer@latest
+$ go install ergo.tools/observer@latest
 ```
 
 You can also embed the [Observer application](https://docs.ergo.services/extra-library/applications/observer) into your node. To see it in action, see example `demo` at https://github.com/ergo-services/examples. For more information https://docs.ergo.services/tools/observer 
@@ -61,7 +61,7 @@ For a quick start, use the [`ergo`](https://docs.ergo.services/tools/ergo) tool
 To install use the following command:
 
 ```
-$ go install ergo.services/tools/ergo@latest
+$ go install ergo.tools/ergo@latest
 ```
 
 Now, you can create your project with just one command. Here is example:
@@ -121,7 +121,7 @@ Since we included Observer application, open http://localhost:9911 to inspect yo
 
 ### Erlang support ###
 
-Starting from version 3.0.0, support for the Erlang network stack has been moved to a separate module and is distributed under the BSL 1.1 license - https://github.com/ergo-services/proto. You can find detailed information on using this module in the documentation at https://docs.ergo.services/extra-library/network-protocols/erlang.
+Starting from version 3.0.0, support for the Erlang network stack has been moved to a separate module - https://github.com/ergo-services/proto. Version 3.0 was distributed under the BSL 1.1 license, but starting from version 3.1 it is available under the MIT license. You can find detailed information on using this module in the documentation at https://docs.ergo.services/extra-library/network-protocols/erlang.
 
 ### Requirements ###
 
@@ -131,23 +131,35 @@ Starting from version 3.0.0, support for the Erlang network stack has been moved
 
 Fully detailed changelog see in the [ChangeLog](CHANGELOG.md) file.
 
-#### [v3.0.0](https://github.com/ergo-services/ergo/releases/tag/v1.999.300) 2024-09-04 [tag version v1.999.300] ####
-
-This version marks a significant milestone in the evolution of the Ergo Framework. The framework's design has been completely overhauled, and this version was built from the ground up. It includes:
-
-- Significant API Improvements: The `gen.Process`, `gen.Node`, and `gen.Network` interfaces have been enhanced with numerous convenient methods.
-- A New Network Stack: This version introduces a completely new network stack for improved performance and flexibility. See https://github.com/ergo-services/benchmarks for the details
-
-Alongside the release of Ergo Framework 3.0.0, new tools and an additional components library are also introduced:
-
-- Tools (observer, saturn) https://github.com/ergo-services/tools
-- Loggers (rotate, colored) - https://github.com/ergo-services/logger
-- Meta (websocket) - https://github.com/ergo-services/meta
-- Application (observer) - https://github.com/ergo-services/application
-- Registrar (client Saturn) - https://github.com/ergo-services/registrar
-- Proto (erlang23) - https://github.com/ergo-services/proto
-
-Finally, we've published comprehensive documentation for the framework, providing detailed guides to assist you in leveraging all the capabilities of Ergo Framework effectively. Its available at https://docs.ergo.services.
+#### [v3.1.0](https://github.com/ergo-services/ergo/releases/tag/v1.999.310) 2025-09-04 [tag version v1.999.310] ####
+
+**New Features**
+- **Cron Scheduler**: New `gen.Cron` interface enables scheduling tasks with cron expressions, supporting second-level precision for precise task execution. See https://docs.ergo.services/basics/cron
+- **Port Meta Process**: New `meta.Port` allows spawning and managing external OS processes with bidirectional communication through stdin/stdout/stderr. See https://docs.ergo.services/meta-processes/port, example https://github.com/ergo-services/examples/port
+- **Unit Testing Framework**: Comprehensive testing library (`testing/unit`) provides isolated actor testing with event capture and validation capabilities. See https://docs.ergo.services/testing/unit
+
+**Enhancements**
+- **Enhanced Logging**: Default logger now supports JSON output format with structured fields, improving observability and log processing
+- **Environment Management**: Added `gen.Process.EnvDefault()` and `gen.Node.EnvDefault()` methods
+- **Logger Fields**: Added `gen.Log.PushFields()` and `gen.Log.PopFields()` for contextual logging
+- **EDF Protocol**: Added support for `encoding.BinaryMarshaler/BinaryUnmarshaler` interfaces
+- **Performance**: Multiple optimizations across message handling and network operations
+
+**Critical Bug Fixes**
+- **Node Shutdown**: Fixed race condition causing "close of closed channel" panic during graceful shutdown
+- **Supervisor Issues**: Fixed OFO supervisor child termination (#213), restart intensity calculation with millisecond precision, and duplicate Terminate callbacks
+- **SIGTERM Handling**: Improved graceful shutdown behavior and SOFO supervisor cleanup
+- **EDF Codec**: Fixed nil slice/map decoding issues
+- **Local Registrar**: Improved resolver detection for service discovery
+
+**Extra Library**
+- **Module Independence**: All extra library modules (Logger, Meta, Registrar, etc...) are now independent Go modules with dependency management
+- **Tools Domain**: All tools moved to dedicated `ergo.tools` domain for better organization and distribution
+- **Proto**: `erlang23` (Erlang network stack implementation) changed from BSL 1.1 to MIT license for broader adoption and commercial use
+- **Registrar**: New etcd registrar implementation with distributed service discovery, hierarchical configuration, real-time cluster events. See https://docs.ergo.services/extra-library/registrars/etcd-client and example https://github.com/ergo-services/examples/docker
+- **Logger**: Added LogField support in colored logger, banner functionality, and fixed options handling. See https://docs.ergo.services/extra-library/loggers
+- **Application**: Observer application enhanced with new Applications page, Cron job details, and UI fixes. See https://docs.ergo.services/extra-library/applications/observer
+- **Benchmarks**: New serialization benchmarks comparing EDF vs Gob vs Protobuf performance, expanded test suite coverage. See https://github.com/ergo-services/benchmarks
 
 ### Development and debugging ###
 
@@ -163,7 +175,7 @@ To run tests with cleaned test cache:
 ```
 go vet
 go clean -testcache
-go test -v ./tests/...
+go test -v ./testing/tests/...
 ```
 
 ### Commercial support

.github/images/lilithgames.png

@@ -192,17 +192,14 @@ func (s *Supervisor) StartChild(name gen.Atom, args ...any) error {
 		return gen.ErrNotAllowed
 	}
 
-	if s.state != supStateNormal {
-		return ErrSupervisorStrategyActive
-	}
-
 	action, err := s.sup.childSpec(name)
 	if err != nil {
 		return err
 	}
 	if len(args) > 0 {
 		action.spec.Args = args
 	}
+
 	return s.handleAction(action)
 }
 
@@ -227,10 +224,6 @@ func (s *Supervisor) EnableChild(name gen.Atom) error {
 		return gen.ErrNotAllowed
 	}
 
-	if s.state != supStateNormal {
-		return ErrSupervisorStrategyActive
-	}
-
 	action, err := s.sup.childEnable(name)
 	if err != nil {
 		return err
@@ -317,6 +310,7 @@ func (s *Supervisor) ProcessInit(process gen.Process, args ...any) (rr error) {
 		if dup {
 			return ErrSupervisorChildDuplicate
 		}
+		duplicate[s.Name] = true
 	}
 
 	// create supervisor
@@ -561,14 +555,18 @@ func (s *Supervisor) handleAction(action supAction) error {
 			action.spec.Options.LinkParent = true
 
 			if action.spec.register {
-				pid, err = s.SpawnRegister(action.spec.Name, action.spec.Factory, action.spec.Options, action.spec.Args...)
+				pid, err = s.SpawnRegister(
+					action.spec.Name,
+					action.spec.Factory,
+					action.spec.Options,
+					action.spec.Args...)
 			} else {
 				pid, err = s.Spawn(action.spec.Factory, action.spec.Options, action.spec.Args...)
 			}
 
 			if err != nil {
-				action = s.sup.childTerminated(action.spec.Name, pid, err)
-				continue
+				s.state = supStateNormal
+				return err
 			}
 
 			if s.handleChild {
@@ -580,16 +578,26 @@ func (s *Supervisor) handleAction(action supAction) error {
 			continue
 
 		case supActionTerminateChildren:
+			if len(action.terminate) == 0 {
+				// no children. terminate this process
+				return action.reason
+			}
 			// on disabling child spec
 			s.state = supStateStrategy
 			for _, pid := range action.terminate {
-				s.SendExit(pid, action.reason)
-				s.Log().Info("Supervisor: terminate children %s", pid)
+				// TODO
+				// Child is disabling if exceeded restart limits. basically we dont need
+				// to send exit again.
+				// Current workaround: SendExit return error if its terminated already,
+				// so dont log misleading message
+				if err := s.SendExit(pid, action.reason); err == nil {
+					s.Log().Info("Supervisor: terminate children %s", pid)
+				}
 			}
+			s.state = supStateNormal
 			return nil
 
 		case supActionTerminate:
-			s.behavior.Terminate(action.reason)
 			return action.reason
 
 		default:
@@ -667,19 +675,26 @@ type supMessageChildTerminate struct {
 	reason error
 }
 
-// checkRestartIntensity returns true if exceeded
+// supCheckRestartIntensity returns true if exceeded
 func supCheckRestartIntensity(restarts []int64, period int, intensity int) ([]int64, bool) {
-	restarts = append(restarts, time.Now().Unix())
-	if len(restarts) < intensity {
+	// Use milliseconds for better granularity
+	now := time.Now().UnixMilli()
+	restarts = append(restarts, now)
+	if len(restarts) <= intensity {
 		return restarts, false
 	}
 
-	p := int(time.Now().Unix() - restarts[0])
-	if p > period {
+	// Remove old restarts outside the period window
+	periodMillis := int64(period) * 1000
+	for len(restarts) > 0 && now-restarts[0] > periodMillis {
 		restarts = restarts[1:]
-		return restarts, false
 	}
-	return restarts, true
+
+	// Check if we still exceed intensity after cleanup
+	if len(restarts) > intensity {
+		return restarts, true
+	}
+	return restarts, false
 }
 
 func validateChildSpec(s SupervisorChildSpec) error {

.github/images/ringcentral.png

@@ -402,6 +402,7 @@ func (s *supARFO) childEnable(name gen.Atom) (supAction, error) {
 		}
 
 		// it was disabled. enable it and start child process with this spec
+		cs.disabled = false
 
 		action.do = supActionStartChild
 		action.spec = *cs

README.md

@@ -311,7 +311,7 @@ func (s *supOFO) childTerminated(name gen.Atom, pid gen.PID, reason error) supAc
 		if cs.pid == empty {
 			continue
 		}
-		action.terminate = append(action.terminate, pid)
+		action.terminate = append(action.terminate, cs.pid)
 	}
 	action.do = supActionTerminateChildren
 	action.reason = ErrSupervisorRestartsExceeded
@@ -335,6 +335,7 @@ func (s *supOFO) childEnable(name gen.Atom) (supAction, error) {
 		}
 
 		// it was disabled. enable it and start child process with this spec
+		cs.disabled = false
 
 		action.do = supActionStartChild
 		action.spec = *cs

act/README.md

@@ -86,6 +86,7 @@ func (s *supSOFO) childSpec(name gen.Atom) (supAction, error) {
 	if spec.disabled {
 		return action, ErrSupervisorChildDisabled
 	}
+
 	action.do = supActionStartChild
 	action.spec = *spec
 	return action, nil