Interface NuggetAdminService

All Superinterfaces:

AutoCloseable, NuggetDiscoveryService

public interface NuggetAdminService
extends NuggetDiscoveryService, AutoCloseable

Headless nugget administration admission service.

This contract is transport-neutral and presentation-neutral. It does not start a listener, parse CLI commands, or grant authorization. Implementations are thread-safe unless their owning runtime has been closed.

Method Summary

Modifier and Type	Method	Description
default NuggetAdminCommandResult<NuggetAdminCapabilities>	adminCapabilities(NuggetAdminRequestContext context)	Returns the public Phase 7.8 administration contract capabilities for this provider.
default NuggetAdminCommandResult<?>	adminCommand(NuggetAdminCommandRequest<?> request)	Evaluates an optional shared command envelope around existing typed public operation families.
NuggetIntrospection.Result<NuggetIntrospection.ApplicationDetail>	application(NuggetIntrospection.Request request, String applicationInstanceId)	Returns safe application detail, or a safe not-found result.
default NuggetApplicationLifecycle.Result	applicationLifecycle(NuggetApplicationLifecycle.Request request)	Executes or plans an application lifecycle operation after admission, authorization, server-side feature gates, deadline checks, and redaction.
NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.ApplicationSummary>>	applications(NuggetIntrospection.Request request, NuggetIntrospection.Query query)	Returns safe application summaries.
NuggetAuthenticationResult	authenticate(NuggetAuthenticationRequest request, char[] pin)	Attempts PIN admission using separate shortest-scope credential material.
void	close()	Stops accepting new admission requests and releases owned secret material where practical.
NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.DiskVolumeSummary>>	disk(NuggetIntrospection.Request request, NuggetIntrospection.DiskQuery query)	Returns safe disk and storage-root summaries.
NuggetIntrospection.Result<NuggetIntrospection.EnvironmentSummary>	environment(NuggetIntrospection.Request request)	Returns safe JVM and process environment information.
NuggetIntrospection.Result<NuggetIntrospection.HealthSummary>	health(NuggetIntrospection.Request request)	Returns read-only health state.
NuggetIntrospection.Result<NuggetIntrospection.MetricsSummary>	metrics(NuggetIntrospection.Request request)	Returns bounded safe metrics.
default NuggetControl.Result	nuggetControl(NuggetControl.Request request)	Executes or plans a nugget-level drain, shutdown, or self-termination operation after admission, authorization, exact target validation, confirmation, server-side feature gates, deadline checks, and redaction.
NuggetIntrospection.Result<NuggetIntrospection.ObjectDetail>	object(NuggetIntrospection.Request request, String objectId)	Returns safe object/service detail, or a safe not-found result.
NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.ObjectSummary>>	objects(NuggetIntrospection.Request request, NuggetIntrospection.Query query)	Returns safe object/service summaries.
NuggetIntrospection.Result<NuggetIntrospection.Overview>	overview(NuggetIntrospection.Request request)	Returns a read-only overview after PIN admission and authorization.
NuggetIntrospection.Result<NuggetIntrospection.ReadinessSummary>	readiness(NuggetIntrospection.Request request)	Returns read-only readiness state.
NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.RecentErrorEntry>>	recentErrors(NuggetIntrospection.Request request, NuggetIntrospection.RecentErrorQuery query)	Returns bounded safe recent errors.
NuggetIntrospection.Result<NuggetIntrospection.RegistrySummary>	registry(NuggetIntrospection.Request request)	Returns a safe registry summary.
NuggetIntrospection.Result<NuggetIntrospection.RepositorySummary>	repository(NuggetIntrospection.Request request)	Returns a safe application repository summary.
NuggetIntrospection.Result<NuggetIntrospection.RuntimeSummary>	runtime(NuggetIntrospection.Request request)	Returns safe runtime status projection.
NuggetStatus	status()	Returns a safe status snapshot.
NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.TransportSummary>>	transports(NuggetIntrospection.Request request, NuggetIntrospection.Query query)	Returns safe transport summaries.

Methods inherited from interface NuggetDiscoveryService

discover, discoveryStatus, resolve

Method Details

status

NuggetStatus status()

Returns a safe status snapshot.

Returns:

current status

adminCapabilities

default NuggetAdminCommandResult<NuggetAdminCapabilities> adminCapabilities(NuggetAdminRequestContext context)

Returns the public Phase 7.8 administration contract capabilities for this provider.

The result is presentation-neutral and does not grant admission or authorization. Implementations that do not understand the public contract must return a truthful unavailable result rather than fabricating support. Unsupported request protocol versions are rejected by NuggetAdminRequestContext construction before this method can be invoked with such a context.

Parameters:

context - request context

Returns:

safe capability result

adminCommand

default NuggetAdminCommandResult<?> adminCommand(NuggetAdminCommandRequest<?> request)

Evaluates an optional shared command envelope around existing typed public operation families.

This method is an adapter surface for clients that need one public envelope shape for JSON or future transport bindings. It must not replace the typed methods on this interface, must not accept command-line text, free-form method names, or arbitrary JSON object maps, and must not fabricate success for providers that do not implement the requested typed family. The default implementation returns a truthful unavailable result without performing admission, authorization, discovery, introspection, lifecycle, control, audit, or provider work.

Parameters:

request - typed command envelope

Returns:

safe unavailable command result

authenticate

NuggetAuthenticationResult authenticate(NuggetAuthenticationRequest request,
 char[] pin)

Attempts PIN admission using separate shortest-scope credential material.

The supplied pin is not retained by the service after the method returns. Callers remain responsible for clearing their original buffer after the call.

Parameters:

request - request metadata

pin - clear PIN characters

Returns:

safe admission result

overview

NuggetIntrospection.Result<NuggetIntrospection.Overview> overview(NuggetIntrospection.Request request)

Returns a read-only overview after PIN admission and authorization.

Parameters:

request - introspection request metadata

Returns:

safe overview result

environment

NuggetIntrospection.Result<NuggetIntrospection.EnvironmentSummary> environment(NuggetIntrospection.Request request)

Returns safe JVM and process environment information.

Parameters:

request - introspection request metadata

Returns:

safe environment result

disk

NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.DiskVolumeSummary>> disk(NuggetIntrospection.Request request,
 NuggetIntrospection.DiskQuery query)

Returns safe disk and storage-root summaries.

Parameters:

request - introspection request metadata

query - disk query

Returns:

safe disk collection result

health

NuggetIntrospection.Result<NuggetIntrospection.HealthSummary> health(NuggetIntrospection.Request request)

Returns read-only health state.

Parameters:

request - introspection request metadata

Returns:

safe health result

readiness

NuggetIntrospection.Result<NuggetIntrospection.ReadinessSummary> readiness(NuggetIntrospection.Request request)

Returns read-only readiness state.

Parameters:

request - introspection request metadata

Returns:

safe readiness result

runtime

NuggetIntrospection.Result<NuggetIntrospection.RuntimeSummary> runtime(NuggetIntrospection.Request request)

Returns safe runtime status projection.

Parameters:

request - introspection request metadata

Returns:

safe runtime result

transports

NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.TransportSummary>> transports(NuggetIntrospection.Request request,
 NuggetIntrospection.Query query)

Returns safe transport summaries.

Parameters:

request - introspection request metadata

query - collection query

Returns:

safe transport collection result

registry

NuggetIntrospection.Result<NuggetIntrospection.RegistrySummary> registry(NuggetIntrospection.Request request)

Returns a safe registry summary.

Parameters:

request - introspection request metadata

Returns:

safe registry result

repository

NuggetIntrospection.Result<NuggetIntrospection.RepositorySummary> repository(NuggetIntrospection.Request request)

Returns a safe application repository summary.

Parameters:

request - introspection request metadata

Returns:

safe repository result

applications

NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.ApplicationSummary>> applications(NuggetIntrospection.Request request,
 NuggetIntrospection.Query query)

Returns safe application summaries.

Parameters:

request - introspection request metadata

query - collection query

Returns:

safe application collection result

application

NuggetIntrospection.Result<NuggetIntrospection.ApplicationDetail> application(NuggetIntrospection.Request request,
 String applicationInstanceId)

Returns safe application detail, or a safe not-found result.

Parameters:

request - introspection request metadata

applicationInstanceId - application instance id

Returns:

safe application detail result

objects

NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.ObjectSummary>> objects(NuggetIntrospection.Request request,
 NuggetIntrospection.Query query)

Returns safe object/service summaries.

Parameters:

request - introspection request metadata

query - collection query

Returns:

safe object collection result

object

NuggetIntrospection.Result<NuggetIntrospection.ObjectDetail> object(NuggetIntrospection.Request request,
 String objectId)

Returns safe object/service detail, or a safe not-found result.

Parameters:

request - introspection request metadata

objectId - object id

Returns:

safe object detail result

metrics

NuggetIntrospection.Result<NuggetIntrospection.MetricsSummary> metrics(NuggetIntrospection.Request request)

Returns bounded safe metrics.

Parameters:

request - introspection request metadata

Returns:

safe metrics result

recentErrors

NuggetIntrospection.Result<NuggetIntrospection.CollectionResult<NuggetIntrospection.RecentErrorEntry>> recentErrors(NuggetIntrospection.Request request,
 NuggetIntrospection.RecentErrorQuery query)

Returns bounded safe recent errors.

Parameters:

request - introspection request metadata

query - recent-error query

Returns:

safe recent-error collection result

applicationLifecycle

default NuggetApplicationLifecycle.Result applicationLifecycle(NuggetApplicationLifecycle.Request request)

Executes or plans an application lifecycle operation after admission, authorization, server-side feature gates, deadline checks, and redaction.

This method is presentation-neutral. Implementations must delegate to the configured public application deployer contract and must not create CLI-local lifecycle state or bypass repository verification, authorization, resource policy, lifecycle state checks, audit, or application-platform cleanup diagnostics. PIN admission is only an admission gate; it is not authorization.

Parameters:

request - lifecycle request metadata

Returns:

safe lifecycle result

The default implementation preserves source compatibility for implementations compiled against earlier versions of this interface. It performs no PIN admission, authorization, provider lookup, planning, activation, drain, stop, unload, audit mutation, or other application lifecycle work. It returns a bounded safe NuggetApplicationLifecycle.Outcome.UNAVAILABLE result with a normalized MiddlewareErrorCode.UNAVAILABLE error so callers can distinguish an older or non-lifecycle implementation from a successful lifecycle operation.

nuggetControl

default NuggetControl.Result nuggetControl(NuggetControl.Request request)

Executes or plans a nugget-level drain, shutdown, or self-termination operation after admission, authorization, exact target validation, confirmation, server-side feature gates, deadline checks, and redaction.

This method is presentation-neutral. Implementations must operate only on the owning nugget subject and must not provide arbitrary operating system process control, shell execution, process-id selection, or direct JVM termination primitives as production behavior. PIN admission is only an admission gate; it is not authorization. Confirmation challenges are credentials and must remain redacted outside the direct confirmation-required response.

Parameters:

request - nugget-control request metadata

Returns:

safe nugget-control result

The default implementation preserves source compatibility for implementations compiled against earlier versions of this interface. It performs no PIN admission, authorization, confirmation, drain, runtime shutdown, termination, audit mutation, or other nugget-control work. It returns a bounded safe NuggetControl.Outcome.UNAVAILABLE result with a normalized MiddlewareErrorCode.UNAVAILABLE error.

close

void close()

Stops accepting new admission requests and releases owned secret material where practical.

Specified by:

close in interface AutoCloseable