[API Proposal]: Add PipeOptions.FirstPipeInstance enum value

[JamesNK]

Background and motivation

It's not possible for an app hosting multiple named pipe connections to verify that no one else is using the pipe name when it starts.

For example, Kestrel is looking at adding a named pipe transport, and when we start Kestrel we want to verify that no one else is using the configured pipe name:

• We don't want to share the pipe between Kestrel instances. It's common for devs to accidentally launch Kestrel when it's already running. A socket errors if you bind to it when it's already open. We want the same protection with a named pipe.
• A pipe gets many of its settings when it is first opened. Want to verify that Kestrel's settings are applied to the pipe.

Named pipes have a built-in option for checking this - FILE_FLAG_FIRST_PIPE_INSTANCE. See https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createnamedpipea

.NET doesn't expose this option. While it is automatically set if the max number of pipe instances is 1, there is no way to explicitly set this option.

runtime/src/libraries/System.IO.Pipes/src/System/IO/Pipes/NamedPipeServerStream.Windows.cs

Lines 121 to 124 in c59b517

	int openMode = ((int)direction) |
	(maxNumberOfServerInstances == 1 ? Interop.Kernel32.FileOperations.FILE_FLAG_FIRST_PIPE_INSTANCE : 0) |
	(int)options |
	(int)additionalAccessRights;

.

If the PipeOptions.FirstPipeInstance options was available, then Kestrel would create the first NamedPipeServerStream with it the option to verify that there is no existing pipe with that name and create subsequent NamedPipeServerStream instances without the option.

Note that validation on the NamedPipeServerStream ctor currently prevents the enum value having FILE_FLAG_FIRST_PIPE_INSTANCE value added to it. e.g.

// NamedPipeServerStream errors when passed this pipe option
pipeOptions |= (PipeOptions)0x00080000;

API Proposal

namespace System.IO.Pipes
{
    [Flags]
    public enum PipeOptions
    {
        FirstPipeInstance = unchecked((int)0x00080000)
    }
}

API Usage

private NamedPipeServerStream CreateServerStream(bool firstStream)
{
    var pipeOptions = PipeOptions.Asynchronous | PipeOptions.WriteThrough;
    if (_options.CurrentUserOnly)
    {
        pipeOptions |= PipeOptions.CurrentUserOnly;
    }
    if (firstStream)
    {
        pipeOptions |= PipeOptions.FirstPipeInstance;
    }

    return new NamedPipeServerStream(
        _endpoint.PipeName,
        PipeDirection.InOut,
        NamedPipeServerStream.MaxAllowedServerInstances,
        PipeTransmissionMode.Byte,
        pipeOptions,
        inBufferSize: 0,
        outBufferSize: 0);
}

Alternative Designs

[Flags]
public enum PipeOptions
{
    EnsureFirstPipeInstance = unchecked((int)0x00080000)
}

It still alludes at the name of the Windows API flag and conveys "throw if already exists".

Risks

No response

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

It's not possible for an app hosting multiple named pipe connections to verify that no one else is using the pipe name when it starts.

For example, Kestrel is looking at adding a named pipe transport, and when we start Kestrel we want to verify that no one else is using the configured pipe name.

Named pipes have a built-in option for checking this - FILE_FLAG_FIRST_PIPE_INSTANCE. See https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createnamedpipea

.NET doesn't expose this option. While it is automatically set if the max number of pipe instances is 1, there is no way to explicitly set this option.

runtime/src/libraries/System.IO.Pipes/src/System/IO/Pipes/NamedPipeServerStream.Windows.cs

Lines 121 to 124 in c59b517

	int openMode = ((int)direction) |
	(maxNumberOfServerInstances == 1 ? Interop.Kernel32.FileOperations.FILE_FLAG_FIRST_PIPE_INSTANCE : 0) |
	(int)options |
	(int)additionalAccessRights;

.

If the PipeOptions.FirstPipeInstance options was available, then Kestrel would create the first NamedPipeServerStream with it the option to verify that there is no existing pipe with that name and create subsequent NamedPipeServerStream instances without the option.

Note that validation on the NamedPipeServerStream ctor currently prevents the enum value having FILE_FLAG_FIRST_PIPE_INSTANCE value added to it. e.g.

// NamedPipeServerStream errors when passed this pipe option
pipeOptions |= (PipeOptions)0x00080000;

API Proposal

namespace System.IO.Pipes
{
    [Flags]
    public enum PipeOptions
    {
        FirstPipeInstance = unchecked((int)0x00080000)
    }
}

API Usage

private NamedPipeServerStream CreateServerStream(bool firstStream)
{
    var pipeOptions = PipeOptions.Asynchronous | PipeOptions.WriteThrough;
    if (_options.CurrentUserOnly)
    {
        pipeOptions |= PipeOptions.CurrentUserOnly;
    }
    if (firstStream)
    {
        pipeOptions |= PipeOptions.FirstPipeInstance;
    }

    return new NamedPipeServerStream(
        _endpoint.PipeName,
        PipeDirection.InOut,
        NamedPipeServerStream.MaxAllowedServerInstances,
        PipeTransmissionMode.Byte,
        pipeOptions,
        inBufferSize: 0,
        outBufferSize: 0);
}

Alternative Designs

No response

Risks

No response

Author:	JamesNK
Assignees:	-
Labels:	api-suggestion, area-System.IO, untriaged
Milestone:	-

[jozkee]

Thanks for the proposal, it looks to me like a good case to expose the option.

Note that validation on the NamedPipeServerStream ctor currently prevents the enum value having

I also thought of just excluding FILE_FLAG_FIRST_PIPE_INSTANCE from said validation, but the history shows that it is in place since Pipe code was ported over to core.

Regarding the proposed name, I'm not sure if FirstPipeInstance is the best name, since it doesn't quite convey that it will throw if the pipe already exists.

As an alternative proposal I suggest EnsureFirstPipeInstance, it still alludes at the Windows flag and conveys "error if already exists".

[JamesNK]

I went with FirstPipeInstance because it lines up with the windows API flag. I agree that something like EnsureFirstPipeInstance is more descriptive.

[terrajobst]

Video

• The proposal looks reasonable, but given the angle is security, we can't just no-op this in the non-Windows implementation. Is there a reasonable cross-platform implementation or do we need to consider this a Windows-only feature?
  • If it's Windows-only we should mark the enum member as [SupportedOSPlatform("windows")] and throw PlatformNotSupportedException from the corresponding methods using it (i.e. the constructors)

namespace System.IO.Pipes
{
    [Flags]
    public enum PipeOptions
    {
        FirstPipeInstance = unchecked((int)0x00080000)
    }
}