Java 공통 runtime 공개 인터페이스

인터페이스 목차 · Host relocation과 종료 계약

이 문서는 Java에서 host의 실행 상태, object relocation, 종료 요청과 공통 비동기 operation을 표현하는 공개 타입을 고정한다. 공통 문서가 동작을 정의하며, 아래 선언은 Java에서 사용하는 타입과 member의 정확한 형태를 보여 준다.

공개 계약은 systems.zlink.framework Java module이 소유한다. 이 module은 이 언어별 interface에 기록한 application package와 runtime.host만 일반 consumer에게 export한다. Raw binding 구현은 별도 internal artifact에 있으며 application compile classpath에는 포함되지 않는다. Named module에서도 Framework companion module에 필요한 package만 export한다. 따라서 raw binding type은 public API inventory에 포함되지 않는다.

public enum ZLinkFrameworkRuntimeState {
 PREPARING(0), SERVING(1), RELOCATING(2), RELOCATED(3),
 DRAINING(4), STOPPED(5), ERROR(6);
 private final int wireValue;
 ZLinkFrameworkRuntimeState(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public enum ZLinkFrameworkRelocationOutcome {
 RELOCATED(0), BLOCKED(1);
 private final int wireValue;
 ZLinkFrameworkRelocationOutcome(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public enum ZLinkFrameworkRelocationMode {
 PLANNED_MAINTENANCE(0), ROLLING_UPDATE(1);
 private final int wireValue;
 ZLinkFrameworkRelocationMode(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public enum ZLinkFrameworkRelocationReason {
 NONE(0), TARGET_UNAVAILABLE(1), STORE_UNAVAILABLE(2),
 RELOCATION_DISABLED(3), STATE_INCOMPATIBLE(4),
 DEADLINE_EXCEEDED(5), RELOCATION_FAILED(6),
 RUNTIME_NOT_READY(7), MANUAL_TOPOLOGY_UNSUPPORTED(8),
 SHUTDOWN_REQUESTED(9), OPERATION_IN_PROGRESS(10);
 private final int wireValue;
 ZLinkFrameworkRelocationReason(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public record ZLinkFrameworkRelocationOptions(
 ZLinkFrameworkRelocationMode mode,
 Long targetApplicationVersion,
 Duration deadline) {}

public record ZLinkFrameworkRelocationResult(
 ZLinkFrameworkRelocationMode mode,
 long effectiveTargetApplicationVersion,
 ZLinkFrameworkRelocationOutcome outcome,
 ZLinkFrameworkRelocationReason reason) {}

public enum ZLinkFrameworkTerminationOutcome {
 STOPPED(0), FORCE_STOPPED(1);
 private final int wireValue;
 ZLinkFrameworkTerminationOutcome(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public enum ZLinkFrameworkTerminationReason {
 NONE(0), DEADLINE_EXCEEDED(1), TEARDOWN_FAILED(2);
 private final int wireValue;
 ZLinkFrameworkTerminationReason(int wireValue) { this.wireValue = wireValue; }
 public int wireValue() { return wireValue; }
}

public record ZLinkFrameworkTerminationResult(
 ZLinkFrameworkTerminationOutcome outcome,
 ZLinkFrameworkTerminationReason reason) {}

public enum ZLinkListenerKind {
 ROUTE_MESH, CLIENT_SERVER, FANOUT, STREAM
}

public record ZLinkListenerStatus(
 ZLinkListenerKind kind,
 String name,
 String endpoint,
 Instant observedAt) {}

public final class ZLinkFrameworkRuntime
 implements AutoCloseable, ZLinkMessageFlowControl {
 public ZLinkClient client();
 public void setMessageFlowMode(ZLinkMessageFlowLogMode mode);
 public ZLinkMessageFlowLogMode messageFlowMode();
 public ZLinkFanoutClient fanout();
 public ZLinkRouteClient route();
 public ZLinkRouteMeshRuntime routeMeshRuntime();
 public ZLinkClientServerRuntime clientServerRuntime();
 public ZLinkFanoutRuntime fanoutRuntime();
 public ZLinkListenerStatus listenerStatus(
 ZLinkListenerKind kind, String name);
 public ZLinkSpotManager spotManager();
 public ZLinkSpotOutbound spotOutbound();
 public ZLinkSpotPublisherClient spotPublisherClient();
 public ZLinkLocationRuntimeQuery monitoringLocationRuntimeQuery();
 public ZLinkLocationReadiness locationReadiness();
 public boolean stopSpotRuntime();
 public ZLinkActorManager actorManager();
 public ZLinkActorClient actorClient();
 public ZLinkSessionActorsRuntime sessionActors(String streamNodeName, RoutingId sessionRid);

 public ZLinkFrameworkRuntimeStatus status();
 public Flow.Publisher<ZLinkObservedStatus<ZLinkFrameworkRuntimeStatus>> observe();
 public CompletionStage<ZLinkFrameworkRelocationResult> relocate(
 ZLinkFrameworkRelocationOptions options);
 public CompletionStage<ZLinkFrameworkTerminationResult> shutdown();
 public CompletionStage<ZLinkFrameworkTerminationResult> shutdown(Duration deadline);
 public void close();
}

observe()가 전달하는 ZLinkObservedStatus<T>와 ZLinkObservationLoss의 canonical declaration은 Monitoring 공개 인터페이스가 소유한다. 이 문서는 host status stream이 같은 envelope를 사용한다는 사실만 고정한다.

relocate(options)와 shutdown()은 host lifecycle API다. Java는 shared operation의 결과를 호출별 CompletableFuture view로 전달하고 취소는 해당 waiter에만 적용한다. Relocation target, deadline, commit과 shutdown은 Host relocation flow가 정한다. Java는 유효하지 않은 mode·version 조합을 IllegalArgumentException으로 표현한다.

ZLinkFrameworkRuntime은 RouteMesh, ClientServer와 automatic fanout의 monitoring view를 각각 하나씩 소유한다. 세 accessor는 runtime 수명 동안 같은 객체를 반환하며 호출할 때 새 adapter를 만들지 않는다. Spring starter가 제공하는 topology runtime bean도 이 accessor가 반환한 객체와 reference identity가 같다.

Spring starter는 ZLinkFrameworkRuntime bean을 제공한다. 운영 maintenance endpoint는 relocate(options) 결과가 RELOCATED일 때 shutdown()을 호출한다. Relocation 없이 종료하려면 shutdown()만 호출한다. 별도 drain facade와 MeshName을 받는 partial operation은 없다.

Application은 ZLinkFrameworkRuntime을 직접 시작하지 않는다. Runtime 생성과 시작은 Spring starter가 소유한다. 따라서 start(...) factory는 public contract에 포함하지 않는다. Core의 internal bootstrap은 starter module에만 qualified export한다. Testkit은 test source에만 같은 package access helper를 둔다.

Runtime은 각 listener의 현재 advertised endpoint를 조회하는 public member도 제공한다. listenerStatus(kind, name)은 공통 listener 상태 조회의 Java 투영이다. kind는 RouteMesh, ClientServer, Fanout 또는 STREAM을 지정하고 name은 해당 registration name을 지정한다. 조회가 configuration error로 끝나면 ZLinkFrameworkErrorKind.NOT_CONFIGURED로 실패한다. 반환된 status의 observedAt은 조회 시각이다.

public member javap inventory

아래 선언은 javap가 출력하는 binary signature 형식으로 Java public type과 member를 고정한다.

public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState PREPARING;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState SERVING;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState RELOCATING;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState RELOCATED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState DRAINING;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState STOPPED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRuntimeState ERROR;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome RELOCATED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome BLOCKED;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode PLANNED_MAINTENANCE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode ROLLING_UPDATE;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason NONE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason TARGET_UNAVAILABLE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason STORE_UNAVAILABLE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason RELOCATION_DISABLED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason STATE_INCOMPATIBLE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason DEADLINE_EXCEEDED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason RELOCATION_FAILED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason RUNTIME_NOT_READY;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason MANUAL_TOPOLOGY_UNSUPPORTED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason SHUTDOWN_REQUESTED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason OPERATION_IN_PROGRESS;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOptions extends java.lang.Record {
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOptions(systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode, java.lang.Long, java.time.Duration);
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode mode();
 public java.lang.Long targetApplicationVersion();
 public java.time.Duration deadline();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationResult extends java.lang.Record {
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationResult(systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode, long, systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome, systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason);
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationMode mode();
 public long effectiveTargetApplicationVersion();
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationOutcome outcome();
 public systems.zlink.framework.runtime.host.ZLinkFrameworkRelocationReason reason();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome STOPPED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome FORCE_STOPPED;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason extends java.lang.Enum<systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason> {
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason NONE;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason DEADLINE_EXCEEDED;
 public static final systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason TEARDOWN_FAILED;
 public int wireValue();
}
public final class systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationResult extends java.lang.Record {
 public systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationResult(systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome, systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason);
 public systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationOutcome outcome();
 public systems.zlink.framework.runtime.host.ZLinkFrameworkTerminationReason reason();
}
public final class systems.zlink.framework.monitoring.ZLinkListenerKind extends java.lang.Enum<systems.zlink.framework.monitoring.ZLinkListenerKind> {
 public static final systems.zlink.framework.monitoring.ZLinkListenerKind ROUTE_MESH;
 public static final systems.zlink.framework.monitoring.ZLinkListenerKind CLIENT_SERVER;
 public static final systems.zlink.framework.monitoring.ZLinkListenerKind FANOUT;
 public static final systems.zlink.framework.monitoring.ZLinkListenerKind STREAM;
 public static systems.zlink.framework.monitoring.ZLinkListenerKind[] values();
 public static systems.zlink.framework.monitoring.ZLinkListenerKind valueOf(java.lang.String);
}
public final class systems.zlink.framework.monitoring.ZLinkListenerStatus extends java.lang.Record {
 public systems.zlink.framework.monitoring.ZLinkListenerStatus(systems.zlink.framework.monitoring.ZLinkListenerKind, java.lang.String, java.lang.String, java.time.Instant);
 public systems.zlink.framework.monitoring.ZLinkListenerKind kind();
 public java.lang.String name();
 public java.lang.String endpoint();
 public java.time.Instant observedAt();
}
public interface systems.zlink.framework.ZLinkMessageContext {
 public abstract java.util.Optional<java.lang.String> meshName();
 public abstract java.util.Optional<java.lang.String> channelName();
 public abstract java.lang.String packetName();
 public abstract java.util.Optional<java.lang.String> contentType();
 public abstract java.util.Map<java.lang.String, java.lang.String> metadata();
 public abstract java.util.Optional<java.lang.String> correlationId();
}
public final class systems.zlink.framework.ZLinkHandlerDispatchKind extends java.lang.Enum<systems.zlink.framework.ZLinkHandlerDispatchKind> {
 public static final systems.zlink.framework.ZLinkHandlerDispatchKind NODE_DIRECT_SEND;
 public static final systems.zlink.framework.ZLinkHandlerDispatchKind NODE_DIRECT_REQUEST;
 public static final systems.zlink.framework.ZLinkHandlerDispatchKind CHANNEL_SEND;
 public static final systems.zlink.framework.ZLinkHandlerDispatchKind CHANNEL_REQUEST;
 public static final systems.zlink.framework.ZLinkHandlerDispatchKind CLASSIC_FANOUT;
}
public interface systems.zlink.framework.ZLinkHandlerFilterContext extends systems.zlink.framework.ZLinkMessageContext {
 public abstract systems.zlink.framework.ZLinkHandlerDispatchKind dispatchKind();
}
public interface systems.zlink.framework.ZLinkHandlerFilter {
 public abstract <T> java.util.concurrent.CompletionStage<T> invoke(systems.zlink.framework.ZLinkHandlerFilterContext, systems.zlink.framework.ZLinkHandlerFilterNext<T>);
}
public interface systems.zlink.framework.ZLinkMessageSerializer {
 public abstract <T> systems.zlink.framework.ZLinkEncodedPayload serialize(T);
 public default <T> systems.zlink.framework.ZLinkEncodedPayload serialize(T, java.lang.Class<?>);
 public abstract <T> T deserialize(systems.zlink.framework.ZLinkEncodedPayload, java.lang.Class<T>);
 public default void prepare(java.lang.Class<?>);
}
public interface systems.zlink.framework.ZLinkHandlerFilterNext<T> {
 public abstract java.util.concurrent.CompletionStage<T> invoke();
}
public final class systems.zlink.framework.errors.ZLinkFrameworkErrorKind extends java.lang.Enum<systems.zlink.framework.errors.ZLinkFrameworkErrorKind> {
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind NOT_FOUND;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind ALREADY_EXISTS;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind TYPE_MISMATCH;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind NOT_CONFIGURED;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind REJECTED;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind UNAVAILABLE;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind DEADLINE_EXCEEDED;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind SHUTTING_DOWN;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind PROTOCOL_ERROR;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind INVALID_OPERATION;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind DATA_LOST;
 public static final systems.zlink.framework.errors.ZLinkFrameworkErrorKind INTERNAL_FAILURE;
 public static systems.zlink.framework.errors.ZLinkFrameworkErrorKind[] values();
 public static systems.zlink.framework.errors.ZLinkFrameworkErrorKind valueOf(java.lang.String);
 public int value();
 public static systems.zlink.framework.errors.ZLinkFrameworkErrorKind fromValue(int);
}
public class systems.zlink.framework.errors.ZLinkFrameworkException extends java.lang.RuntimeException {
 public systems.zlink.framework.errors.ZLinkFrameworkException(systems.zlink.framework.errors.ZLinkFrameworkErrorKind, java.lang.String);
 public systems.zlink.framework.errors.ZLinkFrameworkException(systems.zlink.framework.errors.ZLinkFrameworkErrorKind, java.lang.String, java.lang.Throwable);
 public systems.zlink.framework.errors.ZLinkFrameworkErrorKind kind();
}

ZLinkFrameworkErrorKind.value()는 선언 순서와 무관하게 공통 숫자 0..12를 반환한다. fromValue(int)도 공통 오류 모델의 같은 mapping을 사용한다. Public exception은 재시도 여부를 제공하지 않는다.

Serializer와 오류 public signature

받은 ZLinkMessage에서 첫 decode(Class<T>)가 값 또는 실패를 확정한다. 같은 type으로 다시 호출하면 같은 값을 반환하고 serializer를 다시 호출하지 않는다. 다른 type으로 호출해도 다시 역직렬화하지 않으며, 첫 값이 그 type과 다르면 TYPE_MISMATCH로 끝난다. 첫 호출이 실패했다면 그 실패를 다시 전달한다.

public final class systems.zlink.framework.ZLinkEncodedPayload {
 public static systems.zlink.framework.ZLinkEncodedPayload from(byte[]);
 public byte[] bytes();
}
public final class systems.zlink.framework.errors.ZLinkConfigurationException extends systems.zlink.framework.errors.ZLinkFrameworkException {
 public systems.zlink.framework.errors.ZLinkConfigurationException(java.lang.String);
 public systems.zlink.framework.errors.ZLinkConfigurationException(java.lang.String, java.lang.Throwable);
}
public final class systems.zlink.framework.messaging.ZLinkMessage {
 public static systems.zlink.framework.messaging.ZLinkMessage empty();
 public static systems.zlink.framework.messaging.ZLinkMessage of(java.lang.Object);
 public static systems.zlink.framework.messaging.ZLinkMessage of(java.lang.Object, java.lang.Class<?>);
 public static systems.zlink.framework.messaging.ZLinkMessage fromEncoded(systems.zlink.framework.ZLinkEncodedPayload, systems.zlink.framework.ZLinkMessageSerializer);
 public boolean isEmpty();
 public java.lang.Class<?> declaredType();
 public <T> T decode(java.lang.Class<T>);
 public systems.zlink.framework.ZLinkEncodedPayload toEncodedPayload(systems.zlink.framework.ZLinkMessageSerializer);
}
public final class systems.zlink.framework.codecs.msgpack.ZLinkMessagePackCodec implements systems.zlink.framework.configuration.ZLinkCodecExtension,systems.zlink.stream.connector.ZLinkStreamTypedCodec {
 public static systems.zlink.framework.codecs.msgpack.ZLinkMessagePackCodec defaultCodec();
 public static systems.zlink.framework.codecs.msgpack.ZLinkMessagePackCodec forPayloadTypes(java.util.function.Predicate<java.lang.Class<?>>);
 public <T> systems.zlink.stream.connector.ZLinkStreamEncodedPayload encode(java.lang.String, T);
 public <T> T decode(systems.zlink.stream.connector.ZLinkStreamEncodedPayload, java.lang.Class<T>);
 public void register(systems.zlink.framework.configuration.ZLinkCodecRegistrar);
}
public final class systems.zlink.framework.codecs.protobuf.ZLinkProtobufCodec implements systems.zlink.framework.configuration.ZLinkCodecExtension,systems.zlink.stream.connector.ZLinkStreamTypedCodec {
 public static systems.zlink.framework.codecs.protobuf.ZLinkProtobufCodec defaultCodec();
 public <T> systems.zlink.stream.connector.ZLinkStreamEncodedPayload encode(java.lang.String, T);
 public <T> T decode(systems.zlink.stream.connector.ZLinkStreamEncodedPayload, java.lang.Class<T>);
 public void register(systems.zlink.framework.configuration.ZLinkCodecRegistrar);
}