001/*
002 * Copyright 2025 devteam@scivics-lab.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing,
011 * software distributed under the License is distributed on an
012 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013 * either express or implied.  See the License for the
014 * specific language governing permissions and limitations
015 * under the License.
016 */
017
018package com.scivicslab.actoriac.log;
019
020import java.util.List;
021
022/**
023 * Interface for distributed log storage.
024 *
025 * <p>This interface defines operations for storing and querying logs
026 * from distributed workflow execution across multiple nodes.</p>
027 *
028 * @author devteam@scivics-lab.com
029 */
030public interface DistributedLogStore extends AutoCloseable {
031
032    /**
033     * Starts a new workflow execution session.
034     *
035     * @param workflowName name of the workflow being executed
036     * @param nodeCount number of nodes participating in this session
037     * @return session ID for subsequent log entries
038     */
039    long startSession(String workflowName, int nodeCount);
040
041    /**
042     * Starts a new workflow execution session with overlay and inventory info.
043     *
044     * @param workflowName name of the workflow being executed
045     * @param overlayName name of the overlay being used (may be null)
046     * @param inventoryName name of the inventory file being used (may be null)
047     * @param nodeCount number of nodes participating in this session
048     * @return session ID for subsequent log entries
049     */
050    long startSession(String workflowName, String overlayName, String inventoryName, int nodeCount);
051
052    /**
053     * Records a log entry.
054     *
055     * @param sessionId session ID from startSession()
056     * @param nodeId identifier of the node generating this log
057     * @param level log level
058     * @param message log message
059     */
060    void log(long sessionId, String nodeId, LogLevel level, String message);
061
062    /**
063     * Records a log entry with vertex context.
064     *
065     * @param sessionId session ID from startSession()
066     * @param nodeId identifier of the node
067     * @param vertexName current vertex name in workflow
068     * @param level log level
069     * @param message log message
070     */
071    void log(long sessionId, String nodeId, String vertexName, LogLevel level, String message);
072
073    /**
074     * Records an action result.
075     *
076     * @param sessionId session ID
077     * @param nodeId node identifier
078     * @param vertexName vertex name
079     * @param actionName action/method name
080     * @param exitCode command exit code (0 for success)
081     * @param durationMs execution duration in milliseconds
082     * @param output command output or result message
083     */
084    void logAction(long sessionId, String nodeId, String vertexName,
085                   String actionName, int exitCode, long durationMs, String output);
086
087    /**
088     * Marks a node as succeeded in this session.
089     *
090     * @param sessionId session ID
091     * @param nodeId node identifier
092     */
093    void markNodeSuccess(long sessionId, String nodeId);
094
095    /**
096     * Marks a node as failed in this session.
097     *
098     * @param sessionId session ID
099     * @param nodeId node identifier
100     * @param reason failure reason
101     */
102    void markNodeFailed(long sessionId, String nodeId, String reason);
103
104    /**
105     * Ends a session with the given status.
106     *
107     * @param sessionId session ID
108     * @param status final status
109     */
110    void endSession(long sessionId, SessionStatus status);
111
112    /**
113     * Retrieves all log entries for a specific node in a session.
114     *
115     * @param sessionId session ID
116     * @param nodeId node identifier
117     * @return list of log entries
118     */
119    List<LogEntry> getLogsByNode(long sessionId, String nodeId);
120
121    /**
122     * Retrieves log entries filtered by level.
123     *
124     * @param sessionId session ID
125     * @param minLevel minimum log level to include
126     * @return list of log entries
127     */
128    List<LogEntry> getLogsByLevel(long sessionId, LogLevel minLevel);
129
130    /**
131     * Retrieves error logs for a session.
132     *
133     * @param sessionId session ID
134     * @return list of error log entries
135     */
136    default List<LogEntry> getErrors(long sessionId) {
137        return getLogsByLevel(sessionId, LogLevel.ERROR);
138    }
139
140    /**
141     * Gets a summary of the session.
142     *
143     * @param sessionId session ID
144     * @return session summary
145     */
146    SessionSummary getSummary(long sessionId);
147
148    /**
149     * Gets the most recent session ID.
150     *
151     * @return latest session ID, or -1 if no sessions exist
152     */
153    long getLatestSessionId();
154
155    /**
156     * Lists all sessions.
157     *
158     * @param limit maximum number of sessions to return
159     * @return list of session summaries
160     */
161    List<SessionSummary> listSessions(int limit);
162}