swift-mirror/docs/AccessControl.md

# Access Control

The general guiding principle of Swift access control:

> **No entity can be defined in terms of another entity that has a lower
> access level.**

There are four levels of access: \"private\", \"fileprivate\",
\"internal\", and \"public\". Private entities can only be accessed from
within the lexical scope where they are defined. File-private entities
can only be accessed from within the source file where they are defined.
Internal entities can be accessed anywhere within the module they are
defined. Public entities can be accessed from anywhere within the module
and from any other context that imports the current module.

The names `public` and `private` have precedent in many languages;
`internal` comes from C\# and `fileprivate` from the Swift community. In
the future, `public` may be used for both API and SPI, at which point we
may design additional annotations to distinguish the two.

By default, most entities in a source file have `internal` access. This
optimizes for the most common case – a single-target application
project – while not accidentally revealing entities to clients of a
framework module.

_**Warning**_

This document has not yet been updated for
[SE-0117](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0117-non-public-subclassable-by-default.md),
which adds the \"open\" level of access.

## Rules

Access to a particular entity is considered relative to the current
*access scope.* The access scope of an entity is its immediate lexical
scope (if `private`), the current file (if `fileprivate`), the current
module (if `internal`), or the current program (if `public`). A
reference to an entity may only be written within the entity\'s access
scope.

If a particular entity is not accessible, it does not appear in name
lookup, unlike in C++. However, access control does not restrict access
to members via runtime reflection (where applicable), nor does it
necessarily restrict visibility of symbols in a linked binary.

### Globals and Members

All globals and members have a default access level of `internal`,
except within extensions (as described below).

A declaration may have any access level less than or equal to the access
level of its type. That is, a `private` constant can have `public` type,
but not the other way around. It is legal for a member to have greater
access than its enclosing type, but this has no effect.

Accessors for variables have the same access level as their associated
variable. The setter may be explicitly annotated with an access level
less than or equal to the access level of the variable; this is written
as `private(set)` or `internal(set)` before the `var` introducer.

An initializer, method, subscript, or property may have any access level
less than or equal to the access level of its type (including the
implicit \'Self\' type), with a few additional rules:

-   If a member is used to satisfy a protocol requirement, its access
    level must be at least as high as the protocol conformance\'s; see
    ["Protocols"](#protocols) below.
-   If an initializer is `required` by a superclass, its access level
    must be at least as high as the access level of the subclass itself.
-   Accessors for subscripts follow the same rules as accessors for
    variables.
-   A member may be overridden whenever it is accessible.

The implicit memberwise initializer for a struct has the minimum access
level of all of the struct\'s stored properties, except that if all
properties are `public` the initializer is `internal`. The implicit
no-argument initializer for structs and classes follows the default
access level for the type.

Currently, enum cases always have the same access level as the enclosing
enum.

Deinitializers are only invoked by the runtime and do not nominally have
access. Internally, the compiler represents them as having the same
access level as the enclosing type.

### Protocols

A protocol may have any access level less than or equal to the access
levels of the protocols it refines. That is, a `private` ExtendedWidget
protocol can refine a `public` Widget protocol, but not the other way
around.

The access level of a requirement is the access level of the enclosing
protocol, even when the protocol is `public`. Currently, requirements
may not be given a lower access level than the enclosing protocol.

Swift does not currently support private protocol conformances, so for
runtime consistency, the access level of the conformance of type T to
protocol P is equal to the minimum of T\'s access level and P\'s access
level; that is, the conformance is accessible whenever both T and P are
accessible. This does not change if the protocol is conformed to in an
extension. (The access level of a conformance is not currently reflected
in the source, but is a useful concept for applying restrictions
consistently.)

All members used to satisfy a conformance must have an access level at
least as high as the conformance\'s. This ensures consistency between
views of the type; if any member has a *lower* access level than the
conformance, then the member could be accessed anyway through a generic
function constrained by the protocol.

_**Note**_

This rule disallows an `internal` member of a protocol extension to
satisfy a `public` requirement for a `public` type. Removing this
limitation is not inherently unsafe, but (a) may be unexpected given the
lack of explicit reference to the member, and (b) results in references
to non-public symbols in the current representation.

A protocol may be used as a type whenever it is accessible. A nominal
can conform to a protocol whenever the protocol is accessible.

### Structs, Enums, and Classes

A struct, enum, or class may be used as a type whenever it is
accessible. A struct, enum, or class may be extended whenever it is
accessible.

A class may be subclassed whenever it is accessible. A class may have
any access level less than or equal to the access level of its
superclass.

Members within constrained extensions must have access less than or
equal to the access level of the types used in the constraints.

An extension may be marked with an explicit access modifier (e.g.
`private extension`), in which case the default access level of members
within the extension is changed to match. No member within such an
extension may have broader access than the new default.

Extensions with explicit access modifiers may not add new protocol
conformances, since Swift does not support private protocol conformances
(see ["Protocols"](#protocols) above).

A type may conform to a protocol with lower access than the type itself.

### Types

A nominal type\'s access level is the same as the access level of the
nominal declaration itself. A generic type\'s access level is the
minimum of the access level of the base type and the access levels of
all generic argument types.

A tuple type\'s access level is the minimum of the access levels of its
elements. A function type\'s access level is the minimum of the access
levels of its input and return types.

A typealias may have any access level up to the access level of the type
it aliases. That is, a `private` typealias can refer to a `public` type,
but not the other way around. This includes associated types used to
satisfy protocol conformances.

## Runtime Guarantees

Non-`public` members of a class or extension will not be seen by
subclasses or other extensions from outside the module. Therefore,
members of a subclass or extension will not conflict with or
inadvertently be considered to override non-accessible members of the
superclass.

Access levels lower than `public` increase opportunities for
devirtualization, though it is still possible to put a subclass of a
`private` class within the same scope.

Most information about a non-`public` entity still has to be put into a
module file for now, since we don\'t have resilience implemented. This
can be improved later, and is no more revealing than the information
currently available in the runtime for pure Objective-C classes.

### Interaction with Objective-C

If an entity is exposed to Objective-C, most of the runtime guarantees
and optimization opportunities go out the window. We have to use a
particular selector for members, everything can be inspected at runtime,
and even a private member can cause selector conflicts. In this case,
access control is only useful for discipline purposes.

Members explicitly marked `private` or `fileprivate` are *not* exposed
to Objective-C unless they are also marked `@objc` (or `@IBAction` or
similar), even if declared within a class implicitly or explicitly
marked `@objc`.

Any `public` entities will be included in the generated header. In an
application or unit test target, `internal` entities will be exposed as
well.

## Non-Goals: \"class-only\" and \"protected\"

This proposal omits two forms of access control commonly found in other
languages, a \"class-implementation-only\" access (often called
\"private\"), and a \"class and any subclasses\" access (often called
\"protected\"). We chose not to include these levels of access control
because they do not add useful functionality beyond `private`,
`fileprivate`, `internal`, and `public`.

### "class-only"

If \"class-only\" includes extensions of the class, it is clear that
it provides no protection at all, since a class may be extended from
any context where it is accessible. So a hypothetical \"class-only\"
must already be limited with regards to extensions. Beyond that,
however, a \"class-only\" limit forces code to be declared within
the class that might otherwise naturally be a top-level helper or an
extension method on another type.

`private` and `fileprivate` serve the use case of limiting access to
the implementation details of a class (even from the rest of the
module!) while not tying access to the notion of type.

### "protected"

"protected\" access provides no guarantees of information hiding,
since any subclass can now access the implementation details of its
superclass\-\--and expose them publicly, if it so chooses. This
interacts poorly with our future plans for resilient APIs.
Additionally, it increases the complexity of the access control
model for both the compiler and for developers, and like
\"class-only\" it is not immediately clear how it interacts with
extensions.

Though it is not compiler-enforced, members that might be considered
\"protected\" are effectively publicly accessible, and thus should
be marked `public` in Swift. They can still be documented as
intended for overriding rather than for subclassing, but the
specific details of this are best dealt with on a case-by-case
basis.

## Potential Future Directions

-   Allowing `private` or `internal` protocol conformances, which are
    only accessible at compile-time from a particular access scope.
-   Limiting particular capabilities, such as marking something
    `final(public)` to restrict subclassing or overriding outside of the
    current module.
-   Allowing the Swift parts of a mixed-source framework to access
    private headers.
-   Revealing `internal` Swift API in a mixed-source framework in a
    second generated header.
-   Levels of `public`, for example `public("SPI")`.
-   Enum cases less accessible than the enum.
-   Protocol requirements less accessible than the protocol.